agentcairn

Una memoria duradera para todos los agentes de codificación compatibles.
Tu bóveda de Markdown es la fuente canónica. DuckDB es la caché de recuperación reemplazable.

Sitio web · PyPI · Complemento para Obsidian · Benchmarks

Un mojón marca el camino para quien venga después. agentcairn hace eso por los agentes de codificación: captura contexto duradero de las herramientas que usas, lo almacena como Markdown inspeccionable con procedencia, y recupera solo las piezas más relevantes cuando otro agente las necesita.

Prueba que puedes inspeccionar

La memoria no está oculta detrás de una consola de administración o una base de datos alojada. El complemento independiente agentcairn-obsidian lee los mismos archivos Markdown que los agentes y expone procedencia, actualidad, importancia, reemplazo y enlaces related:.

_{Una bóveda real de agentcairn en Obsidian. La lista es una vista sobre los archivos, no un segundo almacén de memoria.}

Instantánea de dogfooding · 2026-07-15. En 417 recuperaciones locales, la bóveda del mantenedor devolvió contexto sobre 262× smaller que cargar la bóveda completa cada vez—una estimación de 136.6M tokens of full-vault context avoided en total. Los conteos de tokens usan aproximadamente cuatro caracteres por token. Esto no es ahorro de tokens facturados, y agentcairn no envía telemetría.

Instalación

El camino más corto es un complemento de primera clase. Incluye el servidor MCP, la habilidad de memoria y los enlaces ambientales específicos del host—sin necesidad de instalar el paquete agentcairn por separado. El complemento se lanza a través de uvx, así que instala uv primero si uvx --version no está ya disponible.

Claude Code

claude plugin marketplace add ccf/agentcairn
claude plugin install agentcairn@agentcairn

Claude Code obtiene recuperación por turno con alcance de proyecto, captura de sesión/compactación, y los comandos /agentcairn:recall, /agentcairn:remember, /agentcairn:memory, /agentcairn:savings y /agentcairn:ingest.

Codex

codex plugin marketplace add ccf/agentcairn
codex plugin add agentcairn@agentcairn

Codex obtiene las herramientas MCP incluidas y la habilidad de memoria, recuperación SessionStart verificada en vivo, y captura SessionEnd con cairn sweep como respaldo fuera de banda.

Configuración asistida por agente

¿Ya usas skills.sh o un flujo de trabajo find-skills? Instala el asistente de configuración público:

npx skills add ccf/agentcairn --skill agentcairn-setup -g

Luego pídele a tu agente: Use $agentcairn-setup to preview, install, and verify AgentCairn for this coding agent.

Esto instala solo la guía de configuración—no el runtime de AgentCairn, el servidor MCP, el complemento ni los enlaces. El asistente delega esos cambios al instalador nativo de AgentCairn con vista previa y verifica la integración resultante. Los comandos de complemento para Claude Code y Codex de arriba siguen siendo el camino más corto.

La bóveda predeterminada es ~/agentcairn y se crea en el primer uso. Una bóveda nueva vacía no tiene nada útil que recuperar todavía, así que prueba todo el ciclo explícitamente:

You   → Remember this durable fact: staging deploys use blue-green.
Agent → written and indexed
You   → Recall the staging deploy strategy.
Agent → staging deploys use blue-green.  ↳ <memory permalink>

remember escribe la nota Markdown y la entrada del índice juntas, así que la recuperación inmediata es parte del contrato. La primera ejecución local puede descargar y preparar los modelos de incrustación/reordenamiento configurados.

El contrato

Cómo funciona

