@dikolab/kbdb

Файловая база знаний с ранжированным поиском по ключевым словам и семантическим (гибридным) поиском -- изучайте свои документы, затем извлекайте нужные знания. Без внешнего сервера. Работает как CLI и MCP-сервер.

📖 Документация · Настройка MCP · Справочник CLI

GitLab | NPM | JSR | Лицензия: AGPL-3.0

Работает на Node.js 20+ или Deno 2.6+. Без сервера базы данных, без облачного аккаунта -- просто файлы на диске.

Что такое kbdb?

kbdb даёт AI-агентам постоянный, доступный для поиска второй мозг. Укажите на ваши Markdown-документы -- и он проиндексирует их в файловую базу знаний; затем агенты (и вы) извлекают наиболее релевантные знания с помощью ранжированного поиска по ключевым словам и семантического поиска, а не точного совпадения ключей. Это живое хранилище: агенты узнают новые факты, обновляют их и вспоминают их между сессиями.

Никакого внешнего сервера для установки, никакого облачного аккаунта -- просто файлы на диске. Работает везде, где работает Node.js или Deno, и функционирует как MCP-сервер, так что такие агенты, как Claude, могут подключить его как инструмент памяти.

Как работает поиск: kbdb по умолчанию использует поиск по ключевым словам -- синонимы расширяются, термины ранжируются по релевантности, а заголовки имеют вес 2× при оценке. Когда точный запрос ничего не находит, kbdb автоматически ослабляет условие соответствия, чтобы вы всё равно получили лучшие доступные результаты.

Хотите более умные результаты? Используйте --algo hybrid, чтобы объединить поиск по ключевым словам с поиском по сходству -- вы получите результаты, даже когда разные слова описывают одно и то же понятие. Провайдер эмбеддингов TF-IDF по умолчанию работает офлайн без настройки. Замените его на сторонний провайдер (локальная модель ONNX или удалённый API) в worker.toml, когда вам нужны более богатые эмбеддинги.

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

Related MCP server: Librarian

Начало Работы

Что вам нежно

Один из этих вариантов (выбирайте тот, что у же есть):

• Node.js версиии 20 или новее -- Скачать

• Deno версиии 2.6 или новее -- Скачать (2.6 — минимальная версия: движок хранения загружает свой WebAssembly через source-phase imports -- это позволяет ему работать офлайн после одного deno install. Более старые версии Deno падают с вводящей в заблуждение ошибкой Module not found, указывающей на файл .wasm, который присутствует.)

И всё. Никакого сервера баз данных. Никаких дополнительных инструментов.

Установка

С помощью Node.js:

Сборка CLI размещена на NPM.

npm install -g @dikolab/kbdb

С помощью Deno:

Сборка CLI размещена на JSR.

deno install -Agf jsr:@dikolab/kbdb/cli

См. Руководство по установке CLI для требований и шагов проверки.

Попробуйте

1. Создайте базу знаний

kbdb db init --db ./my-kb

Это создаёт папку .kbdb, в которой хранятся все ваши данные.

2. Загрузите в неё ваши документы

kbdb learn ./docs

Укажите папку с Markdown-файлами. kbdb читает их, разбивает на разделы и строит индекс поиска. Добавьте --tags design,v2 для метки разделов по областям, --replace для обновления существующих разделов из того же источника, или --level 2 для установки иерархической глубины (1 = самая широкая, 6 = самая узкая). При обучении каталоге уровень опредляется автоматичски по глубине каталога.

3. Поиск

kbdb search "how does auth work"

Результаты сортируются по релевантности, с фрагментами (snippets), показывающими, где совпали ваши термины. Вывод по умолчанию имеет формат --format rec (recфайфайл: одно field: value на строку) для удобного grepping. Другие форматы: json (мащинно-читаемый), text (нумированный список) и mcp (конверт JSON-RPC 2.0). Используйте --offset для страницы в страницы по большим наборам результаов.

Чтобы попробовать гибридный поиск (ключевые + AI similarity):

kbdb search "how does auth work" --algo hybrid

Совет: --db необязателен для CLI. kbdb поднижается от вашей рабочей каталоги к ближайшей папке .kbdb, чтобы команды работали просто в любом месте в формате. Для конкретной базы используйте --db <dir> (родитель .kbdb), или установите KBDB_DB_DIR. Только сервер mcp требует явного --db -- он никогда не ищет в рабочей каталоге.

