Cairn Remembers

Cairn

Construye conocimiento. Deja señales. — Herramientas para exploradores modernos.

Memoria episódica local-first para agentes de IA — y para ti.

Un cairn es una pila de piedras que marca un sendero. Este marca el sendero de tu pensamiento: cada decisión, callejón sin salida y razón se convierte en un nodo que tú — y cualquier modelo — pueden encontrar de nuevo, entre sesiones y entre generaciones de modelos.

• Local-first — todo vive en un solo archivo SQLite en ~/.cairn/. Sin nube, sin cuenta, sin telemetría.
• Independiente del modelo — cualquier agente que ejecute un comando de shell o hable MCP: Claude, GPT/Codex, Gemini, modelos locales.
• Solo añadido — los recuerdos se anulan, nunca se eliminan. El registro es el registro.
• Tuyo — Cairn no envía nada fuera de tu máquina. Tu chat sigue yendo al modelo que elijas, exactamente como lo haría sin Cairn — usa un modelo local y nada sale en absoluto.

Dos formas de entrar:

• 🧑 ¿Una persona configurando esto? Sigue leyendo — Inicio rápido toma unos 5 minutos. Cada opción y solución: QUICKSTART.md.
• 🤖 ¿Un agente de IA instalando Cairn para alguien? → SETUP_FOR_AGENTS.md está escrito para ti (instalación, consentimiento, atribución).

Ver dentro de Cairn

Guarda las decisiones, razones y trabajo inconcluso al que quieras volver. Cairn los almacena en una bóveda local que tú y tus herramientas de IA conectadas pueden leer y ampliar. Cada IA mantiene su propia memoria y contexto. Estas demos muestran el panel opcional para explorar el registro.

Hub	Proyectos	Conexiones
Retoma el trabajo inconcluso.	Mantén el trabajo relacionado junto.	Explora recuerdos vinculados.

Explora las cinco demos y descripciones.

• Hub — 9 segundos
• Proyectos — 18 segundos
• Índice — 6 segundos
• Feed en vivo — 14 segundos
• Conexiones — 8 segundos

Grabado en una instalación local. El texto privado usa ejemplos; los controles y la atribución de fuentes se conservan. La instalación filmada no se ha verificado contra todos los controles de la versión 0.3.3. Descripciones de demos y notas de grabación.

Contenido

• Inicio rápido
• Conecta tu IA
• Lo que obtienes
• Instalación avanzada
• Múltiples cuentas
• Qué respaldar
• Comandos comunes
• Licencia

Inicio rápido

Dos lugares, nunca los mezcles: 🖥️ Tu terminal (PowerShell / Terminal) — cada comando de esta página se ejecuta aquí, en tu computadora. La conexión siempre es un comando de terminal o una edición de archivo de configuración — una IA puede ejecutar esos pasos de terminal por ti (ese es el camino más rápido abajo), pero la conexión nunca es algo que pegues en el cuadro de chat. 💬 El chat de IA — donde aparece la memoria, y donde pruebas la conexión pidiéndole a la IA que la use.

Lo más rápido — deja que tu IA lo haga

Abre Claude Code, Codex o Cursor y pega:

Instala y configura Cairn para mí desde https://github.com/CairnRemembers/cairn

Tu IA ejecuta los pasos de terminal y pregunta antes de activar la memoria — un sí/no por IA en tu máquina, por defecto No. Nada se registra sin tu sí. (¿Usas Codex? Hay un pegado extra después — ver Conecta tu IA.)

O hazlo tú mismo

1 — Instala 🖥️ (instala solo software — no registra nada, la bóveda comienza vacía)

⚠️ ¿Instalando [all] en Linux / WSL? Ejecuta pip install torch --index-url https://download.pytorch.org/whl/cpu primero, o pip descargará una pila CUDA torch de varios GB que no necesitas. Las ruedas de torch para Windows y macOS ya son solo CPU.

