Claude Code Substrate Memory

claude-code-substrate-memory は、Claude Code を Substrate の組織メモリに接続します。メモリの読み書きのための7つの MCP ツールを提供し、Claude Code のライフサイクルフックを通じて新しいトランスクリプトのターンをキャプチャし、配信に失敗したイベントを容量制限付きのローカルスプールに保持します。

バージョン 0.1.0 は、実行時に Python 標準ライブラリのみを使用します。

インストール

リポジトリをクローンして、Claude Code プラグインとして読み込みます:

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

開発用または CLI での直接使用のために、パッケージを Python 3.11+ 環境にインストールします:

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

プラグインマニフェストは、MCP サーバー、ライフサイクルフック、スラッシュコマンドを提供します。MCP サーバーは、src/ が PYTHONPATH 上にある場合、python -m claude_code_memory.server で直接実行することもできます。

Related MCP server: Claude Memory MCP Server

設定

認証情報は環境変数からのみ受け付けられます:

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

これらの環境変数は Claude Code を起動する環境に設定してください。SUBSTRATE_API_KEY を .mcp.json、hooks/hooks.json、プロジェクト設定ファイル、または他の平文設定ファイルに書き込まないでください。substrate-claude-code configure を実行すると、秘密情報を書き込むことなく必要な配線を出力します。

変数が存在しない場合や API が一時的に到達不能な場合でも、キャプチャは有効のままであり、新しいイベントは ~/.substrate/claude_code_memory/ の下のローカルスプールに配置されます。SUBSTRATE_STATE_HOME を設定すると状態ルートを移動できます。これは分離されたテストに特に役立ちます。サイドチェーンキャプチャはデフォルトで有効です。緊急時の除外キルスイッチを使用するには、SUBSTRATE_CAPTURE_SIDECHAINS=0 を設定します。

MCP ツール

リポジトリは、/substrate-status および /substrate-recall スラッシュコマンドも追加します。

フックキャプチャ

Claude Code は、hooks/hooks.json から4つのコマンドフックを呼び出します:

• Stop は、以前にチェックポイントされていない正規化された user、assistant、tool-call、tool-result、system ブロックをキャプチャし、turn イベントを発行します。

• PreCompact は、Claude Code がコンテキストを圧縮する前に、pre_compress と同じ増分トランスクリプトウィンドウをキャプチャします。

• SessionEnd は、正規化されたメッセージ数とセッション境界のみを含む、内容を含まない session_end イベントを発行します。永続的なマーカーにより、イベントが最大1回だけ発行されることが保証されます。

• SessionStart は、制限付きの Substrate 検索を実行し、関連するメモリが利用可能な場合に、コンパクトな Markdown リコールブロックを出力します。

各フックは新しいプロセスであるため、セッションごとのメッセージダイジェストとワンショットマーカーは、プラグインの状態ディレクトリの下に永続化されます。キャプチャイベントは、ネットワーク配信前に永続的にスプールされます。

プライバシー境界

トランスクリプトリーダーは、トップレベルおよびサイドチェーンの user、assistant、system レコードをキャプチャします。サイドチェーンレコードは、レコード/ブロック座標とセッションの祖先を保持します。ツール呼び出しと結果は、tool_call_id によってペアリングされた、テキストのみの別々のメッセージです。ペアリングされた結果にはツール名が付けられます。孤立した結果または曖昧な結果には理由コードが付けられ、ソースの識別情報は付与されません。

キャプチャされたすべてのブロックについて、65,536バイトの UTF-8 上限の前に完全な認証情報検出が実行されます。認識された認証情報がブロック内のどこかに存在する場合、そのブロック全体が内容を含まないものになります。これにより、以前の切り捨て境界で秘密が切断されるのを防ぎます。バイナリおよびメディア本体、非表示の推論、トークン使用量、課金フィールド、および任意のプロバイダーメタデータはキャプチャされません。

共有キャプチャコアは、永続化と転送の前に、認識された秘密を秘匿化します。秘匿化は多層防御であり、任意の機密性のある散文が存在しないことの証明ではありません。表示されるプロンプトやアシスタントの出力自体に機密資料が含まれる可能性があるため、信頼できる Substrate サーバーのみを設定し、そのアクセスおよび保持ポリシーを確認してください。配信に失敗したイベントは、所有者専用の容量制限付きローカルスプールに残ります。スプールは境界イベントのために容量を確保し、容量が逼迫すると古い証拠を退避させる代わりに、新しいイベントを拒否します。substrate-claude-code status は、コンテンツを公開せずに、永続的な evicted、quarantined、dropped、duplicates カウンターを公開します。

フェイルオープン動作

フックは常にステータス0で終了します。API の失敗、不正な形式のフック入力、読み取り不能または切り詰められたトランスクリプト、破損したローカル状態、およびリコールの失敗は、Claude Code セッションをブロックしたり注釈を付けたりしません。通常のキャプチャフックは stdout に何も書き込みません。オプションの診断情報は、SUBSTRATE_DEBUG が設定されている場合にのみ stderr に出力されます。セッション開始時のリコールのみが、意図的なフック出力です。

リポジトリマップ

• src/claude_code_memory/ — Claude Code ランタイム、トランスクリプトリーダー、フック、リコール、MCP サーバー、CLI。

• src/substrate_capture/ — すべてのホストプラグインで使用される凍結済みの共有キャプチャコア。

• .claude-plugin/ — プラグインおよびセルフリスティングのマーケットプレイスメタデータ。

• .mcp.json — stdio MCP サーバー登録。

• hooks/hooks.json — Claude Code ライフサイクルフック登録。

• commands/ — /substrate-status および /substrate-recall コマンドプロンプト。

• tests/ — 合成フィクスチャを使用した共有コアおよび Claude Code ホスト契約テスト。

• scripts/ — 共有コアの来歴および公開検証ツール。

開発

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

src/substrate_capture/ を直接編集しないでください。そのダイジェストはホストリポジトリ間で共有され、テストスイートによって検証されます。

ライセンス

MIT © 2026 Sightline Technologies Inc. LICENSE を参照してください。