• Captura: los enlaces del host mejoran la inmediatez; cairn sweep lee los almacenes de transcripciones compatibles fuera de banda como respaldo duradero. AgentCairn redacta credenciales reconocidas, deduplica, filtra por importancia y destila antes de sus escrituras automatizadas en texto plano.
• Reconciliación: la primera transacción de lectura sincroniza el índice con alcance de bóveda con el Markdown. Una reconstrucción fallida preserva la última caché buena y los archivos duraderos permanecen intactos.
• Recuperación: los vectores BM25 y semánticos se fusionan con Reciprocal Rank Fusion, y luego se reordenan opcionalmente. Las fallas de modelo/proveedor caen visiblemente a BM25 con diagnósticos en lugar de devolver vectores incompatibles.
• Recordar: la herramienta MCP escribe atómicamente una nota Markdown y actualiza el índice bajo un solo bloqueo de escritura, haciendo que un guardado exitoso sea inmediatamente recuperable.

Diseñado para la confianza

• Local por defecto. FastEmbed se ejecuta localmente, el servidor MCP usa stdio, no hay daemon ni base de datos externa requeridos, y no hay telemetría.
• Límites claros. La bóveda sincronizada contiene Markdown; por defecto, el índice .duckdb reconstruible permanece fuera de ella. Los enlaces simbólicos de la bóveda que escapan de la raíz configurada se rechazan.
• Correcciones conscientes del tiempo. valid_from, valid_until y superseded_by mantienen la evidencia antigua visible mientras hacen que los hechos actuales ocupen el primer lugar.
• Grafo determinista. [[wikilinks]] y los vecinos opcionales cairn link crean un grafo nativo de Obsidian sin pedirle a un LLM que invente entidades.
• Recuperación consciente del proyecto. El proyecto actual se potencia por defecto; los resultados entre proyectos permanecen disponibles y están etiquetados. La recuperación automática tiene alcance de proyecto a menos que optes explícitamente por todos los proyectos.

Agentes compatibles

Cada host resuelve la misma bóveda configurada. cairn install previsualiza los hosts detectados sin escribir. Las escrituras de configuración MCP son primero con respaldo y preservan servidores no relacionados; las instalaciones de complementos delegan al CLI del propio host.

La SessionStart de Codex se verificó en vivo de extremo a extremo con agentcairn 0.24.2 / complemento 0.1.2. El despacho de comandos SessionEnd instalado y el barrido separado pasan sondas de manejador exactas; cairn sweep sigue siendo el respaldo de captura fuera de banda. Consulta la integración con OpenCode y la integración con Hermes para sus detalles de ciclo de vida nativos.

Uso directo

El complemento es la ruta más fácil, pero agentcairn también es un CLI independiente y un servidor MCP bajo demanda. Las instalaciones independientes requieren Python 3.11+.

uv tool install agentcairn

cairn init ~/agentcairn
cairn sweep --vault ~/agentcairn
cairn recall "how did we fix the auth bug?" --vault ~/agentcairn
cairn doctor --vault ~/agentcairn

Lleva la memoria de Claude Code contigo

La auto-memoria de Claude Code puede sembrar la bóveda compartida sin cambiar sus archivos fuente. El comando previsualiza solo el repositorio actual por defecto; agrega --apply para escribir las notas redactadas y actualizar el índice.

cairn import claude-memory                         # preview; writes nothing
cairn import claude-memory --apply                 # import this repository
cairn import claude-memory --project ../other --apply

La importación unidireccional lee MEMORY.md y sus archivos Markdown de temas—nunca CLAUDE.md ni .claude/rules/. Las notas importadas conservan la procedencia de Claude Code, proyecto y archivo fuente. Cuando una fuente cambia, la versión anterior permanece inspeccionable pero se reemplaza; cuando una desaparece, su versión importada expira. Un pequeño registro .agentcairn/native-memory/ preserva ese ciclo de vida sin indexar el contenido fuente dos veces. Usa --source <dir> para un directorio de memoria de Claude personalizado, gestionado o anulado por sesión, o --no-reindex al procesar importaciones por lotes.

¿Prefieres un proceso efímero?

uvx agentcairn                             # MCP server
uvx --from agentcairn cairn recall "..."  # CLI; plain `uvx cairn` is a different package

