785 статей для агентов, а не для людей. База знаний без векторного поиска

Когда агент начинает работу в незнакомом проекте, он тратит первые 30–40% токенов на то, чтобы понять, что вокруг происходит. Не работает, а именно ориентируется. Этот пост описывает Happyin Knowledge Space, библиотеку справочных карточек, которые я пишу для агентов, а не для людей: почему карточка выглядит именно так, почему быстро меняющиеся области имеют порог свежести, почему я связываю карточки вручную, а не кладу их в векторную базу, и как исследования из чатов на нескольких аккаунтах попадают туда без копирования и вставки. Когда 22 апреля 2026 года вышел русскоязычный оригинал, в базе было 785 карточек в 26 областях.

Две проблемы того, как агент учит проект

README объясняет мотивацию, туториал ведёт за руку, справочник API перечисляет параметры. Ни один из них не отвечает на вопрос, с которым агент реально пришёл: вот моя задача, какой паттерн мне скопировать и где мины?

Вторая проблема глубже и заметна не сразу. Модель знает «всё», но это «всё» распределено по обучающим данным неравномерно. Чем дольше технология существует в интернете, тем больше о ней постов, ответов на Stack Overflow и туториалов, и тем больший вес этот подход имеет внутри модели. Когда я прошу Claude обучить LoRA, первое, что он предлагает, — рецепт пятилетней давности. Не потому, что он лучше, а потому что его больше. Для стабильных технологий это нормально. Для всего быстро движущегося, например обучения моделей, инструментов агентов или безопасности, агент незаметно тянет меня в прошлое.

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

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

Формат: карточка, а не статья

У каждой карточки одинаковый скелет. Вверху — тема и определение одним предложением, чтобы агент сразу понимал, попал ли он куда нужно. Затем Key Facts: короткие утверждения с числами, например версиями, порогами и зависимостями. Потом Patterns: код, который можно скопировать, с меткой языка. Внизу — подводные камни, каждый парой «что ломается и что чинит».

Никаких вступлений «давайте посмотрим» и никаких концовок «в этой статье мы рассмотрели». Карточка об архитектуре брокера Kafka — это таблица ZooKeeper против KRaft, конфиг с комментариями, метрики JMX с порогами алертов и пошаговая миграция. Читается это не гладко. Но агент делает grep по «KRaft migration» и получает рабочий рецепт в три шага.

Самый ценный блок — последний. Одна строка «min.insync.replicas действует только при acks=all» экономит полчаса отладки. Агент прочитал её, не допустил ошибку и не потратил цикл повтора на исправление.

26 областей, выросших из работы

В апреле самой большой областью была генерация изображений — 58 карточек, почти вровень с LLM-агентами (57), затем Data Science и Security по 56 (Security выросла через отдельную папку с классами CWE). За ними шли Kafka (43), DevOps (38), Web Frontend (36), Data Engineering (34) и четыре области по 33: Python, SQL, Architecture и Algorithms. Остальные четырнадцать небольших составляли: iOS, Linux CLI, C++, Java Spring, Testing and QA, BI, SEO, Rust, Node.js, PHP, LLM Memory, Audio and Voice, Writing и Go.

Это не план. Это карта того, где на самом деле уходит моё время, когда я работаю с агентами: обучение LoRA, отладка плагинов на C++, исследования. Каждая область собрала свой список мест, где что-то сломалось у меня, и эти списки стали её каркасом.

Знания стареют с разной скоростью

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

Поэтому у каждой области свой порог свежести. У стабильных порога нет. В быстрых областях карточка старше 60 дней помечается на проверку, а хук, который запускается раз в сутки, ставит её в список «проверить и обновить». Это не сигнал на удаление. Это напоминание, что тема, скорее всего, сдвинулась и карточку нужно сверить с тем, что верно сейчас. Устаревшие карточки сами выходят на проверку, а не тихо вводят агента в заблуждение.

Ссылки вместо векторов

Очевидная архитектура для этого — векторная база с RAG поверх. Она быстро находит семантически близкий текст и хорошо работает в продакшене. Я сознательно её не использовала, по трём причинам.

Векторное хранилище нечитаемо для человека. Markdown я могу открыть в текстовом редакторе, найти grep-ом, сравнить через git diff, вставить в письмо или распечатать и повесить на стену. Это работает сегодня и будет работать через десять лет на любом компьютере без специальных инструментов. Векторное хранилище — это бинарник, который понимает только его собственный клиент. Смените поставщика, потеряйте сервис, сломайте API — и данные превращаются в кучу чисел, которую никто не прочитает. Мне нужно, чтобы база знаний переживала смену инструментов, а не зависела от них.

Векторизация почти необратима. Эмбеддинг — это необратимое сжатие с потерями. Без исходных фрагментов, хранящихся рядом, файл с эмбеддингами бесполезен, потому что вернуть читаемый текст почти невозможно. Исследования инверсии эмбеддингов существуют, но работают на очень коротких фрагментах, требуют той же модели эмбеддингов и отдельно обученного декодера. Кроме того, это привязывает вас к одной модели эмбеддингов: сменили модель ради качества — переиндексируйте всё, потому что старые векторы в новом пространстве ничего не значат.

