Предисловие

Я уже довольно долго провожу время за разработкой с AI-агентами. Пробовал разное, щупал разные подходы, но на данный момент моё предпочтение всё-таки пало на Codex.

И вроде бы всё красиво.

Coding-агент умеет читать проект, менять код, запускать тесты, делать ревью, искать ошибки… Ну красота же!

Но потом начинается бытовуха.

В одном чате ты объяснил ему:

Импорты всегда сверху. Проверки прав не размазываем по use case. DTO маппим явно. Алиасы после рефакторинга не оставляем. Старые compatibility-модули не тащим. Тесты запускаем вот так.

В другом чате объяснил то же самое.

В третьем — опять.

В четвёртом уже хочется не промпт писать, а табличку повесить:

Codex, ну ты же уже это делал…

И самое неприятное здесь даже не раздражение. Хотя оно тоже есть, да.

Главная проблема — токены.

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

А память — это не когда ты каждый раз пересказываешь человеку всю историю проекта с нуля.

Память — это когда он сам такой:

Ага, я помню. Тут у нас права через спецификации. Импорты не трогаем. Старые alias-модули не оставляем. Поехали.

Вот примерно такую штуку я и захотел сделать для Codex.

Так появился Hermes Codex Plugin.

---

TL;DR

Если совсем коротко:

Hermes Codex Plugin — это локальная память для Codex, которая хранит правила проекта, прошлые решения, summaries задач и помогает доставать только маленькие релевантные куски контекста, вместо того чтобы каждый раз кормить агента огромным промптом.

Без векторной базы. Без отдельного embedding-сервиса. Без демона на фоне. Без «давайте поднимем ещё один микросервис, потому что можем».

Просто:

SQLite
+ FTS5
+ MCP tools
+ Codex hooks
+ немного здравого смысла

И всё это ради одной простой идеи:

Не надо платить токенами за амнезию агента.

---

Что вообще такое Hermes Agent

Hermes Agent — это агент, который:

1. перед работой вспоминает прошлые решения;

2. достаёт правила проекта;

3. находит похожие workflow;

4. после работы сохраняет компактное summary;

5. в следующий раз не начинает с нуля.

То есть задача не в том, чтобы сделать Codex магически умнее.

Задача проще:

Сделать так, чтобы агент меньше страдал амнезией и меньше тратил контекст на повторение очевидных вещей.

---

Почему это вообще нужно

В реальной разработке большая часть полезного знания живёт не только в коде.

Код — это финальная форма. А вот решения, причины и договорённости часто живут где-то рядом:

• почему выбрали именно такую архитектуру;

• где должны лежать проверки прав;

• какие импорты считаются нормальными, а какие — нет;

• какие тесты запускать перед релизом;

• какие старые решения уже признаны плохими;

• какие ошибки агент уже делал;

• какой стиль ревью принят в проекте;

• какие файлы лучше не трогать без крайней необходимости.

Часть этого можно положить в AGENTS.md.

Часть — в README.md.

Часть — в документацию.

Но есть огромный пласт знания, который появляется прямо в процессе работы с агентом:

«Не, вот так не делай». «Мы это уже пробовали». «В этом проекте так не принято». «Вот этот подход норм, давай его переиспользовать». «Не надо опять тащить infrastructure в application layer!»

И вот это всё обычно остаётся в чате.

А потом чат закончился.

И агент снова как будто впервые видит ваш проект.

Ну классика…

---

Почему длинный промпт — плохая память

Самый простой способ дать агенту контекст — вставить всё руками:

Ты работаешь в таком-то проекте.
Архитектура такая-то.
Правила такие-то.
Проверки прав делаем так-то.
Вот старый пример.
Вот ещё старый пример.
Вот кусок обсуждения из прошлого чата.
Вот список команд.
Вот ещё 40 пунктов, потому что иначе ты опять забудешь.

Работает?

Да.

Удобно?

Нет.

Дёшево?

Тоже нет.

Проблема в том, что длинный промпт — это не память. Это чемодан без колёсиков.

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

У coding-агента есть ещё одна особенность: он работает в цикле.

прочитал запрос
-> подумал
-> вызвал инструмент
-> получил вывод
-> снова подумал
-> полез в файл
-> запустил тесты
-> получил ошибку
-> снова подумал
-> исправил

И чем длиннее тред, тем больше истории едет рядом с задачей.

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

Отсюда три проблемы:

Идея Hermes простая:

Не надо каждый раз нести весь чемодан. Давайте вытащим из него только отвёртку, которая нужна прямо сейчас.

---

