engmem v0.1 · полный разбор

Анатомия engmem

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

Страница выведена из спецификации: при расхождении права ENGMEM-SPEC.md и тесты.

Часть 1 · Что это такое

Память, которая умеет себя измерить

Engmem — память для ИИ-агента: то, что выяснено в одной задаче, доступно ему в следующей. Хранилище, шаблоны записи, поиск и установщик — это она и есть.

Необычно в ней другое: она измеряет собственную пользу. Пре-регистрация, журнал переиспользования с дословными цитатами и телеметрия — надстройка, которая отвечает на вопрос, который памяти обычно не задают: меняет ли поднятый из прошлого документ решение в новой задаче. Ответ не должен поддаваться подгонке задним числом — поэтому измерение встроено в сам порядок работы, а не приделано к нему отчётом в конце.

Продукт стоит на трёх опорах, и порядок здесь содержательный:

  1. Единица памяти — инженерная история, и хранилище лежит вне всех репозиториев. Одна история тянется через несколько репозиториев и несколько сессий: решение принято в одном сервисе, грабли обнаружены в соседнем, договорённость — в третьем. Память, привязанная к репозиторию, режет такую историю по его границе; память, копящая отдельные факты, теряет обстоятельства, в которых факт был верен. Из этого следует всё остальное.
  2. Причинное измерение переиспользования — по документу, а не по ощущению. Как это устроено — четыре такта ниже.
  3. Ограниченный канал выдачи, который можно записать. У каждого вызова известная цена и оставленный след. В этом назначение поиска, а не в полноте выдачи.

Цикл целиком: четыре такта

Порядок обязателен для свидетельства, а не для работы. Пропущенный или переставленный такт не ломает ни задачу, ни разбор: разбор пройдёт по тому, что записано. Он лишь перестаёт быть доказательством — наивный план, написанный после чтения документов, уже ничего не доказывает.

  1. Пре-регистрация. Отдельный под-агент, которому дана только формулировка задачи, пишет наивный план до всякого поиска, и план уходит в черновик документа. Порядок здесь и есть измерение: план, написанный после чтения документов, свидетельством уже не будет. Этот такт идёт только в исследовательском режиме (engmem mode set research). По умолчанию тул работает в дневном: пре-регистрации нет, и сессия в разбор не попадает.
  2. Работа. Поиск отдаёт адреса разделов, агент читает найденное через engmem read, задача делается обычным образом. В середине engmem только выдаёт то, что агент читает, и записывает само чтение; правил он не навязывает и ничего не проверяет.
  3. Строка журнала с дословной цитатой. На каждый повлиявший документ — строка: что процитировано, что в итоге изменилось, какого рода влияние: reuse — пошли за документом, anti-reuse — сознательно против него, harmful — документ увёл не туда. Строка без цитаты недействительна; если не пригодилось ничего — пишется ровно Prior docs used: none.
  4. Разбор (Gate 1). Строки со всего хранилища сводятся в одну таблицу и читаются по правилу, записанному заранее. Документ, который не удалось прочитать, называется по имени в самом начале вывода: в таблицу он не попадает, но и не пропадает молча.

Что именно записано заранее — в ENGMEM-SPEC.md §11. Основная контрольная точка: хотя бы одно дальнее событие переиспользования на всём наборе из 4–5 межрепозиторных историй — одно на набор, а не на каждую историю. «Дальнее» определено механически, а не на глаз: цитируемый документ считается ближним, если делит с цитирующим репозиторий или тег либо связан с ним ребром related; иначе — дальним. Ближний документ вы, скорее всего, вспомнили бы и сами — кредит за него слою поиска не полагается.

Механическую часть каждой строки решает один общий модуль, src/engmem/gate1.py: целостность цитаты, дистанцию и устарелость; классификацию он не решает, а читает — её ставит тот, кто сохраняет документ. tools/verify_citations.py и tools/gate1_report.py читают один и тот же вердикт, а не проверяют независимо — расходятся они только кодом выхода: verify_citations.py падает на непроверяемой цитате и на документе, который не удалось прочитать, gate1_report.py не падает никогда и сводит все четыре оси в таблицу для человека. Пустая колонка — единственное, чего машина решить не может: изменила ли цитата решение. В счёт идут только строки, классифицированные reuse: anti-reuse и harmful печатаются в таблице, но из подсчёта исключаются — как и строка без цитаты, и строка из черновика. Туда же уходят строки из историй про сам engmem — в выдаче это ось dogfooding: разработка инструмента не может служить доказательством его пользы. Отдельно держатся и сессии, прошедшие без протокола: дневные (mode: daily) и исследовательские без наивного плана. Их строки в счёт не идут, а в итогах они стоят отдельным числом. В примере ниже так учтён один дневной документ, честно написавший Prior docs used: none.

| story | cited | quote | integrity | classification | distance | staleness | changed a decision? |
|---|---|---|---|---|---|---|---|
| 2000002-widget-cache | 1000001-response-cache | rejected the separate table because the response already carries the freshness data | verified | reuse | distant | cited_active |  |

rows: 1
citation integrity: 1 verified, 0 no quote, 0 cited doc not in store, 0 quote not found
version references: 0 row(s) cite a version and are checked against it, 1 legacy row(s) cite none and are checked against the cited document's current text, which may have changed since the quote was taken
classification: 1 reuse, 0 anti-reuse, 0 harmful, 0 classification missing, 0 classification not recognized
rows excluded from the count: 0
excluded from the count, by axis (a row may match more than one -- see the total above for the true count, not the sum of these): 0 dogfooding (story about this repository), 0 citing document not active (draft/superseded), 0 outside the experiment (mode: daily), 0 incomplete observation (baseline_unavailable), 0 research without a baseline, 0 mode not recognized
1 valid (the last column above is theirs to fill), of which 1 distant, 0 adjacent, 0 undecidable
of the 1 distant, 0 cite a superseded document (flagged, not excluded -- see the staleness column)
ENGMEM-SPEC.md section 11's primary endpoint counts the distant figure above.
documents reporting no reuse: 1 (1 more kept apart by mode -- daily, incomplete, research without a baseline or mode not recognized -- not counted)
The last column is yours where the tool left it blank.

[... continues with the audit coverage block -- see contracts/gate1.md ...]

Полный прогон печатает под этим ещё один блок — контроль полноты выборки, а не второй гейт. Инструмент сам называет две его оговорки. --session нарочно не проверяется, поэтому строка про «осиротевшие» записи считает и опечатки, и загрязнение из чужого хранилища, а не только настоящие пробелы. А telemetry.jsonl ведётся только дозаписью, без ротации, так что строки до Gate 1 и тестовые неотличимы от экспериментальных в пределах любого окна. Остальное — в docs/design/contracts/gate1.md, раздел «The audit coverage block».

Подделка ловится там же: если поправить цитату так, что она разойдётся с источником, проверка называет файл, строку и саму цитату и выходит с кодом 1. Если не читается сам документ со ссылкой, его имя стоит в первой строке вывода, и код выхода тот же. Цитата сверяется с той версией источника, которую показал поиск: строка выдачи cite as даёт ссылку вида <id>@<version>, а engmem хранит копию этой версии в versions/. Поэтому поздняя правка источника старую цитату не ломает и новую не подтверждает. Строка без версии проверяется по нынешнему тексту, как раньше, и инструмент прямо об этом пишет — как в примере ниже.

