Knowl

Ваш CLAUDE.md только растёт. Knowl устаревает факты, когда они меняются.

Быстрый старт · Зачем устаревание · Что сохраняется · Возможности · Подключение агента · Просмотр · Требования · Полный справочник →

Ваш агент начинает каждую сессию с чистого листа, поэтому вы держите CLAUDE.md. Он только растёт. Через полгода он всё ещё называет ту базу данных, с которой вы перешли прошлой весной, и теперь агент получает оба ответа.

Knowl — это постоянная память для Claude Code, Cursor и Codex, работающая через MCP или CLI. Когда факт заменяется, старый устаревает вместо того, чтобы конкурировать с новым. API-ключ не нужен. Когда Knowl не уверен, что новый факт заменяет старый, он оставляет оба активными и предлагает вам команду knowl supersede, чтобы указать это.

Выключите это — и точность извлечения падает с 98% до 47%. От начала до конца — с 90 до 73. Как это измерялось ↓

Сорок секунд, одно решение, три агента:

Быстрый старт

Требуется Node.js 22 или новее.

npm install -g @dat999zx/knowl
cd your-project
knowl init

knowl init создаёт .knowl/, устанавливает файлы руководства проекта, обновляет .gitignore и регистрирует Knowl в обнаруженных агентах. Он также разогревает локальную модель эмбеддингов (~53 МБ) в фоне — init завершается успешно в любом случае, а без него у вас всё равно будет поиск по ключевым словам.

Это вся настройка. Вы не записываете память вручную: ваш агент читает и записывает её в процессе работы.

Подключение агента

Claude Code MCP · жизненный цикл · субагенты

Codex MCP · жизненный цикл · субагенты

Cursor MCP · жизненный цикл

Gemini CLI MCP · ручной цикл

Claude Desktop MCP · ручной цикл

knowl init регистрирует MCP-сервер для каждого обнаруженного хоста. После этого запустите новый сеанс, чтобы агент подхватил его инструкции, и он будет самостоятельно запрашивать и записывать память.

→ Как агенты используют это · Инструменты и ресурсы MCP

Идея: память, которая устаревает сама

Большинство систем памяти работают только на добавление. Сохранение «мы перешли на SQLite» оставляет «мы используем PostgreSQL» активным и доступным для поиска, поэтому агент получает оба варианта и выбирает по рангу. Knowl рассматривает запись на ту же тему как исправление: предшествующий факт помечается как superseded (заменённый), выпадает из обычного поиска и остаётся доступным через knowl timeline.

Это отдельное поведение и составляет большую часть разницы в точности. На корпусе проверки разрешения конфликтов MemoryAgentBench — 455 фактов, 100 вопросов о том, какой факт актуален, поиск по топ-5, без LLM-ридера:

Тот же корпус, тот же ранжировщик, тот же путь запроса. Единственная переменная — активен ли устаревший факт. Это измерение на уровне поиска в собственном харнессе Knowl: проверяется, возвращается ли текущий факт первым, без модели в цикле.

Проверено сквозным образом, в собственном харнессе бенчмарка

Поскольку результат, который вы оцениваете сами, стоит меньше, чем результат, оценённый кем-то другим, то же утверждение было повторно прогнано внутри харнесса MemoryAgentBench, оценено его собственным кодом, с LLM, читающим то, что вернул Knowl — более сложная, полностью сквозная настройка, на самом большом контексте, который предлагает задача:

18 332 факта, 100 вопросов, точное совпадение подстроки. Каждая строка использует gpt-4o-mini в качестве ридера, Knowl включён — в статье указано это для всех RAG и memory-агентов, так что сравнение корректное. Knowl и agentmemory были измерены здесь; все остальные цифры взяты из статьи MemoryAgentBench, arXiv 2507.05257v4, таблица 3. agentmemory не оценивается в этой статье — его опубликованные цифры относятся к retrieval-recall по LongMemEval-S, это другая задача — поэтому он был прогнан через тот же харнесс с той же конфигурацией, и оба адаптера используют один общий путь кода ридера, так что ни один не может отклониться от собственного RAG-обработчика статьи. Метод, механизм и шаги воспроизведения: FINDINGS.md.