Поиск по нескольким базам: обогатите результаты нередактируемыми (read-only) знаниями из других баз с помощью --other-db <dir> (повторяемый), или добавьте --cascade для также затягивания данных из .kbdb папок в родительских каталогах:

kbdb search "how does auth work" \
   --other-db ~/shared-kb --cascade

Каждый результат несёт поле source_db -- корень базы, из которой она происходит, -- которое можно вставить путь обратно в --db или --other-db.

Скриптование: Добавьте --format json для получения структурированного JSON-вывода для разбора. Используйте --non-interactive или установите переменную KBDB_NON_INTERACTIVE=1 для отключения запросов в CI-процессах.

4. Контекстный просмотр

kbdb recall <kbid> --depth 1

Начните с kbid результата поиска и расширяйте контекст постепенно: с глубиной 0 -- содержимое раздела, глубина 1 добавляет родительские докименты и обратныные ссылки, глубина 2 -- соседние и прямые ссылки, глубина 3 -- полный текст соответных разделов.

База Знаний

Создавайте, ищите и поддерживайте ваше хранилище знаний.

• Импорт Markdown и текстовых files с метками и отслеванием источникоdов

• Умные обновения -- повторное обучение файла заменяет прежднюю версию вместто дубликования

• История -- устаревший раздел уходит в архив, не удаляется: kbdb history следит вдоль цепи с любого конца, и старый kb-id все ещё решается

• Поиск с тремя алгоритами: по ключевым (по умолчанию), AI-сходство, гибридный (оба)

• Автоматический фолбаек -- если ваш точный запрос нечего не находит, kbdb автматически ослабляет условие

• Рекол с прогрессивным конекстектом -- от быстрого резюмме до полного связанного содержимого, или до глубины, который позволяет budget --max-tokens

• Измерение качсва поиска -- kbdb eval выставляет оценки Recall@k, MRR и nDCG@k на ваших собственных даннных и завершается с ненулевым кодом при ухучшении

• Близость -- kbdb neighbourhood показывает, что относится к разделу и каким образом: восемь типов связей, семеро задокументированы, один выводится

• Консолидация -- kbdb consolidate предлагает группы разделов, которые можно объединить. Он только предлагает; вы обновляете объединение и применяете его сами

• Экспорт -- снимите снапшот вашей базы знаний для резервного копирования

• Проверка целостности базы данных и удаления устарелых даннных

• Перестроения индексов, ессли что-то коснулось

См. Руководство по базе знаний для полного описание, включая экспорт и резервное копирование.

Инструменты для агентов

Интегрируйте kbdb с ИИ-агентами и ващими инструментами.

MCP-быстрый старт (Claude CLI):

claude mcp add kbdb -- \
   npx @dikolab/kbdb mcp --db /path/to/project

См. Руководству по инсталляции MCP для файл конфигурации Claude Code, VS Code, и Claude Desktop, плюс отлаживание.

• MCP-сервер с 30 инструментами -- search, rec, learn, revise, gaps, contradictions, export, skills/agent search, и многое другое

• Навыки -- сохраненные шаблоны промптов с аргументами, заполняющими пробелы

• Агенты -- профили ИИ-агентов, которые сочетают персону с навыками

• Полis capture policy -- сервер сообщает агенту заранее, что сохранять во время самого MCP-хендшейка, так что он не требует конфига на каждого хоста. Два из шести пунктов -- что не сохранять: резюме чатов, догадки, секреты и все, что уже есть коде. kbdb передает политику; он не может заставить агента следовать ей.

• АвтозаписьAuto-capture-- может запросить модель самого хоста, освоить знания, стоящие хранить. Ему нужна MCP sampling capability, и Claude Code е не объявляет, так автозахват там не работает.

• Каждая другая функция в этом списке работает -- См. Поддержка хостов

• Стойкость demon -- настраиваемый тайм-аут запроса и автоматический повтор попытки с возрождением демона

• Управление жизненным циклом фонового процесса -- остановка и перезапуск процесса демонизации Granular Deno permissions -- демон запускается с ограниченными правами, а не --allow-all

• Ограничение путей -- демон отвергает traversal (..) в экспорт/импорт

