engram

Engram 是一个自托管的 MCP（Model Context Protocol）服务器与仪表板，让 Claude Code、Cursor、Hermes 以及任何支持 MCP 的智能体共享一套长期记忆。记忆存储在你拥有的、由 git 跟踪的普通 Markdown 文件夹中，并兼容 Obsidian。它面向的场景是单个智能体记忆无法覆盖的：一个团队同时运行多个智能体，共享同一个“第二大脑”。

用途

自主智能体在会话之间会遗忘一切，更严重的是，它们无法判断自己记住的内容是否仍然真实。智能体可能引用几个月前已更改的 README、已停用的价格或 API 文档，因为关键词搜索和向量搜索都按相似度、而非真实性来排序。Engram 将“这是否仍然真实”作为一等、被写下来的属性：把事实标记为已取代或已过期后，检索会将其隐去，并告诉智能体它跳过了什么以及原因。按智能体的读写令牌以及“谁写了什么”的 git 审计轨迹，让写入者是一群智能体而不只是你一个人时也能保持可控。

主要能力

• MCP 服务器：通过一个 bearer 认证的 HTTP 端点（POST /api/mcp，流式 HTTP JSON-RPC）提供 15 个 brain_* 工具。任何 MCP 客户端连接同一个 URL。按智能体分配令牌作用域：只读令牌甚至看不到写入工具。
• 人类仪表板：以搜索为首页，包含文件树、支持 Obsidian callouts／wikilinks／反向链接的笔记查看器、带自动保存的预览／编辑／分屏编辑器、⌘K 搜索与页内键盘导航、“jump back in”最近记录，以及力导向知识图谱。
• 权威感知检索：排序知道相关性，却不知道真实性，因此被取代的笔记可能和当前笔记一样频繁地重复你的查询词。每个命中都携带一个权威级别（authoritative → current → provisional → superseded → archived），由笔记所在文件夹和 frontmatter 推导而来，让智能体引用的是锁定文档而非过时文档。
• 时间有效性 + 可解释的拒绝：把某条事实标记为 superseded_by 另一条笔记，或给它一个 valid_until 日期，检索默认就会隐去它（即使它被锁定），然后向智能体返回一个 excluded 列表，说明跳过了什么，并附上原因（如“expired 2026-06-01”）。一次原子的 brain_supersede 会在单个 commit 中停用旧事实并链接新事实，使新增与停用不会脱节。
• 写入时矛盾防护：权威排序解决读取；这些防护阻止仓库一开始就接受矛盾。若已有实时笔记覆盖某主题，Engram 拒绝创建第二条实时笔记，并指引智能体改用 brain_supersede；拒绝覆盖调用者尚未读取的笔记；当 status: 不是排序模型认识的字词时发出警告，使拼写错误不会悄悄剥掉笔记的权威。
• 审计轨迹 + 访问控制：每次写入都在 git 中归属到做出该写入的令牌或人，活动流中提供可展开的逐文件 diff。给智能体只读令牌，它甚至看不到写入工具；写入令牌可以创建、编辑、移动和归档。
• Curator（可选）：Engram 内置的、在你仓库上运行的智能体框架。可与你的笔记聊天（有依据的回答，附带 wikilink 引用）。或把粗略草稿（会议记录、语音转录）交给 brain_capture，由智能体循环搜索已有内容，然后归档、合并或存档，并返回它所触碰内容的清单。它覆盖前先读取，且从不删除。支持 Opus／Sonnet／Haiku，使用你自己的密钥。
• Markdown 原生：普通 .md + YAML frontmatter + [[wikilinks]]。直接放入现有 Obsidian 仓库即可工作。
• Git 支持：每次变更可选自动 commit + push。完整历史，无锁定，你的数据存放在你的仓库中。
• 无数据库：文件是事实来源；内存中的 MiniSearch 索引加上移植的 wikilink 图驱动搜索与反向链接。无需任何预置。
• 多工作区：连接多个仓库（URL + 令牌或 GitHub OAuth），重命名、切换活动工作区或移除，全部在 UI 中完成。
• 自托管：一个 Docker 容器。可部署于 Railway / Render / Fly / 任何带卷的主机。不是无服务器（需要持久卷、文件监视器和长期运行的索引）。
• 团队认证：仪表板支持 Google SSO + 邮箱允许列表；MCP 使用按智能体的 bearer 令牌，或 Claude.ai 自定义连接器的 OAuth，均在 UI 中创建／撤销。密钥静态加密。
• 运行时配置：在首页直接切换 git 同步和 Curator；在设置中管理 commit 作者、密钥和 OAuth，无需重新部署。

