#记忆系统 (RAG)

#一句话概括

记忆系统通过本地 SQLite 数据库上的混合搜索引擎（向量 + FTS5 关键词 + MMR 重排序）提供检索增强生成，将相关上下文块注入每次 LLM 对话。

#职责

• 将 agent 工作空间的 Markdown 文件索引为可搜索的块（向量嵌入 + FTS5）
• 执行混合搜索（向量相似度 + 关键词匹配）并支持可配置权重
• 应用 MMR（最大边际相关性）重排序以提高结果多样性
• 应用时间衰减优先返回近期内容
• 支持多种嵌入 provider（OpenAI、Gemini、Voyage、Mistral、本地 node-llama-cpp）
• 无嵌入 provider 时优雅降级到纯 FTS 模式
• 将搜索结果作为上下文注入 agent 对话

#架构图

#关键源码文件

#Token 优化影响

#配置旋钮

agents.defaults.memorySearch.query:
  maxResults: 5-20（注入多少块）
  minScore: 0-1（质量阈值）
  hybrid:
    vectorWeight: 0-1
    textWeight: 0-1

#优化机会

• 降低 maxResults：每个结果增加约 175 tokens；从 10 降到 5 每轮节省约 875 tokens
• 提高 minScore：过滤掉低质量结果，这些结果增加 token 但无价值
• MMR 多样性：已通过去除冗余块帮助优化
• 纯 FTS 模式：零嵌入 API 成本，关键词密集查询仍可用
• 时间衰减：自然降低过时内容优先级

#与其他模块的关系

• 依赖：config/（记忆设置）、sessions/（会话感知索引）、SQLite + sqlite-vec、chokidar（文件监视）
• 被依赖：agents/pi-embedded-runner/（通过 Pi SDK hooks 注入记忆上下文）、system-prompt.ts（记忆回忆指令）、auto-reply/reply/memory-flush.ts（回复后记忆刷新）

#我的认知盲区

• 精确的块大小和重叠设置 — 文件如何分割为块
• maxResults 默认值 — 需要在配置默认中查找
• 记忆上下文如何实际注入 — 作为 system 消息还是 user 消息？
• qmd-manager.ts（2000+ 行）— 高级查询元数据系统，基本未探索
• 批量嵌入操作 — 如何处理速率限制和失败
• 搜索结果是否跨轮次缓存

#相关贡献

• 暂无

#变更频率

• manager.ts：中 — 搜索 API 随新功能演进
• hybrid.ts：低 — 合并算法稳定
• embeddings.ts：中 — 新 provider 可用时添加
• mmr.ts：低 — 多样性算法成熟