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. Sidechain capture is enabled by default. Set SUBSTRATE_CAPTURE_SIDECHAINS=0 to use the emergency exclusion kill-switch.

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 normalized user, assistant, tool-call, tool-result, and system blocks 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 captures top-level and sidechain user, assistant, and system records. Sidechain records carry record/block coordinates and session ancestry. Tool calls and results are separate text-only messages paired by tool_call_id. A paired result receives its tool name; an orphaned or ambiguous result receives a reason code and no source identity.

For every captured block, full credential detection runs before the 65,536-byte UTF-8 ceiling. If a recognized credential occurs anywhere in a block, the whole block becomes content-free. This prevents a secret from being cut at a former truncation boundary. Binary and media bodies, hidden reasoning, token usage, billing fields, and arbitrary provider metadata are not captured.

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. The spool reserves capacity for boundary events and refuses newest events under pressure instead of evicting older evidence. substrate-claude-code status exposes persistent evicted, quarantined, dropped, and duplicates counters without exposing content.

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.