Token Savior持久记忆引擎揭秘:FTS5加向量嵌入如何让AI跨会话记住每次Bug修复

原创2026-10-13 23:31:091,678 阅读

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 就能跑。

设计上有两个值得称道的细节:

  1. 优雅降级:没装向量组件、或模型加载失败时,搜索自动退回纯 FTS 模式,行为与旧版完全一致
  2. 距离地板(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 修复记忆就是这么闭环的。

🚀 快速上手清单

  1. pip install "token-savior-recall[mcp,memory-vector]" 安装(带向量检索)
  2. 在 MCP 配置中指向 token-savior,建议 TOKEN_SAVIOR_PROFILE=optimized
  3. (可选)设 TS_AUTO_EXTRACT=1 + TS_API_KEY,开启 LLM 自动记忆抽取
  4. 正常使用即可——记忆积累是渐进的,项目用得越久,跨会话记忆越值钱

📚 延伸阅读

Token Savior 的持久记忆引擎证明了:让 AI"记住"不需要昂贵的向量数据库——SQLite 的 FTS5 + sqlite-vec + RRF 融合,一个单机 MCP 服务器就足以实现跨会话的工程记忆。

登录后查看全文
token-savior