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-сервер, хуки жизненного цикла и слэш-команды. MCP-сервер также можно запустить напрямую с помощью python -m claude_code_memory.server, когда src/ находится в PYTHONPATH.

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 захватывает нормализованные блоки пользователя, ассистента, вызовов инструментов, результатов инструментов и системные блоки, которые ранее не были контрольными точками, и отправляет событие turn.

• PreCompact захватывает то же инкрементальное окно транскрипта, что и pre_compress, перед тем как Claude Code сжимает свой контекст.

• 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; необязательная диагностика идёт только в stderr, когда установлен SUBSTRATE_DEBUG. Воспоминание при запуске сессии — единственный намеренный вывод хука.

Карта репозитория

• src/claude_code_memory/ — среда выполнения Claude Code, читатель транскрипта, хуки, воспоминания, MCP-сервер и CLI.

• src/substrate_capture/ — замороженное общее ядро захвата, используемое всеми плагинами хоста.

• .claude-plugin/ — метаданные плагина и само-листингового маркетплейса.

• .mcp.json — регистрация MCP-сервера через stdio.

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