Основные понятия

Записи

Запись представляет собой небольшую заметку, написанную для будущего читателя без контекста.

Поле	Значение
id	Короткий и читаемый: dec_k3x9q2mf, pit_…, pri_…
kind	Что это, см. ниже
title	Конкретный заголовок для поиска: само решение, а не тема
content	Детали и прежде всего обоснование
tags	Темы в нижнем регистре: auth, db, payments
files	Пути относительно репозитория, нужны для поиска по файлам
status	active, superseded, rejected или archived
importance	От 1 (мелочь) до 5 (несущая конструкция); влияет на ранжирование и сжатие
source	agent, user, adr:docs/adr/0003.md, git:…

Виды

Вид	Для чего
decision	Архитектурный или продуктовый выбор, либо отвергнутый вариант (status: rejected)
pitfall	То, на чём вы обожглись: что случилось, почему, как избежать
principle	Правило, которому должна следовать любая правка
fact	Простой факт, например «прод-БД на Postgres 16»
discussion	Суть обсуждения: варианты, аргументы, итог
note	Всё остальное, что стоит сохранить
file	Для чего нужен модуль, если это не видно из кода
session	Итог рабочей сессии

Дубликаты

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

Статусы и история

Когда вы передумали, ничего не перезаписывается:

• superseded: заменено более новой записью. supersede(old, new) помечает старую и добавляет ребро new —supersedes→ old.
• rejected: вариант, который рассматривали и отвергли. Благодаря таким записям на вопрос «почему не X?» есть ответ.
• archived: мягкое удаление. Запись скрыта из поиска, но хранится в истории. Жёсткое удаление оставляет tombstone, чтобы оно дошло до коллег.

По умолчанию поиск возвращает только active. Чтобы увидеть остальное, передайте include_inactive (в CLI это --all).

Граф

Записи связаны направленными типизированными рёбрами:

Связь	Читается как
relates_to	общая связь
depends_on	from верно, только пока верно to
implements	from реализует решение или принцип to
supersedes	from заменило to
rejected_because	вариант from отвергнут из-за to
caused_by	грабли from вызваны to
part_of	from входит в более крупную тему to

engram_why идёт по supersedes, rejected_because и caused_by и собирает разрозненные записи в хронологию. engram_related ходит по любым рёбрам в обе стороны.

Сессии

engram_session_start открывает сессию под цель и возвращает контекст-пакет. engram_session_end сохраняет итог (сделано, решено, открыто, дальше) как запись session, которую можно найти поиском. Контекст-пакет следующей сессии начинается с неё.

Контекст-пакет

Компрессор контекста собирает брифинг под задачу в рамках бюджета токенов, по умолчанию 2000:

1. Он собирает принципы, грабли по теме задачи, подходящие записи и ключевые решения и ранжирует их.
2. Самые приоритетные записи выводятся целиком.
3. Следующий уровень сокращается до одной строки: id, заголовок и теги.
4. Остальное отбрасывается. Пакет сообщает, сколько записей не влезло, чтобы агент знал, что может вызвать recall.

Поиск

Полнотекстовый поиск работает на SQLite FTS5 с ранжированием BM25 (сильнее всего весит заголовок, затем теги, содержимое и файлы), стеммингом Porter и Unicode-токенизацией, поэтому подходит для английского, русского, украинского и других языков. Затем оценка корректируется по виду, важности, статусу и возрасту записи. Запросы нестрогие: термины объединяются через OR, а длинные ищутся по префиксу, так что «auth» найдёт «authentication».