Что делает Hermes Codex Plugin

Hermes Codex Plugin — это локальный плагин для Codex, который добавляет ему долговременную память, поиск по старым чатам и путь от повторяемых правил к reusable skills.

Если совсем коротко, он делает четыре вещи.

1. Сохраняет полезный контекст

Например:

• пользовательские правила;

• архитектурные решения;

• краткие summaries задач;

• повторяемые workflow;

• важные замечания по проекту.

То есть не весь чат целиком, а нормальную выжимку:

Project rule:
Permission checks should be represented as reusable specifications.
The same rule must support in-memory checks and SQL filtering.

2. Ищет релевантную память перед задачей

Когда приходит новый запрос, плагин может поискать похожие правила и прошлые решения.

Не магия. Не телепатия. Просто локальный поиск по сохранённой памяти.

3. Подкладывает в Codex маленький релевантный фрагмент

Не весь старый чат на 20 тысяч токенов.

А, например:

Relevant memory:
In this project, permission logic should live in reusable specifications.
Application code uses the same specification for in-memory checks.
Infrastructure translates it into SQL predicates.

То есть в контекст попадает не «вся жизнь проекта», а ровно то, что может пригодиться для текущей задачи.

4. Помогает превращать повторяемые правила в SKILL.md

Если одно и то же правило всплывает снова и снова, возможно, это уже не просто memory entry.

Это навык.

Workflow.

То, что стоит оформить отдельно и переиспользовать нормально.

---

Почему я специально сделал это скучно

Когда речь заходит о памяти для агента, очень быстро хочется сделать «как взрослые»:

• embeddings;

• vector database;

• semantic search;

• reranking;

• отдельный сервис;

• UI;

• синхронизацию;

• очередь задач;

• Kubernetes;

• а потом ещё мониторинг Kubernetes, потому что он тоже иногда хочет кушать.

Но я специально пошёл в другую сторону.

Hermes хранит память локально в SQLite.

Для поиска используется FTS5, а если он недоступен — обычный fallback через LIKE.

Да, это звучит скучно.

Но в данном случае скучно — это комплимент!

Потому что память агента должна быть:

• локальной;

• inspectable;

• дешёвой;

• простой в отладке;

• без зависимости от внешних embedding API;

• без отдельной цены за индексацию;

• без ощущения, что ты поставил плагин, а получил маленькую инфраструктурную ферму.

Большая часть правил проекта — это не поэзия, где нужен сверхтонкий семантический поиск.

Обычно это вполне конкретные штуки:

imports at top
permission specification
run unit tests
do not keep alias modules
DTO mapper
project scoped memory
release workflow

Для такого lexical search часто уже достаточно хорош.

И самое приятное: если агент что-то вспомнил — можно открыть базу и посмотреть, почему.

---

Как это выглядит в работе

Допустим, я пишу Codex:

Добавь новый use case для проверки доступа к файлу.

Без памяти агент может начать изобретать подход заново.

Он полезет по проекту, найдёт пару файлов, может сделать проверку прямо в use case, может отдельно продублировать SQL-фильтр, может забыть старую договорённость…

Ну, бывает.

С Hermes сценарий другой.

Перед тем как Codex начнёт задачу, плагин может найти в локальной памяти что-то вроде:

Project rule:
Permission checks should be represented as reusable specifications.
The same rule must support in-memory checks and SQL filtering.

Previous task summary:
We discussed splitting permission logic into specification objects
so application code can check a single object and infrastructure can
translate the same rule into a query predicate.

И в контекст текущей задачи попадает не весь старый диалог, а вот такая маленькая выжимка.

Это принципиально другая экономика контекста.

Мы не говорим модели:

Держи всё, вдруг пригодится.

Мы говорим:

Вот три факта, которые реально похожи на текущую задачу. Пользуйся.

---

Где здесь экономия токенов

Тут нет волшебства.

SQLite не превращается в LLM.

FTS5 не начинает понимать архитектуру вашего проекта на уровне senior-разработчика.

Экономия появляется из более простой вещи:

Мы перестаём подсовывать модели лишний текст.

Было так:

Новый запрос
+ длинный системный промпт
+ правила проекта
+ старые решения
+ куски прошлых чатов
+ напоминание про стиль
+ напоминание про тесты
+ ещё чуть-чуть, чтобы точно не забыл

Стало так:

Новый запрос
+ 2–5 компактных memory entries

Hermes не пытается заменить контекстное окно.

Он пытается не мусорить в нём.

Особенно это полезно в задачах, где правила проекта стабильные, а сами задачи разные:

