@dikolab/kbdb

Una base de conocimiento basada en archivos con búsqueda por palabras clave clasificadas y semántica (híbrida) — aprende tus documentos y luego recupera el conocimiento relevante. Sin servidor externo. Funciona como CLI y servidor MCP.

📖 Documentación · Configuración de MCP · Referencia de CLI

GitLab | NPM | JSR | Licencia: AGPL-3.0

Funciona con Node.js 20+ o Deno 2.6+. Sin servidor de base de datos, sin cuenta en la nube — solo archivos en disco.

¿Qué es kbdb?

kbdb les da a los agentes de IA un segundo cerebro persistente y consultable. Apúntalo a tus documentos Markdown y los indexa en una base de conocimiento basada en archivos; luego, los agentes (y tú) recuperan el conocimiento más relevante mediante búsqueda por palabras clave clasificadas y búsqueda semántica, no con una consulta de clave exacta. Es un almacén vivo: los agentes aprenden datos nuevos, los actualizan y los recuerdan entre sesiones.

No hay servidor externo que instalar, ni cuenta en la nube: solo archivos en disco. Funciona en cualquier lugar donde se ejecute Node.js o Deno, y sirve como servidor MCP, donde agentes como Claude pueden conectarse a él como una herramienta de memoria.

Cómo funciona la búsqueda: kbdb usa búsqueda por palabras clave de forma predeterminada: los sinónimos se expanden, los términos se clasifican por relevancia y los encabezados tienen un peso de 2× en la puntuación. Cuando una consulta exacta no encuentra nada, kbdb afloja automáticamente la coincidencia para ofrecerte los mejores resultados disponibles.

¿Quieres resultados más inteligentes? Usa --algo hybrid para combinar la coincidencia por palabras clave con la búsqueda por similitud, y encuentra resultados aun cuando palabras distintas describen el mismo concepto. El proveedor de embeddings TF-IDF predeterminado funciona sin conexión y sin configuración alguna. La creación de un proveedor del tipo que quieras instalarlo en worker.toml cuando necesites embeddings más ricos: un modelo ONNX local o una API remota.

El conocimiento se mantiene fresco: al volver a aprender un archivo, kbdb reemplaza automáticamente la versión anterior. La detección de casi duplicados te avisa cuando estás aprendiendo algo que ya tienes, por similitud de embeddings, de modo que detecta el mismo hecho reformulado, no solo los mismos bytes. kbdb contradictions informa de las secciones que tratan lo mismo para que puedas leerlas juntas. Las comprobaciones de integridad verifican las sumas de verificación, los huérfanos y las referencias. Las puntaciones de confianza ayudan a los agentes a distinguir las coincidencias fuertes de las débiles.

Related MCP server: Librarian

Cómo empezar

Qué necesitas

Una de estas opciones (elige la que ya tengas):

• Node.js versión 20 o más reciente — Descargar

• Deno versión 2.6 o más reciente — Descargar (2.6 es el mínimo: el motor de almacenamiento carga su WebAssembly mediante imports en fase de fuente, lo que le permite funcionar sin conexión después de un deno install. Las versiones anteriores de Deno fallan con un error engañoso Module not found que menciona un archivo .wasm que está presente.)

Eso es todo. Sin servidor de base de datos. Sin herramientas adicionales.

Instalación

Con Node.js:

La compilación de la CLI está alojada en NPM.

npm install -g @dikolab/kbdb

Con Deno:

La compilación de la CLI está alojada en JSR.

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

Consulta la Guía de instalación de la CLI para conocer los requisitos previos y los pasos de verificación.

Pruébalo

1. Crea una base de conocimiento

kbdb db init --db ./my-kb

Esto crea una carpeta .kbdb que contiene todos tus datos.

2. Alimenta la base con tus documentos

kbdb learn ./docs

Apúntala a una carpeta con archivos Markdown. kbdb los lee, los divide en secciones y construye un índice de búsqueda. Añade --tags design,v2 para etiquetar secciones y acotar el ámbito, --replace para actualizar las secciones existentes de la misma fuente, o --replace all, o --level 2 para fijar la profundidad jerárquica (1 = más amplia, 6 = más estrecha). Al aprender un directorio, el nivel se detecta automáticamente de la profundidad de la carpeta.

3. Busca

kbdb search "how does auth work"

Los resultados se clasifican por sobre el punto de una serie de estado con fragmentos que muestran dónde coinciden tus términos. La salida json.

La salida predeterminada es --format rec (formato recfile: un field: value por línea) para que sea fácil de filtrar con grep. Otros formatos: json (legible para máquinas), text (lista numerada) y mcp (envoltorio JSON-RPC 2.0). Usa --offset para paginar por resultados.

Para probar la búsqueda híbrida (palabras clave + similitud de IA):

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

