Token Savior持久记忆引擎揭秘:FTS5加向量嵌入如何让AI跨会话记住每次Bug修复
Token Savior持久记忆引擎揭秘:FTS5加向量嵌入如何让AI跨会话记住每次Bug修复
Token Savior 是一个 MCP 服务器,它的持久记忆引擎用 SQLite 的 FTS5 全文检索加上向量嵌入(vector embedding),让 AI 编码代理跨会话记住每一次 Bug 修复、架构决策和团队约定——下次打开会话,这些经验会自动重新注入,而不需要你再解释一遍。本文面向新手,拆解这套记忆系统的工作原理与快速上手方法。
🧠 为什么 AI 编码工具"记不住事"?
Claude Code 等 AI 代理有一个通病:会话一结束,一切归零。上周踩过的坑、定下的命名规范、修过的某个 Bug,换个会话就得重新踩一遍。
Token Savior 的解法是一个本地持久记忆引擎:
- 每一次决策、Bug 修复、约定、护栏(guardrail)都会被存成一条观察(observation),落盘到 SQLite(WAL 模式)
- 搜索时走 FTS5 全文检索 + 向量语义检索双通道
- 按 ROI(投入产出比)和贝叶斯有效性排序
- 下一个会话开始时,以**紧凑的增量(Memory Index)**重新注入上下文
据项目描述,加上这套引擎后,Claude 在真实编码基准上达到 97.9%(188/192),同时活跃 token 降低约 80%。
📝 记忆如何被记录:每次 Bug 修复都变成一条"观察"
记忆的最小单位是 observations 表中的一行,每条记录包含:类型(bugfix、convention、error_pattern、decision、guardrail 等)、标题、正文、为什么(why)、如何应用(how_to_apply)、重要度(1-10)、访问次数,以及用于去重的 SHA-256 内容哈希。
表结构定义在 src/token_savior/memory_schema.sql,例如 error_pattern(错误模式)类型的观察,正好承载"上次那个 Bug 是怎么修的"。
更妙的是,你可以让 LLM 自动抽取记忆:开启 TS_AUTO_EXTRACT=1 并配置 TS_API_KEY 后,每次工具调用结束,后台线程会分析工具输出,自动提炼出 0-3 条观察(类型限定为 bugfix、convention、warning、guardrail、infra、command),完全不用你手动记录。逻辑见 src/token_savior/memory/auto_extract.py。
# 一键安装,含 MCP 服务器
pip install "token-savior-recall[mcp]"
🔎 记忆如何被找回:FTS5 全文检索是第一道防线
所有观察都镜像进 FTS5 虚拟表 observations_fts,覆盖标题、正文、why、how_to_apply、标签、叙述、原子事实等 8 个字段,并由触发器在增删改时自动同步,见 src/token_savior/memory_schema.sql。
搜索时用 bm25() 打分排序,并返回高亮摘要(snippet()),核心查询在 src/token_savior/memory/observations.py。
这里藏着一个新手容易忽略的坑:FTS5 的裸词序列默认是"隐式 AND"——一句自然语言长查询会要求每个词都出现,实测在 45 条真实观察上命中率是 0/45。Token Savior 的对策是一条四级重试链:先安全转义查询,失败再放宽,最后用前缀匹配兜底形态变化,最终做到 45/45 命中且零 SQL 错误。
🧬 语义搜索:向量嵌入补上"换个说法"的盲区
全文检索有个死穴:你搜"证书过期",但记忆里写的是"TLS 凭证到期"——词不同,搜不到。向量嵌入就是来补这块的。
Token Savior 用 FastEmbed 加载 nomic-embed-text-v1.5-Q 模型,把每条观察编码为 768 维向量,存入 sqlite-vec 的 obs_vectors 表(见 src/token_savior/db_core.py)。嵌入助手在 src/token_savior/memory/embeddings.py,采用 INT8 量化 ONNX 推理:约 210MB 内存、单次约 160ms,纯 CPU 就能跑。
设计上有两个值得称道的细节:
- 优雅降级:没装向量组件、或模型加载失败时,搜索自动退回纯 FTS 模式,行为与旧版完全一致
- 距离地板(distance floor):k-NN 永远返回 k 个结果,哪怕毫无关联。实测发现"无关邻居"的距离(0.97-1.07)和"相关邻居"(0.85-0.99)几乎重叠,所以代码设了 0.86 的距离阈值,向量不够自信时宁可只信关键词,避免"记忆库变成幻觉生成器"。逻辑见 src/token_savior/memory/search.py
开启向量检索只需多装一个可选依赖:
pip install "token-savior-recall[mcp,memory-vector]"
⚖️ RRF 混合检索:两路结果如何融合
FTS 和向量各自返回一个排序列表,如何合并?Token Savior 采用业界标准的 RRF(Reciprocal Rank Fusion,k=60):每条观察的得分 = Σ 1/(60 + 排名),实现见 src/token_savior/memory/search.py。
但纯 RRF 有个缺陷:一个"两边都平庸"的结果可能压过一个"某一边特别突出"的结果。为此作者加了一个**"头部位置保证"**:两个列表的第一名会被强制提到最前。实测 45 条观察的长查询,平均排名从 2.08 降到 1.26。
融合策略还可通过环境变量 TS_FUSION 切换为 rrf(默认)、rrf_nu 或 additif(按归一化分数加和),方便你在自己的语料上做 A/B 测量。
🔁 跨会话续接:SessionStart 钩子自动注入记忆
记忆存下来、搜得到还不够,最后一步是自动送回上下文。
会话启动时,SessionStart 钩子会把按 ROI 排名的最高价值观察压缩成一个 Memory Index(实测平均仅约 1160 字符)注入给模型,钩子逻辑在 hooks/memory-session-start.sh。它受多个环境变量精细控制:
| 环境变量 | 作用 |
|---|---|
TS_SESSION_INDEX_MAX |
最多注入几条观察(默认 12) |
TS_SESSION_INDEX_TYPES |
只注入哪些类型,如 guardrail,warning,decision |
TS_SESSION_INDEX_RECENT_DAYS |
最近 N 天的观察优先 |
TS_MEMORY_DISABLE=1 |
完全关闭记忆引擎 |
也就是说,新会话里你问"上次那个连接池泄漏最后怎么修的",模型手里已经拿着上次留下的 error_pattern 观察——跨会话的 Bug 修复记忆就是这么闭环的。
🚀 快速上手清单
pip install "token-savior-recall[mcp,memory-vector]"安装(带向量检索)- 在 MCP 配置中指向
token-savior,建议TOKEN_SAVIOR_PROFILE=optimized - (可选)设
TS_AUTO_EXTRACT=1+TS_API_KEY,开启 LLM 自动记忆抽取 - 正常使用即可——记忆积累是渐进的,项目用得越久,跨会话记忆越值钱
📚 延伸阅读
- 完整表结构(FTS5 表、触发器、衰减配置):src/token_savior/memory_schema.sql
- 混合检索与 RRF 融合:src/token_savior/memory/search.py
- 观察的保存与搜索入口:src/token_savior/memory/observations.py
- 会话注入钩子:hooks/memory-session-start.sh
- 项目说明与基准数据:README.md
Token Savior 的持久记忆引擎证明了:让 AI"记住"不需要昂贵的向量数据库——SQLite 的 FTS5 + sqlite-vec + RRF 融合,一个单机 MCP 服务器就足以实现跨会话的工程记忆。