# Profile Manager 六表架构 + 变更溯源 V1.7

> 本次会话(2026-09-21)完成的 Profile Manager 记忆体系核心升级

## 六表架构

| 表 | 策略 | 说明 |
|---|------|------|
| profiles | 覆盖式 | 首次注册+字段变更都记 change_log |
| facts | 追加+过期 | 同predicate新值写入时旧记录expires_at=now，首次+变更都记change_log |
| relationships | 当前状态 | UPSERT，首次建立+关系变化都记change_log |
| relationship_history | 完整日志 | 每次关系变更追加一行 |
| events | 追加式 | 不可变事件记录，创建时记change_log |
| change_log | 通用溯源 | **六要素(who/what/time_desc/location/reason/trigger_method)+场景+触发对话+metadata** |

## change_log 六要素

```python
pm.register_profile('zhangsan', name='张三丰',
    who='李四',                          # 谁引起的变更
    what='身份变更',                     # 变更内容摘要
    time_desc='2024-09-21 午餐后',        # 时间描述（避开SQL保留字when）
    location='会议室A',                   # 地点
    reason='更正+晋升',                   # 原因
    trigger_method='对话触发',             # 如何触发
    scene_context='项目会后闲聊',          # 场景描述
    trigger_dialogue='李四：你叫张三丰对吧？升架构师了？',  # 触发对话
    metadata={'gps': {'lat': 39.9, 'lng': 116.4}}  # 扩展信息
)
```

## 关键修复

1. **首次写入也记录**：所有实体首次创建和后续变更都写入 change_log
2. **SQL保留字**：`when` → `time_desc`
3. **add_event() metadata参数**：新增 metadata 支持
4. **_log_change()签名**：old_value 改为 Optional[str]

## API 更新

```python
# 所有方法都支持六要素参数
pm.register_profile(identity, name, bio, preferences, who=..., what=..., time_desc=..., ...)
pm.add_fact(subject, predicate, object, topic=..., who=..., what=..., time_desc=..., ...)
pm.update_relationship(from_id, to_id, type, strength, who=..., what=..., time_desc=..., ...)
pm.add_event(timestamp, participants, type, desc, metadata=..., who=..., what=..., time_desc=..., ...)
pm.get_change_history(entity_type=None, entity_id=None, limit=50)
```

## 文件路径

- 代码: `profile_manager.py` (V1.7)
- 数据库: `~/.hermes/workspace/livekit-agents/profiles.db`
- PRD: `livekit_agents_PRD.md` (v1.7)