В остальном показаны все коммерческие memory-системы, которые оцениваются в статье, плюс лучший результат из каждого семейства базовых моделей. Таблица в статье менялась между версиями — BM25 читает 56 в v1 и 48 в v4 — поэтому указана версия, а не только таблица.

Результат Knowl в 90 был измерен 2026-08-08 и независимо воспроизведён на уровне 89.0 2026-08-19 с проверенным адаптером; результат agentmemory в 79 — это один прогон. Каждая цифра здесь — один прогон при temperature: 0.7, и разрыв в абляции сместился на 4 пункта между двумя прогонами одной и той же ячейки 6k, так что читайте их до целого числа, а не до десятичной.

Отключение supersession в том же харнессе снижает Knowl до 73, и разрыв сохраняется при изменении размера корпуса в 40 раз:

Эти два раздела измеряют разные вещи и не сравнимы друг с другом: 98% — это retrieval top-1 при 6K без ридера, 90 — это сквозная точность при 262K с ридером. Только второй показатель сравним с опубликованными системами выше. См. benchmarks для протокола, проверенных результатов и того, что задача не покрывает — включая multi-hop, где Knowl набирает 7 против 14-балльного потолка retrieval.

Supersession — это коррекция, а не удаление: элемент, его утверждения и его история сохраняются.

Не макет — та же последовательность против опубликованного CLI, записанная из demo.tape:

Общая память для команды: knowl.cloud

Всё вышеописанное работает локально и не требует аккаунта. knowl.cloud — это необязательный облачный уровень для случаев, когда одной машины недостаточно:

• Общие рабочие пространства. Знания, записанные в одном чек-ауте, достигают агентов коллег, при этом каждый репозиторий сохраняет право собственности на публикуемое.
• Браузерные агенты. claude.ai и chatgpt.com не могут запускать локальный процесс, поэтому они подключаются через удалённую MCP-конечную точку с токеном, ограниченным одним рабочим пространством.

Локальный режим остаётся полноценным способом запуска Knowl. Ничто здесь не обязательно для использования вышеописанного.

Что сохраняется

Каждый атом имеет ровно одну из семи категорий:

Помимо содержимого, каждый атом хранит статус (active, deprecated, rejected, archived, superseded), флаг свежести, уверенность, теги, коммит-источник, затронутые пути и опциональные доказательства, указывающие на файлы, коммиты, тесты, команды, URL-адреса или индексированные символы кода. Доказательства файлов и символов устаревают сами по себе, когда код меняется — именно так атом признаёт, что может быть устаревшим, вместо того чтобы утверждать версию репозитория, которой больше не существует.

Чего Knowl намеренно не хранит — так это ваших разговоров. Захват жизненного цикла записывает ограниченные события и сводки — никогда не подсказки, транскрипты, stdout или переменные окружения. Поиск по сырым транскриптам существует как опциональный индекс, отключённый по умолчанию, по файлам, которые хост уже записал.

→ Справочник по модели знаний

Как агенты это используют

knowl serve предоставляет хранилище через stdio MCP; knowl init регистрирует его за вас. Рабочий процесс, который установленные инструкции предлагают агентам, краток:

1. Запрашивайте память словами, которые называют предмет, перед чтением файлов репозитория.
2. Используйте активное совпадение напрямую; просматривайте файлы только при промахе, конфликте или устаревшем результате.
3. Сохраняйте долговременные выводы, заявленные цели и повторяющиеся диагнозы по ходу работы, и исправляйте противоречащую память, а не дублируйте её.

На практике это выглядит так — новая сессия, без контекста, ничего не вставлено:

You     why did we pick SQLite over Postgres?