pip install cairn-remembers            # base install
pip install "cairn-remembers[all]"     # + embedder + dashboard

Desde el código fuente

Sigue siendo el camino más completo — el instalador maneja el paso de torch-CPU por ti:

Obtén el código 🖥️

git clone https://github.com/CairnRemembers/cairn
cd cairn

Ejecuta el instalador 🖥️

# Windows:      .\install.ps1      (blocked? powershell -ExecutionPolicy Bypass -File .\install.ps1)
# macOS/Linux:  ./install.sh

El instalador encuentra Python 3.11+, instala todo (la primera ejecución descarga PyTorch — la versión ligera de CPU en Linux/Windows, unos minutos), y se verifica a sí mismo.

2 — Conecta tu IA. Aquí es donde la memoria realmente se activa, y cada IA necesita una conexión diferente — un y en la configuración termina el trabajo para Claude Code, pero no para Codex o Claude Desktop. Encuentra tu IA abajo y sigue hasta su ✅.

Conecta tu IA

Cairn tiene dos cables separados, y conocer la diferencia previene todas las sorpresas comunes:

• Captura — tus chats se recuerdan automáticamente (escribe en la bóveda).
• Herramientas — la IA puede buscar y anotar tu bóveda desde el chat (lecturas + escrituras bajo demanda).

Algunas IAs necesitan un cable, otras necesitan ambos. No te detengas en la primera ✓ — sigue tu IA hasta su línea ✅.

Claude Code — un comando

🖥️ En la terminal:

python -X utf8 -m cairn setup        # answer y for Claude Code

Eso conecta la captura: cada nuevo chat de Claude Code se auto-orienta (verás el banner), registra mientras trabajas, y compila al terminar. A nivel de máquina, una vez, reversible (cairn disconnect --global). ¿Prefieres solo un proyecto? Ejecuta cairn connect dentro de ese repositorio en su lugar (global y por proyecto son mutuamente excluyentes — doctor lo señala).

✅ Listo cuando: un nuevo chat se abre con un banner "CAIRN — contexto heredado", y 🖥️ python -X utf8 -m cairn doctor muestra ✓ captura.