2000002-widget-cache.md:32: quote not found in 1000001-response-cache — "rejected the separate table because it would have been slower"
1 row(s) carry no version reference (legacy): checked against the cited document's current text, which may have changed since the quote was taken
verify_citations: 1 unverifiable citation(s), 0 citing a superseded document, 0 with a conflicting Reuse Log

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

Чем это не является. Не векторная база: ни эмбеддингов, ни поискового индекса, ни ранжирования по смыслу. Из производных данных между запусками хранится только кэш разбора (~/.cache/engmem или $XDG_CACHE_HOME/engmem), его можно удалить в любой момент. Не ещё один memory bank при репозитории: цикл «захватить — сжать — подставить» здесь общее место, а не продукт. Не поисковик, соревнующийся с grep: свободный grep агента по хранилищу нельзя ни ограничить по объёму, ни занести в телеметрию — измеримым канал делает именно это, а не качество выдачи.

Часть 2 · Проблема

Агент не помнит вчерашний день

Вы решаете задачу вместе с ИИ-агентом. Обсуждаете варианты, отбрасываете тупиковые, находите подводный камень, о который спотыкались бы ещё неделю. Задача закрыта, ветка влита.

Через два месяца вы возвращаетесь в ту же подсистему. Агент начинает с нуля. Он не знает, что вариант с отдельной таблицей вы уже рассматривали и отвергли — и предлагает его снова. Не знает, что повторный вызов внутри одного запроса удваивает задержку — и пишет код, который на это наступает. Не знает про договорённость с соседней командой, которой нет ни в одном тикете.

Знание было. Оно исчезло в трёх местах: в закрытом окне чата, в вашей голове (где стёрлось) и в комментариях к пул-реквесту, которые никто не перечитывает.

Важно, чего проблема не касается. Речь не про то, «как устроен код» — это видно из самого кода, и дублировать его в заметках вредно: копия устареет первой. Теряется другое: отвергнутые варианты и причины отказа, грабли, бизнес-ограничения, устные договорённости. Того, чего в коде нет и не будет.

Почему обычные способы не срабатывают

Корень у всех четырёх один — цена записи платится сейчас, а польза приходит потом и не гарантирована. Человек в этой сделке всегда проигрывает будущему себе.

СпособПочему не работает
Писать в Confluence / NotionДорого писать, ещё дороже искать: страница не всплывает сама в момент, когда нужна.
Комментарии в коде и в PRОтвечают «что делает эта строка», но не «почему мы отказались от другого решения». К моменту нужды PR давно закрыт.
ADR (записи об архитектурных решениях)Работают, но пишутся вручную и только для крупных решений. Мелкие грабли — а именно они съедают часы — туда не попадают.
Память самого агентаЖивёт в рамках одной сессии или одного продукта, не переносится между инструментами и не поддаётся проверке: нельзя открыть файл и прочитать, что там записано.

Часть 3 · Решение

Пишет агент, ищет машина, решает человек

Engmem превращает каждую закрытую задачу в один markdown-файл и автоматически поднимает нужные файлы в начале следующей.

Сделка переворачивается: писать почти бесплатно, потому что документ составляет агент из диффа и переписки — от вас нужен один ответ «y». А польза приходит сама: агенту запрещено предлагать план, пока он не поискал в прошлом.

Три части, которые делают это возможным:

  • Хранилище — папка markdown-файлов под git. Никакой базы, сервера и облака. Файл можно открыть, прочитать, поправить руками, посмотреть историю через git log.
  • Поиск — команда engmem search. Детерминированный, без ML: одинаковый запрос всегда даёт одинаковый ответ, объём выдачи ограничен сверху, и каждый вызов оставляет строку телеметрии с точной ценой в байтах. Перечитывает шапки всех документов при каждом вызове.
  • Три команды-шаблона для агента: /engmem в начале задачи, /engmem.save в конце, /engmem.save.quick — короткая запись без раунда проверки: решение, причина, отвергнутый вариант, источник и пара строк для следующей задачи. Это markdown-инструкции, а не код — поэтому работают в любом агенте.
/engmem работа /engmem.save store + 1 поднимает прошлое фиксирует новое каждый документ делает следующий старт умнее
Метрика успеха проекта — повторно использованные знания, а не количество написанных документов.

Маховик выше — это цикл для одного документа. Если отступить на шаг, хранилище — граф, который становится всё связнее. В нём два вида связей: те, что вписали вы, и те, что не писал никто. Вторые канал выдачи проводит сам — по сущностям, совпавшим у двух документов. Правило разбора считает такие пары дальними: ни общего репозитория, ни общего тега, ни ребра related — и только на них слой поиска вправе претендовать.

Часть 4 · Путь одной задачи

Что происходит от постановки до сохранения

Роль в цикле: здесь память наполняется — документ попадает в хранилище, и вместе с ним у измерения появляется предмет. Шаги 01 и 07 и есть измерительные такты (пре-регистрация и строка журнала с цитатой); всё между ними — обычная работа. Путь показан в исследовательском режиме; в дневном шага 01 нет.

Печатать вам не придётся ничего: агент проходит путь от наивного плана до готового документа, а вы подтверждаете шапку и отвечаете, отменяет ли эта работа прошлое решение. Полный save просит ещё сверить цитаты — цену этого шага страница называет прямо на 07. Ниже — по шагам: что делает инструмент, что физически попадает в контекст модели и что остаётся после. Задача: «Добавить кеширование ответов для нового эндпоинта»; похожая работа велась три месяца назад, но вы этого уже не помните. Значения сняты с прогона на тестовом хранилище.

00 01 02 03 04 05 06 07 08 09 docs: 6 → 7 самый большой шаг: в контекст входят разделы найденных документов
Что накопилось у задачи к каждому шагу — с нуля на 00 до сохранённого документа на 08. Ровные участки на 05–06 — шаги, где engmem не добавляет в контекст ничего нового; 09 держит новый уровень, но сам ничего не прибавляет.

Часть 5 · Техническая механика

Три пути через код

Роль в цикле: это код самой памяти — через который запрос превращается в ограниченную выдачу и в строку телеметрии, и которым цикл ставится на машину. Ниже — что вызывается, в каком порядке и на каких развилках.

Входа три, ядро одно — расходится лишь то, кто на другом конце читает stdout. У CLI шестнадцать подкоманд, а цикл проходит через три входа. Ниже все три функция за функцией, в порядке реального вызова: engmem search, пара install / uninstall и engmem mcp для клиентов, которые ходят через MCP: Claude Desktop, Codex, ChatGPT. Порядок здесь не формальность: в T4 разобран баг, который виден только из очерёдности трёх вызовов и которого список из десяти функций не показал бы вовсе.

Путь 1 — engmem search: от команды до вывода

