Substrate

Substrate 记忆插件

让你的 Agent 拥有可在 Claude、ChatGPT、Codex 和 Hermes 之间延续的记忆。

为你的团队提供可编辑、可授权、归团队所有的 AI 记忆。

trysubstrate.co：为你的团队和 Agent 提供上下文层。

• Gemini CLI：gemini extensions install https://github.com/Substrate-memory/Substrate-memory-plugins（跟随最新版本；使用 --ref v<version> 固定版本）
• MCP registry 名称：co.trysubstrate/memory（远程服务 https://app.trysubstrate.co/mcp）

Substrate 会记住你的决定、偏好、人物和项目。连接一次后，每个受支持的 Agent 都会在每轮交互前回忆重要信息，并在交互后保存重要内容。只需一个连接界面、一次审核和一次批准。无需 API 密钥，无需粘贴令牌，也无需管理密钥。

你将获得

• 每轮交互前回忆。 Agent 回答前，系统会将相关记忆注入上下文。
• 自动捕获每轮已完成的交互。 保存用户消息、助手回答，以及经过边界限制并脱敏的工具调用和结果。
• 会话边界。 记录会话的开始、恢复、重置、压缩和结束，让记忆始终限定在正确的会话中。
• 子 Agent 捕获。 将子 Agent 完成的工作路由到父会话。
• 持久交付。 不会重复存储内容。Hermes 使用配置文件本地的预写日志暂存区。Claude 和 Codex 将宿主端对话记录作为暂存区：服务端会报告缺失的交互轮次，插件同步时会用确定性 ID 重新导入。
• 明确地记住和遗忘。 说“记住这个”即可保留一条事实。撤回一条事实时，不会删除其证据链。
• 证据。 依赖回忆出的事实之前，可先检查其来源。
• 导入过往对话。 连接后只询问一次，且仅在你确认后导入。

工作原理

Claude (Cowork, Claude Code) --> plugins/substrate-claude --\
ChatGPT (Work, Codex app, Codex CLI) --> plugins/substrate-codex --\
Hermes --> plugins/substrate-hermes --------------------------------+--> one server-side
Other MCP-capable agent --> plugins/substrate-mcp (fallback only) --/    MCP contract (v2)
                                                                              |
                                                                              v
                                                              recall + capture + memory store

每个软件包都是轻量客户端。服务端负责存储、排序、脱敏检查和记忆契约。所有宿主都使用相同的契约（docs/mcp-contract.md，版本 2）：memory_turn_context 开启交互轮次并返回回忆内容，memory_capture_tool 记录工具使用情况，memory_capture_turn 结束交互轮次，memory_session_boundary 标记生命周期事件，memory_import 重放遗漏或过往的交互轮次，memory_search、memory_expand、memory_evidence、memory_remember、memory_forget 则用于读取和写入记忆。迁移期间，服务端仍会支持旧版 Hermes /api/v1 协议。

安装

将以下内容粘贴到你想连接的 Agent 中：

Install Substrate memory in this agent by following https://trysubstrate.co/install.md

Agent 会按照 docs/install.md 操作（该链接提供的也是同一文件）。它会识别自己的宿主并安装对应的软件包。也可以在此仓库中使用同一请求：

Install the memory plug-in at https://github.com/Substrate-memory/Substrate-memory-plugins
``` The flow is the same everywhere: **Install → Sign in → Review → Approve connection → Connected to Substrate.** Only report **Connected to Substrate.** after an authenticated memory smoke test (`memory_search`) succeeds. The browser's **Connection approved** state is consent only; it is not proof that the agent finished connecting. Never paste or request API keys, manual tokens, or client secrets.

| Your host | Package the agent installs | Guide |
|---|---|---|
| Claude Cowork, Claude Code | `plugins/substrate-claude` | [substrate-claude README](plugins/substrate-claude/README.md) |
| ChatGPT Work, Codex app, Codex CLI | `plugins/substrate-codex` | [substrate-codex README](plugins/substrate-codex/README.md) |
| Hermes | `plugins/substrate-hermes` | [substrate-hermes README](plugins/substrate-hermes/README.md) |
| OpenClaw | no package: generic MCP server | [OpenClaw guide](docs/openclaw.md) |
| Grok | no package: generic MCP server through the Grok CLI | [Grok guide](docs/grok.md) |
| Any other MCP-capable agent | no package: generic MCP server (`plugins/substrate-mcp` is the thin fallback) | [substrate-mcp README](plugins/substrate-mcp/README.md) |

**Hermes in one command** (the repository root is a Hermes plugin that loads `plugins/substrate-hermes`; it passes the Hermes install scan with no override):

```sh
hermes plugins install https://github.com/Substrate-memory/Substrate-memory-plugins --enable

