MCP

FAVA Trails：给 AI agent 的 Git 原生共享记忆（MCP）

如果你想让多个 AI agent 共享一份可版本化、可追溯的记忆，FAVA Trails 值得一试：它把 agent 的想法以带 YAML frontmatter 的 Markdown 写进你自己的 Git 数据仓库，草稿经 `propose_truth` 晋级后对所有 agent 可见；但晋级必须配置 OpenRouter API key（Trust Gate 的 LLM 评估经 OpenRouter 调用），且存储引擎 Jujutsu（JJ）与 Git 并行运行，请把维护数据仓库当作使用前提。

官方来源 · MachineWisdomAI/fava-trails

安装

pip install fava-trails

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

适合谁

FAVA Trails（Federated Agents Versioned Audit Trail）是一套通过 MCP 暴露给 AI agent 的 Git 原生记忆系统：agent 产生的想法、决策与观察，会以带 YAML frontmatter 的 Markdown 文件写进一个由你自己控制的 Git 数据仓库，而不是托管在他人服务器上的黑盒。它把“草稿”与“对所有 agent 可见的观察”分成两级，中间设有一道晋级门槛；agent 平时只看到记忆工具本身，不直接接触版本控制命令，版本化细节由引擎在仓库里处理，全部历史都留在提交记录中可回看。

  • 适合：需要让多个 agent 共享并沉淀工作记忆的团队或个人，例如把工程排查结论、跨会话的决策上下文存成可复用的观察；希望记忆可版本化、可追溯、随时能直接查看文件的用户；已经用 Git 管理资产、不介意多维护一个数据仓库的人。
  • 使用前提：本机可用 pip 安装；配置时要给出数据仓库路径 FAVA_TRAILS_DATA_REPO；想让草稿晋级为对所有 agent 可见的观察，必须配置 OpenRouter API key。
  • 需要斟酌：不想维护数据仓库、或不想申请 OpenRouter key 的用户要慎重——跨 agent 共享记忆这条核心链路同时依赖两者。
  • 未知：证据未说明支持哪些具体 MCP 客户端、操作系统与 Python 版本要求，也未说明存储引擎 Jujutsu（JJ）是否需要单独安装。

3 分钟完成第一次尝试

推荐主路径只有一条：从 PyPI 安装引擎，再把它注册进 MCP 客户端的服务器配置。前提有两条：先确定要用作数据仓库的位置，配置里的 FAVA_TRAILS_DATA_REPO 会指向它；要走到晋级那一步，还需要一个 OpenRouter API key。

第一步，安装这个 Apache-2.0 许可的无状态 MCP 服务器：

pip install fava-trails

第二步，在客户端配置中加入官方注册片段，把其中的仓库路径换成你的实际位置：

"fava-trails": {
  "command": "fava-trails-server",
  "env": {
    "FAVA_TRAILS_DATA_REPO": "/path/to/fava-trails-data",
    "OPENROUTER_API_KEY": "sk-or-v1-..."
  }
}

第三步，让 agent 调用一次写入范围最小的能力：用 save_thought 把一条观察写成草稿。

save_thought(trail_name="myorg/eng/my-project", content="My finding about X", source_type="observation")

成功信号：数据仓库的 drafts/ 目录下出现这条草稿。要分清操作性质：这一步是本地写入，文件落进你自己的仓库，不是只读查询；官方未提供删除或撤销草稿的说明，第一次尝试请写无害内容。引擎侧会以 Jujutsu（JJ）作为存储引擎、与 Git 以 colocate 模式并行，仓库仍是标准 Git 仓库，你在这一步不需要碰任何版本控制命令。另外注意 OpenRouter API key 的边界：它在这份官方配置模板里已经出现，官方表格进一步说明它对 propose_truth 必需，用于 Trust Gate 的 LLM 评估，经 OpenRouter 调用；首次尝试停在草稿这一步即可，不必顺手晋级。

使用案例

案例一：把一次排查的结论沉淀成项目记忆。场景：agent 刚完成排查，结论值得留给后续会话复用。做法：调用 save_thought，参数为 trail_name、content 与 source_type，可直接使用上面的官方示例调用。可期待的结果：drafts/ 目录生成草稿文件，内容只落在你的仓库里，其他 agent 尚看不到，不会影响别人；草稿是普通文件，可直接在仓库中打开查看。

案例二：把已确认的草稿晋级为共享观察，再检索验证。场景：某条观察已核实，希望之后所有 agent 都能查到。做法：先确认 OpenRouter API key 有效，调用 propose_truth(trail_name="myorg/eng/my-project", thought_id=thought_id) 把草稿晋级到 observations/，随后用 recall(trail_name="myorg/eng/my-project", query="X") 检索。可期待的结果：recall 能找到这条已晋级的想法，接入同一数据仓库的其他 agent 也能用同样的查询找到它。确认点：晋级结果对所有 agent 可见，官方未提供撤销说明，执行前确认内容适合共享；把变更推送到远端是另一个独立动作，需另行调用 sync 工具或 jj git push。

使用边界

  • 读写性质：save_thought 在数据仓库创建草稿，propose_truth 把草稿晋级到 observations/ 并对所有 agent 可见，两者都是写入；recall 负责查找已晋级的想法。写入发生在你自己的仓库里，晋级本身先落在本地；推送到远端必须另行经 sync MCP 工具或 jj git push 完成，是否同步由你决定。官方未提供撤销或删除路径，不要把写入当成可随时回退的操作。
  • 凭证与配置：FAVA_TRAILS_DATA_REPO 指定数据仓库位置，OPENROUTER_API_KEY 供晋级时的 LLM 评估使用，两者都写在官方配置模板的 env 段里；官方明确后者对 propose_truth 必需。没有这个 key 时 save_thought 与 recall 能否工作，证据未说明。
  • 运行时与数据存放：存储引擎为 Jujutsu（JJ），与 Git 以 colocate 模式并行；仓库仍是标准 Git 仓库，GitHub 与 CI/CD 看到的是正常提交。所有内容以带 YAML frontmatter 的 Markdown 文件存放在你控制的仓库中。
  • 未确认项：容量配额、多仓库规模上限、隐私与数据驻留细节，证据均未提及；Trust Gate 评估的判定标准与失败时的处理方式，同样未说明；是否需要自行安装 jj、支持哪些客户端与 Python 版本也未说明。不要把“未见到说明”当成没有风险，写入内容请按“会长期留在你的仓库”来评估。