agentcairn MCP Server

oficial

Memoria de agente local primero: una bóveda de Obsidian en Markdown simple es la fuente de verdad, con un índice DuckDB reconstruible para recuperación híbrida BM25 + vectorial + de grafo.

GitHub
1

Documentación

🪨 agentcairn

CI Security PyPI Python License: Apache-2.0

Memoria local-first para agentes de IA — que realmente puedes leer, editar y poseer.

cairn  /kɛən/  · sustantivo — un montón de piedras apiladas para marcar un sendero o un lugar digno de recordar, dejado para quien venga después.

agentcairn le da a tu agente de codificación una memoria duradera y de alta calidad — pero en lugar de encerrarla en una base de datos opaca o un servicio en la nube, tus recuerdos viven como Markdown plano en un almacén de Obsidian que tú posees. Un índice rápido y reconstruible de DuckDB se sitúa encima para la recuperación. Abre tu almacén, lee lo que el agente recordó, corrige un dato erróneo a mano o añade tus propias notas — y el agente lo asimila todo.

Por qué agentcairn es diferente

La mayoría de sistemas de memoria para agentes convierten una base de datos o almacén en la nube en la fuente de verdad y tratan los archivos (si los hay) como una exportación unidireccional. agentcairn invierte eso:

  • 📂 Tu almacén es la fuente de verdad — no una exportación. La memoria es Markdown legible por humanos con frontmatter y [[wikilinks]]. Edítala en Obsidian; el índice respeta tus ediciones.
  • ♻️ El índice es desechable. DuckDB es una caché reconstruible (cairn reindex). Tu memoria sobrevive a una actualización de modelo, un índice corrupto, un cambio de esquema o la desinstalación de la herramienta — cero pérdida de datos, porque la verdad son solo archivos en disco.
  • 🧠 Sin pérdidas por construcción. La nota completa siempre se conserva. La destilación solo añade notas derivadas que enlazan de vuelta a la fuente — nunca descarta silenciosamente hechos que no pensó extraer en el momento de escritura.
  • 🔒 Redacción antes de cada escritura. Los secretos se limpian (regex + entropía + detección de credenciales en URL) antes de que nada — cuerpo, título o etiquetas — llegue al almacén de texto plano. Escribimos archivos que puedes leer, así que tratamos una credencial filtrada como el peor modo de fallo.
  • 🕸️ Un grafo de conocimiento gratuito y determinista. Tu [[wikilinks]] y frontmatter son el grafo — sin extracción por LLM, sin entidades alucinadas.
  • 🪶 Sin demonio, cero BD externa. Un archivo DuckDB embebido hace búsqueda semántica vectorial, texto completo BM25 y recorrido de grafos. Sin servidor siempre activo, sin Neo4j/Postgres/Qdrant, sin clave de nube obligatoria — solo una CLI cairn y un servidor MCP bajo demanda.
  • 🔍 Medido con honestidad. Un arnés reproducible LongMemEval-S + LoCoMo se incluye en benchmarks/ — con números reales, ablaciones y advertencias explícitas en lugar de un titular seleccionado a medida (ver más abajo).

Instalación

La forma más fácil de usar agentcairn es el plugin para Claude Code o Codex — una instalación conecta el servidor MCP, la memoria ambiental (recuerdo al inicio de sesión, captura al final), una habilidad de memoria y comandos de barra (Claude Code):

# Claude Code
claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

# Codex (from the Codex plugin marketplace)
codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Al instalar eliges una ruta de almacén (por defecto ~/agentcairn); se crea automáticamente en la primera sesión — no requiere configuración de Obsidian. A partir de entonces, agentcairn muestra la memoria relevante al inicio de cada sesión, destila cada sesión en tu almacén y te da /agentcairn:recall, /remember, /memory, /savings y /ingest. Nada que instalar con pip — el plugin ejecuta el paquete publicado a través de uvx.

¿No usas Claude Code o Codex? agentcairn también es un servidor MCP independiente + CLI para cualquier host — consulta Usarlo directamente.

Cómo funciona