Consejo: --db es opcional para CLI. kbdb asciende desde tu directorio de trabajo hasta la carpeta .kbdb más próxima, así que los comandos funcionan desde cualquier lugar dentro de un proyecto. Apunta a una base concreta con --db <dir> (el padre de .kbdb), o define KBDB_DB_DIR. Solo el servidor mcp requiere un --db explícito; él jamás busca en el directorio de trabajo.

Busca entre bases: enriquece los resultados con conocimiento de solo lectura de otras bases de datos usando --other-db <dir> (repetible), o añade --cascade para tomar además de las carpetas .kbdb un los directorios padre:

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

Cada resultado lleva un campo source_db —la raíz de la base de datos de la que proviene— que puedes pegar directamente en --db o --other-db.

Scripting: añade --format json para obtener una salida JSON estructurada fácil de analizar. Usa --non-interactive o define KBDB_NON_INTERACTIVE=1 para suprimir las preguntas en tus pipelines de CI.

4. Recupera contexto

kbdb recall <kbid> --depth 1

Comienza con el kbid de un resultado de búsqueda y amplía el contexto de forma progresiva: la profundidad 0 da el contenido de la sección; la profundidad 1 añade los documentos superiores y las referencias retrospectivas; la profundidad 2 añade las referencias laterales y las referencias hacia adelante; la profundidad 3 incluye el texto completo de las secciones referenciadas.

Base de conocimiento

Construye, busca y gestiona tu almacén de conocimiento.

• Importa archivos Markdown y texto sin formato con seguimiento de fuentes

• y de fuentes

• Actualizaciones inteligentes — volver a aprender un archivo

• suma la versción anterior en lugar de duplicarla

• Historial — una sección reemplazada se retira, no se elimene: kbdb history recorre la cadena en cualquier diversi, y un kbid antiguo sigueury funcionando

• Búsqueda con dos algoritmos: palabras clave pons (predetermiz), similidad de IA o híbrido (ambos)

• Respillo automático — si tu consulta exact no nada, kbdb afloja la coincidencia automáticamente

• *Recuno la secciones con context progresivo: un un resumo rápido hasta el contenido relacionado completo, tan a fondo como lo permite un presprometo de --max-tokens

• Mide si la recuperación es realmente buena — kbdb eval or las buscamente Recall\@k, MRR y nDCG\@k con tu propio librerí de datosnecesaria, y termina con un códigoo de salida distinta de cero cuando un cambio empeora la clasificación

• Vecinos — kbdb neighbourhood dice qué se relaciona con una sección y de qué modo: ocho aristaas tipadas, siete de ellas hechos registrados y una inferida

• Consolidación — kbdb consolidate propone grupos de secciones que podrían convertirse en una sola. Solo lo propone; tú escribes la fusión y la aplicas tú mismo

• Exportación — crea una instantánea de tu base de conocimiento para respaldo

• Verificación — comprueba la integridad de la base de datos y limpia los datos obsoletos

• Reconstrucción — reconstruye los índices si algo no funciona

Consulta la Guía de base de conocimiento para ver el tutorial completo, incluida la exportación y las copias de seguridad.

Herramientas para agentes

Integra kbdb con agentes de IA y herramientas personalizadas.

Inicio rápido con MCP (Claude CLI):

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

Consulta la Guía de instalación de MCP para ver los archivos de configuración de Claude Code, VS Code y Claude Desktop, además de la solución de probleas y problemas.

• Servidor MCP con 30 herramientas: búsqueda, recuperación, aprendizaje, revisión, también, contradicciones, exportación, búsqueda de habilidades/recuerdos y más

• Skills — guarda patrones de instrucciones reutilizables con argumentos para completar

• Agentes — crea perfiles de agentes de IA que combinan una persona con capacidades

• Política de captura — el servidor le dice al agente qué debe guardar durante el propio handshake de MCP, por lo que no necesito configuración por host. Dos de sus seis cláusulas clases prefieren toda la qué no guardar: resúmenes de chats, conjeturas, secretos y cualquier cosa que el código ya dice. kbdb entrega la política; no puede obligar a un agente a seguirla

• Captura automática — puedo pedirle al modelo propio del host que elija el conocimiento que vale la pena guardar. Requiere la capacidad de sampling de MCP, pero Claude Code no la anuncia, así que la captura automática no hace nada allí. Toda las demás funciones de esta lista no se ven afectadas — consulta Soporte de hosts

• Resiliencia del demonio — tiempo de espera configurable y reintento automático con resucitación del demonio

• Gestión del ciclo de vida del demonio worker — detén y reinicia el proceso en segundo plano

• Permisos granulares de Deno — el demonio se ejecuta con permisos delimitados en lugar de --allow-all

