knowl

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

Inicio rápido · Por qué supersesión · Qué se almacena · Características · Conexión de un agente · Visor · Requisitos y datos locales · Referencia completa →

Los agentes de codificación comienzan cada sesión en blanco, por lo que los equipos toman notas — y esas notas solo crecen. Seis meses después, el almacén sigue reportando la base de datos 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ídos y escritos a través de un servidor de memoria MCP o la CLI knowl, donde un reemplazo retira a su predecesor en el momento de escritura en lugar de colocarse a su lado.

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 calienta el modelo de incrustación local, pero nunca depende de que esa descarga tenga éxito.

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

Registra algo que valga la pena conservar:

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

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

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

Related MCP server: Mnemoverse Memory

La idea: memoria que se retira a sí misma

La mayoría de los sistemas de memoria son de solo añadidura. 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 sobre el 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 en precisión. En el corpus de Resolución de Conflictos de MemoryAgentBench — 455 hechos, 100 preguntas sobre qué hecho es 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 banco de Knowl: pregunta si el hecho actual vuelve primero, sin ningún modelo en el bucle.

Verificado de extremo a extremo, en el propio banco de pruebas

Porque un número que uno mismo obtiene vale menos que uno que otra persona obtiene, la misma afirmación se repitió dentro del banco de MemoryAgentBench, puntuado 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 el de Knowl — el artículo lo indica 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. No se listan sistemas que el artículo no evalúa en esta tarea.

Desactivar la supersesión en ese mismo banco reduce Knowl a 73, y la brecha se mantiene a través de 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 a los sistemas publicados anteriormente. Consulta benchmarks para ver el protocolo, los resultados verificados y lo que la tarea no cubre — incluyendo multi-hop, donde Knowl obtiene 7 frente a un techo de recuperación de 14 puntos.

La supersesión es una corrección, no una eliminación: el elemento, sus afirmaciones y su historia sobreviven.

No es un simulacro — la misma secuencia contra la CLI publicada, grabada desde demo.tape:

Qué se almacena

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

Junto con el contenido, cada átomo mantiene un estado (active, deprecated, rejected, archived, superseded), un indicador 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 archivo y símbolo 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 de ciclo de vida registra eventos acotados y resúmenes — nunca prompts, transcripciones, stdout o variables de entorno. La búsqueda de transcripciones sin procesar existe como un índice optativo, desactivado por defecto sobre archivos que el anfitrión ya escribió.

→ Referencia del modelo de conocimiento

Conexión de un agente

knowl serve expone el almacén a través de stdio MCP; 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 acierto activo directamente; inspecciona archivos solo en caso de fallo, conflicto o resultado desactualizado.

3. Almacena hallazgos duraderos, objetivos declarados y diagnósticos recurrentes sobre la marcha, y corrige la memoria contradicha en lugar de duplicarla.

En la práctica, esto se ve así — una sesión nueva, 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 código base.

Donde hay hooks disponibles, estos gestionan el ciclo de vida de la sesión: el contexto de bootstrap, la captura, los puntos de control 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 cablear uno 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, ni historial de chat — las decisiones, restricciones y arquitectura de un código base, y cuáles de ellas siguen siendo ciertas hoy.

Tres elecciones se derivan de eso:

• Tipado, no texto libre. Una decisión lleva el razonamiento y las alternativas que rechazaste. Una restricción es una regla que debe seguir cumplié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. El estado, la frescura, la procedencia, la identidad de conflicto y la sustitución permiten que el almacén te diga que algo dejó de ser cierto. Esa es toda la diferencia entre la memoria y un montón de notas en constante crecimiento.

• Local al repositorio, no un servicio. La base de datos se encuentra junto al código que describe. Sin cuenta, sin salida, sin proveedor 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 la 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 con la referencia completa para los detalles — y para los límites.

♻️ Conocimiento que se corrige a sí mismo

Siete tipos de átomos tipados, donde una escritura del mismo tema retira a su predecesor en lugar de situarse junto a él. Ese único comportamiento es la diferencia 90 frente a 73. La evidencia adjunta a un archivo o símbolo se vuelve obsoleta por sí misma cuando el código se mueve.

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

🎯 Recuperación ajustada para agentes

Clasificación primaria por vectores con un respaldo BM25 acotado, reordenado por frescura, estado y confianza, para que gane la respuesta actual en lugar de la meramente similar. El modelo de incrustación es local y opcional — sin él aún obtienes recuperación por palabras clave, y nada sale de la máquina.

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

