Knowl

Tu CLAUDE.md solo crece. Knowl retira los hechos cuando cambian.

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

Tu agente comienza cada sesión en blanco, por eso mantienes un CLAUDE.md. Solo crece. Seis meses después todavía menciona la base de datos de la que migraste la primavera pasada, y ahora el agente obtiene ambas respuestas.

Knowl es memoria persistente para Claude Code, Cursor y Codex, mediante MCP o la CLI. Cuando un hecho se reemplaza, el anterior se retira en lugar de competir con el nuevo. No se necesita clave de API. Cuando Knowl no está seguro de que el hecho nuevo reemplace al anterior, deja ambos activos y te entrega el comando knowl supersede para que lo indiques.

Desactiva eso y la recuperación cae del 98% al 47%. De extremo a extremo, de 90 a 73. Cómo se midió ↓

Cuarenta segundos, una decisión, tres agentes:

Inicio rápido

Requiere Node.js 22 o posterior. macOS, Linux y Windows.

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

pnpm add -g @dat999zx/knowl
yarn global add @dat999zx/knowl
bun add -g @dat999zx/knowl

npx @dat999zx/knowl init

knowl init crea .knowl/, instala los archivos de guía del proyecto, actualiza .gitignore y registra Knowl con los agentes que detecte. También calienta un modelo de embeddings local (~53 MB) en segundo plano — init tiene éxito de cualquier manera, y sin él aún obtienes búsqueda por palabras clave.

Esa es toda la configuración. No registras memoria a mano: tu agente la lee y escribe mientras trabaja.

Conexión de un agente

Claude Code MCP · ciclo de vida · compuerta	Codex MCP · ciclo de vida · compuerta	Hermes MCP · ciclo de vida · compuerta	OpenClaw en proceso · plugin · compuerta	Copilot MCP · ciclo de vida · compuerta	Cursor MCP · ciclo de vida · compuerta	OpenHands MCP · ciclo de vida · compuerta
Antigravity MCP · ciclo de vida · compuerta	Windsurf MCP · ciclo de vida · compuerta	Cline MCP · ciclo de vida · plugin	Zed MCP · captura · ACP	JetBrains MCP · captura · ACP	OpenCode MCP · bucle manual	Claude Desktop MCP · bucle manual

knowl init registra el servidor MCP para cada host que encuentre. Inicia una nueva sesión después para que el agente recoja su guía, y consultará y escribirá memoria por sí solo.

compuerta significa que Knowl puede rechazar una edición que invalide código que otra sesión está sosteniendo. Neovim y Kiro funcionan igual que Zed y JetBrains, mediante knowl acp. Cline necesita una línea que lo apunte al plugin incluido. Hermes Agent recibe un plugin de Python, instalado por ti, que funciona tanto en la terminal como en Hermes Desktop, y además puede seleccionarse como proveedor de memoria de Hermes. OpenClaw se ejecuta en proceso dentro de su gateway mediante un plugin de extensión, evaluando compuertas de escritura sin la sobrecarga de subprocesos — knowl init openclaw lo copia e imprime los dos comandos que lo registran. Cualquier otro cliente MCP funciona sin integración alguna.

¿Ejecutas agentes en paralelo? Cada git worktree se resuelve al almacén del checkout principal — los espacios de trabajo de Conductor, el isolation: "worktree" de Claude Code, o tus propios scripts comparten una sola memoria, sin nada que configurar. Cómo funciona y su único límite →

→ Cada host y lo que puede hacer · Cómo lo usan los agentes · Herramientas y recursos MCP

La idea: memoria que se retira sola

La mayoría de los sistemas de memoria son de solo añadido. Almacenar "nos mudamos a SQLite" deja "usamos PostgreSQL" activo y recuperable, así 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 mediante 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 entorno de Knowl: pregunta si el hecho actual vuelve primero, sin ningún modelo en el bucle.

Verificado de extremo a extremo, en el propio entorno del benchmark

Como un número que te puntúas a ti mismo vale menos que uno que puntúa otro, la misma afirmación se volvió a ejecutar dentro del entorno 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, incluida la de Knowl — el artículo lo declara para todos los agentes RAG y de memoria, así que estas son comparaciones equivalentes. Knowl y agentmemory se midieron aquí; todas las demás cifras provienen del artículo de MemoryAgentBench, arXiv 2507.05257v4, Tabla 3. agentmemory no se evalúa en ese artículo — sus cifras publicadas son recall de recuperación de LongMemEval-S, una tarea diferente — así que se ejecutó a través del mismo entorno con la misma configuración, y ambos adaptadores comparten una única ruta de código de lector para que ninguno pueda desviarse del manejador RAG del propio artículo. Método, mecanismo y pasos de reproducción: FINDINGS.md.