Agent   → knowl_query "sqlite postgres database choice"
        ← decision · Use SQLite · active · fresh
          "Keeps storage repository-local and simple to operate."
          alternatives: PostgreSQL, MongoDB
          tags: database, local-first

        SQLite keeps the store repository-local and simple to operate.
        Postgres and MongoDB were both considered and rejected on that
        basis.

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

Там, где доступны хуки, они управляют жизненным циклом сессии: начальный контекст, захват, контрольные точки и финализация происходят без запроса агенту. Где их нет, knowl task run, task start, task checkpoint и task finish покрывают то же самое вручную.

knowl init записывает регистрацию MCP для каждого обнаруженного хоста. Для ручного подключения запись одинакова везде:

{
  "mcpServers": {
    "knowl": { "command": "knowl", "args": ["serve"] }
  }
}

Используйте knowl.cmd как команду в Windows. Codex читает ту же запись под mcp_servers.

→ MCP-инструменты и ресурсы · Справочник по жизненному циклу

Для чего нужен Knowl

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

Отсюда следуют три решения:

• Типизировано, а не свободный текст. Решение несёт обоснование и отклонённые альтернативы. Ограничение — это правило, которое должно сохраняться. Атом state ожидаемо устаревает. Поиск может ранжировать по этим различиям; он не может ранжировать по абзацам в файле заметок.
• Управляемая, а не только добавляемая. Статус, актуальность, происхождение, идентичность конфликта и замещение позволяют хранилищу сообщить вам, что что-то перестало быть истинным. В этом и заключается вся разница между памятью и постоянно растущей кучей заметок.
• Локальная для репозитория, а не сервис. База данных находится рядом с кодом, который она описывает. Никакого аккаунта, никакого исходящего трафика, никакого посредника между вами и историей вашего собственного проекта.

Knowl намеренно не является слоем персонализации. У него нет своего мнения о ваших пользователях, и он не хранит собственных транскриптов.

Возможности

Всё перечисленное ниже работает из CLI и из любого агента, подключённого через MCP, с одной и той же локальной базой данных. Никакого аккаунта, сервера или API-ключа. Каждый пункт ссылается на полную документацию для получения деталей — и ограничений.

Команды, которые стоит знать с первого дня:

knowl query "auth design"              # search project memory
knowl list --unread                    # browse it — and see what nothing ever reads
knowl edit <item-id>                   # open one memory in the viewer to fix it
knowl state                            # the active memory, as a hierarchy
knowl conflicts                        # items that contradict each other
knowl timeline <item-id>               # every version an atom ever had
knowl context --token-budget 1500      # a fixed-size briefing for an agent
knowl pr --since origin/main           # knowledge your diff may invalidate
knowl doctor                           # setup, retrieval, and registration

Знание, которое само себя исправляет — семь типизированных типов атомов и запись, которая замещает то, что заменяет

• Семь типов атомов — перечислены выше. Структура вместо одного растущего файла заметок.
• Автоматическое замещение — запись по той же теме замещает своего предшественника. Это и есть разница между 90 и 73 выше.
• Идентичность конфликта — пометьте атом как эксклюзивный, и Knowl откажется принимать второй активный ответ на тот же вопрос, вместо того чтобы молча хранить оба. knowl conflicts
• Полная история — каждая версия атома, которая когда-либо существовала, сохраняется как неизменяемое утверждение. knowl timeline <item-id>
• Путешествие во времени — спросите, во что проект верил на определённую дату в прошлом: knowl query "auth design" --as-of 2026-01-01T00:00:00Z
• Доказательства — прикрепите файлы, символы, коммиты, тесты, команды или URL-адреса к атому. Доказательства для файлов и символов сами устаревают, когда код меняется.
• Обнаружение расхождений — knowl pr --since origin/main помечает знания, которые ваш дифф мог аннулировать, до того, как вы его объедините.
• Анализ кода — инкрементальный индекс Tree-sitter по .ts / .tsx / .js / .jsx, поэтому доказательства могут указывать на локаторы symbol://, а не только на номера строк. knowl index-code
• Безопасная запись — каждая запись проверяется на обнаруженные секреты, чувствительные пути и чрезмерно большой контент до того, как будет сохранена. Долговременная память — последнее место, где должен оказаться пароль.