Тот же поиск из шага 03, изнутри; значения сняты с прогона ResponseCacheController ETAG revalidation по хранилищу из 8 файлов. Развилок три, и ни одна не имеет права отменить уже готовый ответ.

_cmd_search resolve_store load_store search render_* render_scoreboard log_search cli.py store не найдено? spine.py scoring.py output.py всегда — hit или miss telemetry.py sessions/ нет → fail, код выхода 2 draft — скрыт из выдачи; superseded — редирект на преемника запись не удалась → заметка в stdout, не сбой
render_scoreboard печатается после render_* на обеих ветках — hit или miss не влияет на то, покажется ли он. Обрыв записи телеметрии не отменяет уже напечатанный результат: log_search никогда не бросает исключение.

Путь 2 — engmem install / uninstall: шесть режимов агента

Единственный путь, который трогает файлы за пределами хранилища. Развилка одна на обе команды: --agent выбирает один из шести режимов, у каждого свой каталог и свой формат следа.

cmd_install / cmd_uninstall --local / copilot-ide без .git → код 2, ничего не тронуто agent=claude agent=copilot-ide agent=copilot-cli agent=claude-desktop agent=codex agent=chatgpt ~/.claude/commands + CLAUDE.md, сентинел-правило .github/prompts/*.prompt.md + copilot-instructions.md ~/.copilot/skills/*/SKILL.md правило не пишется claude_desktop_config.json слияние mcpServers.engmem ~/.agents/skills + AGENTS.md блок в config.toml на диск не пишет печатает шаги туннеля
Uninstall проходит той же развилкой и тем же стражем каталога, но снимает ровно то, что установил install — вплоть до узкого совпадения сентинела, а не широкого маркера, которым install решает, добавлять ли правило.

Путь 3 — сессия MCP: engmem mcp, вход для MCP-клиентов

Тот же поиск, что в пути 1, но по протоколу, где stdout — не текст для человека, а кадры JSON-RPC. Поиск здесь только часть входа. Сервер отдаёт восемь инструментов. Два ищут, три пишут документ (создают черновик, закрывают его, помечают документ устаревшим), один записывает вашу оценку находки (engmem_record_feedback), один читает документ (engmem_read), и ещё один записывает цифры базового прогона, которые сообщил клиент (engmem_record_baseline). К ним три промпта, по одному на шаблон. Промпт engmem на каждом вызове начинается со строки engmem mode for this session: …, а engmem_create_draft отказывает черновику, чей mode расходится с настроенным. Файл режима перечитывается на каждый вызов, так что engmem mode set подхватывается без перезапуска; новый код engmem клиент получит, только когда запустит сервер заново. С флагом --read-only сервер отдаёт лишь два инструмента поиска — это для сервера, до которого можно достучаться снаружи машины. Флаг запрещает запись, но читать не мешает: кто достучался до сервера, тот и ищет по хранилищу. Такой поиск пишет строку телеметрии, но не хранит копий версий, не печатает cite as и ничего не пишет в cost.jsonl.

невалидный JSON → PARSE_ERROR serve(): читает строку stdin json.loads(line) _dispatch(msg) _write(stdout), если есть ответ initialize notifications/ initialized tools/list tools/call prompts/list prompts/get _run_search_for_tool → load_store → search → render_* → render_scoreboard на этом пути «fail()» под запретом — stdout несёт только протокол, ни одной лишней строки
Шесть обработчиков из семи расходятся из одной точки разбора — седьмой, ping, не нарисован; tools/call для engmem_search сходится назад — на то же ядро из трёх функций, которым пользуется engmem search на пути 1.

Часть 6 · Установка и удаление

Две команды поставить, одна убрать

Роль в цикле: установка — то, чем цикл переносится на новую машину. Она кладёт шаблоны, которые пишут журнал переиспользования, а в исследовательском режиме ещё и пре-регистрацию, и правило, обязывающее агента пройти измеряемый канал до того, как он предложит план.

Первая команда ставит сам пакет, вторая подключает его к вашему агенту:

uv tool install --editable .     # или: pipx install .
engmem install --agent claude    # или copilot-ide / copilot-cli / claude-desktop / codex / chatgpt

Инструменты разбора из tools/ в пакет не входят. Они лежат в клоне репозитория и запускаются из любой папки через него:

uv run --project <engmem-checkout> python <engmem-checkout>/tools/verify_citations.py --store <store>

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

--editable означает, что после git pull новый код подхватится сам, без переустановки — для инструмента, который сейчас активно правится, это важнее «красивой» установки.

Режим установки диктует агент-потребитель: у каждого свой каталог и свой формат файла.

РежимКуда кладётКогда выбирать
claude~/.claude/commands/engmem.mdClaude Code. Имя файла становится именем команды — отсюда /engmem. С флагом --local — в текущий репозиторий (нужен уже существующий .git в этой папке, иначе выход с кодом 2).
copilot-ide.github/prompts/engmem.prompt.mdПлагин Copilot в VS Code, Visual Studio, JetBrains. Он распознаёт только двойное расширение .prompt.md, обычный .md молча игнорирует. Тоже пишет в текущий репозиторий — нужен .git здесь, иначе выход с кодом 2.
copilot-cli~/.copilot/skills/engmem/SKILL.mdТерминальный copilot. Он не читает .github/prompts/ вообще, только навыки. Точки в именах запрещены, поэтому команды здесь /engmem-save, а не /engmem.save.
claude-desktopclaude_desktop_config.json, ключ mcpServers.engmemПриложение Claude Desktop. Shell у него нет, поэтому и шаблонов нет: engmem подключается как MCP-сервер, и те же команды приходят промптами. После обновления engmem приложение нужно закрыть совсем и открыть заново.
codex~/.agents/skills/engmem/SKILL.md, ~/.codex/AGENTS.md, ~/.codex/config.tomlCodex: CLI, расширение для IDE и приложение. Ставит оба канала сразу: навыки $engmem, $engmem-save, $engmem-save-quick для shell и MCP-сервер там, где shell нет. Песочница Codex по умолчанию не даёт CLI писать в хранилище вне репозитория: добавьте его в writable_roots или подтверждайте каждую запись.
chatgptничего на дискеChatGPT. Печатает команды Secure MCP Tunnel, через которые ChatGPT достаёт до engmem mcp на вашей машине.

Что install создаёт на самом деле

Четыре следа в трёх местах — знать их полезно, потому что именно они потом удаляются:

  • хранилище (~/Developer/engmem по умолчанию): папка sessions/ и git init, если репозитория ещё нет. Существующее не трогается;
  • три файла шаблонов в каталоге агента из таблицы выше;
  • штамп версии первой строкой после YAML-шапки каждого шаблона — по нему видно, какая версия установлена;
  • триггер-правило в CLAUDE.md, .github/copilot-instructions.md или, у Codex, в AGENTS.md — на самом деле две строки: сентинел-комментарий <!-- engmem-trigger-rule --> и сама строка правила сразу под ним: Before proposing a plan, run `engmem search "<key terms for the task>" --session <draft-id>` (the draft `/engmem` just created; without it the search is unattributed). Сентинел здесь не для красоты — именно по нему uninstall потом находит и убирает ровно эти две строки и ничего больше. Для copilot-cli этот шаг пропускается — глобального файла инструкций у него нет, навыки вызываются вручную; у claude-desktop и chatgpt файла с правилом тоже нет.

