Live: https://happyin.space/ Repo: https://github.com/AnastasiyaW/knowledge-space (MIT)

Когда агент пишет код в пустом проекте, он тратит первые 30-40% токенов на понимание того, что происходит вокруг. Не на работу - на ориентацию. README рассказывает мотивацию, туториал ведёт за руку, API-reference описывает параметры. Ни один из этих форматов не отвечает на вопрос, ради которого агент и пришёл: “вот задача, какой паттерн скопировать и где здесь грабли?”

Вторая проблема - глубже, и замечают её не сразу. LLM знает “всё на свете” - но это “всё” распределено в датасете неравномерно. Чем дольше технология живёт в интернете, тем больше по ней статей, вопросов на Stack Overflow, блогпостов и учебных материалов. А значит - тем больше вес этого подхода в голове у модели. Если я прошу Клода натренировать LoRA, первое, что он предлагает, - рецепты пятилетней давности. Не потому что они лучше, а потому что их просто больше в выборке. Для стабильных технологий это нормально. Для всего, что быстро движется - тренировки моделей, работы с агентами, безопасности - это значит, что агент по умолчанию тянет меня в прошлое.

Очевидное лекарство - гонять каждый раз deep research и дотягивать актуальный контекст. Я так и делаю. Однако deep research - операция дорогая. Несколько сотен долларов в месяц на подписки, и лимиты всё равно кончаются мгновенно. Ещё обиднее то, что каждый ресерч уходит в никуда: сессия закрылась - контекст исчез. Завтра по той же теме я запущу тот же поиск и потрачу те же токены на то, что уже выяснила.

Отсюда выросли две связанные идеи. Первая - ресерчи должны накапливаться, а не испаряться. Один раз разобралась - этот результат нужно отложить так, чтобы в следующий раз он уже был, и на на него можно было просто опереться. Вторая - формат должен быть такой, чтобы Клод видел именно актуальные сейчас подходы. Чтобы, открывая проект, агент сразу попадал в контекст “так делают здесь”, а не пересобирал его с нуля из фантазий и памяти.

В какой-то момент стало очевидно: если работа по старому съедает контекст и смещена к устаревшим подходам - её нужно перестроить.

Happyin Knowledge Space - 785 статья в 26 доменах. Домены очевидно отражают области моих интересов, но я думаю, они могут пересекаться и с вашими - программирование, безопасность, работа с нейросетями. Reference cards, не туториалы. Написано по результатам реальных ресерчей и реальных рабочих сессий. Для агентов, не для людей.

Формат: карточка вместо статьи

У каждой “статьи” одинаковый каркас. Сверху - название темы и одно предложение определения, чтобы агент понял, туда ли попал. Дальше блок ключевых фактов (Key Facts) со списком коротких утверждений и числами - версии, пороги, зависимости. Блок Patterns с копипастабельным кодом, снабжённым language tag’ом для правильной подсветки. И в самом низу - список подводных камней, пара “что ломается” / “чем чинится”.

Без лишних введений “давайте разберёмся” и ненужных заключений “мы рассмотрели”. Минимальный overhead, максимум сигнала. Статья про Kafka broker-architecture - это сразу таблица ZooKeeper vs KRaft, конфиг с комментариями, JMX-метрики с порогами алёртов, пошаговая миграция. Гладко не читается. Но агент делает grep по “KRaft migration” и получает работающий рецепт в три шага.

Последний блок - самый важный. Одна строка вида “min.insync.replicas работает только с acks=all” экономит 30 минут дебага. Агент прочёл, не сделал ошибку, а значит - не потратил retry-цикл на починку.

26 доменов, выросшие из практики

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

База пополняется не по расписанию, а из работы. Я регулярно гоняю ресерч-сессии: смотрю, что нового вышло по безопасности, какие появились паттерны в мультиагентных системах. Раньше результаты таких ресерчей испарялись вместе с сессией. Сейчас они становятся статьями - и агенту в следующий раз не нужно заново поднимать ту же тему.

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

Долгоживущее и устаревающее

