Mindtrail

---

每个新的 Agent 会话都从零开始。你要再次说明自己的约定，重申偏好，还要重新描述上周做出的决定。Mindtrail 通过 Model Context Protocol 为你的 Agent 提供共享的长期记忆，让某个会话学到的内容，之后的每个会话（无论使用什么工具）都能回忆起来。

• 🔌 兼容任何 MCP 客户端。 Claude Code、Claude Desktop、Cursor、 VS Code、Codex 和你自己的 Agent 共享同一份记忆。
• 🏠 本地优先，保护隐私。 你的设备上只有一个 SQLite 文件。无需账户、API 密钥，也不收集遥测数据。
• ⚡ 一条命令即可安装。 已发布到 PyPI 和 官方 MCP Registry；使用 uv 时无需预先安装任何内容。
• 🗂️ 自动限定范围。 仓库信息保留在所属仓库中（通过 git 远程地址检测）， 个人偏好则会伴随你随处可用。
• 🔎 混合检索。 结合关键词（BM25）和向量搜索，融合并排序结果，同时显示每项结果的排序信号。
• 🛡️ 默认安全。 拒绝存储凭据，将回忆出的记忆标记为不可信数据，并彻底删除数据。

它真的有用吗？

我们使用真实的 Claude Code 会话进行了测试。在一个会话中，用户随口提到一项项目信息（“顺便说一下，这个项目用 pnpm。”）。之后，一个全新的会话接到一项依赖此信息的任务（“如何添加 lodash？”）。整个过程中，Agent 从未被告知要使用 Mindtrail。

	自行存储了该信息	在后续会话中应用了该信息
不使用 Mindtrail 的 Claude Code	–	0/12
使用 mindtrail[semantic] 的 Claude Code	36/36	36/36

没有记忆时，Agent 每次都会凭习惯回答：npm install lodash、格式错误的提交消息、使用 5432 而非你的 5433 端口。使用 Mindtrail 后，它会先检查记忆，再给出适用于你项目的答案。这只是一个小规模测试（12 条信息各运行三次、一个模型、一个空仓库），并不代表 Agent 在大型代码库中的任务成功率。 测试方法、原始结果和复现步骤。

安装

Mindtrail 需要 Python 3.11 或更高版本。最快的方式是使用 uv：uvx 会按需下载并运行 Mindtrail，因此你只需将其添加到客户端。服务首次启动时，会在后台下载嵌入模型（约 210 MB）。

Claude Code

claude mcp add mindtrail --scope user -- uvx --from "mindtrail[semantic]" mindtrail serve

--scope user 会让 Mindtrail 在每个项目中都可用。使用 claude mcp list 检查是否已配置。

Cursor 和 VS Code

Claude Desktop、Windsurf 和其他使用 JSON 配置的客户端