Повторный запуск — это upgrade: хранилище не пересоздаётся, шаблоны перезаписываются свежей версией, правило не дублируется (проверка идёт по маркеру engmem search, так что даже переформулированное вами правило распознаётся). Шаблон, который вы поправили, не перезаписывается: в штампе лежит дайджест текста, который записал engmem, поэтому install видит правку, оставляет ваш файл, кладёт новую версию рядом как <файл>.engmem-new и выходит с кодом 2, назвав оба пути.

Режим, хранилище и проверка

У тула два однострочных файла настроек, оба в ~/.config/engmem/ ($XDG_CONFIG_HOME/engmem/, в Windows — %APPDATA%\engmem\): store — путь к хранилищу, его пишет только engmem store set, и mode — режим, его пишет только engmem mode set. install не пишет ни тот, ни другой. Удалили файл — настройка вернулась к умолчанию.

В самом хранилище рядом с sessions/ со временем появляются файлы, которые пишет тул: telemetry.jsonl — строка на каждый поиск, versions/ — копии показанных версий документов (с .gitattributes, чтобы git не переписывал в них концы строк), feedback.jsonl — ваши оценки находок, cost.jsonl — размеры ответов поиска и чтения, без самого текста. Сводки по двум последним печатают engmem feedback summary и engmem cost summary --session <id>.

engmem mode set research   # следующие сессии идут по протоколу Gate 1
engmem mode show           # режим и откуда он взят
engmem store show          # какое хранилище в работе и куда смотрят MCP-записи

По умолчанию режим дневной: /engmem не пишет пре-регистрацию, не запускает под-агента, и сессия в разбор не попадает. Исследовательский режим — это цикл из части 1 целиком. Режим записывается в черновик и потом не меняется, так что переключение действует со следующей сессии. Если файл режима не читается, молча это не проходит: engmem mode show выходит с кодом 2 и называет файл, агент говорит вам об ошибке, и сессия идёт в дневном режиме, единственном, который не может испортить эксперимент. Пока файл не исправлен (engmem mode set daily|research), MCP-инструмент принимает только дневные черновики. После обновления с версии без режимов install нужно запустить заново для каждого агента: старые шаблоны пишут черновик без mode, и MCP-инструмент его не примет.

У Claude Desktop нет shell, поэтому режим ставят один раз из терминала. Переменные из профиля shell приложение не видит: если XDG_CONFIG_HOME задан только в терминале, mode set запишет файл, который сервер Desktop не прочитает.

Если агент не видит память и непонятно почему, engmem doctor --agent <агент> проверяет установку этого клиента и ничего не меняет: хранилище и откуда оно взято, чтение и запись в sessions/ (одним пробным файлом, который сразу удаляется), команду engmem и Python из MCP-записи, шаблоны и то, совместим ли записанный в них порядок работы с этой версией (несовместимый — это error), правило, то, смотрят ли CLI и MCP в одно хранилище, и какую версию engmem последним вызовом записал в лог запущенный MCP-сервер: клиент держит старый сервер, пока его не перезапустят. На каждую проверку строка: ok, warning, error или unverified. Песочницу самого клиента doctor изнутри не видит, поэтому ok про неё не бывает. Код выхода 1, если нашлась хоть одна error.

Чтобы один раз пройти цикл целиком до того, как класть в хранилище свою историю, есть engmem walkthrough codex --dir ~/engmem-demo. Команда собирает в этой папке демо-хранилище, свой CODEX_HOME для Codex и маленький репозиторий с примером, проверяет их через doctor и печатает, что набрать в Codex: первая сессия сохраняет решение, вторая находит его снова. Ваше хранилище и ~/.codex она не трогает. В демо-папке Codex попросит войти ещё раз: ваш логин туда не копируется. engmem walkthrough handoff --dir ~/engmem-handoff делает то же для двух клиентов сразу: Codex сохраняет решение, Claude Code в соседнем репозитории находит его и сохраняет своё, а новая сессия Codex находит это второе по id. Хранилище у них одно, папки разные. Потом --verify с той же --dir проверяет по демо-хранилищу, что запись сохранилась и другая сессия её нашла. У handoff он сначала сверяет, что оба клиента смотрят в одно хранилище, и если нет, называет оба и дальше не проверяет.

Чтобы отдать коллеге одно решение и не отдать вместе с ним всё хранилище, есть engmem export <id>. Первый запуск только показывает: весь текст будущего файла, список того, что вырезано, и отпечаток этих байтов. Ссылки на другие ваши документы и локальные пути заменяются на [excluded reference]: id и имена файлов других документов, журнал переиспользования целиком (он цитирует другие документы), заголовки документов, на которые этот ссылается, и заголовки остальных, если в них хотя бы два слова. Поля шапки вне короткого списка, related и superseded_by в их числе, в файл не попадают вовсе. Заголовок из одного слова, на который никто не ссылается, обычно просто слово, поэтому он остаётся. Имена репозиториев, коммиты и ссылки на PR остаются: по ним решение можно проверить. Файл пишет второй запуск, engmem export <id> --out <файл> --confirm <отпечаток>, и только если текст с тех пор не поменялся. Существующий файл он не перезаписывает, внутрь хранилища не пишет, черновики не отдаёт. Хранилище после этого байт в байт то же, по сети ничего не уходит. MCP-инструмента для экспорта нет, так что сам агент вынести документ из хранилища не может.

Удаление

Зеркальная команда с тем же --agent:

engmem uninstall --agent claude

Она удаляет ровно те файлы, что ставила, и убирает ровно те строки триггер-правила, которые сама написала — сентинел-комментарий и строку правила сразу под ним (а для установок постарше, без сентинела, — саму строку правила, побайтово). Совпадение узкое и точное — почему не широкое, разобрано в пути 2. Реальный вывод:

engmem uninstalled: 3 template file(s) removed, 2 trigger rule line(s) removed, agent=claude
store left untouched: /Users/…/Developer/engmem  (your documents — remove it yourself if you want)

Запускать повторно безопасно — второй раз вернёт нули.

Чего она принципиально не делает:

  • не трогает хранилище. Это ваши документы, а не файлы инструмента: они остаются читаемым markdown в git и без engmem. Команда лишь печатает путь, чтобы вы решили сами;
  • не удаляет чужое. Каталог навыка Copilot сносится, только если после удаления SKILL.md он пуст; посторонние строки в CLAUDE.md сохраняются, сам файл не удаляется, даже если опустел;
  • не удаляет сам пакет — команда engmem остаётся в PATH.

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

engmem uninstall --agent claude   # шаблоны и триггер-правило
uv tool uninstall engmem          # сам пакет и команда в PATH
rm -rf ~/.config/engmem           # настройки store и mode (в Windows — %APPDATA%\engmem)
rm -rf ~/.cache/engmem            # кэш разбора, его можно удалить в любой момент
rm -rf ~/Developer/engmem         # документы, журналы и копии версий — только если точно не нужны

