agent-context-substrate

基座是资产；模型是可替换的客户端。

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

要求：Python 3.12+、Docker、make。make setup 会创建 venv 并安装依赖，约 1.4 GB，因为演示在 CPU 上运行并跳过 CUDA wheels；网络较慢时请留出几分钟。数据库绑定 127.0.0.1:5432，因此请先停止占用该端口的任何程序。

为什么存在

我用 AI 智能体构建长期项目，而每次会话开始时重新建立上下文是我付出最频繁的代价。上传同样的文件，重新解释同样的决策，看着窗口中有用的部分被模型已经看过两遍的材料填满。更好的模型发布了，但其中没有任何东西能迁移过去。问题从来不是上下文缺失。问题是上下文不可寻址：无法提出一个问题并只取回回答它的内容，所以你只能发送一切并寄希望于运气。解决办法是停止把上下文当作你带进会话的东西，开始把它当作你查询的东西。

一个模型无关的记忆基座（memory substrate）的参考实现，用于 AI 智能体：项目记忆存在于模型之外，存储在一个可查询、带版本管理的存储中，通过一个 MCP 网关暴露。换模型；保留一切。今天用 Claude，明天用 Gemini 或 GPT，底层是同一个项目记忆。不再把历史粘贴回每个会话，而是由检索选择当前任务实际需要的少量记录。

这个仓库是该模式的洁净室参考实现，针对合成语料从零编写，因此本页上的每个数字都能从干净的克隆加上固定依赖复现。它是模式本身，不是我在自己工作中运行的系统。

无需 API 密钥：make demo 完全在本地组件上运行。固定的本地模型（名称和修订版本）是默认适配器配置 local（make warmup，由 make demo 自动运行，预下载约 180 MB 一次）；无下载的封闭式 deterministic 配置支撑测试和常开的 CI 门禁。

Related MCP server: AI Memory MCP Server

布局

src/acs/adapters/base.py 是代码中的核心论点：每个外部能力都位于其后的四个小接口。src/acs/store/ 将记忆视为记录系统（带版本、可审计、真正可删除）。src/acs/retrieval/ 是作为小型、可独立测试的阶段组成的流水线。eval/ 是门禁：变更只有匹配或超越 baseline.lock.json 才能发布，否则不能发布。

设计理由见 docs/adr/：九条决策记录。大多数只有半页；三条较长，因为论证需要更多篇幅。

docs/ 中还有：architecture.md 说明每一层为何存在，threat-model.md 说明对抗边界及每道防线所在，principles.md 说明其余部分遵循的规则，以及 build-your-own.md 说明本仓库遵循的构建顺序。

它展示了什么

• 摄取 一次写入两种表示：用于相似度的嵌入，以及用于结构的实体/关系图。每份文档都被嵌入；未陈述任何关系的文档不贡献边。

• 检索 是四阶段流水线：带可调混合权重的混合向量 + 全文搜索、多查询融合（RRF）、交叉编码器重排，以及实体锚定分区——图对重排后的列表重新排序，使主题重排器不再把一个组件与其名称相似的兄弟混淆。每个消费者的检索配置是数据，不是代码。

• 治理：检索变更通过匹配或超越锁定的评估基线才能发布。记忆采用 SCD2 版本管理，支持时间旅行读取；清除是真正的删除（包括向量）；审计日志在数据库层面拒绝修改。

• 访问：一个 MCP 网关将基座提供给任何 MCP 客户端，并按调用方限定范围。一个隔离的研究循环以强制引用回写的方式填补空白。

• 可移植性：每个提供者都位于适配器之后；嵌入器是有意固定的。

谱系 ID 和时间戳都来自 make history：不带参数时列出当前记忆及其 ID；带 LINEAGE=<id> 时遍历一条记忆的版本链并打印每个版本的有效期窗口。这些窗口是 ISO 时间戳，因此你粘贴回去的 TS= 会解析到你实际读取的版本，而不是它前后一秒的版本。ID 按克隆生成，因此你的 ID 不会与本页显示的匹配。

make purge 是真正的删除（包括属于被清除主体的黄金集目标），因此针对已清除语料的基准会以 incomplete 拒绝运行，而不是悄悄报告更低的召回率。make demo 重置为干净语料。

本页上的每个基准数字都来自对种子合成语料（corpus/generate.py）的消融，可从干净克隆复现，并在 CI 中（每次推送使用 deterministic 配置，bench-local 标签使用 local 配置）针对同时锁定语料摘要的锁定基线进行门禁。 读增量，不要读绝对值：合成语料上的 recall@5 / mrr@5 展示每个阶段贡献了什么，绝不代表真实世界质量。要看某个阶段在哪里赢得其增量，运行 .venv/bin/python eval/run_benchmark.py --by-family。

消融，local 配置

每个阶段赢得的是不同的东西，这正是支持流水线而非单个更好检索器的论据。tests/test_readme_table.py 会在本表与 eval/baseline.lock.json 不一致时失败，因此本表不可能偏离门禁所强制执行的数字。门禁是下限，因此改进指标的变化会通过，本页数字保持不变，直到基线被有意地用 make lock-baseline 重新锁定——这会使本表失败，直到它被更新以匹配。local 配置，120 条黄金查询，k=5，阶段 1 合并 rank，语料摘要 ad7bf7ca。用 make demo 复现。

这些数字支持和不支持什么，包括为什么模型通道比较是界限而非曲线，在 docs/limitations.md 中有详细说明。