Opcional — herramientas nativas: Claude Code ya puede leer la bóveda ejecutando comandos cairn en su shell. Para herramientas nativas de cairn_* en su lugar, registra el servidor MCP a nivel de usuario, apuntando al Python que pueda import cairn (un python desnudo que no puede es el fallo #1 — prueba la ruta primero, QUICKSTART §6a):

claude mcp add --scope user cairn -- <full-path-to-python> -X utf8 -m cairn mcp

💬 Prueba: pide al chat "llamar a cairn_orient". (doctor no puede ver este cable — la petición es la prueba.)

OpenAI Codex — tres piezas, cada una hace un trabajo diferente

1. Captura 🖥️ — python -X utf8 -m cairn setup → y para Codex (= codex-hook install). Captura turnos en vivo mientras Codex dispara notify (deduplicados por id de turno). Para un barrido completo de todo en disco, ejecuta 🖥️ python -X utf8 -m cairn import codex-sessions --apply en cualquier momento.
2. Herramientas 📄 — añade a ~/.codex/config.toml, luego reinicia Codex completamente (recorrido completo §6):

[mcp_servers.cairn]
command = "<full-path-to-python>"
args = ["-X", "utf8", "-m", "cairn", "mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
default_tools_approval_mode = "approve"

3. Hábito 📄 — crea ~/.codex/AGENTS.md y pega el protocolo de memoria de QUICKSTART §6c para que Codex se oriente, busque, y anote sin que se lo pidan. (Necesita la pieza 2 — el protocolo llama a esas herramientas.)

✅ Listo cuando: 🖥️ python -X utf8 -m cairn codex-hook status imprime INSTALADO, y 💬 un chat de Codex responde "llamar a cairn_orient" con un resumen (con la pieza 3, su primera respuesta comienza con [cairn: oriented — N]). ⚠️ Nota honesta: cairn doctor detecta estructuralmente el registro MCP de Codex (el bloque [mcp_servers.cairn]), pero no prueba que el servidor se inicie o que el hook de notificación capture — las verificaciones anteriores son la prueba real de eso.

Claude Desktop / Cursor — un pegado

📄 Añade a claude_desktop_config.json (o la configuración MCP de Cursor), luego reinicia la aplicación:

{
  "mcpServers": {
    "cairn": { "command": "python", "args": ["-X", "utf8", "-m", "cairn", "mcp"] }
  }
}

Ese es el cable de herramientas — buscar, obtener, vagar, anotar desde el chat. Estas superficies no tienen captura ambiental; lo que le pidas a la IA que cairn_note es lo que se guarda. (Si la aplicación no encuentra Python, usa la ruta completa del Python que instaló Cairn.)

✅ Listo cuando: doctor muestra ✓ MCP — registrado en la configuración de Claude Desktop (Desktop), o 💬 la prueba de humo "llamar a cairn_orient" responde (Cursor).

Aplica a cada IA anterior:

• La conexión es única. Los nuevos chats solo recuerdan — nunca activas por chat. orient lee memoria; nunca activa nada. El alcance varía según el cable: los hooks de Claude Code son a nivel de máquina (o un proyecto vía cairn connect); Desktop/Cursor y Codex viven en la configuración de cada aplicación, por cuenta.
• Solo los NUEVOS chats toman la nueva conexión — termina de conectar, luego abre un chat nuevo. (Los clientes MCP de larga duración releen las herramientas solo con un reinicio completo.)
• Controles de privacidad: salta un chat — CAIRN_CAPTURE=0 en ese shell (PowerShell $env:CAIRN_CAPTURE="0" · cmd set CAIRN_CAPTURE=0 · bash export CAIRN_CAPTURE=0) · pausa en todas partes: cairn capture off / on · secretos eliminados antes de escribir (solo añadido, cierre ante fallo).
• Deshacer: cairn disconnect [--global] · cairn codex-hook uninstall · re-ejecuta cairn setup para revisar.

Lo que obtienes

• Una bóveda, cada modelo. Cualquier agente que hable MCP o pueda ejecutar cairn lee y escribe la misma memoria — así un agente construye sobre lo que otro escribió, incluso entre proveedores rivales.
• Mantén tu lugar a través de un límite de uso. Alcanza un límite en un modelo, continúa en otro, y apúntalo a donde lo dejaste — el sendero está en la bóveda, no en el contexto de un modelo.
• Capturado mientras trabajas — decisiones, callejones sin salida, llamadas de herramientas y turnos se convierten en nodos buscables, desde el momento en que lo conectas.
• Nada que valga la pena conservar desaparece. Cada turno capturado almacena su texto completo: los resultados de búsqueda son resúmenes — un índice — cairn read <id> imprime cualquier nodo completo, y MCP cairn_read lo obtiene entero con un max_chars elevado.
• Un pase de mantenimiento local que ejecutas — cairn sleep, nocturno por hábito o en tu propio programador (no se programa solo): incrustar → consolidar → podar → reconstruir el grafo → compilar, todo en tu máquina. Una excepción a "sin red": la primera incrustación descarga el modelo de ~80 MB, una vez.
• Un mapa de tu pensamiento — la galaxia del panel (cairn dashboard → http://127.0.0.1:7331), más un Hub / Libro / Índice legible por humanos.
• Relleno — destila conversaciones antiguas en nodos claim nítidos y conectados.

Instalación avanzada

# Linux / WSL: install the CPU-only PyTorch first, or pip pulls a ~4.6 GB CUDA
# stack you don't need. (Want a GPU build? Install your torch first, then run the
# line below — it's preserved.) macOS: skip this line — its default wheel is CPU/MPS.
pip install torch --index-url https://download.pytorch.org/whl/cpu

pip install -e ".[all]"      # package + embedder + dashboard

pip install -e ".[embeddings]"   # no dashboard
pip install -e ".[dashboard]"    # no embedder

python3 -m venv .venv && source .venv/bin/activate && ./install.sh

Múltiples cuentas

¿Un inicio de sesión por IA? Omite esto — funciona solo. Cada IA inicia sesión con su propia cuenta, y Cairn archiva el trabajo de esa IA bajo su propia galaxia automáticamente — Claude y GPT nunca se mezclan, con cero configuración.

Sigue leyendo solo si ejecutas dos cuentas de la misma IA (dos inicios de sesión de Claude, dos inicios de sesión de ChatGPT/Codex — digamos, personal y de empresa). Las galaxias están vinculadas al id estable de cada inicio de sesión y nunca se fusionan — pero con dos inicios de sesión de la misma IA en una máquina, Cairn no siempre puede probar cuál está activo. La regla que lo mantiene limpio:

Declara, no detectes: establece CAIRN_ACCOUNT por cuenta, desde el principio.

# Claude Code — launch each account with its label:
export CAIRN_ACCOUNT=work && claude        # bash/zsh (or set it in that profile)
#   PowerShell: $env:CAIRN_ACCOUNT="work"; claude
# Codex — put it in that account's ~/.codex/config.toml:
#   [mcp_servers.cairn]  env = { CAIRN_ACCOUNT = "work" }
# Importing old history? Always pass the flag:
cairn import <export> --source=claude --account=work

Nómbralas y adminístralas en cualquier momento:

cairn account                          # list galaxies + node counts
cairn account rename <key> "Company"   # display label only — never merges or deletes
cairn account doctor                   # read-only check — prints the exact fix command per mismatch
cairn account fix-session <session-id> <slug>   # re-file ONE named session (backed up, then locked)
cairn account fix-session <slug>                # same, for the current session only

Límites honestos — para que nunca te sorprendas:

• Claude Desktop prueba la cuenta activa por sesión automáticamente. Claude Code CLI y Codex no pueden — siguen el archivo de inicio de sesión actual de la máquina, así que un cambio de cuenta a mitad de camino puede etiquetar sesiones con la cuenta anterior, silenciosamente. CAIRN_ACCOUNT es la garantía; la detección no lo es.
• account doctor verifica lo que es probable (sesiones de Claude Desktop); no puede auditar el historial de solo CLI o Codex.
• Solo añadido aplica aquí también: los renombres cambian solo las etiquetas de visualización; nada se fusiona, nada se elimina.

Qué respaldar

Una carpeta: tu bóveda en ~/.cairn/ (eso es cairn.db — tus recuerdos reales). Haz una copia de seguridad de eso. Todo lo demás es reemplazable — el código vive aquí en GitHub, y reinstalar nunca toca tu bóveda.

Comandos comunes

orient · note · fetch · wander · query · read (cualquier nodo completo) · dashboard · doctor · setup · connect / disconnect / capture · account · backfill · sleep (el ciclo de mantenimiento — tú lo ejecutas) · edges · book · import

Referencia completa con todas las opciones: QUICKSTART.md.

Licencia

Gratis para uso personal y no comercial bajo la Business Source License 1.1 — léela, ejecútala, modifícala, autoalójala. El uso comercial o empresarial requiere una licencia comercial — escribe a licensing@cairnremembers.com. Código fuente disponible (no es "código abierto" según OSI); cada versión se convierte a la Licencia MIT permisiva en la Fecha de Cambio de su LICENSE.

Patente pendiente — una solicitud de patente provisional de EE. UU. que cubre los mecanismos centrales de Cairn se presentó el 2026-07-07. Cairn Remembers™ es una marca comercial de James Wescott Maitland IV.

El conocimiento es un sendero, no un destino.