使用方式

运行方式有两种：

• 托管模式（团队）：上述仪表板 + HTTP MCP 服务器——自托管一次，许多智能体和队友通过 POST /api/mcp 连接。这是主要模式。
• 本地模式（stdio）：一个针对文件夹的普通 stdio MCP 服务器，无 HTTP／认证／git——适用于单机、Claude Desktop / Cursor，或注册表的 Docker 内省。

本地模式命令：

bun run mcp:stdio /path/to/your/vault # 默认使用 ./sample-vault

同样的 brain_* 工具。由 Dockerfile.mcp 构建。

每种模式以各自镜像发布，二者不可互换。把 stdio 镜像当作 Web 服务部署是唯一值得点名的错误：它只会 502，因为没有东西在监听。现在它会在 PaaS 上拒绝启动并告知这一点。

智能体只能看到当前活动仓库——不暴露任何仓库、工作区或 GitHub 工具。read 作用域令牌只能看到读取工具。brain_capture 仅在 Curator 为 full 时出现。

连接智能体：仪表板的 Connect 页面会显示确切的命令和令牌。连接你的仓库：在仪表板的 Workspaces 中，通过 URL + 令牌或 GitHub OAuth 连接。用 Google 登录，在 Connect 页面创建 MCP 令牌，把智能体指向该 URL。

部署：可运行 Docker 容器并带持久卷的地方均可——Railway、Render、Fly 或你自己的机器。无服务器（Vercel）不可用：Engram 需要卷、文件监视器和内存索引，无服务器函数无法保持其存活。部署此仓库（根 Dockerfile），在 /data 挂载卷，设置 ENGRAM_DATA_DIR=/data。

Railway：New Project → Deploy from GitHub repo → 在 /data 添加 Volume。Render：通过捆绑的 render.yaml 一键部署（Docker + /data 磁盘）。

若使用预构建镜像而非仓库部署，请使用 ghcr.io/rwnalds/engram-app:latest——不要用 engram:latest，后者是 stdio 服务器，无法响应 HTTP。健康检查设为 /api/health。

大多数运行时配置（git 同步、AI capture、GitHub OAuth、应用名）可在设置页面编辑——只有认证／基础设施引导变量放在主机上。完整设置见 DEPLOY.md。

适用场景

• 合租多个智能体的团队共享记忆——一个仓库，多个智能体并发读写，按智能体分配读写令牌，并有 git 审计轨迹记录谁改了什么。
• 知道什么仍然真实的记忆——停用一个价格、条款或已更改的 API 文档，你的智能体就不再引用它，并被告知跳过了什么及原因。
• Claude Code 及其他编码智能体的长期记忆——不必每次会话重新解释你的项目。
• 自托管、兼容 Obsidian 的、通过 MCP 暴露的第二大脑。
• 可视化而非黑盒的记忆——通过仪表板搜索、观察（带 diff）和整理智能体记住的内容。
• 无向量数据库的 Markdown RAG——在人类可读文件上进行全文搜索加链接图。

已知限制与说明

• 不是无服务器架构，无法部署在 Vercel 等平台。
• 本地 stdio 模式不含 HTTP／认证／git。
• 当前仓库资料截至 2026 年 7 月，对特定产品的对比按类别而非逐项审计。
• 内置 Curator 使用你自己的 Anthropic 密钥，支持 Opus／Sonnet／Haiku。
• 采用 MIT 许可证。技术栈：Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · shadcn/ui · bun · MiniSearch · d3-force · MCP SDK。