flowchart LR
    T["Session transcripts<br/>(out-of-band)"]
    H["You · Obsidian<br/>(hand edits)"]
    V["📂 Obsidian vault<br/>Markdown + frontmatter + wikilinks<br/><b>source of truth</b>"]
    I["♻️ DuckDB index<br/>vector + BM25 + graph<br/><b>rebuildable cache</b>"]
    M["MCP tools<br/>remember · recall · search · build_context · recent"]

    T -- "redact → judge → distill → consolidate" --> V
    H -- "edit" --> V
    V -- "parse / reconcile-on-spawn" --> I
    I -- "READ_ONLY hybrid recall" --> M
    M -. "remember (redacted write)" .-> V

    classDef truth fill:#eaf1ff,stroke:#317cff,color:#191919;
    classDef cache fill:#f5f5f3,stroke:#999999,color:#191919;
    class V truth
    class I cache
  • Captura lee las transcripciones de sesión de tu arnés de agente (solo anexado, ya en disco) fuera de banda — robusto por diseño, sin ganchos frágiles en vivo — luego redacta → deduplica → juzga (durabilidad semántica; destilación LLM opcional vía CAIRN_JUDGE=anthropic) → filtra → destila en el almacén, sin pérdidas. cairn sweep autodetecta cada arnés presente (Claude Code, Codex, Antigravity CLI y Cursor son compatibles, tras una capa HarnessAdapter) para que obtengas memoria unificada en los cuatro sin configuración adicional. En el nivel LLM también consolida: un nuevo recuerdo que duplica uno existente se omite, y una versión más reciente de un hecho en evolución marca la nota anterior superseded_by (conservada + degradada en el recuerdo, nunca eliminada) — a prueba de fallos, para que una llamada errónea nunca descarte un recuerdo distinto (CAIRN_CONSOLIDATE=0 para desactivar). Además, una herramienta remember dirigida por el agente para recuerdos curados y de alto valor.
  • Recuperación fusiona BM25 + vectores semánticos con Fusión de Rango Recíproco, aplica un impulso de grafo opcional y se degrada con gracia a solo palabras clave cuando no hay modelo de embedding disponible — así el recuerdo nunca está silenciosamente muerto. Un reordenador cross-encoder opcional añade precisión.
  • Inteligencia híbrida: embeddings locales sin conexión (FastEmbed / nomic-embed-text-v1.5 por defecto) listos para usar — potente por sí solo y en la fusión híbrida (con nomic, solo vector supera a BM25 incluso en turnos cortos; ver el benchmark). Configura CAIRN_EMBED_MODEL para elegir otro modelo FastEmbed, o ejecuta CAIRN_EMBEDDER=ollama / un nivel en la nube para ir más allá.
  • Memoria temporal: las notas pueden llevar frontmatter valid_from/valid_until/superseded_by. El recuerdo es consciente de la validez — degrada suavemente los hechos superados y expirados (el hecho actual gana) sin ocultarlos nunca (sin pérdidas), y anota el estado de cada resultado (current/superseded/expired/not_yet_valid) más un ancla as_of para que el agente pueda razonar a lo largo del tiempo. Inerte para notas sin campos de validez.
  • Recuerdo consciente de la procedencia: las notas llevan procedencia project/harness, y el recuerdo impulsa los recuerdos de tu proyecto actual (sin pérdidas — los aciertos de otros proyectos aún aparecen, marcados [from: <project>]). Pasa --project <repo> para apuntar a otro repositorio, o --scope project para filtrar estrictamente solo el actual.

Usarlo directamente

El plugin es el camino más fácil, pero agentcairn es solo un paquete — úsalo sin Claude Code a través del servidor MCP bajo demanda (para cualquier host MCP) o la CLI cairn:

uvx agentcairn                                       # on-demand MCP server for any MCP host
cairn ingest --vault ~/vault                         # distill recent agent sessions into the vault
cairn sweep  --vault ~/vault                          # ingest + reindex in one pass (cron-friendly)
cairn schedule install --vault ~/vault                # run sweep automatically every 30 min (launchd on macOS, crontab on Linux)
cairn recall "how did we fix the auth bug?"          # hybrid recall from the CLI
cairn savings                                        # how much context recall has saved you
cairn reindex ~/vault                                # rebuild the index from Markdown (always safe)
cairn doctor                                         # health-check the index