Демо из engmem walkthrough удаляется вместе со своей папкой: хранилище, настройки Codex и репозитории лежат внутри неё. Снаружи остаются только следы самих сессий. Кэш разбора у демо общий с вашим хранилищем, и поиск по демо может выкинуть из кэша записи ваших документов; следующий ваш поиск их пересоберёт. А после handoff Claude Code сам, как для любой папки, помнит доверие к storefront/ в ~/.claude.json и хранит транскрипт в ~/.claude/projects/.

Часть 7 · Границы

Почему эта память такая скупая

Engmem — это память; скупа она намеренно, потому что главный вопрос о ней пока открыт: поднятые в новую задачу прошлые документы измеримо меняют её результат, и выгода превышает цену записи. Пока это не проверено, каждая лишняя функция — вложение в недоказанное. Ответ даёт разбор через 3–4 недели работы, по контрольным точкам, записанным до данных (ENGMEM-SPEC.md §11). Отсюда все ограничения — условия чистоты опыта.

ОграничениеЧто защищает
Две зависимости, стандартный CLI, никаких фич «на вырост»Минимум вложений до вердикта: не подтвердится — выбросить дёшево.
Детерминированный поиск, эталонные тесты как истинаВоспроизводимость датчика: канал, дающий на один запрос разные ответы, нельзя ни сравнить с базовым уровнем, ни осмысленно записать. «Вчера находило, сегодня нет» невозможно по построению.
Инструмент не делает сетевых вызововСвойство самого инструмента, но не всей системы: содержимое документов уходит в модель на каждой задаче — это вопрос к согласованию, а не решённый. ChatGPT вдобавок ходит к хранилищу через мост. Кого пускать в туннель, решает OpenAI, engmem это не проверяет; публичный мост не защищён вовсе (docs/remote-access.md).
Приборы измерения нельзя упрощатьЖурнал переиспользования, pre-reg, телеметрия, скорборд. Выключить их — провести опыт без данных.

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

Где смотреть код: модули в src/engmem/, шаблоны в src/engmem/templates/, контракты поведения в docs/design/contracts/, эталонные тесты в tests/search/test_scoring.py и tests/test_cli.py.

engmem v0.1 · full walkthrough

The Anatomy of engmem

Memory for an AI coding agent: decisions, landmines and agreements stop getting lost between tasks. And unlike other such memories, this one can show whether it helps.

This page is derived from the specification: where they disagree, ENGMEM-SPEC.md and the tests are right.

Part 1 · What it is

Memory that can measure itself

Engmem is memory for an AI coding agent: what you worked out in one task is available to it in the next. The store, the capture templates, the search and the installer are that memory.

What is unusual is the rest: it measures its own worth. Pre-registration, a Reuse Log of verbatim quotes, and telemetry are the layer that answers the question memory is rarely asked — does a document pulled out of the past change a decision in a new task? The answer must not be adjustable after the fact, so the measurement is built into the order of the work, not bolted on as a report at the end.

The product stands on three legs, and the order is the argument:

  1. The unit of memory is an engineering story, and the store lives outside every repository. One story spans several repositories and several sessions: the decision is made in one service, the landmine is found in the next, the agreement is recorded in a third. Memory tied to a repository cuts such a story along the repository boundary; memory that hoards isolated facts loses the circumstances in which the fact was true. Everything else follows from this.
  2. Causal reuse measurement — per document, not per feeling. How that works is the four beats below.
  3. A bounded retrieval channel that can be logged. Every call has a known cost and leaves a trace. That is what search is for — not the completeness of its results.

The loop end to end: four beats

The order is required for the evidence, not for the work. A skipped or reordered beat breaks neither the task nor the review — the review runs on whatever was recorded. It simply stops proving anything: a naive plan written after reading the documents proves nothing.

  1. Pre-registration. A separate sub-agent, given nothing but the task statement, writes the naive plan before any search runs, and the plan goes into the draft document. The order is the measurement: a plan written after the documents are read is no longer evidence. This beat runs in research mode only (engmem mode set research). By default the tool runs in daily mode: no pre-registration, and the session stays out of the review.
  2. The work. Search hands back section addresses, the agent reads what it found through engmem read, the task proceeds as it normally would. In the middle, engmem only hands out what the agent reads and records the read; it imposes no rules and runs no checks.
  3. A Reuse Log row with a verbatim quote. One row per influencing document: what was quoted, what changed as a result, and what kind of influence it was: reuse — the work followed the document, anti-reuse — it deliberately went against it, harmful — the document led it astray. A row without a quote is invalid; if nothing was of use, the line written is exactly Prior docs used: none.
  4. The review (Gate 1). Rows from the whole store are collected into one table and read against a rule written down in advance. A document that could not be read is named at the very top of the output: it gets no row, and it does not vanish quietly either.

What was written down in advance lives in ENGMEM-SPEC.md §11. The primary endpoint: at least one distant reuse event across a set of 4–5 cross-repository stories — one across the set, not one per story. "Distant" is defined mechanically rather than felt: a cited document is adjacent if it shares a repository or a tag with the citing one, or is reachable from it through one related edge; otherwise it is distant. An adjacent document is one you would plausibly have remembered anyway — the retrieval layer gets no credit for it.

One shared module, src/engmem/gate1.py, decides the mechanical part of every row — citation integrity, distance and staleness; classification it does not decide but reads, since whoever saves the document sets it. tools/verify_citations.py and tools/gate1_report.py read that same verdict rather than checking independently; they differ only in what happens with it — verify_citations.py fails the run on an unverifiable quote and on a document it could not read, gate1_report.py never fails and renders all four axes into a table for the human. Its empty column is the one thing a machine cannot decide: whether the quote changed a decision. Only rows classified reuse reach the count: anti-reuse and harmful are printed in the table but excluded from it, as are a row without a quote and a row from a draft. So are rows from stories about engmem itself — the dogfooding axis in the output: building the tool cannot be evidence that the tool helps. Sessions that ran without the protocol are kept apart as well: daily ones (mode: daily) and research ones without a naive plan. Their rows are not counted, and the summary shows them as a separate figure. In the sample below that is one daily document that honestly wrote Prior docs used: none.

| story | cited | quote | integrity | classification | distance | staleness | changed a decision? |
|---|---|---|---|---|---|---|---|
| 2000002-widget-cache | 1000001-response-cache | rejected the separate table because the response already carries the freshness data | verified | reuse | distant | cited_active |  |

rows: 1
citation integrity: 1 verified, 0 no quote, 0 cited doc not in store, 0 quote not found
version references: 0 row(s) cite a version and are checked against it, 1 legacy row(s) cite none and are checked against the cited document's current text, which may have changed since the quote was taken
classification: 1 reuse, 0 anti-reuse, 0 harmful, 0 classification missing, 0 classification not recognized
rows excluded from the count: 0
excluded from the count, by axis (a row may match more than one -- see the total above for the true count, not the sum of these): 0 dogfooding (story about this repository), 0 citing document not active (draft/superseded), 0 outside the experiment (mode: daily), 0 incomplete observation (baseline_unavailable), 0 research without a baseline, 0 mode not recognized
1 valid (the last column above is theirs to fill), of which 1 distant, 0 adjacent, 0 undecidable
of the 1 distant, 0 cite a superseded document (flagged, not excluded -- see the staleness column)
ENGMEM-SPEC.md section 11's primary endpoint counts the distant figure above.
documents reporting no reuse: 1 (1 more kept apart by mode -- daily, incomplete, research without a baseline or mode not recognized -- not counted)
The last column is yours where the tool left it blank.