⏱️ Trabajo que sobrevive a la sesión

En Claude Code, Codex y Cursor, los hooks gestionan bootstrap, captura, puntos de control y finalización sin que se le pida al agente. Una finalización limpia destila hasta ocho candidatos duraderos. Estaciona un flujo de trabajo bajo una clave y retómalo en cualquier sesión, desde cualquier directorio.

task run · handoff · park · resume <key>

🔗 Espacios de trabajo

Tu repositorio de API aprendió algo que el repositorio del frontend necesita. Enlácelos y una consulta se expande, mientras que cada repositorio mantiene su propia base de datos y su propio límite de propiedad. Abre un átomo par compartido por completo por id, o termina el trabajo de ese repositorio desde aquí nombrándolo en la llamada. El conocimiento que un repositorio ya posee se comparte solo cuando lo promocionas.

workspace init · workspace add · workspace promote --apply

📦 Procedimientos reutilizables

Empaqueta un procedimiento con sus scripts bajo .knowl/skills/, luego léelo antes de que se ejecute. Combina varios átomos en un resumen de arquitectura de forma determinista, sin que intervenga ningún proveedor de IA.

skill list · skill read · skill run · synthesize

💾 Tus datos, y cómo recuperarlos

Exportación e importación JSONL con suma de verificación con cuatro políticas explícitas para cuando el mismo átomo cambió en dos lugares. La restauración verifica el esquema, el tamaño, SHA-256 y la integridad de SQLite antes de tocar nada, y toma una instantánea previa a la restauración primero.

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

Los comandos que vale la pena conocer 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

• Siete tipos de átomos — enumerados arriba. Estructura en lugar de un archivo de notas en crecimiento.

• Sustitución automática — una escritura del mismo tema retira a su predecesor. Esta es la diferencia 90 frente a 73 anterior.

• Identidad de conflicto — marca un átomo como exclusivo y Knowl rechaza una segunda respuesta activa a la misma pregunta, en lugar de mantener ambas en silencio. knowl conflicts

• Historial completo — cada versión que un átomo haya tenido sobrevive como una aserción inmutable. knowl timeline <item-id>

• Viaje en el tiempo — pregunta qué creía el proyecto en una fecha pasada: knowl query "auth design" --as-of 2026-01-01T00:00:00Z

• Evidencia — adjunta archivos, símbolos, commits, pruebas, comandos o URL a un átomo. La evidencia de archivos y símbolos se vuelve obsoleta por sí misma cuando el código se mueve.

• Detección de desviación — knowl pr --since origin/main señala el conocimiento que tu diff puede haber invalidado, antes de que lo fusiones.

• Inteligencia de código — índice Tree-sitter incremental sobre .ts / .tsx / .js / .jsx, para que la evidencia pueda apuntar a localizadores symbol://, no solo números de línea. knowl index-code

• Escrituras seguras contra secretos — cada escritura se examina en busca de secretos detectados, rutas sensibles y contenido de gran tamaño antes de que se registre. La memoria de larga duración es el último lugar donde debería terminar una credencial.

→ Modelo de conocimiento · Evidencia y desviación

• Clasificación primaria por vectores con un respaldo BM25 acotado, reordenado por frescura, estado, confianza y actualidad — para que gane la respuesta actual, no meramente la similar. (Este es el camino agente/MCP; una knowl query de un solo repositorio desde la CLI es léxica.)

• Funciona sin conexión. El modelo de incrustación es local y opcional; sin él aún obtienes recuperación por palabras clave. La recuperación nunca envía tu consulta a ningún lado.

• Cinco ajustes preestablecidos de incrustación incluidos, incluido uno multilingüe que cubre más de 200 idiomas, más custom para tu propio modelo ONNX. knowl config set-model <model>

• Soporte de identificadores exactos — nombres de archivo, ID de elementos y localizadores symbol:// siguen acertando incluso cuando la similitud semántica es débil.

• Paquetes de contexto con presupuesto de tokens — entrega a un agente un informe de tamaño fijo con las restricciones fijadas primero, para que las reglas no negociables nunca se trunquen: knowl context --query "auth rollout" --token-budget 1500

• Retroalimentación de uso — los agentes informan si un resultado fue útil, y knowl access muestra qué se usa mucho, qué está obsoleto y qué sigue causando correcciones.

→ Recuperación y contexto

• Ciclo de vida automático en Claude Code, Codex y Cursor — bootstrap, captura, puntos de control y finalización ocurren a través de hooks sin que se le pida al agente.