Configuración

Todos los ajustes viven en un archivo — ~/.agentcairn/config.toml — con variables de entorno como sobrescrituras (precedencia: bandera CLI > var entorno > archivo config > predeterminado):

cairn config --init   # scaffold a fully-commented template (chmod 600)
cairn config          # show every setting's effective value and where it came from

Por ejemplo, habilitar el juez de memoria LLM son dos líneas sin comentar — sin necesidad de exportar variables de shell (el barrido en segundo plano del plugin lee el archivo directamente):

judge = "anthropic"
anthropic_api_key = "sk-ant-..."

Agentes compatibles

agentcairn funciona en dos niveles. Hosts de plugin (Claude Code, Codex y Antigravity) obtienen un plugin de primera clase — un servidor MCP empaquetado (recuerdo/búsqueda/remember), una habilidad de memoria y (en Claude Code y Codex) ganchos de sesión ambientales; cairn install <host> instala el plugin llamando a la CLI del propio host. Hosts MCP (todo lo demás) obtienen las mismas herramientas de recuerdo/búsqueda/remember a través del servidor MCP portable; cairn install <host> escribe la configuración del servidor MCP de forma no destructiva (tus otros servidores se conservan, el original se respalda en <config>.bak). El almacén sigue siendo un único ~/agentcairn global, por lo que la memoria se comparte entre todos los hosts.

HostSoporteConfigurar conCaptura ambiental
Claude Code🟢 Plugincairn install claude-code✅ recuerdo-al-inicio + captura-al-final
Codex🟢 Plugincairn install codex◐ recuerdo/remember en vivo; ganchos ambientales incluidos (verificando) 1
Cursor🔌 Servidor MCP + habilidad + ingestacairn install cursor◐ cairn sweep autodetecta transcripciones 2
Claude Desktop🔌 Servidor MCPcairn install claude-desktop—
VS Code (Copilot)🔌 Servidor MCPcairn install vscode—
Gemini CLI 3🔌 Servidor MCPcairn install gemini—
Antigravity🟢 Plugin + ingestacairn install antigravity◐ cairn sweep autodetecta transcripciones 4
Cualquier otro host MCP🔌 Servidor MCPuvx agentcairn (pega el fragmento cairn install … --print)—

cairn install enruta por tipo de host automáticamente:

cairn install                 # detect installed hosts + preview (writes nothing)
cairn install codex           # install the Codex plugin (shells to `codex plugin …`; strips any stale MCP block from ~/.codex/config.toml)
cairn install antigravity --source ./plugin  # install the Antigravity plugin from a local checkout (see note)
cairn install cursor          # write MCP config + install the memory skill for Cursor
cairn install --all           # configure every detected host
cairn install codex --source /path/to/agentcairn  # use a local checkout instead of the marketplace

Los hosts MCP toman una entrada JSON mcpServers (VS Code usa su clave servers). Los hosts de plugin (Claude Code, Codex, Antigravity) instalan el plugin a través de la CLI del host — el servidor MCP está incluido en el plugin y no necesita una entrada de configuración separada. Si previamente usaste cairn install antigravity para escribir una entrada MCP en ~/.gemini/config/mcp_config.json, volver a ejecutar cairn install antigravity elimina esa entrada obsoleta automáticamente.

Benchmarks medidos

Evaluamos agentcairn de la forma en que nos gustaría que se midiera un sistema de memoria — de forma reproducible, con ablaciones y sin un único número de titular seleccionado a medida. El arnés (benchmarks/) ejecuta LongMemEval-S y LoCoMo a través de un descargador de versión fijada (los conjuntos de datos nunca se incluyen), puntúa la recuperación de forma determinista (recall/nDCG@k, MRR — sin necesidad de clave API, se ejecuta en CI sobre un accesorio sintético) y ofrece una capa opcional de QA juzgada por LLM.

Recuperación — LoCoMo

Conjunto LoCoMo completo, a nivel de turno, macro-promedio, FastEmbed nomic-embed-text-v1.5 (el embedder por defecto):

brazorecall@5recall@10MRR
Solo BM250.5270.6040.459
Solo vector0.5360.6370.433
Híbrido (RRF)0.5620.6480.477
Híbrido + impulso-grafo0.5620.6480.477
Híbrido + reordenador0.6620.7350.608

