agent-context-substrate

Субстрат — это актив; модель — взаимозаменяемый клиент.

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

Требования: Python 3.12+, Docker, make. make setup создаёт виртуальное окружение и устанавливает зависимости, около 1,4 ГБ, поскольку демо работает на CPU и пропускает CUDA-колёса; на медленном соединении дайте несколько минут. База данных привязывается к 127.0.0.1:5432, поэтому остановите всё, что уже занимает этот порт.

Зачем это существует

Я создаю долгосрочные проекты с ИИ-агентами, и восстановление контекста в начале каждой сессии было налогом, который я платил чаще всего. Загрузка одних и тех же файлов, повторное объяснение одних и тех же решений, наблюдение за тем, как полезная часть окна заполняется материалом, который модель уже видела дважды. Выходила новая модель — и ничего из этого не переносилось. Проблема никогда не была в том, что контекст отсутствовал. Проблема была в том, что контекст не был адресуемым: не было способа задать вопрос и получить только то, что на него отвечает, поэтому вы отправляете всё и надеетесь. Решение состояло в том, чтобы перестать относиться к контексту как к чему-то, что вы приносите в сессию, и начать относиться к нему как к чему-то, что вы запрашиваете.

Эталонная реализация независимого от модели субстрата памяти для ИИ-агентов: память проекта живёт вне модели в запрашиваемом, версионируемом хранилище, доступном через единый MCP-шлюз. Меняйте модель — сохраняйте всё. Сегодня Claude, завтра Gemini или GPT, под ними та же память проекта. Вместо вставки истории в каждую сессию поиск выбирает небольшой набор записей, которые действительно нужны текущей задаче.

Этот репозиторий — чистая эталонная реализация этого паттерна, написанная с нуля на синтетическом корпусе, так что каждое число на этой странице воспроизводится из чистого клона с зафиксированными зависимостями. Это паттерн, а не система, на которой я работаю сам.

Ключи API не требуются: make demo работает полностью на локальных компонентах. Зафиксированные локальные модели (имя и ревизия) — это профиль адаптера по умолчанию, local (make warmup, запускается автоматически через make demo, предварительно загружает ~180 МБ один раз); герметичный профиль deterministic без загрузок поддерживает тесты и постоянно включённый CI-шлюз.

Related MCP server: AI Memory MCP Server

Структура

src/acs/adapters/base.py — это тезис в коде: четыре небольших интерфейса, за которыми стоит каждая внешняя возможность. src/acs/store/ рассматривает память как систему записи (версионируемую, аудируемую, по-настоящему удаляемую). src/acs/retrieval/ — это конвейер из небольших, отдельно тестируемых этапов. eval/ — это шлюз: изменения попадают в релиз, если соответствуют или превосходят baseline.lock.json, иначе не попадают.

Обоснование решений находится в docs/adr/: девять записей о решениях. Большинство — полстраницы; три длиннее, где аргументу нужно было место.

Также в docs/: architecture.md — зачем существует каждый слой, threat-model.md — о границах угроз и где находится каждая защита, principles.md — правила, из которых следует остальное, и build-your-own.md — последовательность сборки, которой следовал этот репозиторий.

Что это демонстрирует

• Приём записывает оба представления за один проход: эмбеддинги для сходства, граф сущностей/связей для структуры. Каждый документ встраивается; документ, не содержащий связей, не добавляет рёбер.

• Поиск — это конвейер из четырёх этапов: гибридный векторный + полнотекстовый поиск с настраиваемым смешиванием, мультизапросное слияние (RRF), переранжирование кросс-энкодером и раздел, привязанный к сущностям, где граф переупорядочивает переранжированный список, чтобы тематический ранжировщик перестал путать один компонент с его одноимённым собратом. Профили поиска для каждого потребителя — это данные, а не код.

• Управление: изменения поиска попадают в релиз, если соответствуют или превосходят заблокированный базовый уровень оценки. Память версионируется по SCD2 с чтением на момент времени, очистка действительно удаляет (включая векторы), а журнал аудита отказывает в изменении на уровне базы данных.

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

• Переносимость: каждый провайдер стоит за адаптером; эмбеддер зафиксирован намеренно.

Идентификатор происхождения и временные метки берутся из make history: без аргументов он выводит текущие памяти с их идентификаторами; с LINEAGE=<id> он проходит по цепочке версий одной памяти и выводит окно действия каждой версии. Эти окна — ISO-временные метки, так что TS=, который вы вставляете, разрешается в версию, которую вы действительно читали, а не на секунду раньше или позже. Идентификаторы генерируются для каждого клона, поэтому ваши не совпадут с показанными здесь.

make purge действительно удаляет (включая цели золотого набора, когда они принадлежат очищенному субъекту), поэтому бенчмарк против очищенного корпуса отказывается запускаться как неполный, а не тихо сообщает о более низком recall. make demo сбрасывает к чистому корпусу.

Каждое число бенчмарка на этой странице получено из абляции на посеянном синтетическом корпусе (corpus/generate.py), воспроизводимо из чистого клона и контролируется в CI (профиль deterministic на каждом пуше, профиль local на метке bench-local) против заблокированного базового уровня, который также фиксирует дайджест корпуса. Читайте дельты, а не абсолюты: recall@5 / mrr@5 на синтетическом корпусе показывают, что даёт каждый этап, а не реальное качество. Чтобы увидеть, где этап зарабатывает свою дельту, запустите .venv/bin/python eval/run_benchmark.py --by-family.

Абляция, локальный профиль

Каждый этап даёт разное, что является аргументом в пользу конвейера, а не одного лучшего поисковика. tests/test_readme_table.py падает, если эта таблица и eval/baseline.lock.json когда-либо расходятся, поэтому таблица не может отклониться от чисел, которые обеспечивает шлюз. Шлюз — это нижняя граница, поэтому изменение, улучшающее метрику, проходит его, и числа здесь остаются до тех пор, пока базовый уровень не будет намеренно перезафиксирован с помощью make lock-baseline, что затем приводит к падению этой таблицы, пока она не будет приведена в соответствие. Локальный профиль, 120 золотых запросов, k=5, слияние этапа 1 rank, дайджест корпуса ad7bf7ca. Воспроизведите с помощью make demo.

Что эти числа поддерживают, а что нет, включая то, почему сравнение модельных дорожек является границей, а не кривой, изложено в docs/limitations.md.