Engram

Engram

AI Agent 可读写的第二大脑。

_{▶ 观看完整视频（实时录制，完整画质）}

↗ 试用在线演示 — 无需注册。搜索 retainer price，看看已停用的笔记如何被隐藏。

---

Engram 是一个可自托管的 MCP 服务 + 仪表盘，为 Claude Code、Cursor、Hermes 以及任何 Model Context Protocol Agent 提供共享的长期记忆，供它们读 写——内容存放在由你掌控的纯文本 Git 管理文件夹中。它专为单个 Agent 的记忆无法满足的场景打造：一个团队让多个 Agent 共用同一个大脑。

自主 Agent 在不同会话之间会忘记一切——更糟的是，它们无法判断自己记住的内容_是否仍然有效_。Agent 找到旧 README、已停用的价格，或几个月前已更改的 API 文档，并信心十足地引用，因为关键词搜索和向量搜索都按相似度排序，而非真实性。Engram 将 “这是否仍然有效” 作为一项可明确记录的属性：将事实标记为已被取代或已过期，搜索就会**将其隐藏，并告知 Agent 跳过了哪些内容以及原因。**每个 Agent 都有独立的读写令牌，Git 审计记录也会追踪内容由谁写入，让多 Agent 协作时一切井然有序。

与无界面的记忆存储不同，你可以亲眼看到整个过程。借助快速响应的仪表盘，你可以搜索自己的大脑、准确查看每个 Agent 和队友的修改内容（并查看每个文件的 diff）、跳回近期笔记，并整理所有内容——与此同时，Agent 通过同一个 MCP 端点读写同一个知识库。无需数据库：.md 文件是事实来源，Git 是持久化存储，而内存索引则为全文搜索和维基链接知识图谱提供支持。

对_如何_存储记忆有明确主张——由 Git 管理的 Markdown、无需数据库、Agent 可以写入（而不只是读取）、可自托管。对_存储什么_则不设限制——任何 Markdown 知识库、任何文件夹结构、任何 MCP 客户端。将它指向全新的仓库，或你现有的 Obsidian 知识库：无需导入，也不会被锁定。

---

用途 · 对比 · 功能 · 兼容对象 · 快速开始 · MCP 工具 · 部署 · 常见问题 · 参与贡献

---

用途

• 供多个 Agent 协作使用的团队共享记忆 — 一个知识库，多个 Agent 可同时读取和写入，并为每个 Agent 配备读写令牌，同时通过 git 审计轨迹记录谁更改了什么。
• 能识别哪些信息仍然有效的记忆 — 将价格、术语或已变更的 API 文档标记为过时后，Agent 就不会再引用它们；系统还会告知它们跳过了什么以及原因。这是单个 Agent 的记忆永远无法解决的问题。
• 面向 Claude Code 和其他编码 Agent 的长期记忆 — 不必每次会话都重新解释你的项目。
• 可自托管、兼容 Obsidian 的第二大脑，通过 MCP 提供服务 — 你的笔记、你的服务、你的 git 仓库。
• 看得见的记忆，而非黑箱 — 提供仪表板，可搜索、查看（含差异）和整理 Agent 的记忆。
• 无需向量数据库的 Markdown RAG — 对易读文件进行全文搜索，并提供链接图谱。

对比

大多数 Agent 记忆的设计目标是回答 “我存了关于这件事的什么信息？” Engram 的设计目标则是回答 “关于这件事，哪些信息仍然有效？” — 这是另一个问题，也是 Agent 引用你几个月前就废弃的价格时会让人头疼的问题。

	Engram	向量存储记忆 （mem0、Zep、…）	Markdown 记忆 （Basic Memory、…）	对文档进行纯 RAG
存储	Markdown 文件，git 即数据库	向量数据库中的嵌入向量	Markdown 文件	向量数据库中的嵌入向量
排序	相关性 × 权威性	相似度	相关性	相似度
识别已废弃的事实	✅ superseded_by + valid_until，搜索时强制执行	—	—	—
说明为何不提供某些信息	✅ excluded[]，为每条笔记说明原因	—	—	—
原子化地废弃并替换	✅ brain_supersede，一次提交	—	—	—
拒绝相互矛盾的写入	✅ 写入时检查，而非读取时	—	—	不适用（只读）
审计轨迹	✅ git、逐次写入归属记录、逐文件差异	因产品而异	git，前提是你提交	—
按 Agent 控制访问权限	✅ 读／写令牌权限范围	因产品而异	—	—
人工操作界面	✅ 仪表板、搜索、差异、图谱	因产品而异	—	—
运行位置	你的设备、一个容器	多数为托管式 SaaS	你的设备	你的设备

