Mnemos

mnemos

Dale a tu agente de IA una memoria que pueda citar.

Memoria local para agentes de IA. Con citas de fuentes incluidas.

Claude Code es potente, pero olvida el contexto de tu proyecto:

• olvida por qué rechazaste una arquitectura,
• pierde tus ADRs,
• inventa respuestas en lugar de leer tus documentos,
• no puede citar de forma fiable de dónde proviene una afirmación.

mnemos soluciona eso dándole una memoria local y citada de:

• tus ADRs y documentos de diseño
• tus notas y runbooks
• tu código fuente
• tu base de conocimiento OKF

Sin base de datos vectorial. Sin Ollama. Sin servicio de Python o Node. Solo un binario Go sin cgo que indexa tus archivos — cualquier carpeta de Markdown plano funciona tal cual — y los sirve a través de MCP, para que Claude pueda buscar, leer y citar tu propio conocimiento en lugar de adivinar, con cada respuesta aterrizando en el file#section exacto y el rango de líneas.

Pruébalo en 60 segundos

# 1. install — one cgo-free binary into $GOBIN (requires Go 1.25+)
git clone https://github.com/arhuman/mnemos.git && cd mnemos
make install

# 2. index a project
cd ~/work/myproject
mnemos init                              # creates ./.mnemos/ (mnemos.toml, kb, db, models)
mnemos add docs --collection myproject   # copy a directory into the kb and index it
mnemos search "why did we choose this architecture"

¿Prefieres make build (→ ./bin/mnemos) para mantenerlo fuera de tu $PATH? La compilación por defecto es Go puro / sin cgo (CGO_ENABLED=0).

search imprime citas que puedes abrir:

1. security/scim.md#Provisioning
   lines 42-88
   score 12.7

Luego conéctalo a Claude Code (nota la ruta absoluta de --config):

claude mcp add mnemos -- mnemos serve --config /abs/path/to/myproject/.mnemos/mnemos.toml

Ahora Claude responde desde tu proyecto en lugar de adivinar, y muestra su fuente:

Tú: ¿Cómo recupero commits perdidos?

Claude: Según recovery/reflog.md, el reflog registra hacia dónde han apuntado HEAD y cada puntero de rama — incluso después de un hard reset — así que puedes hacer checkout del hash del commit perdido. (recovery/reflog.md — "Reflog: recuperar commits perdidos")

Ese es el ciclo completo — indexar → preguntar → respuesta citada. Todo lo demás es profundidad: por qué está construido así, cómo funciona y las capacidades completas.

mnemos add ~/work/api/docs   --into api
mnemos add ~/work/infra/docs --into infra

mnemos origin add ~/work/spec --prefix spec --collection spec
mnemos origin reindex spec    # picks up new files, evicts deleted ones

Por qué mnemos

• Verdaderamente local-primero: se ejecuta completamente en tu máquina. Sin red, sin telemetría, sin que los datos salgan de tu proyecto.
• Cero dependencias: un solo binario Go autocontenido y sin cgo. Sin Python, Docker, Qdrant u Ollama.
• Cualquier cliente MCP: construido para Claude Code, funciona con cualquier cosa que hable MCP.
• Respuestas citadas: cada resultado enlaza de vuelta al file#section exacto y al rango de líneas, para que las afirmaciones sean verificables.
• Búsqueda rápida por defecto: SQLite FTS5 / bm25 listo para usar; búsqueda semántica local opcional e híbrida detrás de una etiqueta de compilación.
• Memoria de lectura-escritura: el agente puede capturar notas duraderas (remember); tú puedes gestionar el árbol (forget, move, list).
• Seguro por defecto: solo lectura a menos que optes por más; las escrituras están confinadas a rutas, y el contenido se escanea en busca de secretos al entrar en el índice (tanto en captura como en ingesta, controlado por exclude_secrets).

Cómo funciona

your files  →  mnemos index (SQLite/FTS5)  →  Claude Code memory  →  cited answers

Una vez conectado, Claude puede responder desde tu proyecto en lugar de divagar, y señalar de vuelta a la fuente:

• "¿Por qué elegimos esta arquitectura?"
• "¿Dónde está el ADR sobre el motor de reglas?"
• "Resume lo que sabemos sobre el aprovisionamiento SCIM."
• "¿Qué ha cambiado recientemente en la memoria de este proyecto?"