然后按照显示的步骤操作：Agent 会显示一次性批准链接和代码；你在浏览器中批准后，Agent 会确认 Connected to Substrate as [email protected].（你的账户）

如果 Cowork 需要手动安装，请依次选择 Cowork tab → Customize → Plugins → Personal plugins → + → Add marketplace → Add from a repository (GitHub URL)，然后浏览并安装软件包。仍需用户处理客户端要求的权限对话框。请参阅这份安装和恢复指南。

捕获的内容及其去向

使用钩子插件（Claude Code、Cowork、Codex、Hermes）时，每条提示词、每个已完成的轮次，以及有大小限制的工具调用和结果，都会发送到你自己的 Substrate 租户（位于 app.trysubstrate.co）。密钥会在服务器端存储前进行脱敏；同步和导入脚本也会在客户端进行脱敏。数据不会发送到其他任何地方；只有 Hermes 软件包每天还会从 github.com 读取一次此仓库的 VERSION 文件，以显示更新通知（不会发送任何内容）。Claude Code 和 Codex 插件会运行一个本地脚本，即打包在其中的 scripts/substrate_sync.py：该脚本只会读取此 Agent 自己的对话文件（用于你选择的导入和补充同步），并且只会将这些文件发送到 https://app.trysubstrate.co/mcp；任何其他主机都会被拒绝。它处理的唯一凭证是 Substrate 自己的短期导入票据，该票据通过一次性领取从 Substrate 服务器获取（或者从 Agent 写入的临时文件读取，并在读取后删除）。它绝不会读取你的 Claude Code 或 Codex 登录文件、钥匙串、SSH 或云密钥，也不会下载代码，或运行任何下载的内容：更新仅通过插件市场提供。不使用钩子时（纯 MCP、Gemini CLI），只会存储 Agent 明确保存的内容。你可以查看、编辑或遗忘每一行内容；删除账户后，数据会在 30 天内清除。

安全与隐私

• 仅通过浏览器批准。 你在浏览器中登录，并选择将 Agent 连接到 Substrate。Agent 会显示确切的链接，但绝不会代你批准。
• 无需管理密钥。 本产品绝不会向用户发放 API 密钥，也绝不会要求你粘贴令牌或客户端密钥。
• 双端脱敏。 密钥会先在客户端脱敏后再发送，并在服务器端接收数据时再次脱敏。捕获的工具参数有大小限制（4096 字节），工具结果则以摘录形式存储（8192 字节，外加摘要）。
• 租户隔离。 每个凭证都限定于特定租户。账户身份由服务器管理；客户端绝不会发送租户 ID 或账户 ID。
• 存储的内容。 脱敏后的轮次内容、会话边界、你确认保存的明确记忆，以及带有相关证据的撤回记录。
• 不存储的内容。 密码、API 密钥、令牌及其他密钥都会在存储前脱敏。只有在你选择后才会导入历史记录。

请参阅 SECURITY.md 和 docs/threat-model.md。

导入过往对话

在回复 Connected to Substrate. 后，Agent 会在同一条回复中根据在这台计算机上找到的内容，询问一次：

我在这台计算机上找到了 87 段过往对话（共 1,204 轮，时间从 2026 年 3 月 3 日到 10 月 7 日）。要将它们导入 Substrate 吗？全部导入 / 让我选择 / 暂不导入

• 全部导入会导入除当前对话外的所有本地对话（当前对话已实时捕获）。导入会在后台运行；Agent 会报告进度和最终结果（导入了多少段对话，以及 Substrate 现在正在读取这些对话），不会等待你。
• 让我选择会按日期和标题列出对话；只会导入你选择的对话。
• 暂不导入会被记住，之后不会再询问。你可以随时说“导入我的过往对话”。
• 导入状态按计算机保存，而不是按账户保存。如果你之后在同一台计算机上连接另一个 Substrate 账户，Agent 会检查该账户，并提供将之前的对话导入该账户的选项。