关键在第三行。相似度搜索无法区分矛盾信息和重复信息 — 已废弃的价格与当前价格在文本上完全相同，因此已废弃的价格常常会因为内容更长、更详细而排在当前价格之前。读取时无法解决这个问题，所以 Engram 会在信息废弃时将其记录下来。

_{这组示例包含在 sample-vault/ 中。运行 bun dev，搜索 acme price， 并查看已废弃的笔记如何被排除以及排除原因。}

_{此处比较的是类别，而非针对具体产品逐项审查；据我所知，截至 2026 年 7 月，内容准确无误。如果这里对你维护的工具有所误述，请提交 PR — 我会修正。}

功能

• MCP 服务 — 通过一个使用持有者令牌进行身份验证的 HTTP 端点（POST /api/mcp，可流式传输的 HTTP JSON-RPC）提供 15 个 brain_* 工具。任何 MCP 客户端都可以连接到同一个 URL。按 Agent 划分的令牌权限范围：只读令牌甚至看不到写入工具。
• 人工操作仪表板 — 搜索优先的首页、文件树、支持 Obsidian 标注块、双向链接和反向链接的笔记查看器、带自动保存的预览／编辑／分屏编辑器、⌘K 搜索 + 页面内键盘导航、“继续上次操作”最近记录，以及力导向知识图谱。
• 感知权威性的搜索 — 排名识别的是相关性，而非真实性，因此，即使一条已被取代的笔记包含的查询词与当前笔记一样多，它的排名也不会因此更高。每条搜索结果都会附带根据笔记文件夹和 frontmatter 得出的权威性（authoritative → current → provisional → superseded → archived），让你的 Agent 引用锁定的文档，而不是已失效的文档。不会返回过时答案的 Markdown RAG。
• 时效性 + 可解释的排除原因 — 用 superseded_by 标记某条事实已被另一条笔记取代，或为它设置 valid_until 日期，搜索就会默认将其排除（即使它是locked）——然后向 Agent 返回 excluded 列表，其中每项都附有原因（"expired 2026-06-01"）。一个原子操作 brain_supersede 就能在单次提交中淘汰旧事实并链接新事实，避免新增和淘汰脱节。这就是只会记住的 Agent 与知道哪些仍然属实的 Agent 之间的区别。
• 写入时的矛盾防护 — 权威性排名解决的是读取问题；这些机制则阻止知识库一开始就接受矛盾内容。Engram 会拒绝在现有笔记已涵盖的主题上创建第二条有效笔记（例如 acme-pricing-2026.md 与 acme-pricing.md 并存的问题），并引导 Agent 改用 brain_supersede；拒绝覆盖调用者尚未读取的笔记；如果 status: 的值不在排名模型已知词汇中，则发出警告，避免拼写错误悄无声息地剥夺笔记的权威性。
• 审计跟踪 + 访问控制 — 每次写入都会在 git 中记录操作令牌或执行操作的人，并在活动流中提供可展开的逐文件差异。为 Agent 提供只读令牌，它就完全看不到写入工具；写入令牌则可以创建、编辑、移动和归档内容。
• Curator （可选） — Engram 内置的知识库Agent 框架。与笔记聊天（回答有依据，并附带双向链接引用）。也可以将粗略材料交给 brain_capture——例如会议笔记或语音转录——由一个Agent 循环搜索现有内容，然后归档、合并或存档，并返回所处理内容的清单。它会先读取再覆盖，绝不会删除内容。Opus / Sonnet / Haiku，由你提供密钥。
• 原生支持 Markdown — 纯 .md + YAML frontmatter + [[wikilinks]]。放入现有的 Obsidian 知识库即可使用。
• 由 Git 支持 — 可选自动提交并推送每项更改。完整历史记录，不受供应商锁定，数据保存在你自己的仓库中。
• 无需数据库 — 文件是事实来源；内存中的 MiniSearch 索引 + 移植的双向链接图谱为搜索和反向链接提供支持。无需预配任何资源。
• 多工作区 — 连接多个知识库仓库（URL + 令牌或 GitHub OAuth）、重命名、切换当前工作区或移除工作区——全部通过 UI 完成。
• 可自托管 — 一个 Docker 容器即可。可部署到 Railway / Render / Fly / 任何支持持久化卷的主机。不支持无服务器部署（需要持久化卷、文件监视器和长期运行的索引）。
• 团队身份验证 — 控制面板支持 Google SSO + 电子邮件允许列表；MCP 使用按 Agent 划分的持有者令牌，或用于 Claude.ai 自定义连接器的 OAuth，可在 UI 中创建／撤销。密钥采用静态加密。
• 运行时配置 — 可直接在首页启用或停用 git-sync 和 Curator；在设置中管理提交作者、密钥和 OAuth——无需重新部署。