Не все знания стареют одинаково, и база изначально это учитывает. Алгоритмы и математика стабильны: статья про амортизационный анализ или про network flow, написанная три года назад, актуальна и сегодня. С такими доменами ничего делать не надо, они просто лежат на своём месте. А вот тренировка диффузионных моделей, inference-оптимизации, ComfyUI-ноды - меняются каждые несколько месяцев. То, что работало осенью, к весне уже устарело или переехало в новую версию.

Поэтому каждому домену проставлен собственный порог свежести. Для стабильных доменов ограничения по времени нет. Для быстрых - статья старше 60 дней автоматически помечается на пересмотр, и хук, который гоняется раз в сутки, выкидывает её в отдельный список “проверить и обновить”. Это не алерт на удаление, это напоминание: в этой теме, вероятно, что-то уже усело сдвинуться, нужно сверить с текущей реальностью. Так устаревающие статьи не просто лежат и вводят агента в заблуждение, а сами приходят на ревизию.

Это та же самая идея, что и в семантических тегах из CS-статей про knowledge graph degradation: знание не одинаково во времени, и структура их хранения должна это отражать. Граф доменов - не плоский список, а сортировка по скорости устаревания.

Граф связей без vector search

Очевидная архитектура под такую задачу - векторная база с RAG поверх. Она быстро находит семантически близкое и в проде работает прекрасно. Тем не менее, лично я от неё сознательно отказалась: в моём сценарии у неё есть проблемы, которые перевешивают скорость поиска. Эти проблемы таковы:

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

Вторая - векторизация практически необратима. Эмбеддинг - это lossy one-way compression: текст превращается в вектор с потерей информации. Если где-то рядом не сохранены оригинальные чанки, сам по себе файл с эмбеддингами бесполезен - вернуть из него читаемый текст почти невозможно. Есть академические работы по embedding inversion, но работают они только на очень коротких фрагментах, только при наличии той же модели-эмбеддера и требуют отдельной тренировки декодера. Для статей в 500-2000 токенов точность падает до уровня бессвязной мешанины. А ещё это значит жёсткую привязку к модели эмбеддингов: поменял её ради качества - будь любезен переиндексировать всю базу, потому что старые векторы в новом пространстве не значат ничего.

Третья, и для меня самая важная - граф ссылок кодирует связность доменов и тем, но не семантическую близость текстов. Vector similarity ищет тематически родственное - тексты, которые словарно и концептуально пересекаются. Но в реальной работе ценные связи часто идут между темами, которые семантически разнесены: статья про Kafka replication у меня ссылается на статью про memory profiling не потому что темы похожи, а потому что при настройке consumer’а всплыла утечка памяти, и эти две темы оказались соседями в графе через реальный опыт. Между “репликацией в распределённой очереди” и “профайлингом памяти в Python” в эмбеддинг-пространстве большая дистанция - semantic search такой мост не построит. А ручная wiki-link строит, и теперь агент, который читает про Kafka, за один клик попадает в memory profiling. Граф фиксирует, какие темы реально смежны, даже когда они формально из разных доменов - именно такие связи обычно и нужны при решении конкретных задач.

Механика простая. Статьи ссылаются друг на друга через wiki-links вида [[flux-klein-9b-inference]], [[two-phase-commit]], [[saga-pattern]]. При сборке Python-хук разрешает slug в относительный путь. Slug не нашёлся - warning в лог, а в strict-режиме билд падает, и сломанная ссылка не попадает на production. Всего таких перекрёстных ссылок 2100+. Это и есть граф знаний - без embeddings, без векторной базы, без RAG. Просто markdown + grep. Агент открывает статью про distributed transactions, в секции See Also видит соседние темы, переходит, продолжает. Три шага от входа до рабочего паттерна.

На главной страницы граф визуализирован на Three.js как 3D-сцена из 27 планет с нейронными импульсами между ними. Красиво, но главная польза - видно, какие домены связаны плотнее всего. Data Science и Architecture - самые связанные узлы.

Сайт - это просто отражение репозитория