Bajo el capó, el binario incorpora un servidor MCP, un pipeline de indexación, un almacén SQLite, búsqueda de texto completo, un vigilante de archivos incremental y una CLI de administración. Consulta docs/architecture.md.

¿Realmente recupera?

Un resultado citado, listo para usar (compilación léxica por defecto, con un paquete de ejemplo incluido):

$ mnemos add examples/git-recipes/bundle --into . --collection git
$ mnemos search "recover lost commits" --limit 1
1. recovery/reflog.md#Gotcha
   lines 24-28
   score 7.8

Cada resultado es un file#section real y un rango de líneas que puedes abrir — ese es el punto principal.

Calidad de recuperación, medida. mnemos eval deriva automáticamente pares de consulta→fuente reservados de un paquete OKF (elimina cada bloque de ejemplo de su propio documento, y luego comprueba si la recuperación sigue encontrando el documento correcto) e informa métricas a nivel de documento. En el paquete examples/git-recipes incluido (6 recetas, consultas de estilo palabra clave):

Los tres son fracciones en [0,1] (×100 para un porcentaje); cuanto más alto, mejor. El @K es la profundidad de recuperación — top‑1 para Hit, top‑12 para el resto:

• Hit@1 — proporción de consultas cuyo resultado #1 es el documento correcto (0.83 = 5/6).
• Recall@12 — proporción donde el documento correcto aparece en cualquier lugar del top 12.
• MRR@12 — rango recíproco medio: promedio de 1/(rank of the first correct doc) sobre el top 12 (1.0 = siempre clasificado primero).

La compilación léxica por defecto ya clava la recuperación por palabras clave. La compilación de incrustaciones opcional (consulta Búsqueda semántica) vale la pena en consultas más difíciles de lenguaje natural sobre datos estructurados: en el paquete examples/onpage-seo, cuyas respuestas reservadas son bloques JSON-LD / sitemap-XML que no comparten ninguna palabra clave con su prosa, el léxico puntúa 0.00 mientras que --semantic recupera Hit@1 0.57 / Recall@12 0.86. Reproduce (N es 6 y 7 respectivamente — señales de humo, no benchmarks):

mnemos eval examples/git-recipes/bundle              # lexical → 0.83
make build-embed && mnemos models install all-MiniLM-L6-v2
mnemos eval examples/git-recipes/bundle --semantic   # hybrid  → 1.00
mnemos eval examples/onpage-seo/bundle --semantic    # the hard case → 0.57

Conectar Claude Code

La ruta de 60 segundos anterior usó claude mcp add con una ruta absoluta de --config:

claude mcp add mnemos -- mnemos serve --config /abs/path/to/project/.mnemos/mnemos.toml

Para compartirlo con el repositorio, haz commit a través de .mcp.json en su lugar:

{ "mcpServers": { "mnemos": { "command": "mnemos", "args": ["serve", "--config", "/abs/path/to/project/.mnemos/mnemos.toml"] } } }

Verifica con claude mcp list (debería mostrar mnemos ✓ connected) y /mcp dentro de una sesión. Claude entonces llama a las herramientas automáticamente; consulta Capacidades.

Un comando lo conecta: Claude Code informa mnemos ✓ conectado.

Búsqueda semántica: la pregunta dice "desaparecido" — una palabra que no aparece en ninguna parte de las notas — sin embargo Claude encuentra y cita recovery/reflog.md.

Este clip usa la compilación semántica opcional (make install-embed + mnemos models install all-MiniLM-L6-v2 + use_vectors = true; consulta Búsqueda semántica). El binario make install por defecto es solo léxico, así que no responderá una pregunta sin palabras clave como esta — busca por palabra clave en su lugar (p. ej. mnemos search "recover lost commits", que alcanza el mismo documento).

Haz que Claude use la memoria automáticamente (skill opcional)

Las herramientas MCP son pasivas: están disponibles, pero Claude aún tiene que decidir llamar a mnemos.search antes de responder o a mnemos.remember cuando dices algo que vale la pena guardar, y los modelos a menudo no lo hacen. La skill mnemos-okf incluida cierra esa brecha codificando cuándo recurrir a la memoria: recordar antes de responder desde la suposición, capturar hechos duraderos y manejar las herramientas OKF.