→ Модель знаний · Доказательства и расхождения

Поиск, оптимизированный для агентов — актуальный ответ побеждает, а не просто похожий

• Векторно-первичное ранжирование с ограниченным запасным вариантом BM25, повторное ранжирование по свежести, статусу, уверенности и недавности — так что актуальный ответ побеждает, а не просто похожий. (Это путь агента/MCP; однострочный knowl query из CLI — лексический.)
• Работает офлайн. Модель эмбеддингов локальная и опциональная; без неё вы всё равно получаете поиск по ключевым словам. Поиск никогда не отправляет ваш запрос куда-либо.
• Пять встроенных пресетов эмбеддингов, включая многоязычный, охватывающий более 200 языков, а также custom для вашей собственной модели ONNX. knowl config set-model <model>
• Поддержка точных идентификаторов — имена файлов, ID элементов и локаторы symbol:// находятся даже тогда, когда семантическая близость слаба.
• Контекстные пакеты с ограничением токенов — выдайте агенту бриф фиксированного размера, где ограничения указаны первыми, чтобы незыблемые правила никогда не обрезались: knowl context --query "auth rollout" --token-budget 1500
• Обратная связь об использовании — агенты сообщают, помог ли результат, и knowl access показывает, что активно используется, что устарело и что постоянно вызывает исправления.

→ Поиск и контекст

Работа, которая переживает завершение сессии — хуки, рабочие циклы, эстафетные палочки и ключи возобновления

• Автоматический жизненный цикл в Claude Code, Codex и Cursor — загрузка, захват, контрольные точки и финализация выполняются через хуки без запроса агенту.
• Рабочие циклы для всего остального — knowl task start, checkpoint, finish или обёртка одной команды через knowl task run "Run tests" -- npm test.
• Повышение в конце сессии — чистое завершение выделяет до восьми устойчивых кандидатов из сессии, а команда, успешно выполненная три раза, становится атомом skill, описывающим её.
• Передача — оставьте одну эстафетную палочку для следующей сессии в этом репозитории. Она доставляется один раз, затем архивируется.
• Ключи возобновления — приостановите рабочий поток под коротким ключом, который вы храните, и возобновите его в любой сессии, из любого каталога, любое количество раз позже. knowl resume <key>
• Необязательный поиск по транскриптам — выключен по умолчанию, и выключенный означает, что ничего не существует на диске. Включите его, и текст прошлых сессий станет доступен для поиска, так что промах памяти деградирует до более медленного поиска вместо амнезии.

→ Задачи, сессии и жизненный цикл

Рабочие пространства: много репозиториев, одна общая память — вы решаете, чем делится каждый репозиторий

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

knowl workspace init product      # create the workspace
knowl workspace add product       # run inside each repo that joins it
                                # ...or --default-visibility repo to keep its writes private

knowl workspace promote                               # pick what to share from a list
knowl workspace promote --category decision --apply   # or name it outright

Присоединение к рабочему пространству делится тем, что репозиторий записывает с этого момента, и сообщает об этом, когда это делает; передайте --default-visibility repo, чтобы отказаться. То, что репозиторий уже знает, делится только когда вы это повышаете. Результаты от пиров помечаются репозиторием-владельцем, и общий результат можно открыть полностью по id — без его affectedPaths или доказательств, которые разрешаются относительно чекаута, в котором вы не находитесь. Пир, который отсутствует или нечитаем, пропускается и раскрывается, и никогда не является причиной сбоя вашего локального поиска.

Запись в соседний репозиторий — это намеренное действие, а не случайное. Агент называет репозиторий в вызове, и этот один вызов выполняется как этот репозиторий — его хранилище, его конфигурация, его правила владения, помеченные как его собственные — точно так же, как cd туда всегда работал для CLI. Не называйте ничего, и чужой id будет отклонён, как и раньше. В любом случае приватные знания репозитория остаются приватными, пока не будут повышены. → Рабочие области