[... continues with the audit coverage block -- see contracts/gate1.md ...]

The full run prints a second block beneath this one — sample-completeness audit coverage, not another gate. The tool states two standing caveats of its own. --session is deliberately unvalidated, so the orphan-row figure also counts typos and cross-store contamination, not only genuine gaps. And telemetry.jsonl is append-only with no rotation, so pre-Gate-1 and testing rows are indistinguishable from experimental ones within whatever window is in force. See docs/design/contracts/gate1.md, "The audit coverage block," for the rest.

Fabrication is caught in the same place: edit a quote so it drifts from its source, and the check names the file, the line and the quote itself, and exits 1. If the citing document itself cannot be read, its name is the first line of the output, with the same exit code. A quote is checked against the version of its source that the search showed: the result's cite as line gives a reference of the form <id>@<version>, and engmem keeps a copy of that version under versions/. So a later edit to the source neither breaks the old quote nor confirms a new one. A row without a version is checked against the current text, as before, and the tool says so — as in the sample below.

2000002-widget-cache.md:32: quote not found in 1000001-response-cache — "rejected the separate table because it would have been slower"
1 row(s) carry no version reference (legacy): checked against the cited document's current text, which may have changed since the quote was taken
verify_citations: 1 unverifiable citation(s), 0 citing a superseded document, 0 with a conflicting Reuse Log

The reading of the result is fixed in advance too. If the primary endpoint is missed while the secondaries hold, the verdict reads: the store as compressed context earned its keep, the measurement superstructure did not — and the superstructure gets wound down. A miss is a result, not grounds for softening the criterion and trying again.

What this is not. Not a vector database: no embeddings, no search index, no ranking by meaning. The only derived data kept between runs is a parse cache (~/.cache/engmem, or $XDG_CACHE_HOME/engmem), safe to delete at any time. Not another repository-side memory bank: the capture→compress→inject loop is common ground here, not the product. Not a search engine competing with grep: an agent's free-form grep over the store can neither be capped in volume nor written to telemetry — and that, rather than result quality, is what makes a channel measurable.

Part 2 · The problem

Your agent doesn't remember yesterday

You solve a task with an AI agent. You weigh options, discard the dead ends, uncover a pitfall that would have cost you another week. The task closes, the branch merges.

Two months later you're back in the same subsystem. The agent starts from zero. It doesn't know you already considered a separate table for cache metadata and rejected it — so it proposes exactly that again. It doesn't know a repeated lookup inside one request doubles the latency — so it writes code that walks straight into it. It doesn't know about the agreement with the neighbouring team that lives in no ticket at all.

The knowledge existed. It vanished in three places: a closed chat window, your own memory (where it faded), and pull-request comments nobody ever re-reads.

What the problem is not about. Not "how the code works" — that's visible in the code, and copying it into notes is actively harmful: the copy goes stale first. What gets lost is different: rejected options and the reasons for rejecting them, pitfalls, business constraints, verbal agreements. The things that aren't in the code and never will be.

Why the usual answers fail

All four share one root cause: the cost of writing is paid now, the benefit arrives later and isn't guaranteed. In that trade, the present self always beats the future one.

ApproachWhy it doesn't hold
Write it in Confluence / NotionExpensive to write, more expensive to find: the page never surfaces itself at the moment it's needed.
Comments in code and PRsThey answer "what does this line do", never "why did we reject the alternative". By the time you need it, the PR is long closed.
ADRs (architecture decision records)They work, but they're written by hand and only for big decisions. The small traps — the ones that actually eat hours — never make it in.
The agent's own memoryScoped to one session or one vendor, doesn't travel between tools, and can't be inspected: you can't open a file and read what it holds.

Part 3 · The solution

The agent writes, the machine searches, the human decides

Engmem turns every closed task into one markdown file, and automatically surfaces the right files at the start of the next one.

That inverts the trade: writing is nearly free, because the agent composes the document from the diff and the conversation — all you supply is a single "y". And the benefit arrives on its own: the agent is forbidden to propose a plan before it has searched the past.

Three parts make that possible:

  • The store — a folder of markdown files under git. No database, no server, no cloud. You can open a file, read it, fix it by hand, inspect its history with git log.
  • The search — the engmem search command. Deterministic, no ML: the same query always yields the same answer, the result has a fixed ceiling, and every call leaves a telemetry line carrying its exact cost in bytes. It re-reads every document's header on every call.
  • Three template commands for the agent: /engmem at the start of a task, /engmem.save at the end, /engmem.save.quick for a short record with no review round: the decision, its reason, the rejected alternative, the source and a few lines for the next task. They're markdown instructions rather than code — which is why they work in any agent.
/engmem the work /engmem.save store + 1 surfaces the past captures the new every document makes the next start smarter
The project's measure of success is knowledge actually reused — not the number of documents written.

The flywheel above traces the loop for one document. Zoom out, and the store is a graph that keeps getting more connected. Two kinds of edge sit side by side in it: the ones you wrote, and the ones nobody wrote. The retrieval channel carries the second kind on its own, through entities two documents happen to share. The review rule counts such a pair as distant — no shared repository, no shared tag, no related edge — and those are the only ones the retrieval layer may claim credit for.

Part 4 · One task, end to end

From the ask to the saved document

Its role in the loop: this is how the memory fills up — a document reaches the store, and with it the measurement acquires something to measure. Steps 01 and 07 are the measuring beats themselves (pre-registration and the quoted Reuse Log row); everything between them is ordinary work. The path is shown in research mode; in daily mode there is no step 01.

You type nothing: the agent walks the path from the naive plan to the finished document, and you confirm the header and answer whether this work supersedes an earlier decision. A full save also asks you to check the quotes — step 07 names the cost of that plainly. Below, step by step: what the tool does, what physically lands in the model's context, and what remains afterwards. The task: "Add response caching for a new endpoint"; similar work happened three months ago, but you no longer remember it. Every value was captured from a live run against a test store.

00 01 02 03 04 05 06 07 08 09 docs: 6 → 7 the biggest single step: sections of the found documents enter the context
What the task has accumulated by each step — from nothing at 00 to a saved document at 08. The flat stretch at 05–06 marks steps where engmem adds nothing new to the context; 09 holds the new level but doesn't add to it either.

Part 5 · The machinery

Three paths through the code

Its role in the loop: this is the memory's own code — what turns a query into a bounded result and a telemetry line, and what puts the loop on a machine. Below: what gets called, in what order, and at which branch points.