Es opcional y específica de Claude Code: el servidor funciona con cualquier cliente MCP sin ella. Instálala a nivel de usuario (todos los proyectos):

make install-skill        # copies skills/mnemos-okf -> ~/.claude/skills/ and merges its hooks

O colócala manualmente, p. ej. a nivel de proyecto solo para este repositorio:

mkdir -p .claude/skills && cp -r skills/mnemos-okf .claude/skills/mnemos-okf

La captura es deliberadamente conservadora (solo hechos duraderos, escaneada en busca de secretos) y permanece restringida detrás de allow_write/allow_delete: la skill nunca otorga acceso que la configuración no haya aceptado. Consulta skills/mnemos-okf/SKILL.md.

El bucle de memoria

mnemos es memoria de proyecto local para agentes de codificación: recuperación citada, estado de proyecto duradero, consolidación de conocimiento.

prompt
  -> recall (search first, cite)
  -> act
  -> capture durable facts to the inbox
  -> update project/task state
  -> consolidate raw captures into canonical docs
  -> cite everything

La skill mnemos-okf incluida codifica esto en seis modos: RECALL, CAPTURE, OKF, RESTORE, TASK y CONSOLIDATE. Las tareas son documentos Task agrupados por mnemos task list. La consolidación nunca sobrescribe en silencio: los conflictos se muestran y las pasadas se registran en un diario.

El diseño de referencia está en examples/project-memory/bundle/, un proyecto ficticio con estado, restricciones, decisiones, tareas (división estado/historial) y un diario de consolidación. Ingiértelo para ver mnemos task list en acción:

mnemos add examples/project-memory/bundle --into aurora --collection aurora
mnemos task list

in_progress (1)
  aurora/tasks/rate-limit-ingest.md  Rate-limit the ingest endpoint
todo (1)
  aurora/tasks/csv-export.md  Add CSV export
done (1)
  aurora/tasks/fix-auth-timeout.md  Fix auth token timeout

Automatización con hooks

La skill es consultiva: el modelo decide cuándo disparar cada modo. Los hooks de Claude Code hacen determinista el bucle de memoria. make install-skill (o make install-hooks por sí solo) fusiona skills/mnemos-okf/hooks/settings.example.json en tu ~/.claude/settings.json de forma idempotente, manteniendo un .bak; pasa SKIP_HOOKS=1 para optar por no participar, o fusiona el archivo a mano para un .claude/settings.json a nivel de proyecto. Se activan dos hooks:

La persistencia de PreCompact y Stop (resúmenes de sesión, vaciado de captura) permanece en la skill porque esos eventos de hook no pueden inyectar contexto en el modelo.

Capacidades

Claude alcanza tu memoria a través de herramientas MCP (y tú a través de los comandos CLI correspondientes). Nota la ortografía: mnemos.search es la herramienta MCP que Claude llama; mnemos search es el comando CLI que tú ejecutas.

Consulta (solo lectura, sin compuerta)

• mnemos.search: recuperación clasificada y filtrada con citas.
• mnemos.read: lee un fragmento preciso (por chunk_id) o un documento completo (por uri). Pasa follow_links: true para adjuntar también los vecinos de enlace de 1 salto del documento.
• mnemos.context: resultados top-k como bloques de contexto listos para LLM (uri:start-end → contenido). Pasa follow_links: true para adjuntar los vecinos de enlace de 1 salto de cada bloque de documento.
• mnemos.related: los vecinos del grafo de enlaces de un documento, sus enlaces salientes y enlaces entrantes (1 salto, a nivel de documento). Los objetivos salientes colgantes se devuelven con resolved: false. Filtra con direction (saliente/entrante/ambos) y limit.
• mnemos.list: recorre el árbol OKF en disco y anota cada archivo con metadatos de índice (título, tipo, etiquetas, colección) más una marca indexed, de modo que tanto los archivos almacenados como los aún no indexados sean visibles. Filtra por path, collection, type o estado indexado.

Escritura (requiere allow_write = true)

• mnemos.remember: escribe una nota en la memoria. Pasa un path opcional (p. ej., "adr/0003-rule-engine.md") para colocarla en una ubicación explícita en el árbol OKF en lugar de nombrarla automáticamente bajo kb/capture/. El contenido se escanea en busca de secretos antes de escribirse e indexarse.
• mnemos.okfy: convierte un archivo .txt/.md existente en el árbol en un documento OKF (frontmatter + cuerpo) en out (por defecto, la ruta de origen con una extensión .md) y lo indexa, dejando el origen intacto. El cuerpo de origen se escanea en busca de secretos primero.