将以下内容添加到客户端的 MCP 配置中（在 Claude Desktop 中：Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "mindtrail": {
      "command": "uvx",
      "args": ["--from", "mindtrail[semantic]", "mindtrail", "serve"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.mindtrail]
command = "uvx"
args = ["--from", "mindtrail[semantic]", "mindtrail", "serve"]

不使用 uv

使用 pipx（或 pip）安装一次 CLI，然后将客户端指向 mindtrail serve：

pipx install "mindtrail[semantic]"
mindtrail init                                             # downloads the model now and prints client configs
claude mcp add mindtrail --scope user -- mindtrail serve   # Claude Code

想要尽可能精简地安装？去掉 [semantic]：这样 Mindtrail 就不需要下载模型，而是按词而非含义进行匹配（参见提升语义召回效果）。 更多客户端和故障排除信息请参阅 docs/integrations.md。

试用

Session 1 › FYI, this project uses conventional commits and squash merges.
Session 2 › Write a commit message for these changes.
            → the agent recalls the convention and writes "feat(api): add pagination to /orders"

升级

uvx 会自动获取新版本（运行 uvx --refresh ... 可强制检查）。使用 pipx 时，运行 pipx upgrade mindtrail。你的记忆存储在 ~/.mindtrail 中，升级后会保留。 如需了解变更内容，请参阅更新日志。

日常使用

你不需要使用特殊命令。照常工作，由 Agent 决定要保留哪些内容：

• 提及一次即可。“我们从 release 分支部署”、“相比 unittest，我更喜欢 pytest”、“那个不稳定的测试是时区问题，通过固定 TZ=UTC 修复了”。Agent 会自动存储这类事实。想确保内容被记住时，可以说“记住……”。
• **区分项目与个人信息。**关于仓库的事实会保存到项目空间，同一 git 远程仓库的所有克隆共享该空间。关于你自己的事实（“我喜欢简短的回答”）会保存到个人空间，并适用于所有项目。
• **内容会变化。**说“我们从 npm 改用 pnpm”，Agent 就会替换旧记忆，而不是将新旧内容都保留。旧记忆会作为历史记录保留，但不再被召回。
• 询问它记得什么。“你记得这个项目的哪些内容？”或者在终端中运行 mindtrail list 和 mindtrail recall "<question>"。
• **忘记任何内容。**在聊天中说“忘记暂存环境 URL”，或者运行 mindtrail forget <id>。删除后无法恢复。
• **自由切换工具。**将 Claude Code、Cursor 和 Codex 指向同一个 Mindtrail 后，它们会共享同一份记忆，因此在一个工具中教会它的约定，在其他工具中也能使用。

值得存储的内容包括：约定、命令、负责人、配置文件的位置、决策及其原因，以及棘手错误的根本原因。代码或 git 历史中已有的内容就不必存了。系统会自动拒绝保存机密信息。

工作原理

Agent 会获得三个工具，而 Mindtrail 的服务说明会告诉它何时使用这些工具：

工具	功能
remember	在项目或个人空间中存储一条事实、偏好、决策或事件。传入 replaces 可取代过时的记忆。
recall	从当前项目和个人空间中查找相关记忆。如果没有相关内容，则不返回任何结果。
forget	永久删除一条记忆。

设置 MINDTRAIL_TOOLS=full 可启用另外四个工具：search_memory（按空间、类型和有效性筛选）， get_context（在 token 预算内生成可直接用于提示词的内容块），update_memory（编辑记忆并保留版本历史）以及 get_memory。

这些工具背后是一个经过充分测试的小型引擎，支持重复项合并、记忆取代、有效期、版本历史和混合排序。请参阅 docs/architecture.md。

从终端管理记忆

mindtrail recall "how do we deploy?"   # search project + personal memory
mindtrail remember "Staging is at staging.example.com" --scope project
mindtrail list                         # newest first
mindtrail forget <id>                  # permanent delete
mindtrail export -o memories.jsonl     # everything you've stored, as JSON Lines
mindtrail doctor                       # diagnose the install

更好的语义回忆

默认嵌入器会匹配词语和词语片段。若要按含义回忆（“我们如何部署？” → “部署通过 GitHub Actions 进行”），请安装本地神经模型。它在 CPU 上运行，且无需 API 密钥：

pipx install "mindtrail[semantic]"   # or use the uvx config above
mindtrail init        # downloads the model once (~210 MB) and re-indexes existing memories

如需下载更小的模型（67 MB，回忆效果略低），请设置 MINDTRAIL_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5。使用其他模型存储的记忆会在下次启动服务时自动重新嵌入。

检索基准测试

Agent 测试见它真的有帮助吗？。我们使用两组留出的开发者记忆问题集（共 82 个）进行测试，这些问题从未用于调优（方法）：

	recall@1	recall@5	同义改写 recall@5	正确回答“未存储任何内容”	过时/外部信息泄露
默认安装	58–64%	68–75%	44–46%	82–100%	0%
mindtrail[semantic]	82–90%	93–94%	85–89%	100%	0%

这是我们编写的小型合成检索基准测试。运行 mindtrail bench 即可复现，也可以添加自己的数据集。

在 Python 中使用

from mindtrail import MemoryService

memory = MemoryService.from_config()
memory.remember("The API uses FastAPI and PostgreSQL", space_id="project:shop")
print(memory.get_context("add a new endpoint", space_ids=["project:shop"]).text)

隐私与安全

所有数据都保存在你本机的 ~/.mindtrail/mindtrail.db 中。Mindtrail 会拒绝写入看起来像 API 密钥、令牌或私钥的内容。forget 会在磁盘上覆写已删除的数据，并将回忆出的记忆标记为不可信参考数据，避免 Agent 遵循其中存储的指令。 如需报告问题，请参阅 SECURITY.md。

路线图

• 核心引擎：混合检索、去重、取代机制、有效期窗口、历史记录
• MCP 服务和 CLI，支持自动按项目划分范围
• CI 中的检索基准测试套件（recall@k、MRR、弃答率、泄露率）
• 已发布到 PyPI 和官方 MCP Registry（v0.1.0）
• PostgreSQL + pgvector 后端，支持多租户隔离
• 托管远程 MCP，支持一键式 OAuth 连接器
• Web 记忆查看器（浏览、编辑、删除、导出）
• 实体图谱、矛盾检测和记忆整合

参与贡献

欢迎提交问题和 PR。请阅读 CONTRIBUTING.md 了解如何开始；整个套件约需 15 秒即可运行完毕。如果 Mindtrail 让你不必再反复解释代码库，请给个 ⭐，帮助其他人发现它。

许可证

MIT