Substrate

Substrate Memory Plugins

Give your agents a memory that follows you across Claude, ChatGPT, Codex and Hermes.

AI memory for your team, editable, permissioned, owned.

trysubstrate.co: a context layer for your team and agents.

• Gemini CLI: gemini extensions install https://github.com/Substrate-memory/Substrate-memory-plugins (follows the latest release; pin one with --ref v<version>)
• MCP registry name: co.trysubstrate/memory (remote server https://app.trysubstrate.co/mcp)

Substrate remembers your decisions, preferences, people and projects. Connect once, and every supported agent recalls what matters before each turn and saves what matters after it. One connection screen, one review step, one approval. No API keys. No tokens to paste. No secrets to manage.

What you get

• Recall before every turn. Relevant memories are injected as context before the agent answers.
• Automatic capture of every completed turn. User messages, assistant answers and bounded redacted tool calls and results are saved.
• Session boundaries. Starts, resumes, resets, compacts and ends are recorded, so memory stays scoped to the right session.
• Subagent capture. Work done by subagents is routed to the parent session.
• Durable delivery. Nothing is stored twice. Hermes uses a profile-local write-ahead spool. Claude and Codex treat the host transcript as the spool: the server reports missing turns and the plugin sync re-imports them with deterministic ids.
• Explicit remember and forget. Say "remember this" to keep a fact. Retract one fact without deleting its evidence trail.
• Evidence. Check the source behind a recalled fact before you rely on it.
• Import past conversations. Asked once, after connection. Only with your confirmation.

How it works

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

Each package is a thin client. The server owns storage, ranking, redaction checks and the memory contract. Every host speaks the same contract (docs/mcp-contract.md, version 2): memory_turn_context opens the turn and returns recall, memory_capture_tool records tool use, memory_capture_turn closes the turn, memory_session_boundary marks lifecycle events, memory_import replays missed or past turns, and memory_search, memory_expand, memory_evidence, memory_remember, memory_forget read and write memory. The legacy Hermes /api/v1 wire stays supported on the server during the rollout.

Install

Paste this into the agent you want to connect:

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

The agent follows docs/install.md (the same file served at that link). It identifies its host and installs the right package. From this repository, the same request works too:

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):
```shhermes plugins install https://github.com/Substrate-memory/Substrate-memory-plugins --enable

Then follow the printed steps: the agent shows a one-time approval link and code, you approve in the browser, and the agent confirms Connected to Substrate as [email protected]. (your account)

If Cowork needs manual installation, use Cowork tab → Customize → Plugins → Personal plugins → + → Add marketplace → Add from a repository (GitHub URL), then browse and install the package. Client-required permission dialogs still need the user. Follow the single installation and recovery guide.

What is captured and where it goes

With the hook plugins (Claude Code, Cowork, Codex, Hermes), each prompt, each completed turn and bounded tool calls and results go to your own Substrate tenant at app.trysubstrate.co. Secrets are redacted on the server before storage; the sync and import scripts also redact on the client. Nothing goes anywhere else; only the Hermes package also reads this repository's VERSION file on github.com once a day to show an update notice (nothing is sent). The Claude Code and Codex plugins run one local script, the bundled scripts/substrate_sync.py: it reads only this agent's own conversation files (for the import you choose and for catch-up sync) and sends them only to https://app.trysubstrate.co/mcp; any other host is refused. The only credential it handles is Substrate's own short-lived import ticket, which it gets from the Substrate server by a single-use claim (or from a temporary file the agent writes, deleted on read). It never reads your Claude Code or Codex sign-in files, the keychain, SSH or cloud keys, it downloads no code, and it runs nothing it downloaded: updates come only through the plugin marketplace. Without hooks (plain MCP, Gemini CLI) only what the agent explicitly saves is stored. You can read, edit and forget every line; account deletion purges within 30 days.

Security and privacy

• Browser approval only. You sign in and choose Connect your agent to Substrate in the browser. The agent shows the exact link and never approves for you.
• No keys to manage. The product never issues API keys to users and never asks for pasted tokens or client secrets.
• Redaction on both sides. Secrets are redacted client-side before sending and again server-side on ingest. Captured tool arguments are bounded (4096 bytes) and tool results are stored as excerpts (8192 bytes plus a digest).
• Tenant isolation. Every credential is tenant-scoped. The server owns account identity; clients never send tenant or account ids.
• What is stored. Redacted turn content, session boundaries, explicit memories you confirm, and retraction records with their evidence.
• What is not stored. Passwords, API keys, tokens, and other secrets are redacted before storage. History import runs only after you choose it.

See SECURITY.md and docs/threat-model.md.

Import past conversations

Right after Connected to Substrate., in the same reply, the agent offers once, with what it found on this computer:

I found 87 past conversations on this computer (1,204 turns, 3 Mar to 7 Oct 2026). Import them into Substrate? Import all / Let me pick / Not now

• Import all imports every local conversation except the current one (already captured live). It runs in the background; the agent reports progress and the final line (how many conversations were imported, and that Substrate is reading them now) without waiting for you.
• Let me pick lists conversations by date and title; only those are imported.
• Not now is remembered and never asked again. Ask "import my past conversations" any time.
• The import state is kept per computer, not per account. If you later connect a different Substrate account on the same computer, the agent checks it and offers to import the earlier conversations into that account.

Claude Code and Codex upload straight from the package script with a short-lived, import-only ticket (memory_import_ticket), so your history never passes through the chat. Hermes reads its own profile history and sends it through its spool. Cowork cloud sessions have no local history, so the offer is skipped. Imports are redacted client- and server-side, and repeats are ignored.

Supported hosts and versions

Every package installs on any host version. Outside the tested range the agent (and the Hermes plugin itself) shows a friendly note instead of refusing: Tested on Hermes 0.21.0 or newer; you are on X. It should work; tell us if not. Newer Hermes versions get no note. See COMPATIBILITY.md.

Known limits, stated honestly:

• Codex has no session-end hook, so the server seals idle sessions after 30 minutes.
• Claude Code allows no MCP tool hook on SessionStart, so the first turn implies the session boundary.
• If a Cowork cloud session ends while Substrate is unreachable and is never reopened, its last turn is not recovered.
• Codex asks you to approve Substrate's hooks once: in the Codex app, in its hooks settings; in the terminal, /hooks.
• Cowork needs a new session after install before tools appear.
• Claude Code can show red "MCP server not connected" or "Unauthorized" hook errors while you are signed out or after a removed sign-in. Claude Code reports these from the plugin's capture hooks and the plugin cannot hide them. Reconnect with /substrate-claude:substrate-connect.

See COMPATIBILITY.md for the full matrix and history.

FAQ

Do I need an API key? No. Sign in in the browser and approve. There is nothing to copy or paste.

Which package does my agent install? Claude Cowork and Claude Code use plugins/substrate-claude. ChatGPT Work, the Codex app and Codex CLI use plugins/substrate-codex. Hermes uses plugins/substrate-hermes. OpenClaw, Grok and any other MCP-capable agent connect over the generic MCP server, the default for any system without its own package. plugins/substrate-mcp is the thin fallback package.

How do I know it is connected? The agent runs an authenticated memory smoke test. Only a passed memory_search means Connected to Substrate.

What exactly is sent to Substrate? Each completed turn: your message, the agent's answer, and bounded tool calls and results, all redacted before sending and again on the server. History import sends the same redacted turn content, only after you choose Import all or pick sessions.

What about my old August 2026 API-key plugin? Those plugins (substrate_capture, local spool paths, SUBSTRATE_API_KEY setups) are deprecated. Uninstall them and connect with the browser flow. Their local spools are not migrated.

Can I roll back? Yes. The immutable v0.5.0 and v0.6.0 tags remain available for rollback.

Development and releases

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

Releases are staged and gated; no tag or publication happens from a review branch. See docs/releasing.md.

Links

• Installation and recovery guide
• Architecture
• Source-of-truth boundary
• Compatibility
• Security
• Changelog
• MCP contract v2 (single source of truth for the memory tools)