Основні поняття

Записи

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

Поле	Значення
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».