claude-memory-engine 0.14.0

Что это

claude-memory-engine добавляет в Claude Code долговременную память «уроков». Урок: короткая запись о том, как в проекте принято делать, на какие ошибки уже наступали и что нельзя ломать. Уроки записывает сам ассистент по ходу работы над проектом; при желании вы можете добавлять их и сами, но это не обязательно. Движок упорядочивает уроки и подсказывает вашей LLM нужный урок тогда, когда он ей пригодится.

Важно: в движок входит только механизм. Ваши уроки (это ваши знания и, возможно, приватные данные) хранятся отдельно.

Зачем это нужно

Когда работаешь с ИИ-ассистентом над проектом, возникает общая проблема: у него нет единой сквозной памяти. Из-за этого одни и те же ошибки повторяются раз за разом. Чтобы их избежать, приходится всё больше записывать в память проекта; она разрастается, а большой файл ассистент уже не читает целиком, и внимание достаётся только первым 200 строкам. В итоге вести сложный проект становится тяжело и долго.

Движок убирает эту боль: уроки лежат маленькими отдельными markdown-файлами, нужный урок показывается сам в подходящий момент, оглавление со всеми уроками собирается автоматически, а размер памяти держится под контролем. Подробнее: смотрите раздел «Возможности» ниже.

Быстрый старт

Самый короткий путь:

pip install claude-memory-engine
cd /путь/к/вашему/проекту
claude-memory init

Первая команда ставит движок. Команда cd переводит вас в папку вашего проекта. Команда claude-memory init подключает движок к этому проекту: создаёт файл настроек, находит папку, куда встроенная авто-память Claude Code пишет уроки (~/.claude/projects/<slug>/memory), и делает так, чтобы движок срабатывал в нужные моменты. Своей папки уроков движок не заводит — он работает с той, что ведёт Claude Code. На этом всё: подсказки заработают со следующей сессии Claude Code. Настраивать ничего не нужно, по умолчанию всё работает; как изменить настройки под себя, описано ниже в разделе «Настройка».

Как устроено

Движок состоит из трёх слоёв.

1. Логика. Набор небольших программ на Python, которые делают всю работу: находят нужный урок, собирают оглавление, отправляют устаревшее в архив и так далее. Это чистый Python без сторонних библиотек, отдельно ставить ничего не нужно.

2. Связка с Claude Code. Один маленький скрипт, который Claude Code вызывает в нужные моменты (в начале сессии, перед правкой файла и тому подобное) и который просто запускает логику.

3. Данные. Сами уроки: ваши знания о проекте. Они хранятся отдельно и в движок не входят.

Зачем это деление: первые два слоя составляют универсальный механизм, который переносится в любой проект, а третий слой содержит только ваши приватные данные. Поэтому движок легко переиспользовать и даже открыть публично, а ваши уроки при этом остаются только у вас.

А вот что происходит на каждый ваш запрос: запрос приходит к Claude Code и через хук запускает движок; тот подбирает урок из памяти обычным кодом и возвращает его в контекст LLM; после этого ассистент отвечает с учётом урока.

flowchart LR
  Q["Ваш запрос"] -->|"1. запрос"| C["Claude Code (ваша LLM)"]
  C -->|"2. хук на запрос"| E["Движок: подбор урока кодом, не ИИ"]
  L["Уроки (markdown)"] -.->|"3. источник"| E
  E -->|"4. нужный урок"| C
  C -->|"5. ответ с учётом урока"| A["Ответ"]

Движок срабатывает и на другие события Claude Code: перед правкой файла (урок по пути), в начале и в конце сессии, при завершении работы.

Пример вывода для вашего LLM-ассистента

Подсказку с подходящими уроками движок добавляет в контекст вашего LLM-ассистента (в чате вы её обычно не видите). Выглядит она примерно так:

[память] Возможно полезные уроки. Прочтите нужные ДО действий:
  • по смыслу:
    - api-error-format: ошибки отдаём в формате {code, message}
    - db-migrations: новые поля БД только через миграцию, не руками
  • по пути файла:
    - payment-flow: не менять статус оплаты вручную

Уроки в примере выдуманы для иллюстрации. По умолчанию надписи английские; перевод — в разделе «Настройка».

Возможности

Уроки и порядок