Многократно используемые процедуры — навыки на основе файлов, которые можно проверить до их запуска

• Навыки на основе файлов — упакуйте процедуру с её скриптами в .knowl/skills/, затем проверьте её до запуска. knowl skill list · read · run
• Детерминированная сборка — объедините несколько атомов в одну сводку архитектуры без участия ИИ-провайдера: knowl synthesize --scope storage

→ Навыки и сборка

Ваши данные и их возврат — переносимый экспорт, проверенные снимки и одна команда doctor

• Переносимый экспорт/импорт — JSONL с контрольными суммами и четырьмя явными политиками расхождений для случаев, когда один и тот же атом изменился в двух местах. knowl export · knowl import --on-divergence newer
• Проверенные снимки — knowl snapshot create записывает манифест контрольных сумм; восстановление проверяет версию схемы, размер, SHA-256 и целостность SQLite до изменения чего-либо, а также сначала создаёт снимок перед восстановлением.
• Сборка мусора — по умолчанию показывает предпросмотр и защищает недавно использованные данные. knowl gc
• knowl doctor — одна команда, которая проверяет настройку, конфигурацию, целостность, схему, поиск, векторное покрытие, регистрацию агентов и состояние рабочей области.
• Опциональный ИИ — настройте провайдера для knowl ask и приёма текста в сыром виде. Каждая функция выше работает и без него.

→ Переносимость и обслуживание · Опциональный ИИ

Посмотрите сами: локальный просмотрщик

knowl view запускает редактор на 127.0.0.1 с новым токеном доступа при каждом запуске — знание порта недостаточно для чтения данных, а для записи дополнительно требуется, чтобы запрос указывал этот просмотрщик как источник, поэтому другая открытая у вас страница не сможет сюда записать.

knowl view

Здесь вы исправляете то, что ваши агенты сделали неправильно. Откройте любой атом, чтобы прочитать его доказательства и временную шкалу, затем отредактируйте его, архивируйте или напишите новый вручную. Архивация обратима — кнопка «Восстановить» находится на той же панели.

Рядом с графом есть список с фильтром для того, что никто никогда не читал. Он оправдывает своё место: поиск достигает только памяти, о существовании которой вы уже подозреваете, а атом, не несущий информации, — именно тот, который никто не думает искать. Сортировка сначала по старым — он всплывает сам по себе. knowl list --unread задаёт тот же вопрос из терминала.

Граф связывает атомы только через теги, которые делят немногие атомы — тег на десятках атомов — это категория, и боковая панель уже фильтрует по ним. Атом, о котором ничего больше нет, остаётся несвязанным, а не привязывается к произвольному соседу. Это навигационное средство, а не граф причинности или доказательств. Он показывает полное локальное содержимое всех статусов, поэтому привязка к loopback — это граница конфиденциальности: не размещайте его за публичным прокси или туннелем.

→ Локальный просмотрщик

Всё остальное

27 MCP-инструментов (плюс 3 при включённом поиске по транскриптам, 1 при подключении к облачной рабочей области, 1 при связывании с локальной рабочей областью и 1 при включённом анализе изменений)

и два URI ресурсов · полный CLI, от knowl status до knowl audit · аудит целостности только для чтения · оценка поиска, которую можно запустить самостоятельно против включённых наборов тестов управления и регрессии на 500 случаев с помощью knowl eval.

→ Справочник по CLI · MCP-инструменты · Бенчмарки

Требования и локальные данные

Node.js 22 или новее. Все, что Knowl записывает для проекта, хранится в .knowl/, которую knowl init добавляет в .gitignore:

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

Документация

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

Участие в разработке

См. CONTRIBUTING.md для настройки, проверок, которые необходимо выполнить перед pull request, и соглашений, которым следует эта кодовая база. Участникам предлагается один раз согласиться с Лицензионным соглашением с участником при первом pull request.

Лицензия

Knowl распространяется под Apache License 2.0. Apache-2.0 не предоставляет прав на товарные знаки.