De lo contrario, se muestran todos los sistemas de memoria comerciales que evalúa el artículo, más el puntaje más alto de cada familia de línea base. La tabla del artículo ha cambiado entre versiones — BM25 leía 56 en v1 y lee 48 en v4 — así que se cita la versión, no solo la tabla.

El 90 de Knowl se midió el 2026-08-08 y se reprodujo de forma independiente en 89.0 el 2026-08-19 con el adaptador incluido; el 79 de agentmemory es una sola ejecución. Cada cifra aquí es una ejecución en temperature: 0.7, y la brecha de ablación se movió 4 puntos entre dos ejecuciones de la misma celda de 6k, así que léelas por el punto en lugar del decimal.

Desactivar la supersesión en ese mismo entorno 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 en 6K sin lector, 90 es precisión de extremo a extremo en 262K con uno. Solo la segunda es comparable con los sistemas publicados anteriores. Consulta benchmarks para el protocolo, los resultados incluidos 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 la CLI publicada, grabada desde demo.tape:

Compartir memoria en un equipo: knowl.cloud

Todo lo anterior es local y no requiere cuenta. knowl.cloud es la capa opcional alojada para cuando una sola máquina no es suficiente:

• Espacios de trabajo compartidos. El conocimiento escrito en un checkout llega a los agentes de los compañeros, y cada repositorio sigue siendo dueño de lo que publica.
• Agentes de navegador. claude.ai y chatgpt.com no pueden ejecutar un proceso local, así que se conectan mediante un endpoint MCP remoto con un token limitado a un espacio de trabajo.

El modo solo local sigue siendo una forma de primera clase de ejecutar Knowl. Nada de lo anterior es necesario para usar nada de lo que está arriba.

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 queda 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, salida estándar ni variables de entorno. La búsqueda de transcripciones crudas existe como un índice que puedes desactivar sobre archivos que el host ya escribió.

→ Referencia del modelo de conocimiento

Cómo lo usan los agentes

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

1. Consulta la memoria con las palabras que nombran el tema antes de leer archivos del repositorio.
2. Usa un resultado activo directamente; inspecciona archivos solo ante un fallo, conflicto o resultado obsoleto.
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 se ve así — una sesión nueva, sin contexto, sin 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.

Detalle completo, y por qué existe cada brecha, en docs/hosts.md.

Donde hay hooks disponibles, ellos gestionan el ciclo de vida de la sesión: el contexto de arranque, la captura, los puntos de control y la finalización ocurren sin que se lo pidan 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 solo trabajo: mantener el conocimiento asentado de un proyecto preciso para los agentes que trabajan en él. No preferencias de usuario, no historial de chat — las decisiones, restricciones y arquitectura sobre las que un proyecto funciona, y cuáles de ellas siguen siendo ciertas hoy. La mayoría de los almacenes viven en un codebase, y las herramientas de deriva y evidencia apuntan allí, pero nada en el modelo de conocimiento lo exige.

Tres decisiones 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 cumpliéndose. Un átomo de state se espera que quede obsoleto. 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 sustitució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 que crece sin fin.
• Local al repositorio, no un servicio. La base de datos está junto al proyecto que describe. Sin cuenta, sin salida de datos, 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.

Funciones

Todo lo siguiente funciona desde la CLI y desde cualquier agente conectado por MCP, contra la misma base de datos local. Sin cuenta, sin servidor, sin clave API. Cada elemento enlaza con 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 list --unread                    # browse it — and see what nothing ever reads
knowl edit <item-id>                   # open one memory in the viewer to fix it
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 fleet                            # every agent session live on this machine, and what it is on
knowl config list                      # every setting, its value, and how to change it
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 editor en 127.0.0.1 con un token de acceso nuevo por cada lanzamiento — saber el puerto no es suficiente para leer nada, y las escrituras además requieren que la solicitud nombre a este visor como su origen, por lo que otra página que tengas abierta no puede escribir aquí.

knowl view