Lo que leemos de esto — y decimos en voz alta:

  • Híbrido supera a cualquier brazo por separado — la fusión RRF vale la pena.
  • El reordenador cross-encoder es la mayor palanca (+0.10 recall@5 sobre híbrido); la preocupación de que "el cambio de dominio ms-marco pudiera perjudicar" no se materializó en datos conversacionales.
  • El embedder por defecto ahora cumple su función — con nomic, solo vector supera a BM25 (0.536 vs 0.527); cambiar del antiguo bge-small por defecto (que quedaba atrás con 0.483) cerró la brecha. Un barrido de 5 modelos FastEmbed definió la elección — nomic (768-d) gana en calidad por dimensión; modelos más grandes de 1024-d no lo superan. Tabla completa: benchmarks/README.md.
  • impulso-grafo es inerte en estos corpus — LoCoMo/LongMemEval no tienen un grafo [[wikilink]] nativo, por lo que el impulso no tiene sobre qué actuar. Es para almacenes reales interconectados, no para registros de chat, y no pretendemos lo contrario.

Recuperación — LongMemEval-S

Conjunto completo de 500 instancias: una tarea más sencilla con sesiones de evidencia bien separadas. El nivel de sesión es la granularidad que reportan los trabajos previos; el nivel de turno es el corte más fino que revela el corpus:

brazor@5 de sesiónMRR de sesiónr@5 de turnor@10 de turnoMRR de turno
Solo BM250.9200.9180.6800.7910.638
Solo vectorial0.9360.9160.5070.6920.454
Híbrido (RRF)0.9540.9380.6400.7980.544
Híbrido + reranker0.9690.9630.7880.8910.716

Lectura honesta:

  • Nuestro recall@5 de sesión de 0.969 se sitúa justo al lado del ≈0.95 de trabajos previos sobre el mismo conjunto completo de 500 preguntas, y a escala completa discrimina (0.920 BM25 → 0.969 reranker) en lugar de saturarse como ocurre con una muestra pequeña.
  • El reranker vuelve a ser la palanca más grande: r@5 de turno 0.640 → 0.788, r@5 de sesión 0.954 → 0.969.
  • El nivel de turno revela el corpus: aquí BM25 solo (0.680) supera al híbrido RRF (0.640) porque el vectorial puro es débil en estos tramos de evidencia de un solo turno (0.507); el reranker es lo que impulsa el valor por defecto hacia adelante. (Contraste con LoCoMo, donde el vectorial puro supera ligeramente a BM25.)

Eficiencia de contexto

¿Cuánto más pequeño es el contexto que agentcairn recupera en comparación con el historial completo que de otro modo llevarías al modelo? Configuración por defecto (híbrido + reranker, k=10):

conjunto de datosconsultaspajar mediorecuperado medio (k=10)reducción de contexto
LoCoMo (3 conversaciones)49725,646 tok529 tok51.1× media / 50.3× mediana
LongMemEval-S (500 completo)470136,552 tok2,207 tok64.7× media / 61.6× mediana

Estimación (~4 caracteres/token), no es un costo facturado; "pajar" = el historial completo indexado, "recuperado" = los fragmentos top-k devueltos. Mide el tamaño del contexto, independientemente de la calidad de la recuperación.

Precisión de QA

Las cifras de precisión de QA (evaluadas por LLM) también están disponibles, pero utilizan un juez Anthropic en lugar del GPT-4o de los artículos, por lo que no son comparables con las tablas de clasificación publicadas; son válidas solo como señal de ablación relativa. Consulta benchmarks/README.md para saber cómo ejecutarlo y cómo leer las cifras.