Three entry points, one core — what diverges is only who reads stdout at the other end. The CLI has sixteen subcommands; the loop runs through three entry points. Below are all three, function by function, in the order they actually run: engmem search, the install / uninstall pair, and engmem mcp for clients that come in over MCP: Claude Desktop, Codex, ChatGPT. Order here is not a formality: T4 dissects a bug visible only from the sequence of three calls, one a list of ten functions would never have shown.

Path 1 — engmem search: from the command to the output

The same search from step 03, from the inside; the values come from running ResponseCacheController ETAG revalidation against a store of 8 files. There are three branch points, and none of them may discard an answer that's already built.

_cmd_search resolve_store load_store search render_* render_scoreboard log_search cli.py store missing? spine.py scoring.py output.py always — hit or miss telemetry.py sessions/ missing → fail, exit code 2 draft — hidden from results; superseded — redirected to successor write fails → stdout note, not a crash
render_scoreboard prints after render_* on both branches — a hit or a miss doesn't change whether it appears. A telemetry write failure never unprints the result already shown: log_search never raises.

Path 2 — engmem install / uninstall: six agent modes

The only path that touches files outside the store. Both commands share one fork: --agent picks one of six modes, each with its own directory and its own trace shape.

cmd_install / cmd_uninstall --local / copilot-ide, no .git → exit 2, nothing touched agent=claude agent=copilot-ide agent=copilot-cli agent=claude-desktop agent=codex agent=chatgpt ~/.claude/commands + CLAUDE.md, sentinel rule .github/prompts/*.prompt.md + copilot-instructions.md ~/.copilot/skills/*/SKILL.md no trigger rule written claude_desktop_config.json merges mcpServers.engmem ~/.agents/skills + AGENTS.md a block in config.toml writes nothing to disk prints the tunnel steps
Uninstall walks the same fork and the same directory guard, but removes exactly what install wrote — down to the narrow sentinel match, not the broad marker install uses to decide whether to add the rule.

Path 3 — an MCP session: engmem mcp, the entry point for MCP clients

The same search as path 1, but over a protocol where stdout isn't text for a human — it's JSON-RPC frames. Search is only part of this entry point. The server exposes eight tools. Two search, three write a document (create a draft, complete it, mark a document superseded), one records your assessment of a find (engmem_record_feedback), one reads a document (engmem_read), and one more records the baseline figures the client reported (engmem_record_baseline). On top come three prompts, one per template. The engmem prompt opens with engmem mode for this session: … on every call, and engmem_create_draft refuses a draft whose mode differs from the configured one. The mode file is read again on every call, so engmem mode set takes effect without a restart; new engmem code reaches the client only when it starts the server again. With --read-only the server exposes just the two search tools — meant for a server reachable from outside the machine. It refuses writes and does not limit who reads: whoever reaches the server still searches the store. Such a search writes its telemetry row, but keeps no version copies, prints no cite as and writes nothing to cost.jsonl.

invalid JSON → PARSE_ERROR serve(): reads a stdin line json.loads(line) _dispatch(msg) _write(stdout), if there's a reply initialize notifications/ initialized tools/list tools/call prompts/list prompts/get _run_search_for_tool → load_store → search → render_* → render_scoreboard «fail()» is banned on this path — stdout carries protocol only, never one extra line
Six of the seven handlers fan out from one dispatch point — the seventh, ping, is not drawn; tools/call for engmem_search folds back onto the same three-function core that engmem search uses on path 1.

Part 6 · Install and removal

Two commands to set up, one to undo

Its role in the loop: installation is how the loop travels to a new machine. It lays down the templates that write the Reuse Log, and in research mode the pre-registration too, and the rule that obliges the agent to go through the measured channel before it proposes a plan.

The first command installs the package itself; the second wires it into your agent:

uv tool install --editable .     # or: pipx install .
engmem install --agent claude    # or copilot-ide / copilot-cli / claude-desktop / codex / chatgpt

The review tools in tools/ are not part of the package. They live in the repository checkout and run from any directory through it:

uv run --project <engmem-checkout> python <engmem-checkout>/tools/verify_citations.py --store <store>

Installing carries the first steps of the loop to a new machine; the review needs the checkout as well.

--editable means a git pull picks up new code without reinstalling — for a tool under active repair that matters more than a tidy install.

The mode is dictated by the consuming agent: each has its own directory and its own file format.

ModeWrites toWhen to pick it
claude~/.claude/commands/engmem.mdClaude Code. The file name becomes the command name — hence /engmem. With --local, into the current repository instead (needs an existing .git there already, or it exits 2).
copilot-ide.github/prompts/engmem.prompt.mdThe Copilot plugin in VS Code, Visual Studio, JetBrains. It only recognizes the double extension .prompt.md; a plain .md is silently ignored. Also writes into the current repository — needs a .git here, or it exits 2.
copilot-cli~/.copilot/skills/engmem/SKILL.mdThe terminal copilot. It doesn't read .github/prompts/ at all, only skills. Dots are illegal in skill names, so the commands there are /engmem-save, not /engmem.save.
claude-desktopclaude_desktop_config.json, key mcpServers.engmemThe Claude Desktop app. It has no shell, so there are no templates either: engmem connects as an MCP server, and the same commands arrive as prompts. After upgrading engmem, quit the app completely and reopen it.
codex~/.agents/skills/engmem/SKILL.md, ~/.codex/AGENTS.md, ~/.codex/config.tomlCodex: the CLI, the IDE extension and the app. Wires both channels at once: the skills $engmem, $engmem-save, $engmem-save-quick for the shell, and the MCP server where there is none. Codex's default sandbox keeps the CLI from writing to a store outside the repository: add the store to writable_roots, or approve each write.
chatgptnothing on diskChatGPT. Prints the Secure MCP Tunnel commands through which ChatGPT reaches engmem mcp on your machine.

What install actually creates

Four traces across three places — worth knowing, because these are exactly what gets removed later:

  • the store (~/Developer/engmem by default): a sessions/ folder and git init if it isn't a repository yet. An existing one is left alone;
  • three template files in the agent directory from the table above;
  • a version stamp on the first line after each template's YAML front matter — that's how you see which version is installed;
  • the trigger rule in CLAUDE.md, .github/copilot-instructions.md or, for Codex, AGENTS.md — actually two lines: a <!-- engmem-trigger-rule --> sentinel comment, then the rule itself right below it: Before proposing a plan, run `engmem search "<key terms for the task>" --session <draft-id>` (the draft `/engmem` just created; without it the search is unattributed). The sentinel is not decoration — it is exactly what uninstall later matches to remove precisely those two lines and nothing else. copilot-cli skips this step — it has no global instructions file, and skills are invoked by hand; claude-desktop and chatgpt have no rule file either.

A repeat run is an upgrade: the store isn't recreated, templates are overwritten with the fresh version, and the rule isn't duplicated (detection goes by the engmem search marker, so even a rule you reworded is recognized). A template you edited is not overwritten: the stamp holds a digest of the text engmem wrote, so install sees the edit, leaves your file, puts the new version beside it as <file>.engmem-new and exits 2 with both paths.

Mode, store and checking the setup

The tool has two one-line setting files, both in ~/.config/engmem/ ($XDG_CONFIG_HOME/engmem/; %APPDATA%\engmem\ on Windows): store, the store path, written only by engmem store set, and mode, written only by engmem mode set. install writes neither. Delete a file and that setting returns to its default.