兼容客户端

任何支持 Model Context Protocol 的客户端——一个端点，使用 bearer token 进行身份验证。按使用频率排序：

• Claude Code — Anthropic 的 Agent 式编码命令行工具
• Codex — OpenAI 的编码 Agent（CLI + IDE）
• Hermes — 始终在线的自主 Agent 运行时
• openclaw — 开源编码 Agent
• Cursor — AI 代码编辑器
• Cline — VS Code Agent
• Windsurf — Agent 式 IDE
• Claude Desktop — Anthropic 的桌面应用
• ……以及其他任何 MCP 客户端——Continue、Goose、Zed、Amp 等

只要支持 MCP，就可以将 Engram 作为共享记忆来读取和写入。

快速开始

想先试用一下？这里有一个在线演示——公开访问，无需注册，每天会重置几次。尽管随意折腾。

bun install
bun dev            # http://localhost:3000 — runs against ./sample-vault

将它指向你自己的知识库：

VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev

两种运行方式

• **托管模式（团队）：**上方的仪表板 + HTTP MCP 服务——只需自托管一次，多个 Agent 和团队成员便可通过 POST /api/mcp 连接。这是主要模式。

• **本地模式（stdio）：**通过文件夹运行的纯 stdio MCP 服务，无需 HTTP/身份验证/git——适用于单台机器、Claude Desktop / Cursor，或注册表的 Docker 检查：

  bun run mcp:stdio /path/to/your/vault      # defaults to ./sample-vault
  

  使用相同的 brain_* 工具。基于 Dockerfile.mcp 构建。

每种模式都有自己的镜像，二者不可互换：

镜像	模式	用途
ghcr.io/rwnalds/engram-app	HTTP — 仪表板 + /api/mcp	**Railway、Render、Fly 及任何主机。**要部署的就是这个镜像。
ghcr.io/rwnalds/engram	stdio — 通过 stdin/stdout 传输 JSON-RPC	Claude Desktop、Cursor、MCP 注册表。绝不会打开端口。

将 stdio 镜像部署为 Web 服务是唯一值得特别指出的错误：它只能返回 502，因为没有任何程序在监听。现在，它会拒绝在 PaaS 上启动，并改为提示你这一点。

MCP 工具

Agent 只能看到当前激活的知识库——不会暴露任何仓库、工作区或 GitHub 工具。 read 权限范围的令牌只能使用读取工具。只有 Curator 处于 full 模式时，才会显示 brain_capture。

	工具
读取	brain_search · brain_read · brain_list · brain_recent · brain_tree · brain_backlinks · brain_graph · brain_schema
写入（需要 write 权限范围的令牌）	brain_write · brain_edit · brain_append · brain_move · brain_supersede · brain_create_folder · brain_delete

连接 Agent（仪表板 → Connect 页面会显示准确的命令和令牌）：

claude mcp add --transport http engram https://<host>/api/mcp \
  --header "Authorization: Bearer <token>"

部署

可在任何能够运行带持久化卷的 Docker 容器的环境中运行——Railway、Render、Fly 或你自己的服务器。无服务器环境（Vercel）无法运行：Engram 需要持有一个卷、文件监视器和内存索引，而无服务器函数无法让它们持续运行。

1. 部署此仓库（根目录中的 Dockerfile），在 /data 挂载一个卷，并设置 ENGRAM_DATA_DIR=/data。
2. 在仪表板（Workspaces）中连接你的知识库仓库——通过 URL + 令牌，或 GitHub OAuth。
3. 使用 Google 登录，在 Connect 页面创建 MCP 令牌，然后将 Agent 指向该 URL。

大多数运行时配置（git-sync、AI 捕获、GitHub OAuth、应用名称）都可在 Settings 页面中编辑——只有身份验证/基础设施引导变量需要在主机上设置。完整设置指南：DEPLOY.md。

• **Railway：**新建项目 → Deploy from GitHub repo → 在 /data 添加卷。
• **Render：**使用随附的 render.yaml 一键部署（Docker + /data 磁盘）。

想通过预构建镜像而非仓库进行部署？请使用 ghcr.io/rwnalds/engram-app:latest—— 不要使用 engram:latest，它是 stdio 服务，无法响应 HTTP 请求。将健康检查路径设为 /api/health。

常见问题

如何为 Claude Code 提供长期记忆？ 部署 Engram，连接一个 markdown 知识库，然后通过 claude mcp add 添加端点。brain_* 工具可让 Claude Code 跨会话搜索、读取和写入持久化笔记。