• Уроки хранятся маленькими markdown-файлами с короткой шапкой (название, тема, ключевые слова) плюс одно «горячее ядро» (главный файл, который читается всегда) с ограничением размера, чтобы оно не разрасталось.
• Оглавление всех уроков собирается само из их тем; вручную его вести не нужно.

Подсказки в нужный момент

• На каждый ваш запрос движок сам подбирает подходящие уроки по словам и показывает их вашей LLM; если ничего важного нет, он молчит. Подбор делает обычный код, без обращения к ИИ.
• Урок можно привязать к файлу: тогда он покажется ровно перед тем, как ассистент соберётся править этот файл.
• Подсказки остаются быстрыми, даже когда уроков становится много (за счёт внутреннего кэша).

Память сама себя поддерживает

• Старые записи уходят в архив, большой архив остаётся удобным для поиска, а в конце сессии движок помечает устаревшие правила и оборванные привязки уроков к файлам.
• Размер памяти под контролем, в свалку она не превращается.

Страховки

• Если две сессии правят один и тот же файл памяти, вторая получает мягкое «перечитай и повтори» вместо тихой потери правок.
• В конце работы движок мягко напоминает записать урок, если после свежего коммита заметки ещё нет (особенно когда коммит закрывает задачу).
• Чтобы движок проверил уроки на устаревание, в конце сессии напишите фразу закрытия (например «Туши свет» или «Done»): в ответ он покажет чек-лист итогов памяти — какие уроки всплывали при правках и не были обновлены, близкие по смыслу и какие стражи включены. Эту фразу нужно писать в конце каждой сессии: именно она запускает проверку (если забыли — движок запишет долг и напомнит на старте следующей сессии). Так знания в памяти не расходятся с кодом.
• Не даёт случайно запустить вспомогательного помощника (суб-агента) на самой дорогой модели и ведёт журнал таких запусков.
• Предупреждает, если модель сессии незнакомая, и раз в сутки просит сверить линейку моделей (нет ли новых/отключённых) — итог попадает в чек-лист закрытия.
• Проверяет настройки при старте и ловит опечатки, пока они не сломали работу. Отдельно предупредит, если движок смотрит не в ту папку, куда Claude Code пишет уроки, — иначе это выглядит как «всё хорошо, уроков просто нет».

Гибкость

• Любой язык: все надписи движка переводятся через настройки, не трогая код.
• Корректно работает внутри git-worktree (отдельной рабочей копии репозитория).
• Ноль сторонних зависимостей: нужен только обычный Python.

Стражи памяти

Движок включает несколько «стражей» — небольших автоматических проверок. Они срабатывают в разные моменты, и что включено, а что нет, всегда видно в чек-листе итогов сессии.

Устаревшие уроки. Когда вы пишете фразу закрытия сессии (session_close_pattern), движок показывает чек-лист итогов памяти: какие уроки всплывали при правках и не были обновлены (вдруг ваши изменения сделали их неверными), близкие по смыслу уроки, статус сроков годности и список включённых/выключенных стражей. Срабатывает на фразу закрытия. Включён по умолчанию.

Запись уроков. В конце хода, если после свежего коммита в память ещё не записан урок, движок мягко напоминает зафиксировать вывод. Триггер — коммит, проверка при завершении ответа. Включён.