Claude Code 和 Codex 会通过软件包脚本直接上传，并使用短期、仅限导入的票据（memory_import_ticket），因此你的历史记录不会经过聊天。Hermes 会读取自己的配置文件历史记录，并通过其暂存队列发送。Cowork 云端会话没有本地历史记录，因此会跳过此提示。导入数据会在客户端和服务器端进行脱敏，并忽略重复内容。

支持的宿主和版本

发布版本	Hermes	Claude Code	Cowork	Codex / ChatGPT Work	其他 MCP 客户端	状态
v0.10.0	plugins/substrate-hermes（在 Hermes 0.21.0 或更高版本上测试）	plugins/substrate-claude	plugins/substrate-claude	plugins/substrate-codex	plugins/substrate-mcp 后备方案	候选发布版

每个软件包都可以安装在任何宿主版本上。对于测试范围以外的版本，Agent（以及 Hermes 插件本身）会显示友好提示，而不是拒绝使用：已在 Hermes 0.21.0 或更高版本上测试；你当前使用的是 X。应该可以正常运行；如果不行，请告知我们。 较新的 Hermes 版本不会显示提示。参见 COMPATIBILITY.md。

如实说明的已知限制：

• Codex 没有会话结束钩子，因此服务会在会话空闲 30 分钟后将其封存。
• Claude Code 不允许在 SessionStart 上使用 MCP 工具钩子，因此第一轮交互会被视为会话边界。
• 如果 Cowork 云端会话在 Substrate 无法访问时结束，且之后从未重新打开，则无法恢复该会话的最后一轮交互。
• Codex 会要求你批准 Substrate 的钩子：在 Codex 应用中，前往其钩子设置；在终端中，输入 /hooks。
• 安装后，Cowork 需要新建会话，工具才会显示。
• 当你已退出登录或移除了登录状态后，Claude Code 可能会显示红色的“MCP server not connected”或“Unauthorized”钩子错误。这些错误由插件的捕获钩子报告，插件无法隐藏。使用 /substrate-claude:substrate-connect 重新连接。

完整的兼容性矩阵和历史记录请参见 COMPATIBILITY.md。

常见问题

我需要 API 密钥吗？ 不需要。在浏览器中登录并批准即可，无需复制或粘贴任何内容。

我的 Agent 应安装哪个软件包？ Claude Cowork 和 Claude Code 使用 plugins/substrate-claude。ChatGPT Work、Codex 应用和 Codex CLI 使用 plugins/substrate-codex。Hermes 使用 plugins/substrate-hermes。OpenClaw、Grok 和任何其他支持 MCP 的 Agent 都通过通用 MCP 服务连接；对于没有专用软件包的系统，这是默认方式。plugins/substrate-mcp 是精简的后备软件包。

如何确认已连接？ Agent 会运行经过身份验证的记忆冒烟测试。只有 memory_search 测试通过，才表示已连接到 Substrate。

究竟会向 Substrate 发送哪些内容？ 每轮完成后：你的消息、Agent 的回答，以及经过限制的工具调用和结果；所有内容在发送前都会进行脱敏，并在服务端再次脱敏。只有在你选择导入全部或选择会话后，历史记录导入才会发送同样经过脱敏的每轮交互内容。

我之前使用的 2026 年 8 月 API 密钥插件该怎么办？ 这些插件（substrate_capture、本地暂存路径、SUBSTRATE_API_KEY 设置）已弃用。请卸载它们，并通过浏览器流程连接。它们的本地暂存内容不会迁移。

我可以回退吗？ 可以。不可变的 v0.5.0 和 v0.6.0 标签仍可用于回退。

开发和发布

UV_PROJECT_ENVIRONMENT=$PWD/.venv uv sync --project tooling --frozen --extra dev
.venv/bin/ruff check .
.venv/bin/python -m pytest -q
python3 scripts/check_public_hygiene.py --root .
.venv/bin/python scripts/build_release.py
.venv/bin/python scripts/build_release.py --check

发布分阶段进行并设有门禁；不会从评审分支创建标签或发布内容。参见 docs/releasing.md。

链接

• 安装和恢复指南
• 架构
• 事实来源边界
• 兼容性
• 安全性
• 变更日志
• MCP 合约 v2（记忆工具的唯一事实来源）