554 lines
15 KiB
Markdown
554 lines
15 KiB
Markdown
# 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 的记忆系统就会从“可用”变成“可信、可演进”。
|