Inside the store, next to sessions/, the tool writes more files over time: telemetry.jsonl, one line per search; versions/, copies of the document versions it showed (with a .gitattributes so git does not rewrite their line endings); feedback.jsonl, your assessments of finds; cost.jsonl, the size of each search and read response, never the text. engmem feedback summary and engmem cost summary --session <id> print the summaries of the last two.

engmem mode set research   # sessions from now on run the Gate 1 protocol
engmem mode show           # the mode, and where it came from
engmem store show          # the store in use, and where the MCP entries point

The default mode is daily: /engmem writes no pre-registration, launches no sub-agent, and the session stays out of the review. Research mode is the whole loop from part 1. The mode is written into the draft and never changes after, so a switch applies from the next session. A mode file that cannot be read never passes silently: engmem mode show exits 2 and names the file, the agent tells you about the error, and the session runs in daily mode, the one mode that cannot spoil the experiment. Until the file is fixed (engmem mode set daily|research), the MCP tool accepts only daily drafts. After upgrading from a version without modes, re-run install for every agent: old templates write a draft without mode, and the MCP tool refuses it.

Claude Desktop has no shell, so the mode is set once from a terminal. The app does not see variables from your shell profile: if XDG_CONFIG_HOME is set only in the terminal, mode set writes a file the Desktop server never reads.

When an agent does not see its memory and you cannot tell why, engmem doctor --agent <agent> checks that client's setup and changes nothing: the store and where it came from, reading and writing sessions/ (with one probe file, removed at once), the engmem command and the MCP entry's Python, the templates and whether the workflow they describe is one this version runs (an incompatible one is an error), the rule, whether the CLI and MCP look at the same store, and which engmem version the running MCP server logged with its latest call: a client keeps its old server until it is restarted. One line per check: ok, warning, error or unverified. Doctor cannot see the client's own sandbox from the inside, so that line is never ok. The exit code is 1 when any line is an error.

To walk the whole loop once before you load your own history into the store, there is engmem walkthrough codex --dir ~/engmem-demo. The command builds a demo store in that folder, a CODEX_HOME of its own for Codex and a small repository with an example, checks them with doctor and prints what to type in Codex: the first session saves a decision, the second finds it again. It does not touch your store or ~/.codex. In the demo folder Codex asks you to sign in again: your login is not copied there. engmem walkthrough handoff --dir ~/engmem-handoff does the same for two clients at once: Codex saves a decision, Claude Code in a neighbouring repository finds it and saves its own, and a new Codex session finds that second one by its id. They share one store and work in separate folders. Then --verify with the same --dir checks the demo store for a saved record that another session found. For handoff it first checks that both clients look at the same store, and if not, names both and checks nothing further.

To hand a colleague one decision without handing over the whole store, there is engmem export <id>. The first run only shows: the whole text of the file-to-be, a list of what was cut, and a fingerprint of those bytes. Links to your other documents and local paths become [excluded reference]: other documents' ids and file names, the whole reuse log (it quotes other documents), the titles of documents this one points at, and any other document's title of two words or more. Front-matter fields outside a short list, related and superseded_by among them, never reach the file at all. A one-word title nothing points at is usually just a word, so it stays. Repository names, commits and PR links stay: they are how the decision gets checked. The second run, engmem export <id> --out <file> --confirm <fingerprint>, writes the file, and only if the text has not changed since. It never overwrites an existing file, never writes inside the store, and does not export drafts. The store stays byte-for-byte the same and nothing goes over the network. There is no MCP tool for export, so an agent cannot take a document out of the store on its own.

Removal

The mirror command, with the same --agent:

engmem uninstall --agent claude

It deletes exactly the files it installed, and removes exactly the trigger-rule lines it wrote itself — the sentinel comment plus the rule line right after it (or, for older installs with no sentinel, the bare rule line, matched byte-for-byte). The match is narrow and exact — why it is not broad is worked through in path 2. The real output:

engmem uninstalled: 3 template file(s) removed, 2 trigger rule line(s) removed, agent=claude
store left untouched: /Users/…/Developer/engmem  (your documents — remove it yourself if you want)

Safe to run twice — the second run reports zeros.

What it deliberately does not do:

  • never touches the store. Those are your documents, not the tool's files: they stay readable markdown under git without engmem. The command only prints the path, so the decision stays yours;
  • never removes what isn't its own. A Copilot skill directory is pruned only if it's empty after its SKILL.md goes; unrelated lines in CLAUDE.md survive, and the file itself is never deleted even if it ends up empty;
  • doesn't remove the package — the engmem command stays on your PATH.

So a full removal is five steps, and only the first is required to stop agents calling a command that no longer exists:

engmem uninstall --agent claude   # templates and the trigger rule
uv tool uninstall engmem          # the package and the PATH command
rm -rf ~/.config/engmem           # the store and mode settings (%APPDATA%\engmem on Windows)
rm -rf ~/.cache/engmem            # the parse cache, safe to delete at any time
rm -rf ~/Developer/engmem         # documents, logs and version copies — only if you're sure

A demo from engmem walkthrough goes with its folder: the store, the Codex settings and the repositories are all inside it. What stays outside is left by the sessions themselves. The demo shares the parse cache with your store, and a demo search can drop cache entries for your documents; your next search rebuilds them. And after handoff, Claude Code itself, as for any folder, remembers the trust in storefront/ in ~/.claude.json and keeps the transcript in ~/.claude/projects/.

Part 7 · Limits

Why this memory is so frugal

Engmem is memory; v0.1 is frugal on purpose, because the central question about it is still open: prior documents pulled into a new task measurably change its outcome, and the benefit exceeds the cost of writing them. Until that is tested, every extra feature is an investment in something unproven. The answer comes from a review after 3–4 weeks of real work, against endpoints written down before the data (ENGMEM-SPEC.md §11). Hence every constraint: they are the conditions for a clean experiment.

ConstraintWhat it protects
Two dependencies, a standard-library CLI, no "just in case" featuresMinimum investment before the verdict: if it doesn't hold up, throwing it away is cheap.
Deterministic search, golden tests as the source of truthA reproducible sensor: a channel that answers one query differently on different days can neither be compared against a baseline nor meaningfully logged. "It found it yesterday, not today" is impossible by construction.
The tool makes no network callsTrue of the tool, not of the system: document contents reach the model on every task — that's a sign-off question, not a settled one. ChatGPT also reaches the store through a bridge. OpenAI decides who may use the tunnel, and engmem does not check that; a public bridge is not protected at all (docs/remote-access.md).
The measuring instruments may not be simplifiedReuse Log, pre-reg, telemetry, scoreboard. Switching them off means running the experiment with no data.

Frozen until the review: elaborate ranking formulas, vector and semantic search, indexes of any kind, automatic staleness marking, a web interface, team mode.

Where to read the code: the modules in src/engmem/, templates in src/engmem/templates/, behaviour contracts in docs/design/contracts/, golden tests in tests/search/test_scoring.py and tests/test_cli.py.