记忆系统

云雀 Agent 拥有受人类认知科学启发的 五层记忆架构。记忆是 Agent 从交互中学习、构建长期理解的基础。

架构

┌─────────────────────────────────────────────────────┐
│              记忆编排器 (Orchestrator)               │
│  摄取 → 提取 → 分类 → 存储 → 提升 → 衰减           │
├────────┬────────┬─────────┬──────────┬──────────────┤
│ 短期   │  中期  │  长期   │ 可编辑   │ 知识图谱     │
│ (对话) │ (事实) │ (规则)  │ (置顶)   │ 实体+关系    │
│ TTL    │ 衰减   │ 永久    │ 手动     │ 结构化       │
│ 1小时  │ 天级   │ 永远    │          │              │
├────────┴────────┴─────────┴──────────┴──────────────┤
│             统一召回管线 (5阶段)                      │
├─────────────────────────────────────────────────────┤
│        持久化: LedgerPersister + LedgerOrchPersister │
│        存储: SQLite memories 表 + Ledger KV          │
└─────────────────────────────────────────────────────┘

五个层级

1. 短期记忆

保存当前对话上下文。会话结束后自动过期（默认 TTL: 1 小时）。

2. 中期记忆

从对话中异步提取的事实和观察。随时间置信度衰减——不常被调用的记忆逐渐淡化。TF-IDF 评估重要性。

3. 长期记忆

Agent 学到的关于用户、领域或通用模式的永久知识。永不过期，只会被更高置信度的新事实覆盖。

4. 可编辑记忆

用户通过 Web 仪表盘手动添加、修改或删除的记忆。优先级最高 — 始终排在召回结果前面。

5. 知识图谱

捕获概念、人物、话题和任务之间结构化关系的实体-关系图。支持多跳推理查询。

召回管线

当 Agent 需要回忆时，5 阶段召回管线启动：

1. 查询嵌入: 将查询转为向量 (支持多种嵌入模型)
2. 向量搜索: ANN 跨所有记忆层搜索 (IVF/HNSW/暴力搜索自动切换)
3. BM25 关键词检索: 稀疏关键词匹配（混合检索），支持 CJK 单字切分
4. 评分与融合: RRF (Reciprocal Rank Fusion) 融合向量 + BM25 结果
5. 去重与排序: 移除重复，按最终得分排序，可选 Rerank (Jina/Cohere/LLM)

TF-IDF 重要性评分

使用 TF-IDF 替代硬编码关键词匹配来评估记忆重要性：

• 在线 IDF 表: 随记忆增删动态更新
• 评分阈值: ≥ 0.7 → 高重要性, ≥ 0.4 → 中, 其他 → 低

记忆提升

记忆可以从低层"提升"到高层：

• 高频访问的中期记忆 → 自动提升为长期记忆
• LLM 事实提取结果 → 根据重要性评分分类到相应层级

持久化

• LedgerPersister: 持久化中期/长期记忆到 SQLite，定期 flush
• LedgerOrchPersister: 持久化知识图谱和可编辑记忆
• 自动维护: 6 小时一次时间衰减，24 小时一次事件压缩

API

方法	路径	说明
GET	/v1/memory/stats	各层统计
GET	/v1/memory/search?q=...	混合检索
POST	/v1/memory/add	添加记忆
POST	/v1/memory/compact	整理压缩
GET	/v1/graph/entities	图谱实体
GET	/v1/graph/relations	图谱关系
DELETE	/v1/memory/:id	删除记忆