Важная мысль, которая делает базу полезной не только мне. Всё, что вы видите на happyin.space , - это статический сайт, собранный из markdown-файлов в открытом репозитории. Никакой БД, никакого backend’а, никаких скрытых слоёв. Файл docs/kafka/broker-architecture.md в репозитории становится страницей happyin.space/kafka/broker-architecture/ после билда. И всё.

Это значит, что базу можно форкнуть и развернуть у себя за пять минут. git clone, pip install -r requirements.txt, mkdocs serve - открываешь localhost:8000 и у тебя локальная копия со всеми 785 статьями, полным поиском и графом связей. Дальше можно чистить моё, дописывать своё, натравливать агентов на локальный сайт вместо публичного - всё одинаково работает. Я сама именно так с ним и живу: большую часть времени у меня открыт локальный билд, а продакшн - это просто зеркало.

Скорость здесь - практическое свойство, полный пересбор всех статей занимает пять секунд, и это важно не для меня, а для того, кто форкнет базу и будет ей пользоваться. Агент, который работает над локальной копией, не тратит токены на сетевой round-trip и ожидание деплоя: пересобрал, увидел нужную статью, забрал рецепт. Слабая рабочая машина тянет весь сайт без проблем, серверы не нужны. Билд на древнем ноутбуке идёт так же быстро, как на рабочей станции - потому что под капотом статический сайт-генератор, который в индустрии используется пятнадцать лет и доведён до ума задолго до того, как появились AI-агенты. Не изобретать велосипед, а взять зрелый инструмент и применить к новой задаче - эта установка и дала такую скорость.

Нулевая тёмная материя среди ссылок - тоже отсюда. У меня 2100+ wiki-ссылок между статьями, и ни одной битой. Механика простая: при билде скрипт проходит по всем [[slug]] в тексте, ищет статью с таким именем и превращает ссылку в правильный относительный путь. Не нашёл - выкидывает ошибку, и билд падает. Локально я это вижу мгновенно, до коммита. На CI та же проверка гоняется в strict-режиме: любая битая ссылка блокирует деплой. Поэтому читатель никогда не попадает на 404 от моей опечатки - такие статьи просто не доезжают до сайта.

Ещё один приятный эффект от того, что сайт = репозиторий: всё под git’ом. Можно посмотреть, как статья менялась со временем, какие факты добавились после какого ресерча, когда была последняя правка. Для базы, где знания стратифицированы по старению, это особенно важно - можно буквально заглянуть в историю и понять, что в этой теме успело устареть.

Как ресёрчи попадают в базу

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

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

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

Разделение моделей по типу работы здесь прямое - и на этом конвейере я, кажется, наконец нашла, куда применять Sonnet. Раньше Sonnet как будто висел между “слишком умный для совсем простых вещей и слишком простой для всего интересного”, и лимиты плана жгли мне глаза. А вот задачи типа “прочитай сырой ресерч, вытащи факты, переупакуй под формат карточки, сверь с соседями по папке” - это ровно его жанр. Механическая, но с языком. Sonnet справляется с переупаковкой текстов отлично, не хуже старшей модели, а стоит заметно меньше. Чаты, которые гоняют ресерч, и сам разбор inbox’а - всё на нём. Когда же дело доходит до проверки wiki-связей, принятия решений о слиянии статей или разбора конфликта между двумя источниками - это “пойми-реши-спроектируй”, и туда уже включается умная модель. Экономия на этом различии выходит в разы, без ущерба для качества.

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

Можно сделать так же и пополнять базу вместе

Вся эта штука под MIT. Репозиторий открыт, база доступна целиком - и я буду рада, если она станет не только моей.

Самый простой способ использовать - отправить своего агента на https://happyin.space/llms.txt. Дальше он сам сориентируется и будет подтягивать карточки по мере надобности. Это сразу срезает ту самую первую треть токенов, которые уходили на ориентацию в чужой документации.

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

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

Сайт: happyin.space Репозиторий (MIT): github.com/AnastasiyaW/knowledge-space Гайды: CONTRIBUTING.md (общий) и AGENTS.md (для агента) в корне репозитория

Если делали что-то похожее - расскажите в комментариях, как решали проблему формата: RAG, обычные docs, свой вариант reference-карточек. Интересно сравнить.