• рефакторинг слоёв;

• права доступа;

• миграции;

• добавление API endpoint;

• ревью PR;

• генерация тестов;

• release-процессы;

• работа с DDD-подобной структурой;

• поддержка одного и того же стиля кода.

Каждый раз объяснять это руками — ну такое…

Один раз сохранить как память и потом доставать по необходимости — намного приятнее.

---

Hooks: где память цепляется к Codex

Плагин использует hooks Codex.

Идея примерно такая:

SessionStart      -> подложить свежую локальную память
UserPromptSubmit  -> сохранить prompt и добавить релевантный recall
Stop              -> при необходимости сохранить ответ ассистента
PreCompact        -> сохранить snapshot перед compaction

То есть память не живёт где-то отдельно от рабочего процесса.

Она подключается в моменты, где это действительно полезно:

• в начале сессии;

• перед обработкой пользовательского запроса;

• после ответа;

• перед сжатием контекста.

На практике это похоже на маленького секретаря, который стоит рядом с агентом и шепчет:

Мы уже обсуждали похожую задачу. Вот правило. Вот прошлое решение. Вот summary. Не надо опять изобретать велосипед.

---

MCP tools: памятью можно управлять руками

Кроме hooks, плагин поднимает MCP-инструменты.

И это важный момент.

Память не должна быть чёрным ящиком.

Основные инструменты:

hermes_codex_search
hermes_codex_search_chats
hermes_codex_remember
hermes_codex_remember_summary
hermes_codex_forget
hermes_codex_stats
hermes_codex_propose_skill
hermes_codex_write_skill

То есть можно не только автоматически искать и сохранять, но и явно сказать:

Запомни: в этом проекте все команды application layer
не должны импортировать infrastructure.

Или:

Найди, что мы раньше обсуждали про permissions.

Или:

Предложи skill на основе правил про release workflow.

Мне нравится, что это не «память где-то там».

Её можно:

• посмотреть;

• почистить;

• дополнить;

• удалить;

• превратить в более устойчивую инструкцию.

---

Memory → Skill: когда правило выросло

Память хороша для фактов и решений.

Но если одно и то же правило всплывает много раз, это уже не просто memory entry.

Это workflow.

Например:

Перед релизом:
1. прогнать unit tests;
2. проверить changelog;
3. обновить version;
4. сделать compileall;
5. не коммитить raw logs и secrets.

Можно каждый раз искать это в памяти.

А можно однажды оформить в SKILL.md.

В этом и смысл skill evolution:

разовая просьба
-> повторяемое правило
-> сохранённая память
-> reusable skill
-> стабильный workflow

Hermes не только вспоминает прошлое.

Он помогает понять, какие повторяемые паттерны уже пора вынести в отдельный навык.

---

Чем это отличается от AGENTS.md

Справедливый вопрос:

А зачем всё это, если можно просто написать AGENTS.md?

Ответ: AGENTS.md всё ещё нужен.

Я не вижу Hermes как замену AGENTS.md.

Скорее так:

Если правило железобетонное и относится ко всему репозиторию — ему место в AGENTS.md.

Если правило родилось в чате, пока ещё проверяется, относится к конкретной задаче или может потом стать skill — ему удобно сначала пожить в Hermes.

А если оно повторилось достаточно раз — можно превратить его в SKILL.md.

---

Установка

Из корня репозитория:

codex plugin marketplace add .
codex plugin add hermes-codex-plugin@hermes-codex-plugin

Проверить, что Codex видит плагин:

codex plugin list --marketplace hermes-codex-plugin
codex mcp get hermes-codex-plugin

Для локального теста через CLI можно использовать отдельную временную базу:

cd plugins/hermes-codex-plugin

export HERMES_CODEX_DB=/tmp/hermes-codex-plugin.sqlite3

PYTHONPATH=src python3 -m hermes_codex_plugin.presentation.cli.main init

PYTHONPATH=src python3 -m hermes_codex_plugin.presentation.cli.main remember \
  "Always run the unit test suite before release." \
  --kind rule \
  --scope project

PYTHONPATH=src python3 -m hermes_codex_plugin.presentation.cli.main search "unit test suite"

PYTHONPATH=src python3 -m hermes_codex_plugin.presentation.cli.main stats

---

Какой должна быть хорошая память

Важный момент: в память не надо сохранять всё подряд.

Память должна быть компактной.

Плохая память:

Вот огромный transcript, где мы 40 минут обсуждали архитектуру,
потом Codex ошибся, потом мы спорили, потом всё починили,
потом ещё кто-то вспомнил старый PR...

