agentcairn

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

Sitio web · PyPI · Complemento para Obsidian · Benchmarks

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

Prueba que puedes inspeccionar

La memoria no está oculta tras una consola de administración o una base de datos alojada. El complemento separado agentcairn-obsidian lee los mismos archivos Markdown que los agentes y expone la procedencia, vigencia, importancia, sustitución 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 Dogfood · 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—un estimado de 136.6M tokens of full-vault context avoided en total. Los conteos de tokens usan aproximadamente cuatro caracteres por token. Esto no es un ahorro de tokens facturados, y agentcairn no envía telemetría.

Instalar

El camino más corto es un complemento de primera clase. Incluye el servidor MCP, la habilidad de memoria y los ganchos 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á 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 y la habilidad de memoria incluidas, recuperación verificada en vivo al inicio de sesión (SessionStart) y captura al finalizar sesión (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 tiempo de ejecución de AgentCairn, el servidor MCP, el complemento o los ganchos. El asistente delega esos cambios al instalador nativo de vista previa primero de AgentCairn y verifica la integración resultante. Los comandos del complemento de Claude Code y Codex anteriores siguen siendo el camino más corto.

La bóveda predeterminada es ~/agentcairn y se crea en el primer uso. Una bóveda nueva y vacía no tiene nada útil que recordar aún, así que prueba el ciclo completo 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, por lo que la recuperación inmediata es parte del contrato. La primera ejecución local puede descargar y calentar los modelos de embedding/re-ranking configurados.

El contrato

Cómo funciona

• Captura: los ganchos del host mejoran la inmediatez; cairn sweep lee 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.
• Reconciliar: la primera lectura pone transaccionalmente el índice con alcance de bóveda en sincronía con Markdown. Una reconstrucción fallida preserva la última buena caché y los archivos duraderos permanecen intactos.
• Recuperar: BM25 y vectores semánticos se fusionan con Reciprocal Rank Fusion, luego opcionalmente se reordenan. Los fallos del modelo/proveedor recurren 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 bloqueo de escritor, 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 un demonio o base de datos externa requerida, y no hay telemetría.
• Límites claros. La bóveda sincronizada contiene Markdown; por defecto, el índice reconstruible .duckdb permanece fuera de ella. Los enlaces simbólicos de la bóveda que escapan de la raíz configurada son rechazados.
• Correcciones conscientes del tiempo. valid_from, valid_until y superseded_by mantienen visible la evidencia antigua mientras hacen que los hechos actuales se clasifiquen primero.
• 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 impulsa por defecto; los resultados de otros 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 copia de seguridad y preservan servidores no relacionados; las instalaciones de complementos de host delegan en la CLI propia del host.

La SessionStart de Codex fue verificada en vivo de extremo a extremo con agentcairn 0.24.2 / complemento 0.1.2. El despacho del comando 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 de OpenCode y la integración de Hermes para sus detalles de ciclo de vida nativo.

Usándolo directamente

El complemento es la ruta más fácil, pero agentcairn también es una 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 memoria automática de Claude Code puede sembrar la bóveda compartida sin cambiar sus archivos fuente. El comando previsualiza solo el repositorio actual por defecto; añade --apply para escribir las notas redactadas y refrescar 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 o .claude/rules/. Las notas importadas retienen la procedencia de Claude Code, proyecto y archivo fuente. Cuando una fuente cambia, la versión anterior permanece inspeccionable pero es sustituida; 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 sobrescrito por sesión, o --no-reindex al importar por lotes.

Prefiere 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 LongMemEval-S + LoCoMo con revisión fijada y reproducible. El predeterminado es nomic-embed-text-v1.5 local más el reordenador de cross-encoder.

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:

• La recuperación (recall) no es precisión de QA. Estas tablas comparan brazos de recuperación controlados, no la calidad de respuesta del usuario final o la puntuación de otro producto en una tabla de clasificación.
• 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 un ahorro de costos facturado.
• El impulso de grafo es inerte en estos corpus de chat porque no contienen un 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, por lo que esos resultados de QA son útiles para ablaciones relativas—no para comparaciones con tablas de clasificación publicadas.

Las métricas completas, barridos de embedding, mediciones de latencia, licencias, comandos y advertencias se encuentran 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 siguen siendo tu responsabilidad.
• Las funciones en la nube son egreso explícito. El comportamiento predeterminado se mantiene 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 tomar 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 por 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 apunta 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 conexión sin claves API:

uv run pytest benchmarks/tests/

Licencia

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