Knowl

Local-first. Tipado. Y retirado en el momento en que deja de ser cierto.

Inicio rápido · Por qué la supersesión · Qué se almacena · Características · Configuración del agente · Visor · Requisitos · Referencia completa →

Los agentes de codificación comienzan cada sesión en blanco, por lo que los equipos escriben las cosas — y esas notas solo crecen. Seis meses después, el almacén todavía informa de la base de datos de la que migraste la primavera pasada, porque nada le dijo nunca que esa decisión había terminado.

Knowl es memoria persistente entre sesiones para Claude Code, Cursor y Codex: un almacén local al repositorio de átomos de conocimiento tipados — decisiones, restricciones, arquitectura, hechos, objetivos, estado y habilidades — leído y escrito a través de un MCP memory server o el CLI de knowl, donde un reemplazo retira a su predecesor en el momento de la escritura en lugar de situarse junto a él.

Inicio rápido

Requiere Node.js 22 o posterior.

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

knowl init crea .knowl/, instala los archivos de guía del proyecto, actualiza .gitignore, y ofrece configuración de MCP y ciclo de vida para los agentes que detecte — Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop. También prepara el modelo de incrustación local, pero nunca depende de que esa descarga tenga éxito.

Registra algo que valga la pena conservar:

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

Léelo de vuelta, desde el CLI o desde cualquier agente conectado:

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

Luego inicia una nueva sesión de agente para que el host recoja su guía y el registro MCP. El CLI y knowl_query leen el mismo almacén bajo las mismas reglas de gobernanza.

La idea: memoria que se retira sola

La mayoría de los sistemas de memoria son de solo añadir. Almacenar "nos mudamos a SQLite" deja "usamos PostgreSQL" activo y recuperable, por lo que el agente obtiene ambos y elige por rango. Knowl trata una escritura del mismo tema como una corrección: el predecesor se marca como superseded, sale de la recuperación normal y permanece consultable a través de knowl timeline.

Ese único comportamiento es la mayor parte de la diferencia de precisión. En el corpus de Resolución de Conflictos de MemoryAgentBench — 455 hechos, 100 preguntas sobre qué hecho es el actual, recuperación top-5, sin lector LLM:

Mismo corpus, mismo clasificador, misma ruta de consulta. La única variable es si el hecho desactualizado sigue activo. Esta es una medición a nivel de recuperación en el propio arnés de Knowl: pregunta si el hecho actual vuelve primero, sin ningún modelo en el bucle.

Verificado de extremo a extremo, en el arnés del propio benchmark

Debido a que una puntuación que te pones a ti mismo vale menos que una que puntúa otro, la misma afirmación se volvió a ejecutar dentro del arnés de MemoryAgentBench, puntuada por su propio código, con un LLM leyendo lo que Knowl devolvió — la configuración más difícil, completamente de extremo a extremo, en el contexto más grande que ofrece la tarea:

18,332 hechos, 100 preguntas, coincidencia exacta de subcadena. Cada fila usa gpt-4o-mini como lector, incluido Knowl — el artículo lo establece para todos los agentes RAG y de memoria, por lo que son comparables. La cifra de Knowl se midió aquí; todas las demás cifras provienen del artículo de MemoryAgentBench, Tabla 2. Los sistemas que el artículo no evalúa en esta tarea no se enumeran.

Desactivar la supersesión en ese mismo arnés reduce Knowl a 73, y la brecha se mantiene en un cambio de 40× en el tamaño del corpus:

Las dos secciones miden cosas diferentes y no son comparables entre sí: 98% es recuperación top-1 a 6K sin lector, 90 es precisión de extremo a extremo a 262K con uno. Solo la segunda es comparable con los sistemas publicados anteriores. Consulta benchmarks para el protocolo, los resultados verificados y lo que la tarea no cubre — incluido multi-hop, donde Knowl puntúa 7 contra un techo de recuperación de 14 puntos.

La supersesión es una corrección, no un borrado: el elemento, sus afirmaciones y su historial sobreviven todos.

No es una maqueta — la misma secuencia contra el CLI publicado, grabada desde demo.tape:

Qué se almacena

Cada átomo tiene exactamente una de siete categorías:

Junto al contenido, cada átomo mantiene un estado (active, deprecated, rejected, archived, superseded), una marca de frescura, confianza, etiquetas, commit de origen, rutas afectadas y evidencia opcional que apunta a archivos, commits, pruebas, comandos, URLs o símbolos de código indexados. La evidencia de archivos y símbolos se vuelve obsoleta por sí sola cuando el código se mueve, que es como un átomo admite que puede estar desactualizado en lugar de afirmar una versión del repositorio que ya no existe.

Lo que Knowl deliberadamente no almacena son tus conversaciones. La captura del ciclo de vida registra eventos acotados y resúmenes — nunca prompts, transcripciones, stdout o variables de entorno. La búsqueda de transcripciones crudas existe como un índice opcional, desactivado por defecto sobre archivos que el host ya escribió.

→ Referencia del modelo de conocimiento

Conectando un agente

Claude Code MCP · ciclo de vida · subagentes

Codex MCP · ciclo de vida · subagentes

Cursor MCP · ciclo de vida

Gemini CLI MCP · bucle manual