多个 AI Agent 能共用一个知识库吗？ 可以。每个 Agent 都指向同一个 MCP URL，并读写同一个活动知识库——这正是它的用途。 为每个 Agent 分配独立的 bearer token：read 或 write。只读 token 无法修改你的笔记。

如何防止 Agent 引用过时事实？ 停用该事实后，搜索结果便不会再显示它。值发生变化时，调用 brain_supersede(old, new) — 一次原子提交会将旧笔记标记为 superseded_by 新笔记，并且默认不会在搜索中显示（即使它是 locked）。 或者，在笔记上设置 valid_until: 2026-12-31，让它自动过期。 已停用的匹配项不会悄无声息地消失：brain_search 会在 excluded 列表中返回这些项及其 原因（"expired 2026-06-01"），这样 Agent 就能说明忽略了什么以及原因，而不是引用它。

如何防止 Agent 只是再添加一条相互矛盾的笔记？ Engram 会拒绝写入。如果被告知“价格现在是 X”，而 Agent 无法覆盖一条自己从未读取过的笔记，它会欣然在 acme-pricing.md 旁边 添加 acme-pricing-2026.md——没有内容被覆盖，但现在有两条有效笔记对同一个数字各执一词。该写入会被拒绝，并提示使用 brain_supersede，它会在一次提交中停用旧笔记并添加新笔记。只有当两条笔记确实都需要保留时，才传入 allow_conflict: true。

如何知道 Agent 改了什么？ 每次写入都会提交到 git，并注明操作者对应的 token 或人员；仪表板的活动动态会显示每个文件的差异——为自主 Agent 内置了审计跟踪。

它支持我的 Obsidian 知识库吗？ 支持。它会读取带有 frontmatter 和 [[wikilinks]] 的纯 markdown，并呈现 Obsidian 风格的 callout 和反向链接。无需导入。

我需要向量数据库吗？ 不需要。Engram 使用全文搜索（MiniSearch）以及基于人类可读 markdown 的 wikilink 图谱—— 无需嵌入服务，也无需运行向量存储。

我可以和笔记聊天吗？ 可以——启用可选的 Curator，这是一个聊天 Agent，它会搜索并读取你的知识库，通过 wikilink 引用回答 （Opus / Sonnet / Haiku）。聊天时它是只读的，因此可以帮你理清思路而不修改任何内容；它使用你自己的 Anthropic 密钥运行。

我可以查看 Agent 做了哪些更改吗？ 可以——Activity 视图会读取你知识库的 git 历史记录，并显示每项更改（包括 Agent 和队友所做的更改），还可展开查看每个文件的差异。因为它只是 git，所以你无需额外付费就能获得完整的审计跟踪。

我的数据会被锁定吗？ 不会。它只是你拥有的 git 仓库中的 .md 文件。关闭 Engram 后，你仍保留所有笔记及其完整历史记录。

它运行在哪里／可以自托管吗？ 由你自行托管。使用 Railway / Render / Fly / 任何带卷的 VM 运行一个 Docker 容器即可。密钥归你，数据也归你。

贡献

欢迎提交问题和 PR——尤其欢迎反馈有效性模型在结构与我的知识库不同的知识库中遇到的问题。

• CONTRIBUTING.md — 设置、规范和 PR 前检查清单。
• docs/curator.md — 可选的 Curator Agent 工作循环如何运作。
• SECURITY.md — 请私下报告漏洞，不要将其作为问题提交。

bun install && bun dev
bun test          # the ranking/authority suite, incl. the stale-truth fixtures

如果 Engram 对你有用，为仓库点个星确实能帮助其他人发现它。

技术栈

Next.js 16（App Router）· React 19 · TypeScript · Tailwind v4 · shadcn/ui · bun · MiniSearch · d3-force · MCP SDK。采用 MIT 许可证。

---

_{关键词： MCP 服务 · Model Context Protocol · AI Agent 的第二大脑 · Agent 记忆 · Claude Code 的长期记忆 · AI Agent 的共享记忆 · 可自托管的知识库 · 兼容 Obsidian · Markdown · 知识图谱 · 双向链接 · PKM · Zettelkasten · Git 支持的笔记 · Hermes Agent 记忆 · Cursor 记忆 · 无需向量数据库的 RAG · 与 Markdown 笔记对话 · Git 支持的 Agent 活动动态 · AI Agent 审计追踪 · 权限感知搜索 · 只读与写入 MCP 令牌 · Agent 访问控制 · 自组织笔记 · Agent 自动捕获笔记 · 自动整理笔记的 AI · 时间有效性 · 过时记忆 · Agent 引用过时事实 · 取代 · 笔记过期 · Agent 团队的共享记忆 · Basic Memory 替代方案 · mem0 替代方案。}