Закрытие задачи. В конце хода, если коммит закрывает задачу (Closes #N), но урока про неё в памяти нет, движок просит записать его. Это отдельный от «устаревших уроков» страж со своим триггером — коммитом, не фразой. Честно об изъяне: этот путь видит только текст ПОСЛЕДНЕГО коммита, а команда gh issue close коммита вообще не создаёт — после перехода проекта на GitHub Issues страж на такие закрытия молчал. Поэтому есть второй источник того же сигнала: хук на Bash замечает саму команду gh issue close и кладёт метку в память, а тот же страж при завершении её читает и точно так же требует урок. Включён по умолчанию (task_close_command_watch); метка живёт task_close_marker_ttl_seconds секунд (по умолчанию 4 часа), потом гаснет сама.

Срок хранения архива. В конце сессии движок помечает архивные уроки старше полугода и показывает их на следующем старте как кандидатов на пересмотр. Память сама ничего не удаляет — решение за вами. Включён (6 месяцев); 0 выключает.

Счётчик уроков. Когда уроков больше порога, на старте появляется подсказка проверить точные дубли (не «слить» — это теряет детали). Включён, порог 500; 0 выключает.

Актуальность линейки моделей. Объединяет две проверки. Реактивно: на старте предупреждает, если модель сессии не из подтверждённого списка семейств (по умолчанию opus, sonnet, haiku, fable). Суточно: раз в сутки просит ассистента сверить линейку — нет ли новых или отключённых моделей (проверку можно поручить самой дешёвой модели с веб-поиском), и записать итог командой cme_hook.sh llm-verified / llm-changes. Результат хранится в служебном файле и показывается строкой в чек-листе закрытия. Включено по умолчанию (llm_actuality_enabled; период — llm_actuality_interval_hours, 24 ч).

Параллельные сессии. Если другая сессия изменила файл памяти, который вы собираетесь править, движок просит перечитать его — чтобы правки не затёрли друг друга. Включён всегда.

Размер файлов и формат маркеров. Движок предупреждает, когда «горячее ядро» или урок превышают бюджет, и не даёт записать session-маркер неверного формата. Включены.

Дорогая модель суб-агента. Один раз за сессию предупреждает, если суб-агент запускается на самой сильной (дорогой) модели или без явного выбора модели. Включён.

Самопроверка настроек. На каждом старте ловит ошибки, которые ломают работу молча: опечатки в переопределениях надписей и в именах ключей, битые regex-шаблоны, даты не в ISO, шаблон закрытия задачи (task_close_pattern), отставший от дефолта движка, а также расхождение с настройками самого Claude Code — движок смотрит не в ту папку, куда пишет авто-память, или авто-память выключена и уроки писать некому. Отставший шаблон — не то же самое, что битый: он компилируется и молча работает, просто не узнаёт часть официальных слов закрытия GitHub (например, семью resolve/resolves/resolved, добавленную в 0.10.0 уже после того, как проектную копию отделили от дефолта); на осмысленную полную замену под чужой трекер задач (ни одно слово не узнано) жалоба не срабатывает. Последнее (расхождение с Claude Code) важнее всего: снаружи это выглядит как «всё хорошо, уроков просто нет». Включён.

Карта модулей

Таблица для тех, кто будет читать или дорабатывать код: какая возможность каким модулем реализована. Обычному пользователю она не нужна.

Уроки и порядок

Подсказки

Память сама себя поддерживает

Страховки

Проверить, что путь к урокам настроен верно

python3 -m claude_memory.self_check

Команда печатает картину настройки и, если что-то не так, объясняет, что поправить:

config self-check report:
  engine memory_dir : /Users/you/.claude/projects/-Users-you-proj/memory
  Claude Code memory: /Users/you/.claude/projects/-Users-you-proj/memory
  same directory    : yes
  lessons visible   : 87  [feedback: 70, project: 10, reference: 6, user: 1]
config self-check: OK

Почему это важно проверять. Файлы уроков создаёт не движок, а встроенная авто-память Claude Code — движок их читает, индексирует и сторожит. Поэтому memory_dir обязан указывать ровно туда, куда пишет Claude Code (~/.claude/projects/<slug>/memory). Если пути разойдутся, движок будет честно читать пустую папку: каталог пуст, подсказок нет, а Stop-страж требует записать урок, которого в его папке никогда не появится. Со стороны это выглядит как «всё хорошо, уроков просто пока нет» — потому и стоит проверить глазами.

Строка same directory: NO или lessons visible: 0 при непустой памяти — знак, что путь надо поправить. Начиная с 0.10.0 установщик находит папку сам, но проекты, поставленные раньше, могли получить старый дефолт ~/.claude/memory, куда не пишет никто.

Гибкость

Инфраструктура

Установка

Поставить движок можно двумя способами. Оба дают один и тот же результат и одинаково подключают хуки. Разница только в том, где лежит сам движок: своя копия внутри каждого проекта (способ A) или одна общая установка на всю машину (способ B). На то, где хранятся уроки, выбор способа не влияет.

Способ A: git + install.sh

Подходит, когда важно, чтобы проект был полностью самодостаточным: движок лежит внутри проекта, ничего внешнего.

git clone https://github.com/Arnoldig/claude-memory-engine.git
cd claude-memory-engine
./install.sh /путь/к/вашему/проекту /путь/к/папке/памяти

Скрипт install.sh кладёт движок внутрь проекта (в папку .claude/memory_engine/), ставит связующий скрипт, создаёт файл настроек, а также прописывает хуки в settings.json, не затирая чужие. Повторный запуск безопасен: дубликаты не появляются. Аргументы можно опустить: тогда проектом считается текущая папка, а каталог памяти определяется автоматически — тот, куда пишет авто-память Claude Code (~/.claude/projects/<slug>/memory).

Способ B: pip + одна команда

Подходит, когда машина одна, а проектов много: движок ставится один раз, а подключается к проектам одной командой.

pip install claude-memory-engine
claude-memory init /путь/к/вашему/проекту /путь/к/папке/памяти

Здесь движок остаётся в окружении pip и в проект не копируется; команда claude-memory init разворачивает в проект только тонкий слой: связующий скрипт, файл настроек и регистрацию хуков. Аргументы те же и так же необязательны.

Важная деталь: связующий скрипт запоминает именно тот Python, которым вы поставили пакет. Если потом сменить окружение или переустановить пакет, выполните claude-memory init ещё раз, чтобы обновить эту привязку.

Какой способ выбрать

Коротко, по одному признаку: способ A держит отдельную копию движка внутри каждого проекта (проект ни от чего внешнего не зависит), а способ B держит один общий движок на всю машину (ставить и обновлять удобно в одном месте).

Уточнение: файл настроек у каждого проекта свой (<проект>/.claude/claude-memory.config.json) при любом способе установки. Поэтому отдельная память на каждый проект настраивается одинаково и в способе A, и в способе B. Общим для всех проектов в способе B остаётся только код движка.

Уроки каждого проекта хранит встроенная авто-память Claude Code — в своём каталоге на проект (~/.claude/projects/<slug>/memory). Настройка memory_dir должна указывать именно туда; при обоих способах установки движок находит этот каталог сам.

Средствами движка общий пул уроков на все проекты не делается: движок уроков не создаёт — он читает то, что пишет Claude Code, а она по умолчанию ведёт память отдельно по каждому проекту. Если просто направить memory_dir в общую папку, движок станет читать каталог, в который никто не пишет: подсказок не будет, а страж завершения начнёт требовать урок, которого там никогда не появится.

Свести все проекты в одну папку может только сам Claude Code — настройкой autoMemoryDirectory в его settings.json. Тогда туда же нужно направить и memory_dir, и движок это поддержит штатно. Проверить свой путь: python3 -m claude_memory.self_check.

В обоих случаях хуки начинают работать со следующей сессии Claude Code.

Настройка

Все настройки лежат в файле проекта .claude/claude-memory.config.json. Сразу после установки он минимальный и содержит только пути проекта:

{
  "memory_dir": "/Users/you/.claude/projects/<slug>/memory",
  "project_root": "."
}

(у вас в этих двух строках будут реальные пути, подставленные при установке)

Менять что-либо не обязательно: из коробки всё работает на значениях по умолчанию. Чтобы настроить под себя, откройте файл любым текстовым редактором из корня проекта (вместо $EDITOR подставьте свой, например nano или code):

$EDITOR .claude/claude-memory.config.json

Если вы ставили движок через pip (способ B), есть две удобные команды: claude-memory config показывает текущие настройки, а claude-memory doctor проверяет настройки на опечатки, битые шаблоны и расхождения с настройками Claude Code.

Чтобы увидеть саму картину настройки — куда смотрит движок, куда пишет Claude Code, совпадают ли пути и сколько уроков видно, — выполните python3 -m claude_memory.self_check: он печатает отчёт всегда, даже когда всё в порядке.

Ниже частые правки в формате «было → стало». Нужные ключи добавляются в файл рядом с уже имеющимися; файл целиком не заменяется.

Перевести надписи движка на свой язык. Добавлен ключ messages. В нём каждая строка заменяет одну встроенную английскую фразу: слева имя фразы, справа ваш текст. Заменяются только указанные строки, остальные остаются английскими.

{
  "memory_dir": "/Users/you/.claude/projects/<slug>/memory",
  "project_root": ".",
  "messages": {
    "unit.chars": "символов",
    "retrieve.hook_header": "[память] Возможно полезные уроки. Прочтите нужные ДО действий:"
  }
}

Что именно меняется в этом примере:

Здесь unit.chars: слово для единицы размера, когда движок сообщает объём памяти (например, «12000 символов»). А retrieve.hook_header: заголовок, который движок печатает перед списком подсказанных уроков.

Задать свои разделы в оглавлении уроков. Добавлен ключ topic_order (слева короткое имя темы, справа заголовок раздела). По умолчанию это технические темы (workflow, testing, infra, security, docs, core); здесь заменяем их на свои.

{
  "memory_dir": "/Users/you/.claude/projects/<slug>/memory",
  "project_root": ".",
  "topic_order": [
    ["backend", "Backend"],
    ["frontend", "Frontend"],
    ["ops", "Эксплуатация и CI"]
  ]
}

Увеличить лимит «горячего ядра» (главного файла памяти). Добавлены ключи core_budget_bytes и core_size_unit. По умолчанию лимит 15000; здесь увеличиваем до 20000.

{
  "memory_dir": "/Users/you/.claude/projects/<slug>/memory",
  "project_root": ".",
  "core_budget_bytes": 20000,
  "core_size_unit": "chars"
}

Задать свою фразу закрытия сессии. Когда ваше сообщение совпадает с session_close_pattern, движок показывает чек-лист итогов памяти и проверяет уроки на устаревание. По умолчанию это английская фраза close session; здесь задаём свои формы и включаем учёт регистра (session_close_case_sensitive), чтобы строчное «done» в обычной фразе не срабатывало.

{
  "memory_dir": "/Users/you/.claude/projects/<slug>/memory",
  "project_root": ".",
  "session_close_pattern": "Туши свет|\\bDone\\b",
  "session_close_case_sensitive": true
}

Полный список всех опций со значениями по умолчанию находится в файле examples/claude-memory.config.json в репозитории.

Требования

• Python 3.9 или новее.
• Claude Code (движок работает через его хуки).
• Сторонние библиотеки не нужны: используется только стандартная библиотека Python.

Тесты и разработка

Этот раздел для тех, кто дорабатывает код движка: тесты проверяют, что после изменений всё по-прежнему работает правильно. Обычному пользователю они не нужны.

Тесты не требуют сети, внешней базы данных или Docker: только стандартная библиотека Python (их более 200). Запустить так:

pip install pytest
python3 -m pytest

Первая команда устанавливает pytest (программу, которая прогоняет тесты), вторая запускает весь набор и показывает, что всё «зелёное».

Релиз новой версии

Публикация на PyPI автоматическая — она запускается, когда на GitHub публикуется Release, а не при обычном git push. Порядок:

1. Поднять версию в claude_memory/__init__.py и pyproject.toml (два места).
2. Добавить запись в CHANGELOG.md (рус) и CHANGELOG.en.md (англ).
3. Закоммитить и запушить в main.
4. Создать релиз: gh release create vX.Y.Z --target main — дальше .github/workflows/publish.yml сам прогонит тесты, соберёт пакет и опубликует его на PyPI (Trusted Publishing, без токенов).

Пуш в GitHub сам по себе PyPI не обновляет (нужен шаг 4). Чтобы не забыть, включите разово хук-напоминалку в своём клоне:

git config core.hooksPath .githooks

Тогда .githooks/pre-push при пуше проверит: если версия пакета ещё не выпущена как тег vX.Y.Z (ни локально, ни на origin) — напечатает напоминание создать релиз. Push при этом не блокируется.

Удаление

Движок не трогает ваши уроки: папка с уроками (memory_dir) при удалении остаётся на месте.

Если ставили через pip (способ B), отключить движок в проекте можно одной командой:

claude-memory uninstall

Она убирает из проекта связующий скрипт, регистрацию хуков и файл настроек. Чтобы убрать и сам пакет из окружения: pip uninstall claude-memory-engine.

Если ставили через git (способ A), удалите вручную папку .claude/memory_engine/, файл .claude/hooks/cme_hook.sh, файл .claude/claude-memory.config.json и строки с cme_hook.sh в .claude/settings.json.

Статус

Движок стабилен и используется в реальном рабочем проекте. Вопросы, идеи и сообщения об ошибках приветствуются через Issues репозитория.

Лицензия

Apache-2.0. См. файл LICENSE.