Hoja de ruta

  • v1 — completada. El bucle central: ingesta de transcripciones → redacción → Markdown → índice DuckDB reconstruible → recuperación híbrida; servidor MCP + CLI; redacción de secretos; embeddings locales; arnés de evaluación reproducible.
  • v1.1 — siguiente, priorizada por la evaluación anterior:
    • ✅ Reranker activado por defecto — la palanca de recuperación medida más grande; CAIRN_RERANK=0 para desactivarlo. (publicado)
    • Nivel de embedding Ollama — ✅ modelos locales mediante CAIRN_EMBEDDER=ollama (CAIRN_EMBED_MODEL/OLLAMA_HOST); cloud (OpenAI/Voyage) aún pendiente.
    • ✅ Validez bitemporal — frontmatter valid_from/valid_until/superseded_by; la recuperación degrada suavemente los hechos reemplazados/expirados (sin pérdida — nunca se ocultan) y anota la vigencia de cada resultado más un ancla as_of, para que el hecho actual prevalezca y el agente pueda razonar a lo largo del tiempo. (publicado)
    • HNSW en memoria para latencia de recuperación en bóvedas grandes.
  • v2 — ◐ Plugin para Obsidian (agentcairn-obsidian) — una vista de Memoria nativa de la bóveda (lista + procedencia + vigencia + grafo) para leer/navegar tu memoria en Obsidian; (MVP publicado; la recuperación semántica permanece en CLI/MCP). Sincronización en la nube MotherDuck, extracción opcional de entidades por LLM aún pendiente.

Desarrollo

agentcairn utiliza uv exclusivamente para la gestión de dependencias y herramientas.

No uses pip, poetry ni entornos virtuales globales.

# First-time setup
uv sync                         # create .venv and install all deps (including dev)
uv run pre-commit install       # install git hooks (ruff + pytest run on every commit)

# Daily use
uv run pytest                   # run the test suite
uv run cairn --help             # run the CLI
uvx agentcairn                  # run the installed tool ephemerally (as the MCP server does)

# Formatting and linting
uv run ruff format .            # format all Python files
uv run ruff check --fix .       # lint with auto-fix
uv run pre-commit run --all-files

# Benchmarks (offline retrieval metrics need no API key)
uv run pytest benchmarks/tests/                                      # offline synthetic-fixture suite
PYTHONPATH=benchmarks uv run --group bench python -m cairn_bench.run --dataset locomo

El servidor MCP se lanza mediante uvx agentcairn — no se requiere instalación global.

Licencia

Licencia Apache 2.0 — permisiva, con una concesión explícita de patente. Copyright © 2026 Charles C. Figueiredo.

Footnotes

  1. The La instalación del plugin de Codex y su servidor MCP empaquetado (recuerdo/búsqueda/remember) se verifica en vivo en Codex. Los ganchos de sesión ambientales (recuerdo-al-inicio, captura-al-final) se incluyen en el plugin y usan el esquema de ganchos documentado de Codex, pero su comportamiento en Codex aún no está confirmado de extremo a extremo; la captura también ocurre fuera de banda a través de cairn sweep independientemente. ↩

  2. Cursor no tiene ganchos de plugin, por lo que la captura ambiental es fuera de banda vía cairn sweep (fuente: base de datos SQLite global globalStorage/state.vscdb de Cursor, tabla cursorDiskKV, usuario "bubbles"). Cursor sigue siendo un host MCP para la salida (cairn install cursor → ~/.cursor/mcp.json); no hay plugin de Cursor. cairn install cursor también instala la habilidad using-agentcairn-memory (guía de recuerdo/recordatorio) en ~/.cursor/skills/using-agentcairn-memory/SKILL.md. ↩

  3. Gemini La ingesta de transcripciones de Gemini CLI (consumidor) no está soportada — Google está retirando Gemini CLI (corte para consumidores 2026-06-18) en favor de Antigravity CLI, que agentcairn ingiere en su lugar. cairn install gemini (conexión del servidor MCP) sigue siendo válido para cualquier host basado en Gemini que hable MCP. ↩

  4. The El plugin de Antigravity incluye el servidor MCP + habilidad de memoria; cairn install antigravity --source <dir> lo instala vía agy plugin install y elimina cualquier entrada obsoleta mcpServers.agentcairn de ~/.gemini/config/mcp_config.json. Nota: agy plugin install toma un directorio local o un marketplace registrado (no un repositorio git), así que apunta --source al directorio plugin/ de un checkout clonado por ahora. Antigravity no tiene ganchos de plugin reconocidos, por lo que la captura ambiental es fuera de banda vía cairn sweep (ruta: ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript.jsonl). ↩