Claude Code Substrate Memory

claude-code-substrate-memory connects Claude Code to Substrate organizational memory. It provides seven MCP tools for reading and writing memory, captures new transcript turns through Claude Code lifecycle hooks, and keeps failed deliveries in a bounded local spool.

Version 0.1.0 uses only the Python standard library at runtime.

Install

Clone the repository and load it as a Claude Code plugin:

git clone https://github.com/Substrate-memory/claude-code-substrate-memory.git
claude --plugin-dir /absolute/path/to/claude-code-substrate-memory

For development or direct CLI use, install the package into a Python 3.11+ environment:

python -m pip install -e .
substrate-claude-code status

The plugin manifests provide the MCP server, lifecycle hooks, and slash commands. The MCP server can also be run directly with python -m claude_code_memory.server when src/ is on PYTHONPATH.

Configuration

Credentials are accepted from environment variables only:

SUBSTRATE_API_URL=https://your-substrate-server.example
SUBSTRATE_API_KEY=your-profile-scoped-bearer-key

Set them in the environment that launches Claude Code. Never write SUBSTRATE_API_KEY to .mcp.json, hooks/hooks.json, a project settings file, or another plaintext configuration file. Run substrate-claude-code configure to print the required wiring without writing any secret.

If the variables are absent or the API is temporarily unreachable, capture remains enabled and new events are placed in the local spool beneath ~/.substrate/claude_code_memory/. Set SUBSTRATE_STATE_HOME to relocate the state root, which is particularly useful for isolated tests.

MCP tools

Tool	Purpose
substrate_search	Search organizational memory and return cited memory cards.
substrate_read	Read one wiki page by repository-relative path.
substrate_query	Ask a cited question over Substrate memory.
substrate_ingest	Submit text for asynchronous wiki ingestion.
substrate_remember	Record a durable fact or decision requested by the user.
substrate_sync	Retry delivery of locally spooled capture events.
substrate_status	Show content-free configuration and spool counters.

The repository also adds /substrate-status and /substrate-recall slash commands.

Hook capture

Claude Code invokes four command hooks from hooks/hooks.json:

• Stop captures only user and assistant messages not previously checkpointed and emits a turn event.
• PreCompact captures the same incremental transcript window as pre_compress before Claude Code compacts its context.
• SessionEnd emits a content-free session_end event containing only the normalized message count and session boundary. A persistent marker ensures it is emitted at most once.
• SessionStart performs a bounded Substrate search and prints a compact Markdown recall block when relevant memory is available.

Each hook is a fresh process, so per-session message digests and one-shot markers are persisted under the plugin state directory. Capture events are durably spooled before network delivery.

Privacy boundary

The transcript reader keeps only top-level user and assistant records. It excludes sidechain records produced by subagents and ignores system, attachment, mode, permission-mode, and last-prompt records.

For captured user and assistant messages, the plugin may send:

• visible text from string content and text, input_text, or output_text blocks;
• short markers such as [tool_use: Read] and [tool_result];
• role, message index, bounded message identifier, session boundary, and capture metadata.

It does not intentionally send:

• raw tool inputs or raw tool-result payloads;
• hidden reasoning, token usage, billing fields, or arbitrary provider metadata;
• attachment bodies, binary media, data URLs, or sidechain transcript text;
• SUBSTRATE_API_KEY or other recognized credential-shaped values.

The shared capture core redacts recognized secrets before persistence and transfer. Redaction is defense in depth, not proof that arbitrary sensitive prose is absent. Visible prompts and assistant output can themselves contain confidential material, so configure only a trusted Substrate server and review its access and retention policy. Failed deliveries remain in a bounded owner-private local spool until delivered, evicted by the bound, quarantined, or removed by the operator.

Fail-open behavior

Hooks always exit with status 0. API failures, malformed hook input, unreadable or truncated transcripts, corrupt local state, and recall failures do not block or annotate a Claude Code session. Normal capture hooks write nothing to stdout; optional diagnostics go only to stderr when SUBSTRATE_DEBUG is set. Session-start recall is the sole intentional hook output.

Repository map

• src/claude_code_memory/ — Claude Code runtime, transcript reader, hooks, recall, MCP server, and CLI.
• src/substrate_capture/ — frozen shared capture core used by all host plugins.
• .claude-plugin/ — plugin and self-listing marketplace metadata.
• .mcp.json — stdio MCP server registration.
• hooks/hooks.json — Claude Code lifecycle hook registration.
• commands/ — /substrate-status and /substrate-recall command prompts.
• tests/ — shared-core and Claude Code host contract tests with synthetic fixtures.
• scripts/ — shared-core provenance and publication verification tooling.

Development

python -m pip install -e '.[dev]'
python -m pytest tests/ -q
ruff check .

Do not edit src/substrate_capture/ directly. Its digests are shared across host repositories and verified by the test suite.

License

MIT © 2026 Sightline Technologies Inc. See LICENSE.