# Profile Manager 记忆体系架构 ## 概述 基于 SQLite 的人物档案管理系统，支持 profile/fact/relationship/event 四类实体，统一通过 change_log 表记录完整变更上下文。 --- ## 数据库表结构（六表） ### 1. profiles - 人物档案 ``` identity TEXT PRIMARY KEY -- 唯一标识 name TEXT -- 姓名 bio TEXT -- 简介 avatar_hash TEXT -- 头像哈希 preferences TEXT (JSON) -- 偏好设置 created_at REAL -- 创建时间 updated_at REAL -- 更新时间 ``` **用途**：存储人物基础信息，首次注册和后续变更都自动记录到 change_log。 --- ### 2. facts - 事实三元组 ``` id INTEGER PRIMARY KEY AUTOINCREMENT subject_id TEXT NOT NULL -- 主体身份 ID (FK→profiles) predicate TEXT NOT NULL -- 谓词（如 favorite_color, works_at） object TEXT NOT NULL -- 客体值 topic TEXT -- 主题分类（profile/work/study/hobby等） time TEXT -- 时间维度 source_dialogue_id INTEGER -- 来源对话 ID confidence REAL DEFAULT 1.0 -- 可信度 0-1 verified INTEGER DEFAULT 0 -- 是否验证 created_at REAL -- 创建时间 expires_at REAL -- 过期时间（追加模式使用） source_type TEXT -- 数据来源（dialogue/photo/video/file） source_id TEXT -- 来源唯一ID ``` **用途**：存储人物的静态属性/事实，采用追加模式（同predicate新事实写入时旧记录自动过期）。首次添加和值变更都记录到 change_log。 --- ### 3. relationships - 当前关系 ``` from_identity TEXT NOT NULL -- 关系发起方 to_identity TEXT NOT NULL -- 关系目标方 relation_type TEXT NOT NULL -- 关系类型（colleague/friend/family等） strength REAL DEFAULT 0.5 -- 关系强度 0-1 note TEXT -- 备注 source_dialogue_id INTEGER -- 来源对话 ID created_at REAL -- 创建时间 updated_at REAL -- 更新时间 PRIMARY KEY (from_identity, to_identity) ``` **用途**：存储当前有效的人际关系状态。首次建立和关系变化都记录到 change_log。 --- ### 4. relationship_history - 关系变更历史 ``` id INTEGER PRIMARY KEY AUTOINCREMENT from_identity TEXT NOT NULL to_identity TEXT NOT NULL relation_type TEXT strength REAL changed_at REAL NOT NULL source_dialogue_id INTEGER change_reason TEXT -- 变更原因（LLM提取） ``` **用途**：追加式记录关系变化时间线。 --- ### 5. events - 事件时间线 ``` id INTEGER PRIMARY KEY AUTOINCREMENT timestamp REAL NOT NULL -- 时间戳 participant_ids TEXT (JSON) -- 参与者列表 event_type TEXT NOT NULL -- 事件类型 description TEXT -- 事件描述 scene_hash TEXT -- 场景哈希 importance REAL DEFAULT 0.5 -- 重要性 0-1 metadata TEXT (JSON) -- 扩展信息（可含5W1H） ``` **用途**：记录人物参与的具体事件，支持时间线查询。创建时记录到 change_log。 --- ### 6. change_log - 通用变更日志（核心） ``` id INTEGER PRIMARY KEY AUTOINCREMENT entity_type TEXT NOT NULL -- profile/fact/relationship/event entity_id TEXT NOT NULL -- 实体标识 field_name TEXT -- 变更字段 -- 六要素 who TEXT -- 谁引起的变更 what TEXT -- 变更内容摘要 time_desc TEXT -- 时间描述（绝对+相对） location TEXT -- 地点 reason TEXT -- 原因 trigger_method TEXT -- 如何触发（对话/系统同步/线下见面等） old_value TEXT (JSON) -- 变更前值 new_value TEXT (JSON) -- 变更后值 changed_at REAL NOT NULL -- 变更时间戳 source_dialogue_id INTEGER -- 来源对话 ID scene_context TEXT -- 场景描述（在做什么） trigger_dialogue TEXT -- 触发变更的原始对话 metadata TEXT (JSON) -- 扩展信息（GPS/设备/参与者等） ``` **用途**：所有实体变更的统一溯源入口，记录完整上下文。 --- ## 四表数据关系 ``` ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │ profiles │────▶│ facts │ │ change_log │ │ (人物档案) │ │ (事实属性) │◀────│ (变更溯源日志) │ └─────────────┘ └─────────────┘ └──────────────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────┐ │relationships│ │ events │ │ (当前关系) │ │ (事件时间线) │ └─────────────┘ └─────────────┘ │ ▼ ┌─────────────────────┐ │ relationship_history│ │ (关系变更历史) │ └─────────────────────┘ ``` --- ## 变更日志写入时机 | 方法 | 触发条件 | 写入内容 | |------|---------|---------| | `register_profile()` | 首次注册 | 记录"创建" | | `register_profile()` | 字段变更 | 记录每个变化字段的 old→new | | `add_fact()` | 首次添加 | 记录"创建" | | `add_fact()` | 值变更（旧值被过期） | 记录 old→new | | `update_relationship()` | 首次建立 | 记录"创建" | | `update_relationship()` | 关系变化 | 记录 relation_type/strength 变化 | | `add_event()` | 事件创建 | 记录"创建" | --- ## 核心 API ```python pm = ProfileManager(db_path="~/profiles.db") pm.initialize() # 人物档案 pm.register_profile(identity, name, bio, preferences, ...) # 注册/更新 pm.get_profile(identity) # 查询 # 事实 pm.add_fact(subject_id, predicate, object, topic, ...) # 添加（追加模式） pm.get_facts(subject_id, include_expired=False) # 查询 pm.search_facts(predicate, subject_id) # 搜索 # 关系 pm.update_relationship(from_id, to_id, relation_type, strength, ...) # 更新 pm.get_relationships(identity) # 查询当前关系 pm.get_relationship_history(from_id, to_id) # 查询关系历史 # 事件 pm.add_event(timestamp, participant_ids, event_type, description, ...) # 添加 pm.get_events(time_range=None, last_hours=None) # 查询 # 变更溯源（核心） pm.get_change_history(entity_type=None, entity_id=None, limit=50) # 查询所有变更 ``` --- ## 六要素示例 ```python pm.register_profile('zhangsan', name='张三丰', who='李四', # 谁引起的变更 what='身份变更', # 变更内容摘要 time_desc='2024-09-21 午餐后', # 时间描述 location='会议室A', # 地点 reason='更正+晋升', # 原因 trigger_method='对话触发', # 如何触发 scene_context='项目会后闲聊', # 场景描述 trigger_dialogue='李四：你叫张三丰对吧？升架构师了？', # 触发对话 metadata={'gps': {'lat': 39.9, 'lng': 116.4}} # 扩展信息 ) ``` 查询结果： ```json { "entity_type": "profile", "entity_id": "zhangsan", "field_name": "create", "old_value": null, "new_value": "{\"name\": \"张三丰\", \"bio\": \"架构师\"}", "who": "李四", "what": "身份变更", "time_desc": "2024-09-21 午餐后", "location": "会议室A", "reason": "更正+晋升", "trigger_method": "对话触发", "scene_context": "项目会后闲聊", "trigger_dialogue": "李四：你叫张三丰对吧？升架构师了？", "metadata": "{\"gps\": {\"lat\": 39.9, \"lng\": 116.4}}" } ``` --- ## 设计原则 1. **首次+变更都记录**：所有实体首次写入和后续变更都记录 change_log 2. **六要素完整**：尽可能记录 who/what/when/where/why/how 3. **上下文关联**：scene_context + trigger_dialogue 还原变更场景 4. **扩展性强**：metadata JSON 字段支持任意扩展信息 5. **统一入口**：change_log 是所有变更的单一溯源表 --- ## 版本历史 | 版本 | 日期 | 说明 | |------|------|------| | v1.4 | 2026-09-20 | 新增llm_wiki知识库整合 | | v1.5 | 2026-09-20 | 完善多源整合处理流程 | | v1.6 | 2026-09-20 | facts追加模式+relationship_history表 | | v1.7 | 2026-09-20 | 新增change_log表实现通用六要素变更溯源；所有实体首次写入和变更都记录 |