Claude Code Substrate Memory

claude-code-substrate-memory connects Claude Code to Substrate organizational memory. Itprovides seven MCP tools for reading and writing memory, captures new transcript turns throughClaude 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 servercan also be run directly with python -m claude_code_memory.server when src/ is onPYTHONPATH.

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 andnew events are placed in the local spool beneath ~/.substrate/claude_code_memory/. SetSUBSTRATE_STATE_HOME to relocate the state root, which is particularly useful for isolatedtests.

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 aturn event.
PreCompact captures the same incremental transcript window as pre_compress before ClaudeCode compacts its context.
SessionEnd emits a content-free session_end event containing only the normalized messagecount 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 blockwhen relevant memory is available.

Each hook is a fresh process, so per-session message digests and one-shot markers are persistedunder 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 sidechainrecords produced by subagents and ignores system, attachment, mode, permission-mode, andlast-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 isdefense in depth, not proof that arbitrary sensitive prose is absent. Visible prompts andassistant output can themselves contain confidential material, so configure only a trustedSubstrate server and review its access and retention policy. Failed deliveries remain in abounded owner-private local spool until delivered, evicted by the bound, quarantined, or removedby the operator.

Fail-open behavior

Hooks always exit with status 0. API failures, malformed hook input, unreadable or truncatedtranscripts, corrupt local state, and recall failures do not block or annotate a Claude Codesession. Normal capture hooks write nothing to stdout; optional diagnostics go only to stderr whenSUBSTRATE_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 andverified by the test suite.

Claude Code Substrate Memory