mnemos edit <uri> es la contraparte humana: un editor de terminal para un documento, controlado por la misma marca allow_write, sin herramienta MCP propia. Consulta Editar documentos interactivamente.

Gestión (requiere allow_delete = true)

• mnemos.forget: elimina un archivo del árbol OKF y lo desindexa; idempotente.
• mnemos.move: mueve un archivo o directorio dentro del árbol y lo reindexa bajo la nueva ruta. Un directorio mueve todo su subárbol, conservando la colección de cada documento. Los enlaces entrantes de Markdown a las rutas antiguas no se reescriben en V0 (se registran como advertencia).

Mantén la memoria fresca

Ejecuta un vigilante para reindexar ante cambios (incremental; elimina archivos borrados):

mnemos watch . --collection myproject

Habilita la escritura en .mnemos/mnemos.toml para que Claude pueda capturar y gestionar notas:

[mcp]
allow_write = true     # gates mnemos.remember and mnemos.okfy
allow_delete = true    # gates mnemos.forget and mnemos.move

Si un vigilante se ejecuta sobre el árbol, las operaciones forget/move también son vistas por el vigilante (redundante pero idempotente); las herramientas actualizan el índice directamente y funcionan sin vigilante. Establece [capture] defer_to_watcher = true cuando un vigilante cubra kb/capture/ para evitar la doble indexación de notas recordadas.

Editar documentos interactivamente

mnemos edit <uri> abre un editor de terminal sobre un documento OKF a la vez, dividido en tres paneles:

• NAV: los enlaces salientes del documento, enlaces entrantes y (una vez que una compilación de incrustaciones haya calculado las incrustaciones del corpus) documentos semánticamente similares; de lo contrario, esa sección muestra una pista de no disponible en lugar de resultados.
• METADATA: campos de frontmatter, tipados según el type OKF del documento. Una enumeración conocida (el status o priority de una tarea) cicla con las teclas de flecha, tags se reescribe como una lista completa, los campos desconocidos caen en texto libre y los campos propiedad del índice como type son de solo lectura.
• CONTENIDO: el cuerpo, entregado a $EDITOR para edición y recargado al salir.

mnemos edit tasks/ship.md

Teclas: tab foco, ↑↓ mover, enter abrir/editar, ←→ ciclar una enumeración, e $EDITOR, m mover/renombrar, s guardar, b/retroceso atrás, q salir. Guardar escribe el archivo primero y luego reindexa solo ese documento, de modo que una edición nunca se pierde incluso si la reindexación falla; las escrituras de frontmatter preservan el resto del archivo (comentarios, orden de claves, campos no relacionados) en lugar de reescribirlo. Navegar a otro documento mientras el actual no está guardado lo guarda primero.

m mueve o renombra el documento abierto. Solicita con la uri actual: edítala libremente, o presiona tab para un selector filtrado difuso de los directorios que ya contienen documentos (enter reubica el nombre de archivo bajo el seleccionado, esc vuelve a la solicitud). Confirmar renombra el archivo en disco, lo reindexa bajo la nueva uri y reabre el editor allí; los enlaces entrantes que aún apuntan a la ruta antigua se informan, no se reescriben. Como mnemos mv, necesita [mcp].allow_delete = true ya que las entradas de índice antiguas se eliminan.

Requiere una uri: un mnemos edit desnudo da error, no hay selector de navegación de árbol aún. Está controlado de la misma manera que mnemos.remember/mnemos.okfy:

[mcp]
allow_write = true   # also gates mnemos edit

No hay herramienta MCP correspondiente: mnemos edit es solo CLI, para un humano en el teclado.

Búsqueda semántica (opcional)

El binario predeterminado es solo léxico (FTS5 / bm25) y permanece pequeño y sin cgo. La recuperación semántica local + híbrida está completamente implementada pero compilada detrás de la etiqueta de compilación embed, de modo que las dependencias ONNX/tokenizer nunca entran en el binario predeterminado. Para habilitarla:

