拆解 ai-memory 八步数据流:钩子捕获、脱敏入库、RRF 融合检索一次讲透
拆解 ai-memory 八步数据流:钩子捕获、脱敏入库、RRF 融合检索一次讲透
大模型驱动的编程智能体正在经历一场"失忆"危机:Claude Code 今天修好的 bug,Codex 明天又要重新踩一遍;Claude 昨晚讨论的架构决策,Cursor 早上开机时一无所知。社区里关于"给智能体装上长期记忆"的讨论已经从一个技术概念长成了一条赛道——从 Mem0、Chroma 的记忆即服务,到腾讯云 Agent Memory 这类团队级记忆中枢,各家方案纷纷登场。而 ai-memory 选择了一条更"工程化"的路线:用 Rust 实现一个本地优先的长期记忆服务,以 Markdown Wiki 为唯一事实源、SQLite 为派生索引,打通钩子捕获、脱敏入库、会话摘要生成、Handoff 交接、混合检索、分层遗忘与备份恢复的完整八步数据流。本文结合仓库源码,把这八步一次讲透。
一、先看全景:双层存储下的八步链路
ai-memory 的存储架构有一个关键判断:记忆的第一性事实是"人能读懂的文本",而不是向量。因此它把 Markdown 文件当作唯一事实源(source of truth),SQLite 只是从 Wiki 派生的可检索索引——搜索命中、向量召回、实体匹配都建立在同一份可 git 版本化的文本之上。社区将其概括为"知识只编译一次"的范式,区别于传统 RAG 每次检索都重新切片、知识永远不积累的做法。
围绕这双层存储,数据流可以切成八个步骤,下文逐一展开:钩子捕获 → 脱敏入库 → 会话摘要生成 → Handoff 交接 → FTS5 全文检索 → 实体匹配 → 邻域扩展 → RRF 融合排序,最后以分层遗忘与备份恢复完成记忆的生命周期闭环。
二、钩子捕获:十余种 CLI 的零侵入接入
第一步是"看见"。ai-memory 不要求你改变工作流,而是复用各家 CLI 原生的钩子机制。以 Claude Code 为例,hooks/claude-code/session-start.sh 在会话启动时把事件 JSON 以 fire-and-forget 方式 POST 给本地服务(默认 http://127.0.0.1:49374):
printf '%s' "$PAYLOAD" \
| ai_memory_post_hook "$SERVER/hook?event=session-start&agent=claude-code${QS}" >/dev/null 2>&1 || true
而 hooks/claude-code/post-tool-use.sh 则在每次工具调用后把 payload 转发给服务端,并固定输出 {}——既完成采集,又不污染客户端调试日志。整个钩子体系由 hooks/_lib.sh 这个 POSIX shell 辅助库支撑,被 claude-code、codex、cursor、gemini-cli、kimi-code、kiro-cli、antigravity-cli、opencode 等十余种 agent 的钩子脚本共同 source,全脚本零 bash 特有语法、零 jq 依赖。
值得注意的两个工程细节:
- 标记文件路由:钩子脚本从 cwd 向上遍历查找
.ai-memory.toml标记文件(在$HOME边界内停止,避免多用户场景下串号),把workspace、project、project_strategy等声明作为 query 参数附加到请求上,从而把事件归入正确的项目桶。 - 失败不阻塞:POST 使用
curl --max-time 0.2的 200ms 预算,超时、5xx 事件进入本地 spool 稍后重放,4xx 视为永久拒绝不再重试——钩子永远不拖慢智能体本身。
三、脱敏入库:类型化清洗与"拒绝而非改写"
采集到的事件 payload 不能直接入库,这是隐私底线。ai-memory 的做法分两道闸门。
第一道在客户端侧完成:companions/ai-memory-client/src/scrub.rs 的 sanitize_external_text 定义了多组脱敏规则——PEM 私钥块整体替换为 [REDACTED PRIVATE KEY],github_pat_、ghp_、sk-、AWS AKIA 等凭据模式替换为 [REDACTED CREDENTIAL],bearer token 与 api_key=... 键值对则保留键名、只抹掉值。同时控制字符和 Unicode 双向控制符(\u{202a}–\u{202e} 等)统一替换为 \u{fffd},防止注入与干扰解析。
第二道闸门在服务端入口:companions/ai-memory-client/src/lib.rs 的 reject_sensitive 采用更严格的口径——发现敏感内容直接拒绝整个 envelope 落库,而不是改写后放行("sensitive envelope rejected before persistence or delivery")。sensitive_key 会把 camelCase 键名归一化为 snake_case 再做词表匹配,并做了一处很细的区分:access_tokens、refresh_tokens 这类带凭据限定词的键照常脱敏,而 total_tokens、cache_read_input_tokens 这类纯用量度量(数字值)则放行,因为它们对后续会话摘要生成是必要输入而非秘密。check_body 更进一步,拒绝 hook body 携带 workspace、project、actor、author_id、headers 等权威字段——目标归属只能由服务端按标记文件解析,客户端无权指定,同时约束 payload 不超过 256KB、嵌套深度不超过 64 层。
四、会话摘要生成与 Handoff 交接
原始观察(observations)会积累成噪声,所以 ai-memory 在会话结束后用 LLM 做一次结构化整合。这一步由 crates/ai-memory-consolidate 承担:Consolidator 通过 complete_structured_with_retry 调用带结构化输出约束的 LLM,把一次会话整理为带元数据的 Markdown 页面,并映射到四层记忆层级——working(工作台)、episodic(情景)、semantic(语义)、procedural(流程),见 consolidator.rs 的 tier 映射。整合结果落回 Wiki 目录,成为可 git 版本化的第一手事实。
而 Handoff 交接是 ai-memory 的招牌能力:让不同厂商的智能体接力同一个项目。crates/ai-memory-core/src/handoff.rs 把它建模为一等公民类型:HandoffState 三态(Open → Accepted → Expired),NewHandoff 携带 summary、open_questions、next_steps、files_touched 四类结构化字段,让下一个智能体拿到的是"我们停在哪里、还欠什么、下一步做什么",而不是一整段未消化的日志。回看 session-start.sh 的第二步:同步 GET /handoff?agent=claude-code...,把交接内容包装成 hookSpecificOutput.additionalContext 输出到 stdout——Claude Code 会把 SessionStart 钩子的 stdout 前置到下一轮会话上下文里,于是接力方在没有任何人工干预的情况下,开场就带着前任的全部上下文。
五、混合检索:FTS5 + 实体 + 邻域扩展 + RRF 融合
检索是记忆变现的地方,也是 ai-memory 最值得抄作业的部分。核心实现在 crates/ai-memory-store/src/reader.rs 的 hybrid_search_inner,它把四路检索结果用 RRF(Reciprocal Rank Fusion)融合:
- FTS5 全文流:SQLite FTS5 + BM25 排名,配合
prepare_fts5_query做停用词与查询规范化,是默认路径(零 LLM 也能检索)。 - 向量流:
page_embeddings表按(provider, model, dim)精确匹配嵌入,做余弦相似度召回;另有 opt-in 的page_abstract_embeddings只对 frontmatter 的 abstract 行嵌入,作为第五路补充。 - 实体流:
entity_query_tokens把查询切成 3 字符以上的名词性 token(连字符/下划线形态同时保留),按"多少页面携带该实体"的逆频率加权——ai-memory、ai_memory、ai memory三种写法都能命中同一实体。 - 邻域扩展流:以上三路命中的页面作为种子,沿
references链接与causes/fixes/contradicts类型化边做入向/出向扩展,把"相关但没直接命中"的页面拉进候选池。
四路候选最终进入 RRF 融合,代码注释里写得很直白:score(d) = Σ 1/(k + rank_i(d)),k=60:
// RRF fuse: score(d) = Σ 1/(k + rank_i(d)) over rankers.
let k = 60.0_f64;
...
let contrib = 1.0 / (k + (rank + 1) as f64);
融合之后还有两道精细的收尾:一是页面权威度调整(PageAuthority),rule/decision 类页面 +0.15,session 类 -0.15,frontmatter 里 canonical/source-of-truth 标签 +0.20,do-not-answer-from 则把权威封顶在 0.55——有意的"不答"指令优先生效但绝不把页面藏起来;二是 SearchExplain 把每一路的原始排名、余弦值、实体权重和 RRF 贡献全部透明输出,让"为什么是这条结果"可以逐项审计。各流独立降级:没有 query 向量就跳过向量流,实体表为空就跳过实体流,邻域扩展照常从其余种子出发。
六、分层遗忘与备份恢复:记忆的生命周期管理
记忆系统真正的难点不是"存得下",而是"忘得掉"。ai-memory 的分层遗忘模型在 crates/ai-memory-store/src/decay.rs:保留分 retention_score 由年龄、访问次数、访问新鲜度与显式 salience 共同决定,衰减率由半衰期换算 λ = ln(2) / half_life_days。默认参数下 λ=0.02(约 35 天半衰期)、cold_threshold=0.20,低于阈值的情景层页面成为逐出候选;TierLambdas 允许运维按层覆盖 λ——想留更久的情景历史、想更快清理工作台草稿,各调各的旋钮,且默认全 None 时行为与单 λ 完全一致,无迁移悬崖。被逐出的页面会先以墓碑(tombstone)与版本祖先形式存活 hard_delete_after_days(默认 180 天),之后才由 ops.rs 的逐出清理 连同重建 FTS 索引、VACUUM 归还磁盘空间一起完成硬删除。
备份侧同样"工程化"。crates/ai-memory-cli/src/commands/backup.rs 一行 ai-memory backup --to <tarball> 即可 POST 到服务端 /admin/backup 拿到 gzip 归档——服务端走 SQLite online backup API,热库在线状态下也不会被竞态读坏。而 schema 演进由 crates/ai-memory-store/src/migrations.rs 用 refinery 嵌入式迁移管理(V01–V76 共 76 个版本):abort_missing = true 保证旧二进制遇到新库时以可操作的 DataSchemaAhead 错误拒绝打开,而不是静默带病运行。
结语
把八步连起来看,ai-memory 的竞争力不在任何单一算法,而在把记忆当成一个有完整生命周期的工程系统:捕获层用原生钩子零侵入接入十余种 CLI,入库层用类型化脱敏守住隐私底线,整合层用结构化摘要把噪声沉淀为可读事实,交接层让不同厂商的智能体无缝接力,检索层用 RRF 融合五路信号并保持全程可解释,遗忘层用分层衰减对抗信息熵增,备份与迁移则让这套系统本身可运维、可演进。当社区还在争论"向量库 vs 关系库"时,它用"文本为事实源、索引为派生"的双层架构回答了一个更本质的问题:记忆首先要是人可读的,其次才是机器可检索的。