MetaBrain 实战指南：给 AI Agent 一个本地文档记忆库

AI Agent 的工作流里，有一个被反复提及但很少被认真解决的问题：Agent 的状态散落在哪里？

Claude Code 写了 .claude/transcripts/，Codex CLI 有自己的 .codex/，你自己的 .md 笔记、.json 配置、脚本片段各安其位。当 Agent 需要”记得”之前做的事或结构化地存储知识碎片时，这些松散文件既不好搜索，也不好版本管理。

MetaBrain 正是为解决这个问题而来——一个开源的本地文档记忆库，让 AI Agent（以及开发者本人）拥有一个统一、可搜索、版本化的本地记忆空间。

安装与环境

MetaBrain 用 Swift 写成，跨平台支持 macOS、Linux 和 Windows。

macOS：

brew tap OpenCow42/tap && brew install mb

Ubuntu 24.04：

echo 'deb [trusted=yes] https://opencow42.github.io/apt-repo ubuntu24.04 main' | sudo tee /etc/apt/sources.list.d/opencow.list
sudo apt update && sudo apt install metabrain

安装后得到两个命令：mb（CLI 工具）和 mbd（本地守护进程）。运行 mb version 确认安装成功。

实战场景 1：用 CLI 快速建立 Agent 记忆

MetaBrain 的核心模型很简单：每个工作区一个 .metabrain/store.leveldb 仓库，用类文件系统路径组织文档。

初始化仓库：

cd my-project
mb init

这条命令创建 .metabrain/ 目录。之后所有 mb 命令自动使用该仓库。

写入一条记忆：

mb put /notes/today "今天发现 MetaBrain 可以用作 Agent 的长时记忆存储。支持搜索和版本管理。" --tag research --meta source=agent

--tag 和 --meta 为文档附加结构化元数据，后续搜索和过滤时非常有用。

列出所有笔记：

mb list /notes --recursive --dates

搜索内容：

mb search "长时记忆" --tag research

搜索基于词频覆盖和邻近度排序，支持按标签、元数据和路径前缀过滤。

这个基础流程对应一个经典场景：Agent 执行任务时记录中间结论，下次会话中快速检索。不再需要翻几十个 .md 文件。

实战场景 2：Agent 持久化任务上下文

MetaBrain 真正的价值在于让 Agent 把记忆当结构化数据来管理，而不仅是文本片段。

为任务创建结构化笔记：

mb put /tasks/refactor-auth \
  "重构认证模块：Clerk → Supabase Auth
  状态: 进行中
  依赖: user-service 的 JWT 签发接口
  风险: 需要处理 3 万存量用户的 token 刷新" \
  --tag task --meta status=active --meta priority=high

用补丁更新而不是整体替换——对 Agent 友好：

当 Agent 只想修改文档中的某一部分，而不是重写整个文档时，patch 命令派上用场。先生成 unified diff，再应用：

mb patch /tasks/refactor-auth --patch-file change.diff

--check 参数可以只做 dry-run：

mb patch /tasks/refactor-auth --patch-file change.diff --check

查看版本历史：

mb versions /tasks/refactor-auth

保留最近 5 个版本，清理老纪录：

mb prune /tasks/refactor-auth --keep-last 5

这意味着 Agent 修改任务上下文时，每一次修改都留下快照。如果一个步骤出错，可以随时回溯到上个版本，而不用依赖 Git commit 的”脏工作区”。

导出子树为本地文件：

mb dump /tasks --output-dir ./tasks-backup

导出的文件按路径扩展名保存（.json、.md），方便人工阅读和备份。Agent 也可以在导出后处理这些文件。

实战场景 3：用守护进程让多个 Agent 共享记忆

单 CLI 模式对”一个 Agent 一个终端”的场景够用。但真实工作中，你可能同时开着 Claude Code、Codex CLI 和本地脚本——它们都需要读写同一个记忆库。

这时启动 mbd 守护进程：

mbd serve --store .metabrain/store.leveldb

默认监听 http://127.0.0.1:6374（”META” 在 leetspeak 里的数字）。所有 mb 命令会自动探测该端口，如果检测到 daemon，自动转为 daemon-backed 请求，无需修改命令行：

mb put /notes/shared "所有 Agent 都能读到这条笔记" --tag shared
mb search "共享记忆"

如果要强制走 daemon 或指定不同的 daemon 端点：

mb --server http://127.0.0.1:6374 search "共享记忆"
mb --server ~/.metabrain/mbd.sock search "socket 模式"

多仓库共存：一个 daemon 可以同时服务多个 store 路径。每个 store 由独立的 LevelDB actor 管理，互不阻塞：

mbd serve --store project-a/.metabrain/store.leveldb --socket ~/.metabrain/mbd.sock

mb --store project-b/.metabrain/store.leveldb put /notes/sprint "Sprint 计划"

Idle store 在 30 秒后自动释放 LevelDB 锁，不会长期占用手柄。

最佳实践

1. 按路径组织代替散落文件

用 /notes/、/tasks/、/research/ 等顶层分类，再按项目或日期细分。Agent 通过 mb tree --max-depth 2 可以快速了解记忆库的整体结构。

2. Agent 脚本中嵌入 mb put

在 Agent 的工作流脚本里，在关键决策点加入 mb put 记录。例如代码修改完成后自动记录变更摘要：

mb put /research/analysis-$(date +%Y%m%d) --body-file analysis.md --tag research

3. 用 --no-server 跳过 daemon 探测

在一次性脚本或 CI 中，直接读写 LevelDB 更快速。daemon 模式适用于常驻后台的 Agent 或多人协作场景。

4. 定期 prune 保留关键版本

版本历史默认无限保留。建议建立定期任务，对 /notes/ 等非关键路径 prune 到保留最近 5 个版本，对 /tasks/ 等关键路径保留更多。

5. 稳定 ID 优于路径引用

文档的 stable document ID 在 move 操作后仍然不变。如果需要跨文档引用，优先使用 --ref-id 而非硬编码路径。

总结

MetaBrain 填补了一个被多数 AI 工具忽略的空白：Agent 需要什么样的本地记忆管理系统？是结构化、可搜索、版本化、daemon 可共享的——而不是散落地上的 .md 文件。

它不试图取代 Git、向量数据库或 Notion。它的定位更底层：一个 CLI + daemon 级别的本地持久化层，让 Agent 在写入笔记、维护任务上下文、跨会话查询时，有一个一致、可靠的接口。

GitHub: github.com/OpenCow42/metaBrain 官网: metabrain.eu 许可: BSD 3-Clause