И самое важное для меня: граф ссылок фиксирует, какие темы соседствуют, а не какие тексты похожи. Векторное сходство находит темы, которые пересекаются в лексике и понятиях. В реальной работе ценные связи часто идут между темами, которые далеко друг от друга. Моя карточка о репликации Kafka ссылается на карточку о профилировании памяти — не потому, что темы похожи, а потому что настройка потребителя выявила утечку памяти, и опыт сделал их соседями. В пространстве эмбеддингов «репликация в распределённой очереди» и «профилирование памяти в Python» лежат далеко друг от друга, и семантический поиск этот мост не построит. Ручная вики-ссылка построит, и теперь агент, читающий про Kafka, в одном шаге от профилирования памяти.

Механика простая. Карточки ссылаются друг на друга как [[flux-klein-9b-inference]], [[two-phase-commit]], [[saga-pattern]]. На этапе сборки Python-хук превращает каждый slug в относительный путь. Если slug не найден, в лог пишется предупреждение, а в строгом режиме сборка падает, так что битая ссылка не попадает на живой сайт. В апреле таких ссылок было больше 2100. Это и есть весь граф знаний: никаких эмбеддингов, никакой векторной базы, никакого RAG. Markdown и grep. Агент открывает карточку о распределённых транзакциях, видит соседние темы в разделе See Also, переходит по одной и продолжает. Три шага от точки входа до рабочего паттерна.

Это та же идея, что ссылки [[filename]] в памяти моих агентов, о которой я писала в Мой CLAUDE.md — 582 строки.

Сайт — это сборка репозитория

Всё на happyin.space — статический сайт, собранный из Markdown в открытом репозитории. Без базы данных, без бэкенда, без скрытого слоя. Файл docs/kafka/broker-architecture.md после сборки становится страницей happyin.space/kafka/broker-architecture/, и это весь механизм.

Значит, любой может сделать форк и запустить его локально примерно за пять минут:

git clone https://github.com/AnastasiyaW/knowledge-space.git
cd knowledge-space
pip install -r requirements.txt
mkdocs serve        # then open http://localhost:8000

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

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

Тот же шаг сборки следит за честностью ссылок. Он проходит по каждому [[slug]], находит соответствующую карточку и записывает относительный путь, а если ничего не находит, сборка падает. Я вижу это локально до коммита, а CI запускает ту же проверку в строгом режиме, где любая битая ссылка блокирует деплой. В апреле это было больше 2100 ссылок, и ни одна не была битой. А поскольку сайт — это и есть репозиторий, всё лежит в git: видно, как менялась карточка, какие факты появились после какого прогона исследования и когда её в последний раз трогали. Для базы, отсортированной по скорости устаревания знаний, эта история важна.

Как исследования попадают внутрь

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

Это место — проект Claude Code, привязанный к репозиторию knowledge-space, с собственной папкой research/inbox/, куда собираются сырые выгрузки из каждого чата каждого аккаунта. Никакого копирования и вставки, только правило, которое каждый чат читает в начале и выполняет, когда исследование завершено.

Затем идёт второй проход. Отдельная сессия над проектом knowledge-space разбирает inbox: читает каждую сырую выгрузку, вынимает конкретные факты и подводные камни, пересобирает их в формат карточки и сверяет с тем, что уже есть в этой области, чтобы дубликаты дополняли существующие карточки, а не размножались. Потом проверяет вики-ссылки, запускает сборку, читает diff и пушит. Одна такая сессия обычно даёт от 20 до 40 новых или дополненных карточек за несколько часов.

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

Результат — поток. Я веду основную работу, по ходу запускаю исследования в разных чатах, и база наполняется сама, без того, чтобы я что-то переносила или форматировала.

Использование и вклад

Проще всего использовать базу так: указать агенту на happyin.space/llms.txt и дать ему подтягивать карточки по мере надобности. Одно это уже сокращает первую треть токенов, которая раньше уходила на ориентирование.

Следующий уровень — вклад. В репозитории есть два файла, написанные для этого: CONTRIBUTING.md, общее руководство по подготовке страниц и отправке изменений, и AGENTS.md, инструкции для вашего агента. В них описаны формат карточки, насколько плотным должен быть текст, что относится к разделу Gotchas, как писать вики-ссылки и как открыть pull request с новой карточкой или исправлением. Дайте агенту руководство и свежий результат исследования, и он соберёт карточку сам. Ваше исследование попадает в базу, вы перестаёте платить за него повторно, и то же самое получают все остальные. README заявляет лицензию MIT.

Чем больше исследований в базе, тем меньше кто-либо должен их повторять. Чем больше людей и агентов присылают карточки, тем больше неожиданных мостов появляется между областями, а именно они и ценны. Страница проекта на этом сайте — happyin.space.

Что изменилось после апреля

Обновление, сентябрь 2026. README репозитория теперь сообщает о 1287+ статьях в 28 областях и 3139+ перекрёстных ссылках. Основной рост — два новых вида страниц: projects/, 388 страниц, по одной на каждый инструмент, модель или продукт, за которым следит новостной конвейер, и organizations/, 45 страниц, по одной на компанию или лабораторию. Правило свежести теперь описано в README как четырёхшаговый цикл: стабильные, ежегодные, раз в полгода и ежемесячные; генерация изображений и агентные фреймворки попали в ежемесячную группу.

Цифры из апреля выше (785 карточек, 26 областей, 2100+ ссылок, порог 60 дней, пятисекундная сборка) были верны в день публикации, и я оставила их как есть. Та же привязанность к простым файлам вместо сервиса, применённая к нескольким агентным сессиям, работающим одновременно, описана в Несколько Claude в одном репо.