Vestige enhances agents by deterministic root-cause retrieval that reaches backward through time to find the quiet change, decision, or service that caused today’s failure, not the lookalike.

Vestige – 面向 AI 辅助开发者的本地优先记忆系统

是什么 – Vestige 是一个开源、本地运行的记忆层，允许大型语言模型（LLM）编码代理（Claude Code、Claude Desktop、Codex、Cursor 等）存储和检索关于代码库的“记忆”。它在你工作时记录决策、配置选择和其他上下文事实，之后在发生故障时，通过因果-时间链接而非简单的相似性搜索，返回最相关的部分。

核心理念（来自 README）

概念	Vestige 的实现方式
预测误差门控	仅记录新事实；重复事实被合并，矛盾事实被标记。
回溯性显著性回填	当报告一个错误时，Vestige 会反向遍历记忆图，提升导致失败的早期事实的显著性。
间隔重复衰减（FSRS-6）	未使用的记忆逐渐降低权重，保持存储紧凑。
双强度存储	分离“存储强度”（事实被牢固保留的程度）和“检索强度”（被轻易找到的程度）。
离线运行	一次性下载 130MB 嵌入模型和约 150MB 重排序模型后，所有操作均在本地完成，无需网络调用。

主要用户可见功能

自动写回：任何兼容 MCP 的代理均可调用 smart_ingest 存储一个事实；Vestige 决定其是否为新事实、合并重复项或标记矛盾。
聚焦召回：recall 返回与当前代码上下文存在因果关联的记忆，而不仅仅是文本相似。
回填：vestige backfill --contrast 从一个失败开始，回溯并展示最可能引发该失败的最早记忆，同时提供一个收据，展示证据路径。
仪表板：一个 WebGPU 可视化工具（vestige dashboard）可实时显示记忆图（1000+ 节点，60fps），并可导出短视频或“脑图”（不暴露实际数据，仅表示图结构）。
项目投影：持久性决策可导出为 Markdown 规则文件（如 CLAUDE.md），供代理在后续会话中尊重。
Pro 版本（可选，每月 19 美元）：使用 XChaCha20-Poly1305 和 Argon2id 实现加密、跨设备连续性；免费版完全离线且无限制。

安装与快速入门（如说明）

使用 Node 全局安装 MCP 服务器：

npm install -g vestige-mcp-server@latest

将服务器添加到代理的 MCP 配置中（README 中提供 JSON 示例）。README 列出了 Claude Code、Codex、Cursor、Claude Desktop 等的精确命令。
运行 vestige dashboard 并打开 http://localhost:3927/dashboard。
首次运行时，二进制文件会下载嵌入器和重排序器；之后工具完全离线运行。

与普通 RAG 的区别

RAG（向量相似性）	Vestige
检索与查询文本相似的项目。	检索通过因果+时间关系链接的项目，再用相似性重新排序。
无矛盾概念；重复项不断累积。	检测矛盾，合并重复项，淡化未使用记忆。
数据通常存储在云服务中。	所有数据均保留在开发者的机器上（SQLite，可选 SQLCipher 加密）。
无法定位与症状看似无关的错误的根本原因。	`backfill` 可追溯到设置失败的决策，提供带证据路径的候选原因。

基准测试与证据（报告内容）

静默旋转基准测试 – 使用 246 个代理会话，比较三种设置：无记忆、密集余弦 RAG、Vestige。
结果（每种设置 23 次试验）显示，Vestige 在 23 次中 20 次收敛到正确修复，零次错误收敛；而 RAG 仅在 4/23 次正确收敛，且 12/23 次产生错误修复。
基准测试可通过提供的 Python 脚本在数秒内复现（参见 benchmark/silent-rotation）。

技术栈（来自“内部机制”表）

引擎：Rust（约 145k LOC），编译为单个约 25MB 二进制文件，超过 2000 个测试，clippy 清理。
检索：Nomic Embed v1.5（Matryoshka 768→256），USearch HNSW 索引，SQLite FTS5；可选 Qwen-3 重排序器。
存储：SQLite（加密可选 SQLCipher）。
嵌入模型：下载一次后永久离线使用。

谁会受益？

使用 LLM 编码助手并反复遭遇“代理遗忘”问题的开发者。
需要 AI 代理决策审计追踪的团队（收据提供可复现的证据）。
要求严格数据隐私的用户（所有处理均在设备上完成，无需 API 密钥）。

限制与待解决问题（已承认）

系统依赖底层嵌入器和可选重排序器的质量；若这些模型表现差，相似性排名仍可能遗漏相关事实。
“回填”机制的有效性取决于已记录的因果链接；遗漏关键决策则无法后续检索。
只有 Pro 版本支持跨设备同步记忆；免费版仅限单设备使用。
基准测试由作者提供；更广泛信任需独立复现。

许可证

AGPL-3.0（完整源码可用；商业使用必须遵守 copyleft 条款）。

总结 – Vestige 是一个真正基于研究的工具，为 LLM 编码代理添加了因果性、本地记忆图，旨在通过记住“为何做出该决定”并在故障发生时呈现该上下文，消除重复错误。

samvallad33/vestige