Хорошая память:

Project rule:
Permission logic should live in reusable specifications.
Application code uses the same specification for in-memory checks,
infrastructure translates it into SQL predicates.

Ещё пример:

User preference:
When proposing refactoring, include a Codex-ready prompt at the end.
Keep it concrete and exclude unrelated base use cases.

Вот такая память реально полезна.

Она короткая. Она actionable. Она не превращает контекст в болото.

---

Про приватность и секреты

Так как память локальная, она не требует отправлять старые чаты в отдельный embedding-сервис.

Это плюс.

Но это не значит, что туда можно бездумно складывать всё подряд.

В проекте есть редактирование очевидных токенов, bearer-ключей, паролей и JWT-похожих значений перед сохранением.

Но давайте честно:

Это safety layer, а не полноценная DLP-система.

Поэтому правило простое:

Не сохраняйте секреты намеренно.

В память должны попадать:

• правила;

• решения;

• summaries;

• workflow;

• полезные замечания по проекту.

Не должны попадать:

• .env;

• production-логи;

• приватные дампы;

• реальные ключи;

• bearer-токены;

• пароли;

• всё, после чего хочется сказать: «ой…»

---

Ограничения

Важно честно сказать: Hermes Codex Plugin — это не магическая память из фантастики.

Это простой локальный инструмент, и у него есть ограничения.

Например:

• поиск лексический, а не семантический;

• skill generation эвристический;

• результат генерации skills надо ревьюить;

• UI пока нет;

• фонового демона нет;

• память надо поддерживать в чистоте;

• плохие записи в памяти будут мешать так же, как плохие инструкции в промпте.

То есть если сохранить мусор, агент будет вспоминать мусор.

Junk in — junk out. Только теперь локально и с SQLite.

---

Где честный benchmark?

Я не хочу писать в стиле:

Экономит 90% токенов!!! Ускоряет разработку в 12 раз!!! Senior-разработчики ненавидят его!!!

Потому что без нормального замера это будет не инженерия, а маркетинговая магия.

Правильный benchmark я вижу так:

1. Берём набор типовых задач по одному репозиторию.

2. Прогоняем Codex без Hermes.

3. Прогоняем Codex с Hermes.

4. Сравниваем:

   • input tokens;

   • output tokens;

   • число повторных уточнений;

   • время до готового diff;

   • количество правок после ревью;

   • процент задач, где агент вспомнил нужное правило.

Только после этого можно честно говорить цифрами.

Пока моя формулировка скромнее:

Hermes снижает токеновую нагрузку там, где вы раньше вручную повторяли длинный стабильный контекст, потому что заменяет простыни промпта на маленькие релевантные memory entries.

И для меня этого уже достаточно, чтобы идея была полезной.

---

Что дальше

Мне интересно развивать Hermes в нескольких направлениях:

• лучшее deduplication правил;

• удобный просмотр памяти;

• импорт summaries из старых Codex-сессий;

• более умное предложение skills;

• опциональный semantic search, но так, чтобы не сломать local-first подход;

• нормальные benchmark-сценарии;

• больше готовых примеров для реальных Python/TypeScript-проектов.

Но главное направление я бы не менял.

Память должна оставаться:

• простой;

• локальной;

• проверяемой;

• дешёвой;

• понятной.

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

А странного поведения у нас и так хватает, спасибо.

---

Итог

Hermes Codex Plugin — это попытка сделать Codex менее забывчивым без тяжёлой инфраструктуры.

Не новая модель. Не облачная база знаний. Не RAG-комбайн с тремя сервисами.

А маленькая локальная прослойка:

старые решения
+ правила проекта
+ summaries задач
+ SQLite FTS
+ MCP tools
+ Codex hooks
= меньше повторного контекста в промпте

Мне нравится думать об этом так:

Хороший coding-агент должен не только писать код, но и помнить, как вы договорились писать код.

Если каждый раз объяснять агенту одно и то же, мы не используем ИИ.

Мы просто очень быстро печатаем документацию в чат.

Hermes пытается сделать следующий шаг: пусть повторяемые правила живут не в голове пользователя и не в километровом промпте, а в локальной памяти, откуда Codex достанет ровно то, что нужно для текущей задачи.

---

Код проекта: Hermes-Codex-Plugin

Будет интересно услышать в комментариях: как вы сейчас решаете проблему памяти у coding-агентов?

AGENTS.md? Длинные промпты? Свои MCP? Векторные базы? Скрипты?

Или просто старое доброе:

«Надеюсь, в этот раз не забудет…»