# 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:

```bash
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:

```bash
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:

```text
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

```bash
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](LICENSE).