cairn schedule install --vault ~/agentcairn  # launchd on macOS / user crontab on Linux
cairn schedule status
cairn link --vault ~/agentcairn              # write deterministic related: neighbors
cairn reindex ~/agentcairn                   # rebuild the disposable cache
cairn savings                                # local context-efficiency estimate
cairn index-status --vault ~/agentcairn

cairn config --init
cairn config

auto_recall = true
auto_recall_k = 3
auto_recall_scope = "project"  # use "all" only as an explicit cross-project opt-in

Benchmarks medidos

El repositorio incluye un arnés reproducible LongMemEval-S + LoCoMo fijado por revisión. El predeterminado es nomic-embed-text-v1.5 local más el reordenador de codificador cruzado.

El contexto devuelto en el k=10 predeterminado es mucho más pequeño que el historial indexado completo:

Lee los números con honestidad:

• El recall de recuperación no es precisión de QA. Estas tablas comparan brazos de recuperación controlados, no la calidad de respuesta del usuario final ni la puntuación de un leaderboard de otro producto.
• Los conteos de tokens usan una heurística de aproximadamente cuatro caracteres por token. La reducción compara el pajar indexado con los fragmentos devueltos; no es ahorro de costo facturado.
• El impulso de grafo es inerte en estos corpus de chat porque no contienen grafo [[wikilink]] nativo. Está diseñado para bóvedas reales interconectadas.
• El juez de QA opcional usa Anthropic en lugar de la configuración GPT-4o de los artículos, así que esos resultados de QA son útiles para ablaciones relativas—no comparaciones de leaderboard publicadas.

Las métricas completas, barridos de incrustación, mediciones de latencia, licencias, comandos y advertencias viven en benchmarks/README.md.

Privacidad y límites

• La bóveda es texto plano por diseño, no almacenamiento cifrado. AgentCairn redacta patrones de credenciales reconocidos antes de sus escrituras automáticas de cuerpo/título/etiquetas; los patrones desconocidos y las ediciones manuales son responsabilidad tuya.
• Los archivos de la bóveda son solo del propietario (0600/0700). Debido a que la bóveda es texto plano y la redacción es de mejor esfuerzo, el modo de archivo es efectivamente su único control de acceso. Las configuraciones de GID compartido (por ejemplo, dos contenedores Docker en el mismo grupo pero con diferentes UIDs) necesitan acceso de grupo, por lo que vault_group_writable = true amplía nuevas notas y directorios de la bóveda a 0660/0770. Es opt-in a propósito: en macOS el grupo principal de cada usuario local es staff, por lo que un valor predeterminado legible por grupo expondría tus recuerdos a otras cuentas en la máquina. El control nunca amplía nada fuera de la bóveda: el índice, los libros mayores, los archivos de bloqueo y ~/.agentcairn/config.toml permanecen privados.
• Las funciones en la nube son salida explícita. El valor predeterminado sigue siendo local. Optar por un incrustador en la nube o un juez LLM envía el texto redactado restante a ese proveedor.
• El proyecto está en beta. El uso independiente requiere Python 3.11+, y la primera carga del modelo local puede llevar tiempo. La evidencia de recuperación publicada es más sólida para la memoria conversacional, no una afirmación universal de búsqueda de código.
• El comportamiento ambiental varía según el host. La matriz anterior es intencional: Cursor y Antigravity dependen de la captura de barrido; los hosts MCP genéricos pueden exponer herramientas sin enlaces de ciclo de vida.
• La automatización es específica de la plataforma. La programación gestionada se dirige a launchd de macOS y crontab de usuario de Linux; usa tu propio programador en otros lugares.

Desarrollo

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

uv sync
uv run pre-commit install

uv run pytest
uv run ruff format .
uv run ruff check --fix .
uv run pre-commit run --all-files

Ejecuta la regresión de referencia sin claves API:

uv run pytest benchmarks/tests/

Licencia

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