• Bucles de trabajo para todo lo demás — knowl task start, checkpoint, finish, o envuelve un solo comando con knowl task run "Ejecutar pruebas" -- npm test.

• Promoción al final de la sesión — una finalización limpia destila hasta ocho candidatos duraderos de la sesión, y un comando que ha tenido éxito tres veces se convierte en un átomo skill que lo describe.

• Traspaso — deja un bastón para la próxima sesión en este repositorio. Se entrega una vez, luego se archiva.

• Claves de reanudación — estaciona un flujo de trabajo bajo una clave corta que conservas, y retómalo en cualquier sesión, desde cualquier directorio, cualquier número de veces después. knowl resume <key>

• Búsqueda de transcripciones opcional — desactivada por defecto, y desactivada significa que no existe nada en el disco. Actívala y la prosa de sesiones pasadas se vuelve buscable, por lo que un fallo de memoria se degrada a una búsqueda más lenta en lugar de amnesia.

→ Tareas, sesiones y ciclo de vida

Tu repositorio de API aprendió algo que el repositorio del frontend necesita. Enlácelos, y una consulta se expande — mientras que cada repositorio mantiene su propia base de datos y su propio límite de propiedad.

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

Unirse a un espacio de trabajo comparte lo que el repositorio escribe a partir de entonces, y lo dice cuando lo hace; pasa --default-visibility repo para rechazarlo. Lo que el repositorio ya sabe se comparte solo cuando lo promocionas. Los resultados pares se etiquetan con el repositorio que los posee, y uno compartido se puede abrir por completo por id — sin sus affectedPaths o evidencia, que se resuelven contra un checkout en el que no te encuentras. Un par que falta o es ilegible se omite y se divulga, nunca es una razón para que tu búsqueda local falle.

Escribir en un repositorio hermano es deliberado, no incidental. Un agente nombra el repositorio en la llamada y esa única llamada se ejecuta como ese repositorio — su almacén, su configuración, sus reglas de propiedad, sellado como propio — exactamente como cd allí siempre se ha comportado para la CLI. No nombres nada y un id extranjero se rechaza como antes. De cualquier manera, el conocimiento privado de un repositorio permanece privado hasta que se promociona.

→ Espacios de trabajo

• Habilidades respaldadas por archivos — empaqueta un procedimiento con sus scripts en .knowl/skills/, luego inspecciónalo antes de que se ejecute. knowl skill list · read · run

• Síntesis determinista — combina varios átomos en un resumen de arquitectura sin que intervenga ningún proveedor de IA: knowl synthesize --scope storage

→ Habilidades y síntesis

• Exportación/importación portátil — JSONL con suma de verificación y cuatro políticas explícitas de divergencia para cuando el mismo átomo cambió en dos lugares. knowl export · knowl import --on-divergence newer

• Instantáneas verificadas — knowl snapshot create escribe un manifiesto de suma de verificación; restaurar verifica la versión del esquema, el tamaño, SHA-256 y la integridad de SQLite antes de tocar nada, y toma una instantánea previa a la restauración primero.

• Recolección de basura que previsualiza por defecto y protege cualquier elemento usado recientemente. knowl gc

• knowl doctor — un comando que verifica la configuración, el ajuste, la integridad, el esquema, la recuperación, la cobertura de vectores, el registro de agentes y el estado del espacio de trabajo.

• IA opcional — configura un proveedor para knowl ask y la ingesta de texto sin formato. Todas las funciones anteriores funcionan sin ella.

→ Portabilidad y mantenimiento · IA opcional

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 cada inicio — 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 grafo enlaza átomos a través de etiquetas compartidas y aristas derivadas de categorías, una ayuda de navegación, no un grafo causal o de evidencia. Muestra todo el contenido local de cada estado, por lo que el enlace de bucle invertido es el límite de privacidad: no lo pongas detrás de un proxy público o un 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 URI 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 los conjuntos de pruebas de gobernanza y 500 casos verificados con knowl eval.

→ Referencia de la CLI · Herramientas MCP · Puntos de referencia

Requisitos y datos locales

Node.js 22 o posterior. Todo lo que Knowl escribe para un proyecto reside en .knowl/, que knowl init añade a .gitignore:

Los manifiestos del espacio de trabajo residen fuera de los repositorios miembros, porque sus rutas de checkout son locales a 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 suele ser lo que realmente necesitas saber.

Contribuir

Consulta CONTRIBUTING.md para la configuración, las comprobaciones 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 del 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 registrada.