• Confinamiento de rutas — el demonio rechaza los ataques de path traversal (..) en exportados/

Lo que el servidor dice de sí mismo. La respuesta de initialize lleva una cadena instructions — el único canal que todo host MCP compatible recibe sin necesidad de configurarción. kbdb the emb measa en política de capture: antes responder; tratar un resultado unanswered como un vacío que hay at que investigar y no como un inuento; guardar desios y correcciones que costan un esfuerzo real encontrar; tod no guardar lo que el códigao ya dice. Estas This espanol eses indenticas se citan en las descripciones too de las herramientas learn, revise y search en vez de parafrasear, de modo que hay una única fuente como.

Consulta la Guía de herramientas para agentes para la configuración de MCP, skills, agentes y la API de la biblioteca, y la Política de captura para ver las seis cláusulas completas y por qué se escriben una sola vez.

Para desarrolladores

API de biblioteca

Qué hace kbdb dentro de tus proyectos Node.js o Deno de forma programática:

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();

Se pasa contextPath (el directorio .kbdb propiamente) o dbPath (el directorio padre — kbdb discover .kbdb dentro de él).

Consulta la Referencia de la API de biblioteca para ver la API completa.

Configuración de desarrollo

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

Docker

Hay dos Dockerfiles, y no son interchangeables.

Dockerfile en la raíz del repositorio construye el servidor MCP — ese es el que construyen los directorios MCP, y el que debes usar si quieres kbdb en un contenedor. Consulta Instalar el servidor MCP para ver la configuración del host y por qué es necesario un volumen con nombre en lugar de un montaje vinculado.

Dockerfile.tooling construye la cadena de herramientas de desarrollo (Node.js y Deno), que todos los objetivos de make usan mediante docker-compose.yaml:

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

Ejecuta make benchmark para medir la latencia de búsqueda y reconstrucción a escala — los resultados se escriben automáticamente en docs/benchmark/benchmark.md.

Consulta el Makefile para ver todos los destinos de compilación disponibles.

Contribuciones

1. Haz un fork del repositorio

2. Crea una rama de funcionalidad

3. Haz los cambios correspondientes y añade tests

4. Ejecuta npm test y npm run lint

5. Abre una solicitud de merge

Documentación

• Segundo cerebro con Claude Code -- la guía canónica de configuración: estructura del espacio de trabajo, comandos correctos y conexión de MCP

• Guía de instalación de CLI -- requisitos previos, instalación con npm/JSR, verificación

• Guía de la base de conocimiento -- importación, búsqueda, recuperación, exportación

• Guía de herramientas para agentes -- MCP, habilidades, agentes, API de la biblioteca

• Referencia de CLI -- lista completa de comandos con ejemplos

• Guía de instalación de MCP -- Claude CLI, Claude Code, VS Code, Claude Desktop

• Guía del servidor MCP -- setup, configuración del entorno y lo que el servidor le comunica a un agente en initialize

• Compatibilidad con hosts -- qué hosts de MCP entregan la política de captura y anuncian el muestreo, medido en lugar de supuesto

• Política de captura -- lo que kbdb le dice a un agente que almacene, y por qué se enuncia una sola vez

• Búsqueda y clasificación -- cómo funciona la búsqueda bajo el capó

• Arquitectura de almacenamiento -- formatos de archivo, estructura de directorios y cuánto cuesta conservar el historial

• Permisos de Deno -- las banderas de permisos que kbdb necesita y por qué

• Resultados de benchmark -- latencia de búsqueda y reconstrucción a escala

• Escalado del aprendizaje -- cómo crece el coste del aprendizaje con el tamaño del corpus

• Señales de contradicción -- calibrar los umbrales de cuasi-duplicado y contradicción sobre 1128 pares etiquetados

• Notas de la versión

• Visión general de la arquitectura

El motor de búsqueda

El almacenamiento, la indexación y la clasificación provienen de @dikolab/vdb, proyecto hermano de kbdb del mismo autor. Su documentación cubre en profundidad el lado de la recuperación:

• Visión general de vdb -- modelo de almacenamiento, particiones, BM25F, búsqueda vectorial e híbrida

• Ejemplos de vdb -- consultas resueltas y comportamiento de clasificación

Soporte

kbdb es software gratuito con licencia AGPL. Si se gana un lugar en tu flujo de trabajo, puedes apoyar el desarrollo continuado a través de PayPal.

Licencia

Este proyecto tiene licencia dual:

• Código abierto bajo la GNU Affero Public General License v3.0 (AGPL-3.0-only)

• Licencia comercial disponible para uso de código cerrado o SaaS

Las versiones <= 0.5.0 permanecen bajo la licencia ISC.

Consulta LICENSING.md para obtener más detalles e información de contacto.