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, максимум сигнала. Статья про Kafkabroker-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у меня ссылается на статью про memoryprofilingне потому что темы похожи, а потому что при настройке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-карточек. Интересно сравнить.
