Claude Code Substrate Memory

claude-code-substrate-memory 将 Claude Code 连接到 Substrate 组织记忆。它提供七个用于读写记忆的 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 服务器、生命周期钩子和斜杠命令。当 src/ 位于 PYTHONPATH 中时，MCP 服务器也可以直接通过 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 调用四个命令钩子：

• Stop 捕获此前未设置检查点的规范化 user、assistant、tool-call、tool-result 和 system 块，并发出 turn 事件。

• PreCompact 在 Claude Code 压缩其上下文之前，捕获与 pre_compress 相同的增量转录窗口。

• SessionEnd 发出一个不含内容的 session_end 事件，仅包含规范化消息计数和会话边界。持久标记确保它最多发出一次。

• 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。