make build-embed                       # or: make install-embed  (still cgo-free, CGO_ENABLED=0)
mnemos models install all-MiniLM-L6-v2 # downloads the embedding model into ~/.mnemos/models
mnemos reindex --embeddings            # compute vectors for already-indexed chunks
mnemos search "why did we choose this architecture" --semantic

--semantic fusiona bm25 con similitud vectorial, de modo que las consultas en lenguaje natural que el índice léxico no capta aún se resuelven. Sin la compilación de incrustaciones (o un modelo instalado), la marca se rechaza con un mensaje claro; el mnemos search simple siempre funciona.

Cómo funciona internamente (modelo, inferencia ONNX en Go puro, fusión RRF): docs/architecture.md.

Soporte OKF

mnemos entiende de forma nativa OKF (Formato de Conocimiento Abierto) y cualquier bóveda de Markdown con frontmatter YAML y enlaces cruzados, sin modo especial:

• el tags/type del frontmatter se convierte en señales de clasificación difusa en FTS,
• los enlaces de Markdown se capturan como aristas y se recorren: mnemos related (y la herramienta mnemos.related) recorre los enlaces salientes y entrantes de un documento, follow_links los adjunta a una llamada de lectura o contexto, y [search] graph_expansion = true llena los espacios de resultados vacíos con los vecinos de 1 salto de los mejores resultados,
• los archivos index.md se tratan solo como estructura (se mantienen fuera de FTS y del grafo de enlaces).

Los paquetes OKF sirven como corpus para mnemos eval, que deriva automáticamente pares consulta→fuente retenidos e informa Hit@1 / Recall@12 / MRR@12 contra una línea base confirmada. Consulta docs/architecture.md.

Referencia

• docs/commands.md — cada comando CLI y sus marcas.
• docs/configuration.md: el <MNEMOS_DIR>/mnemos.toml en capas, con todos los valores predeterminados.
• docs/paths-and-indexing.md — cómo se ubica el estado, qué se indexa, dónde aterrizan las escrituras y las reglas de idempotencia/URI.
• docs/architecture.md — principios de diseño y la metodología de evaluación de recuperación.

Seguridad

• Sin red, sin telemetría; el servidor MCP es solo stdio.
• Los binarios enviados llevan SBOM (generados con syft) y están firmados con cosign (OIDC sin clave).
• Solo lectura por defecto. La escritura es opcional (allow_write = true). Las operaciones destructivas (olvidar, mover) requieren una opción separada (allow_delete = true).
• Todas las rutas proporcionadas por el llamador se validan mediante un guardián de confinamiento antes de cualquier operación de disco: se rechazan el recorrido .., las rutas absolutas fuera de la raíz del árbol, los escapes de enlaces simbólicos, el acceso a .mnemos/ y los globs [security].exclude.
• Los orígenes externos registrados son de solo lectura: cada verbo de escritura rechaza una uri en un espacio de nombres registrado y nombra el origen propietario. El guardián no cambia para todo lo que está fuera de un origen registrado, de modo que un escape de enlace simbólico no registrado se rechaza exactamente como antes.
• El contenido se escanea en busca de secretos antes de indexarse, tanto en la ruta de captura (remember, okfy, que rechazan) como en la ruta de ingesta (ingest, add, watch, reindex, que omiten el archivo con una advertencia que nombra las reglas coincidentes y continúan la ejecución). Establece [security] exclude_secrets = false para deshabilitar.
• Los patrones de exclusión de rutas/secretos mantienen .env, claves y directorios secretos fuera del índice.

Consulta SECURITY.md para la política completa.

Desarrollo

make build      # cgo-free binary -> bin/
make test       # go test -race ./...
make audit      # golangci-lint (incl. govet + staticcheck) + govulncheck + race tests
make tools      # install pinned dev tools (golangci-lint, govulncheck)
make help       # list all targets

La arquitectura, los principios de diseño y la metodología de evaluación de recuperación viven en docs/architecture.md; las decisiones de diseño se registran como ADRs. Las contribuciones son bienvenidas; consulta CONTRIBUTING.md.

Licencia

mnemos está licenciado bajo la Licencia MIT: esto cubre el código y contenido propios de mnemos. El repositorio también incluye material de terceros que no está cubierto por la Licencia MIT y permanece bajo sus propios términos; consulta THIRD-PARTY-NOTICES.md (notablemente el paquete OKF de ejemplo en examples/onpage-seo/bundle/).