# PicoBot 记忆系统设计与迁移方案 编写日期：2026-06-17 > 历史说明：本文的 `ContextCompressor`、Timeline 回填和时间戳边界描述是 1.19.0 之前的基线。当前上下文恢复由单一活动 checkpoint 和 durable `seq` 边界驱动，Timeline 只是提交后的派生检索记录；以 [CONTEXT_COMPACTION_DESIGN.md](CONTEXT_COMPACTION_DESIGN.md) 和 [ARCHITECTURE.md](ARCHITECTURE.md) 为准。 ## 背景 PicoBot 当前已经具备最基础的记忆能力： - `Knowledge` 记忆：长期事实、偏好、项目知识。 - `Timeline` 记忆：由上下文压缩产生的会话摘要。 - `memory_recall` / `timeline_recall`：模型可主动检索记忆。 - 上下文压缩时会把摘要写入 `Timeline`，并在恢复会话时回填最近摘要。 这套实现已经能工作，但它更像“存储 + 召回”的初版，而不是完整的记忆系统。主要短板是： - 记忆写入依赖显式工具调用，缺少自动抽取与整理闭环。 - 检索主要是关键词/FTS，缺少排序、衰减和冲突消解。 - `Timeline`、`Knowledge`、运行时上下文之间的边界还不够严格。 - 记忆治理能力不足，缺少过期、失效、来源追踪、置信度等元数据。 本方案目标是把 PicoBot 的记忆从“能记住”升级为“记得准、找得到、能更新、会遗忘、可观测”。 ## 现状基线 当前代码中的记忆链路大致如下： 1. `SessionManager` 在处理用户消息时，先召回 `Knowledge` 记忆并拼进运行时上下文。 2. `ContextCompressor` 在上下文过大时压缩消息历史，并把压缩结果写为 `Timeline` 记忆。 3. `timeline_recall` 工具允许模型主动检索历史摘要。 4. `memory_store` / `memory_recall` / `memory_forget` 允许模型手动管理 `Knowledge` 记忆。 现有实现的特点： - 存储是 SQLite。 - 检索是 FTS5 + LIKE 回退。 - 记忆条目只有 `key/content/category/importance/session_id/timestamps`。 - 配置里已经预留了 `recall_limit`、`timeline_retention_days`、`idle_consolidation_minutes` 等参数，但整体闭环还没有完全落地。 ## 设计目标 ### 必须达到 1. 自动化 - 从对话中自动抽取稳定事实、偏好、项目约束、关键决定。 - 不依赖模型每次都显式调用 `memory_store`。 2. 可控 - 记忆写入要有明确来源、置信度和类别。 - 支持更新、失效、覆盖、删除。 3. 可检索 - 检索不能只依赖关键词匹配。 - 需要结合相关性、重要性、时效性、会话范围进行排序。 4. 可回填 - 会话恢复时，要能回填“最近摘要 + 相关历史 + 相关知识”，但不能把噪声无限回灌。 5. 可治理 - 需要定期清理过期 timeline。 - 低质量或冲突记忆要可降权、可 supersede、可追溯。 ### 暂不做 - 不在第一阶段引入复杂的分布式记忆服务。 - 不强制接入外部向量数据库。 - 不把记忆系统做成一个独立的产品边界；它仍然属于 PicoBot runtime。 ## 目标架构 建议把记忆系统拆成四层。 ### 1. 运行时上下文层 用途： - 当前轮的系统提示词。 - 运行时间、会话 ID、临时提醒、技能提示。 - 不应被长期记忆污染。 规则： - 只属于当前 turn。 - 不入库，或仅作为可追踪的审计记录入库，不参与长期 recall。 ### 2. Timeline 层 用途： - 会话摘要。 - 上下文压缩结果。 - 历史状态回放。 规则： - 按 session 归属。 - 可被 `timeline_recall` 查询。 - 默认保留有限时间，过期可清理。 - 适合作为“发生过什么”的记录，而不是“世界上长期成立的事实”。 ### 3. Knowledge 层 用途： - 用户稳定偏好。 - 项目事实。 - 长期决策。 - 可复用的经验和约束。 规则： - 需要来源追踪和更新时间。 - 可以被时间衰减、冲突消解、覆盖和删除。 - 适合被 `memory_recall` 检索并注入 system/runtime context。 ### 4. Archive 层 用途： - 低价值但不该直接丢弃的历史。 - 被 supersede 的旧知识。 - 过期 timeline 的冷存档。 规则： - 不参与默认 recall。 - 仅在排障、导出、审计或手工恢复时查看。 ## 统一数据模型 建议将 `memories` 表从“扁平文本”升级为“可治理条目”。 ### 推荐字段 ```text id 唯一 ID key 语义 key，稳定标识一条知识或摘要 content 正文 category knowledge / timeline / archive / scratch session_id 归属会话 source_session_id 来源会话 source_message_id 来源消息或 turn 标识 source_type explicit_tool / auto_consolidation / context_compression / manual importance 重要性 0.0-1.0 confidence 置信度 0.0-1.0 created_at 创建时间 updated_at 更新时间 last_accessed_at 最近召回时间 expires_at 过期时间，可空 superseded_by 被哪条记忆覆盖 status active / superseded / archived / deleted tags 便于过滤和检索 embedding_ref 未来可选的向量引用 ``` ### 字段意义 - `importance`：这条记忆值不值得保留。 - `confidence`：这条记忆有多可靠。 - `source_*`：这条记忆从哪里来，方便审计和冲突处理。 - `expires_at`：是否该被自动遗忘。 - `superseded_by`：是否已经被更可信的新版本覆盖。 ## 写入策略 ### 1. 显式写入 仍保留 `memory_store` 工具。 适用场景： - 用户明确要求记住。 - 模型确认了稳定事实。 - 人工/外部流程显式提供知识条目。 要求： - 必须带稳定 `key`。 - 建议附带 `importance` 和 `confidence`。 - 允许覆盖同 key 的旧值，但要保留变更痕迹。 ### 2. 自动知识抽取 新增一条 consolidation 流程，从 turn 中抽取结构化记忆： - `facts` - `preferences` - `decisions` - `constraints` - `open_loops` 抽取结果应满足： - 只写“稳定可复用”的信息。 - 不写临时情绪、不写会话噪声、不写大段原文。 - 默认先进入“候选记忆区”，通过规则或 LLM 二次确认后再升格为 active knowledge。 ### 3. 会话压缩写入 Timeline 当前 `ContextCompressor` 继续承担“会话摘要”的职责，但建议改成两步： 1. 压缩当前上下文，生成可注入的短摘要。 2. 同时生成结构化 timeline entry，写入 timeline store。 这样 timeline 摘要和给模型看的压缩摘要可以一致，但不必完全相同。 ## 读取策略 ### 默认读取顺序 每轮 user turn 建议按以下顺序构建上下文： 1. 运行时上下文 2. 当前会话最近消息 3. 当前会话最近 timeline 摘要 4. 与当前 query 相关的 Knowledge 记忆 5. 必要时再补充更旧的 Timeline 召回 ### Knowledge 召回排序 建议使用混合评分： ```text final_score = relevance_score + importance_weight + recency_weight - redundancy_penalty - superseded_penalty ``` 建议排序规则： - 先按相关性筛选候选。 - 再按重要性和更新时间重排。 - 被 supersede 的条目默认不参与主召回。 - 低置信度条目只在结果不足时补位。 ### Timeline 召回策略 Timeline 更适合按 session 和时间窗口召回： - 恢复会话时优先加载最近几条摘要。 - 只有当模型显式需要回顾历史，或者当前话题明显切换，才主动拉更多 timeline。 - 跨会话回顾时先查同主题摘要，再查同 session 摘要。 ## 冲突与失效 ### 冲突类型 1. 同 key 冲突 - 新记忆与旧记忆 key 相同。 - 处理方式：upsert，旧版本保留更新历史。 2. 语义冲突 - 内容不同，但描述的是同一事实。 - 处理方式：标记旧条目 superseded，保留新条目为 active。 3. 时效冲突 - 旧事实已经过期。 - 处理方式：按 `expires_at` 或规则自动归档。 ### 推荐处理流程 1. 新记忆先入候选队列。 2. 对候选记忆做相似度检查。 3. 如果与已有 active knowledge 冲突： - 保留新条目。 - 给旧条目标记 `superseded_by`。 4. 如果置信度过低： - 降权但不立即删除。 5. 如果确定失效： - 移入 archive 或直接删除。 ## 过期与清理 ### Timeline 清理 Timeline 默认保留 90 天是合理起点，但建议把它变成真正的后台任务： - 每日或定时运行。 - 清理 `category = timeline` 且过期的条目。 - 清理前先做统计和日志记录。 ### Knowledge 清理 Knowledge 不建议简单按天数删。 更合理的是： - 低重要度 + 低置信度 + 长时间未访问的记忆，先降权。 - 明确过期的条目进入 archive。 - 被 superseded 的条目保留一段审计窗口后再清理。 ### 噪声过滤 禁止写入或默认不回灌的内容： - 自动压缩摘要的中间副本。 - 运行时元信息。 - 工具回显噪声。 - 模板/框架泄漏。 - 明显的无意义重复片段。 ## 与现有代码的映射 建议的模块职责演进如下： ### `src/memory/` 保留高层 API，但增加： - 条目元数据 - 记忆状态机 - 统一评分接口 - 冲突处理接口 ### `src/storage/memory.rs` 负责： - SQLite CRUD - FTS/LIKE 检索 - Timeline 清理 - 批量更新 superseded 状态 后续可扩展： - `last_accessed_at` 更新 - 记忆状态批处理 - 按 session / namespace 的索引优化 ### `src/agent/context_compressor.rs` 继续负责上下文压缩，但建议拆成两步： - 压缩历史 - 产出 timeline 记录 并把“是否生成 timeline / 是否写入 memory”做成明确开关。 ### `src/session/session.rs` 负责： - 选择哪些记忆进入当前 turn - 会话恢复时注入最近 timeline - 持久化 session 级别的压缩/归档状态 不应承担记忆抽取和冲突消解的重逻辑。 ### `src/tools/memory.rs` 保留工具接口，但建议： - 增加 `confidence`、`expires_at`、`tags` 等参数。 - `memory_recall` 支持更清晰的过滤条件。 - `memory_forget` 支持软删和 hard delete 两种模式。 ## 迁移方案 建议分 5 个阶段推进。 ### Phase 0: 文档和协议对齐 目标： - 先把目标讲清楚，避免边改边跑偏。 产物： - 本文档。 - 更新 `README` 中的记忆入口。 - 补齐记忆数据模型和流程图。 验收： - 团队能明确区分 runtime / timeline / knowledge / archive 四层。 ### Phase 1: 只扩 schema，不改行为 目标： - 给后续治理能力留好数据位。 改动建议： - `memories` 表增加 `confidence`、`source_type`、`source_message_id`、`source_session_id`、`last_accessed_at`、`expires_at`、`superseded_by`、`status`、`tags` 等字段。 - 兼容老数据：老字段缺省时回退到旧逻辑。 - `SessionMeta` 可继续保留现有压缩时间戳。 验收： - 老数据能正常读写。 - 现有记忆工具和压缩流程不需要改调用方。 ### Phase 2: 补自动 consolidation 目标： - 从“显式写记忆”升级为“自动抽取记忆”。 改动建议： - 在一次 turn 结束后，异步启动 consolidation。 - 从最近 turn 中抽取： - timeline summary - knowledge candidates - 新增去噪逻辑： - 不写工具噪声 - 不写运行时上下文 - 不写重复摘要 推荐落点： - `src/session/session.rs` - `src/agent/context_compressor.rs` - `src/memory/` 验收： - 用户不手动调用 `memory_store` 时，也能逐步积累稳定知识。 - timeline 记录与知识条目不再混写。 ### Phase 3: 引入混合召回与排序 目标： - 让 recall 真正“像记忆”而不是“像全文搜索”。 改动建议： - 召回增加排序层： - 相关性 - 重要性 - 时效性 - 状态过滤 - `Knowledge` 与 `Timeline` 使用不同召回策略。 - 恢复会话时优先加载最近 timeline，再按 query 召回知识。 可选增强： - 后续接入 embedding / rerank。 验收： - 长会话和多主题对话的召回质量明显提升。 - 旧记忆不会总是压过新记忆。 ### Phase 4: 冲突消解、失效与清理 目标： - 让记忆系统可治理。 改动建议： - 对知识条目做冲突检测。 - 支持 supersede。 - 对 timeline 做定期清理。 - 对低质量或长期未访问的知识降权或归档。 推荐定时任务： - timeline retention cleanup - stale memory decay - archive compaction 验收： - 过期内容不会无限膨胀。 - 旧事实能被新事实覆盖。 ### Phase 5: 兼容层收口 目标： - 把临时兼容逻辑收敛成稳定接口。 改动建议： - 清理历史遗留的“摘要直接当知识”路径。 - 统一只从 memory service 读取记忆，不再绕过治理层直接查表。 - 为 debug/export 保留只读视图，但不参与默认注入。 验收： - 记忆系统对外只有稳定接口。 - 内部实现可继续演进，而不影响 Session / Agent 调用方。 ## 推荐实现顺序 如果只做一轮最有性价比的改造，我建议按这个顺序： 1. `schema + metadata` 2. `自动 consolidation` 3. `混合召回与重排` 4. `冲突消解与衰减` 5. `定时清理` 这个顺序的好处是： - 先把可观察和可治理的数据补齐。 - 再补自动写入，避免“写进去但以后无法管理”。 - 最后再优化召回体验。 ## 风险与回退 ### 风险 - 自动抽取可能把短期上下文误判成长期知识。 - 召回排序不稳时，模型可能看到过多或过少记忆。 - 迁移 schema 时如果没有兼容逻辑，老数据会丢。 ### 回退策略 - 保留现有 `memory_store` / `memory_recall` 作为兼容入口。 - 所有新字段都应可空。 - consolidation 可以通过配置关闭。 - 召回排序可退回 FTS5 + importance 的简化模式。 ## 验收标准 记忆系统完成迁移后，应满足： 1. 用户不手动存记忆时，系统仍能逐步积累稳定知识。 2. `Knowledge` 的 recall 结果更准，噪声更少。 3. `Timeline` 不会无限膨胀，且能按 session 回放。 4. 旧事实可被新事实覆盖，冲突状态可追踪。 5. `SessionManager` 不再承担记忆抽取的核心业务逻辑。 6. 任意记忆条目都能回答三个问题： - 它从哪里来？ - 它为什么还活着？ - 它什么时候该被忘掉？ ## 对 PicoBot 当前实现的落地建议 最直接的落点是： - 先在 `src/storage/memory.rs` 和 `src/memory/types.rs` 扩字段。 - 再在 `src/agent/context_compressor.rs` 增加结构化摘要输出。 - 然后在 `src/session/session.rs` 增加 consolidation hook。 - 最后把 `src/tools/memory.rs` 升级为带治理字段的工具接口。 如果只做最小闭环，至少要先实现： - `Timeline` 的定时清理 - `Knowledge` 的自动抽取 - `Knowledge` 的冲突消解 - 召回结果的时间衰减和重排 这样 PicoBot 的记忆系统就会从“可用”变成“可信、可演进”。