Déjalo abierto mientras trabajas y te muestra el razonamiento del agente. Una recuperación ilumina los átomos con los que respondió, en orden de rango, y deja caer el resto del grafo. Una escritura llega a un escenario despejado. Una retirada se oscurece y permanece oscura. Cada átomo cambiado tiene un pie de foto con lo que le sucedió — NEW, UPDATED, SUPERSEDED.

Observa la base de datos en lugar del agente, por lo que no importa qué herramienta esté trabajando: Claude Code, Codex, Cursor, o tú ejecutando knowl query en otra terminal iluminan el mismo grafo. No se agregó nada a ninguna ruta de escritura para que esto funcione, así que cuando no hay visor abierto, nada de eso se ejecuta.

Aquí también es donde corriges lo que tus agentes hicieron mal. Abre cualquier átomo para leer su evidencia y línea de tiempo, luego edítalo, archívalo o escribe uno nuevo a mano. El archivado es reversible — Restaurar está en el mismo panel. Los átomos retirados permanecen en el grafo como puntos oscuros: son la historia, y ya no pretenden ser actuales.

Junto al grafo hay una lista, con una lente para lo que nada ha leído nunca. Esa se gana su lugar: la búsqueda solo alcanza memoria que ya sospechas que existe, y un átomo sin información es precisamente el que nadie piensa en buscar. Ordenada de más antigua a más reciente, aparece por sí sola. knowl list --unread hace la misma pregunta desde la terminal.

El grafo enlaza átomos solo a través de etiquetas que pocos átomos comparten — una etiqueta en docenas de ellos es una categoría, y el carril ya filtra por esas. Un átomo sobre el que nada más trata permanece sin enlazar en lugar de estar atado a un vecino arbitrario. Es una ayuda de navegación, no un grafo 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 un túnel.

→ Visor local

Memoria que es verdadera de ti, no de un repositorio

Algunas cosas no pertenecen a ningún repositorio: que prefieres pnpm, que el controlador de esta máquina se rompe con CUDA 12, que cada proyecto aquí usa commits convencionales. Knowl guarda esas en un almacén a nivel de máquina en ~/.knowl/global.db, separado de la memoria de cualquier proyecto.

knowl link global        # this project may read and write it; reversible with --off
knowl store "I prefer pnpm over npm" --title "Package manager" --category constraint --namespace global

Tu proyecto siempre responde primero. El enlazado nunca cambia lo que un repositorio dice sobre sí mismo — las entradas globales se sitúan detrás de las del proyecto, y nunca pueden desplazarlas. Y una sesión sin repositorio en absoluto, como una ventana de Hermes Desktop sin carpeta abierta, lee el almacén global solo en lugar de no tener memoria. Un proyecto que existe pero no se abre sigue siendo un error: lo global son preferencias personales, nunca un respaldo para un almacén roto.

Te sigue a otra máquina. El almacén de la máquina se sincroniza con un espacio de trabajo en la nube de la misma manera que un proyecto — no es un proyecto, pero se aborda como uno:

knowl cloud connect --global   # then push and pull with --global

Ejecuta cualquier comando knowl cloud fuera de un repositorio y usa el almacén de la máquina por sí solo, diciéndolo. Esa inferencia es estrecha a propósito: solo cuando no hay proyecto por encima del directorio en absoluto. Un proyecto cuya configuración no se puede analizar es un error sobre ese proyecto, nunca respondido en silencio desde tus preferencias personales.

→ Espacios de nombres de memoria y la capa global

Todo lo demás

28 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, 2 cuando está vinculado a un espacio de trabajo local, 1 cuando el impacto de cambios está activado, 1 para conciencia de flota a menos que esté desactivado, y 1 cuando los hooks se ejecutan sobre MCP)

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 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:

Un poco vive junto a tu directorio de inicio en su lugar, bajo ~/.knowl/, porque es verdadero de la máquina en lugar de cualquier repositorio: el almacén de preferencias personales a nivel de máquina (~/.knowl/global.db), claves de reanudación, el registro de la flota de las sesiones que se ejecutan ahora mismo, tu credencial en la nube y el espejo local de un espacio de trabajo en la nube. Los manifiestos de espacio de trabajo viven fuera de los repositorios miembros por la misma razón — sus rutas de checkout son locales a la máquina. Las exportaciones e instantáneas se escriben solo cuando las pides.

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.

Contribuir

Consulta CONTRIBUTING.md para la configuración, las verificaciones a 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.