Claude Desktop MCP · bucle manual

knowl serve expone el almacén a través de MCP stdio; knowl init lo registra por ti. El flujo de trabajo que la guía instalada pide a los agentes que sigan es breve:

1. Consulta la memoria con las palabras que nombran el tema antes de leer los archivos del repositorio.
2. Usa un resultado activo directamente; inspecciona archivos solo en caso de fallo, conflicto o resultado obsoleto.
3. Almacena hallazgos duraderos, objetivos declarados y diagnósticos recurrentes a medida que avanzas, y corrige la memoria contradicha en lugar de duplicarla.

En la práctica se ve así — una nueva sesión, sin contexto, nada pegado:

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.

El agente respondió antes de abrir un solo archivo, y sabía las opciones que rechazaste — que el código no puede decirle, porque las alternativas rechazadas no dejan rastro en un codebase.

Donde hay hooks disponibles, ellos gestionan el ciclo de vida de la sesión: el contexto de arranque, la captura, los checkpoints y la finalización ocurren sin que se le pida al agente. Donde no los hay, knowl task run, task start, task checkpoint y task finish cubren el mismo terreno manualmente.

knowl init escribe el registro MCP para cada host que detecta. Para conectarlo a mano, la entrada es la misma en todas partes:

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

Usa knowl.cmd como comando en Windows. Codex lee la misma entrada bajo mcp_servers.

→ Herramientas y recursos MCP · Referencia del ciclo de vida

Para qué sirve Knowl

Knowl hace un trabajo: mantener la verdad de ingeniería de un repositorio precisa para los agentes que trabajan en él. No preferencias de usuario, no historial de chat — las decisiones, restricciones y arquitectura de un codebase, y cuáles de ellas siguen siendo ciertas hoy.

Tres elecciones se derivan de eso:

• Tipado, no texto libre. Una decisión lleva razonamiento y las alternativas que rechazaste. Una restricción es una regla que debe seguir manteniéndose. Se espera que un átomo de state quede desactualizado. La recuperación puede clasificar según esas diferencias; no puede clasificar según párrafos en un archivo de notas.
• Gobernado, no solo añadir. Estado, frescura, procedencia, identidad de conflicto y supersesión permiten que el almacén te diga que algo dejó de ser cierto. Esa es toda la diferencia entre memoria y una pila de notas en constante crecimiento.
• Local al repositorio, no un servicio. La base de datos se sitúa junto al código que describe. Sin cuenta, sin salida de datos, sin intermediario entre tú y tu propio historial de proyecto.

Knowl no es deliberadamente una capa de personalización. No tiene opinión sobre tus usuarios y no guarda transcripciones propias.

Características

Todo lo siguiente funciona desde el CLI y desde cualquier agente conectado a MCP, contra la misma base de datos local. Sin cuenta, sin servidor, sin clave API. Cada elemento enlaza a la referencia completa para el detalle — y para los límites.

Los comandos que vale la pena conocer desde el primer día:

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

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

Véalo: el visor local

knowl view inicia un inspector de solo lectura en 127.0.0.1 con un token de acceso nuevo por lanzamiento — saber el puerto no es suficiente para leer nada.

knowl view

Busca, filtra por categoría, detecta anillos obsoletos, enfoca un vecindario y abre cualquier átomo para leer su evidencia y línea de tiempo. El gráfico vincula átomos a través de etiquetas compartidas y bordes derivados de categorías — una ayuda de navegación, no un gráfico causal o de evidencia. Muestra contenido local completo en cada estado, por lo que el enlace de bucle local es el límite de privacidad: no lo pongas detrás de un proxy público o túnel.

→ Visor local

Todo lo demás

27 herramientas MCP (más 3 cuando la búsqueda de transcripciones está activada, 1 cuando está conectado a un espacio de trabajo en la nube, 1 cuando está vinculado a un espacio de trabajo local, y 1 cuando el impacto de cambios está activado)

y dos URIs de recursos · la CLI completa, desde knowl status hasta knowl audit · una auditoría de integridad de solo lectura · evaluación de recuperación que puedes ejecutar tú mismo contra la gobernanza incluida y las suites de regresión de 500 casos con knowl eval.

→ Referencia de CLI · Herramientas MCP · Benchmarks

Requisitos y datos locales

Node.js 22 o posterior. Todo lo que Knowl escribe para un proyecto vive bajo .knowl/, que knowl init agrega a .gitignore:

Los manifiestos de espacio de trabajo viven fuera de los repositorios miembros, porque sus rutas de checkout son específicas de la máquina. Las exportaciones e instantáneas se escriben solo cuando las solicitas.

Documentación

Todo lo anterior es el resumen. La referencia completa es un documento que cubre cada subsistema en profundidad — incluidas las partes que están deliberadamente limitadas, que es generalmente lo que realmente necesitas saber.

Contribuciones

Consulta CONTRIBUTING.md para la configuración, las verificaciones que se deben ejecutar antes de una solicitud de extracción y las convenciones que sigue este código base. Se pide a los contribuyentes que acepten el Acuerdo de Licencia de Contribuyente una vez, en su primera solicitud de extracción.

Licencia

Knowl está licenciado bajo la Licencia Apache 2.0. Apache-2.0 no otorga derechos de marca comercial.