knowl

Локально-ориентирован. Типизирован. И устаревает в тот момент, когда перестаёт быть актуальным.

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

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

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

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

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

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

knowl init создаёт .knowl/, устанавливает файлы руководства проекта, обновляет .gitignore и предлагает настройку MCP и жизненного цикла для обнаруженных агентов — Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop. Он также прогревает локальную модель эмбеддингов, но никогда не зависит от того, успешно ли прошла эта загрузка.

Запишите что-то, что стоит сохранить:

knowl decide "Use SQLite" "Use SQLite for local project memory." \
  --reasoning "Keeps storage repository-local and simple to operate." \
  --alternatives PostgreSQL MongoDB \
  --tags database local-first

Прочитайте это обратно — из CLI или от любого подключённого агента:

knowl query "why sqlite"     # search project memory
knowl state                  # the active memory, as a hierarchy
knowl status                 # repository, memory, AI, and workspace status
knowl doctor                 # check setup, retrieval, and agent registration

Затем запустите новую сессию агента, чтобы хост подхватил его руководство и регистрацию MCP. CLI и knowl_query читают одно и то же хранилище по одним и тем же правилам управления.

Related MCP server: Mnemoverse Memory

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

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

Одно это поведение обеспечивает большую часть разницы в точности. В тесте MemoryAgentBench Conflict Resolution — 455 фактов, 100 вопросов о том, какой факт актуален, поиск top-5, без LLM-ридера:

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

Проверено end-to-end, в собственном стенде бенчмарка

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

18 332 факта, 100 вопросов, точное совпадение подстроки. Каждая строка использует gpt-4o-mini в качестве ридера, включая Knowl — в статье это указано для всех RAG и агентов памяти, так что сопоставление корректно. Показатель Knowl был измерен здесь; все остальные показатели — из таблицы 2 статьи MemoryAgentBench. Системы, которые статья не оценивает на этой задаче, не перечислены.

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

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

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

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

Что хранится

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

Наряду с содержимым, каждый атом хранит статус (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. Каждый пункт ведёт к полному справочнику для подробностей — и для ограничений.

♻️ Знания, которые исправляют себя

Семь типизированных типов атомов, где запись по той же теме удаляет своего предшественника вместо того, чтобы находиться рядом с ним. Это одно поведение и есть разница между 90 и 73. Свидетельство, прикреплённое к файлу или символу, устаревает само по себе, когда код перемещается.

conflicts · timeline · query --as-of · pr --since · index-code

🎯 Поиск, настроенный для агентов

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

query · context --token-budget · config set-model · access

⏱️ Работа, которая переживает сеанс

В Claude Code, Codex и Cursor хуки управляют начальной загрузкой, захватом, контрольными точками и финализацией без запроса агенту. Чистое завершение отбирает до восьми долговечных кандидатов. Приостановите рабочий поток под ключом и возобновите его в любом сеансе, из любого каталога.

task run · handoff · park · resume <key>

🔗 Рабочие пространства

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

workspace init · workspace add · workspace promote --apply

📦 Повторно используемые процедуры

Упакуйте процедуру с её скриптами в .knowl/skills/, затем прочитайте её до того, как она когда-либо запустится. Сверните несколько атомов в одну детерминированную сводку архитектуры без участия какого-либо поставщика ИИ.

skill list · skill read · skill run · synthesize

💾 Ваши данные и их возврат

Экспорт и импорт JSONL с контрольной суммой и четырьмя явными политиками на случай, когда один и тот же атом изменился в двух местах. Восстановление проверяет схему, размер, SHA-256 и целостность SQLite до того, как что-либо трогать, и сначала делает снимок до восстановления.

export · import --on-divergence · snapshot create · gc · doctor

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

knowl query "auth design"              # search project memory
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 помечает знания, которые ваш diff мог сделать недействительными, до того, как вы их сольёте.

• Интеллект кода — инкрементальный индекс Tree-sitter для .ts / .tsx / .js / .jsx, чтобы свидетельства могли указывать на локаторы symbol://, а не только на номера строк. knowl index-code

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

→ Модель знаний · Свидетельства и дрейф

• Векторный первичный рейтинг с ограниченным запасным вариантом BM25, переранжированный по свежести, статусу, уверенности и недавности — так что текущий ответ побеждает, а не просто похожий. (Это путь агента/MCP; knowl query из CLI для одного репозитория является лексическим.)

• Работает офлайн. Модель встраивания локальна и опциональна; без неё вы всё равно получаете поиск по ключевым словам. Поиск никогда не отправляет ваш запрос куда-либо.

• Пять встроенных пресетов встраивания, включая многоязычный, охватывающий более 200 языков, плюс custom для вашей собственной модели ONNX. knowl config set-model <model>

• Поддержка точных идентификаторов — имена файлов, идентификаторы элементов и локаторы 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, чтобы отказаться. То, что репозиторий уже знает, становится общим только тогда, когда вы это продвигаете. Результаты коллег помечены репозиторием-владельцем, и общий результат можно открыть полностью по идентификатору — без его affectedPaths или свидетельств, которые разрешаются относительно рабочей копии, в которой вы не находитесь. Результат коллеги, который отсутствует или нечитаем, пропускается и раскрывается, но никогда не является причиной сбоя вашего локального поиска.

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

→ Рабочие пространства

• Навыки на основе файлов — упакуйте процедуру с её скриптами в .knowl/skills/, затем проверьте её до первого запуска. knowl skill list · read · run

• Детерминированный синтез — объедините несколько атомов в одну сводку архитектуры без участия AI-провайдера: knowl synthesize --scope storage

→ Навыки и синтез

• Портативный экспорт/импорт — JSONL с контрольными суммами и четырьмя явными политиками расхождения на случай, если один и тот же атом изменился в двух местах. knowl export · knowl import --on-divergence newer

• Проверенные снимки — knowl snapshot create записывает манифест с контрольными суммами; восстановление проверяет версию схемы, размер, SHA-256 и целостность SQLite до того, как что-либо трогать, и сначала создаёт снимок перед восстановлением.

• Сборка мусора, которая по умолчанию показывает предварительный просмотр и защищает недавно использованное. knowl gc

• knowl doctor — одна команда, проверяющая настройку, конфигурацию, целостность, схему, поиск, покрытие векторов, регистрацию агентов и работоспособность рабочего пространства.

• Опциональный AI — настройте провайдера для knowl ask и приёма необработанного текста. Все перечисленные выше функции работают без него.

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

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

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

knowl view

Поиск, фильтрация по категориям, обнаружение устаревших колец, фокусировка на окрестности и открытие любого атома для просмотра его доказательств и временной шкалы. Граф связывает атомы через общие теги и рёбра, производные от категорий — навигационный инструмент, а не граф причинно-следственных связей или доказательств. Он показывает полное локальное содержимое для всех статусов, поэтому граница конфиденциальности — это 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:

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

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

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

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

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

Лицензия

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