Что серввер говорит агентам. Ответ initialize несет строку instructions -- единственный канал, который любой соответствующий MCP-хосте получает без настройки. kbdb тратит ее на политику захвата: ищите перед ответом, treatе unanswered как пробелв для исследования, а не догкаыстов; сохраняйте решения и исправления, которые требуют реальных усилий для находения и не храните то, что уже озвучивает код. Те же самые предложения цитируются в описаниях инструментов learn, revise и search, а не перефразируются, поэтому существует единый источник для всех них.

См. Руководство по инструментам агенов для MCP setup, skills, agents, и библиотечного API, а Capture Policy для полного описения шести условий and why they are written once.

This is a section of a longer document. Translate the text content only, never the tags or their attributes, and preserve the exact structure of Markdown tables (same number of rows, columns, and pipe separators).

For Developers

Library API

Use kbdb programmatically in your Node.js or Deno project:

import { createWorkerClient } from '@dikolab/kbdb';

// Spawns a background worker if not already running
const client = await createWorkerClient({
   contextPath: '/path/to/.kbdb',
   requestTimeoutMs: 30_000,
});

const results = await client.search({
   query: 'authentication',
   limit: 10,
   offset: 0,
});

console.log(results.items);
client.disconnect();

Pass contextPath (the .kbdb directory itself) or dbPath (the parent directory -- kbdb discovers .kbdb inside it).

See the Library API Reference for the full API.

Development Setup

git clone https://gitlab.com/diko316/knowledge-base-db.git
cd knowledge-base-db
npm install
npm test

Docker

Two Dockerfiles, and they are not interchangeable.

Dockerfile at the repository root builds the MCP server -- that is the one MCP directories build, and the one to use if you want kbdb in a container. See Install MCP Server for the host configuration and why it needs a named volume rather than a bind mount.

Dockerfile.tooling builds the development toolchain (Node.js and Deno), which every make target uses through docker-compose.yaml:

HOST_UMASK=$(umask) docker compose run --rm tool sh

Run make benchmark to measure search and rebuild latency at scale -- results are written to docs/benchmark/benchmark.md automatically.

See the Makefile for all available build targets.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes and add tests

4. Run npm test and npm run lint

5. Open a merge request

Documentation

• Второй мозг с Claude Code -- каноническое руководство по настройке: структура рабочего пространства, правильные команды, подключение MCP

• Руководство по установке CLI -- предварительные требования, установка через npm/JSR, проверка

• Руководство по базе знаний -- импорт,поиск, извлечение, экспорт

• Руководство по инструментам агентов -- MCP, навыки, агенты, библиотечный API

• Справочник по CLI -- полный список команд с примерами

• Руководство по устновке MCP -- Claude CLI, Claude Code, VS Code, Claude Desktop

• Руководство по MCP-серверу -- настройка, инструменты, конфигурация среды и что сервер сообщает агенту при initialize

• Подержка хостов -- какие MCP-хосты подерживают политику захвата и анонсируют сэмплинг, это измеренное значение, а не предположение

• Политика захвата -- что kbdb повелевает агенту сохранять, и почему это указано один раз

• Поиcк и ранжирование -- как работает поиск внутри

• Архитектура хранения -- форматы файлов, структура каталогов и во сколько обходится сохранённая история

• Разрешения Deno -- флаги разрешений, необходимые kbdb, и зачем

• Результаты бенчмарка -- задержка поиска и пересборки при масштабировании

• Масштабирование обучения -- как стоимость обучения растёт с размером корпуса

• Сигналы противоречий -- калибровка порогов почти дубликатов и противоречий на 1128 размеченных парах

• История изменений

• Обзор архитектуры

Поисковый движок

Хранение, индексация и ранжирование реализованы на базе @dikolab/vdb, проекта-соседа kbdb от того же автора. Его документация подробно покрывает сторону поиска:

• Обзор vdb -- модель хранения, партиции, BM25F, векторный и гибридный поиск

• Примеры vdb -- проработанные запросы и поведение ранжирования

Поддержка

kbdb — свободное ПО под лицензией AGPL. Если оно заслужило место в вашем рабочем процессе, вы можете поддержать развитие проекта через PayPal.

Лицензия

Проект имеет двойное лицензирование:

• Открытый исходный код под лицензией GNU Affero General Public License v3.0 (AGPL-3.0-only)

• Коммерческая лицензия для закрытого кода или SaaS

Версии <= 0.5.0 остаются под лицензией ISC.

Подробнее см. в LICENSING.md и контактной информации.