ai-memory: Memoria de Largo Plazo para CLIs de Código

Cada CLI de código que usás tiene amnesia por diseño. Le explicás tu arquitectura a Claude Code el lunes, cambiás a Codex el martes y arrancás de cero — re-explicando los enfoques que fallaron, las preguntas abiertas y dónde habías quedado. Cada agente guarda sus propias notas, en su propia máquina, invisibles para todo lo demás.

En esta guía te muestro qué es ai-memory y por qué más de 6.000 desarrolladores le dieron estrella en menos de cuatro meses, cómo funciona su pipeline de captura → consolidación → recuerdo → handoff en 4 pasos, el quickstart verificado que podés correr hoy con Docker o cargo y — igual de importante — cuándo NO deberías usarlo.

1. Qué es ai-memory: Stars, Licencia y la Idea

ai-memory es una capa de memoria de largo plazo open-source en Rust para CLIs de código con IA, creada por Fabio Akita (akitaonrails) en mayo de 2026 — construida en colaboración con Claude Code, según el README. Su tagline lo dice todo: cerrá Claude Code a mitad de tarea, abrí OpenAI Codex en el mismo directorio y seguí sin re-explicar la arquitectura, los enfoques fallidos ni las preguntas abiertas. Al 12 de septiembre de 2026 el repositorio en github.com/akitaonrails/ai-memory ronda las 6.600+ estrellas y 450+ forks bajo licencia MIT — uno de los repos de infraestructura de agentes de más rápido crecimiento del año.

Datos del Repo (verificados Sep 2026)

Repositorio: github.com/akitaonrails/ai-memory
Estrellas: ~6.600+ (verificá el conteo vivo en GitHub)
Licencia: MIT — uso comercial permitido
Stack: Un binario Rust (servidor MCP/HTTP con axum) + SQLite + wiki Markdown
Agentes: 20+ harnesses: Claude Code, Codex, OpenCode, Cursor, Gemini CLI y más

La apuesta central es simple y con eco de Karpathy: la memoria del agente es texto. El texto vive en disco como una wiki Markdown versionada con git — la podés buscar con grep, abrir en Obsidian, editar a mano. SQLite es un índice derivado que siempre se puede reconstruir desde los archivos. Y el camino por defecto usa cero llamadas al LLM: captura, búsqueda y handoffs funcionan sin ninguna API key.

Por qué importa en 2026

Cada plataforma suma su propia memoria, pero todas comparten las mismas paredes: las notas viven en una máquina, pertenecen a un agente y desaparecen en cuanto cambiás de herramienta — o de compañero. ai-memory pone una memoria compartida debajo de 20+ harnesses, en tu laptop o un homelab, así el proyecto que dejaste en la desktop es el que retomás en la laptop.

2. Arquitectura en 4 Pasos: Del Keystroke al Handoff

El README y docs/ARCHITECTURE.md describen el flujo como captura → consolidación → recuerdo → handoff. Acá va, paso a paso, tal como lo documenta el proyecto:

📥

Paso 1 — los hooks capturan en silencio

Los hooks de ciclo de vida (shell hooks para Claude Code y Codex, plugin TypeScript para OpenCode, config JSON para Cursor y Gemini CLI) hacen POST de observaciones sanitizadas — prompts, tool calls, límites de sesión — con fire-and-forget al servidor HTTP local en 127.0.0.1:49374. El agente nunca espera; si ai-memory está caído, la sesión sigue normal, solo sin captura.

📝

Paso 2 — las sesiones se consolidan en páginas wiki

Al cerrar la sesión, las observaciones se compilan en páginas Markdown coherentes en la wiki del proyecto (opcionalmente escritas por LLM, útiles igual sin él). La wiki es la fuente de verdad: wiki/ guarda las páginas, raw/ los segmentos inmutables de transcripts sanitizados, db/ los índices SQLite, y un único writer de SQLite serializa todas las escrituras (techo medido de ~700/s, no adivinado).

🔍

Paso 3 — el recuerdo fusiona cinco señales

La recuperación combina full-text FTS5, entity-match y RRF de vecinos del grafo, RRF vectorial opcional cuando hay un embedder configurado, ajuste acotado de autoridad de fuente y fallback acotado a observaciones crudas. La próxima sesión — cualquier agente, cualquier máquina — recibe un brief acotado y puede buscar todo, con explain: true mostrando por qué cada hit rankeó donde rankeó.

🔀

Paso 4 — los handoffs son protocolo, no convención

Los handoffs entre agentes llevan el testimonio explícitamente: tipados, con dueño, reclamados exactamente una vez. El launcher gerenciado opcional (ai-memory run claude, después ai-memory run codex --yolo) suma resume nativo de sesión más historial portable visible sobre la memoria compartida, así una sesión local obsoleta jamás puede pisar historial más nuevo de otro harness.

Notas de diseño que vale conocer

Un servidor es dueño de un data directory — nunca dos. El conocimiento se comparte por proyecto mientras los handoffs personales siguen personales, con auth multi-usuario, atribución por persona y audit log de cada mutación incluidos, no como tier pago. Los comandos de purga documentan exactamente qué significa “borrado”, y los comandos de instalación son idempotentes con backups timestamped junto a cada archivo que tocan.

3. Quickstart: Memoria Compartida en 10 Minutos (Verificado)

Todos los comandos de abajo salen directo del README vivo y de docs/install.md — verifiqué cada uno contra el repo el 12 de septiembre de 2026. Docker es el camino recomendado; cargo desde fuente y paquetes AUR son alternativas documentadas. Omití las líneas del LLM para modo cero-LLM — la búsqueda FTS5 funciona igual sin keys.

# Opción A — compilar desde fuente con cargo (workspace, toolchain pineado en rust-toolchain.toml)
git clone https://github.com/akitaonrails/ai-memory.git
cd ai-memory
cargo build --release
./target/release/ai-memory --version

# Opción B — Arch Linux (AUR)
yay -S ai-memory-bin    # binario precompilado Linux x86_64/aarch64
yay -S ai-memory        # compila desde fuente

# Opción C (recomendada) — Docker: instalá el wrapper CLI y levantá el servidor
mkdir -p ~/.local/bin
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

docker run -d --name ai-memory \
  --restart unless-stopped \
  -p 127.0.0.1:49374:49374 \
  -v ai-memory-data:/data \
  -e AI_MEMORY_LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  docker.io/akitaonrails/ai-memory:latest

# Conectá tu CLI de agente en dos comandos (repetí con --agent codex, opencode, gemini-cli…)
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

# Comandos de todos los días
ai-memory status        # salud del servidor
ai-memory search "auth refactor"   # búsqueda FTS5 rápida solo-terminal
ai-memory bootstrap     # adoptar un proyecto existente con meses de historia

# Workstreams gerenciados opcionales: resume nativo + historial portable entre vendors
cd /path/to/project
ai-memory run claude            # empezá acá…
ai-memory run codex --yolo      # …cerrá Claude, seguí en Codex, nada que re-explicar
ai-memory continue              # retomar el checkout gerenciado más nuevo
ai-memory uninstall --apply     # borra todo lo que instaló, solo lo que instaló

Eso es todo en Linux y macOS: abrí una sesión de Claude Code como siempre y cada prompt y tool call cae en ai-memory. Abrí Codex en el mismo directorio después y el próximo agente levanta un handoff real — dónde quedaste, qué falló, qué sigue abierto. En macOS el binario nativo es lo recomendado cuando no necesitás Docker (ver docs/macos.md); Windows corre vía WSL2, con Windows nativo todavía experimental.

Tip: mantené loopback primero

El quickstart por defecto escucha en 127.0.0.1:49374 sin auth — nada fuera de tu máquina puede alcanzarlo, que es exactamente lo que querés en una laptop personal. Solo agregá un bearer token (y TLS con los templates de Caddy/Cloudflare Tunnel en docs/https-via-proxy.md) cuando muevas el servidor a la LAN o a un homelab para equipos y varias máquinas.

4. Casos de Uso: Dónde ai-memory Realmente Rinde

La memoria compartida no es un feature — es la diferencia entre reiniciar cada conversación y acumular conocimiento. Estos son los escenarios que el proyecto documenta en docs/use-cases.md, y mapean directo al trabajo diario con CLIs:

🔀

Handoff entre vendors a mitad de tarea

Cerrá Claude Code, seguí el mismo workstream en Codex, Command Code u OpenCode. El próximo harness recibe handoffs pendientes más historial buscable — nunca más pegar contexto entre vendors.

💻

Continuidad desktop-to-laptop

Corré el servidor en un homelab y apuntá cada máquina hacia él. El proyecto que dejaste en la desktop es el que retomás en la laptop: mismo conocimiento, mismas preguntas abiertas.

👥

Memoria de proyecto compartida en equipo

Apuntá a todo el equipo a un servidor y lo que aprenden las sesiones de una persona lo pueden recuperar los agentes de todos — sharing por proyecto, atribución por persona y audit log completo incluidos.

🕰️

“¿Qué decidimos hace seis semanas?”

La consolidación de fin de sesión convierte transcripts crudos en páginas de decisiones coherentes. Preguntale al agente o corré ai-memory search desde la terminal en lugar de escarbar sesiones muertas.

El patrón común a los cuatro: proyectos de larga vida + sesiones repetidas + conocimiento que debe sobrevivir cambios de herramienta. Si tocás el mismo repo con más de un CLI — o más de una máquina — un servidor de memoria compartida se paga solo la primera vez que te ahorrás el re-briefing.

5. Cuándo NO Usar ai-memory: Límites Honestos

Me gusta ai-memory, pero un servidor de memoria es infraestructura — tiene instalación, un proceso que mantener vivo y un data directory que backupear. Esta es mi checklist honesta:

❌ Mejor otra cosa cuando

• Usás un solo agente en una sola máquina y nunca cambiás — el resume nativo de sesión o las notas propias del agente son más simples con cero partes móviles.
• Necesitás respuestas citadas sobre tus propios documentos — eso es trabajo de RAG; usá una base vectorial más citas, no memoria de sesiones de agente.
• No podés correr un proceso siempre encendido más — el servidor (Docker o systemd) tiene que estar levantado para capturar; si no, las sesiones silenciosamente no registran nada.
• Windows nativo sin WSL2 — todavía experimental, con caveats de hooks/MCP documentados en docs/windows.md.
• Inputs regulados o adversariales sin boundary de confianza — cualquiera que hable con el agente puede generar observaciones; configurá reglas [capture] por repo (excluir paths o modo allowlist) antes de producción.

✅ ai-memory encaja genial cuando

• Alternás entre Claude Code, Codex, OpenCode o Cursor en los mismos proyectos.
• Trabajás desde varias máquinas o con un equipo compartiendo un servidor.
• Querés la memoria como Markdown plano en disco — grepeable, versionado con git, reconstruible — no un blob binario.
• Querés captura cero-LLM con upgrades opcionales a LLM (resúmenes, embeddings) después.

Regla de oro

La memoria es infraestructura, no un plugin. Si no podés responder “dónde corre el servidor, quién puede alcanzarlo y cómo backupeo y purgo el data directory”, todavía no estás listo para una capa de memoria — primero resolvé el ciclo de vida del servidor (docs/deploy.md, docs/lifecycle-ops.md), después conectá los agentes.

Conclusión

ai-memory se gana honestamente sus 6.600+ estrellas: convierte la parte más difícil del trabajo multi-CLI — memoria persistente, compartida e independiente del vendor — en un binario Rust con ingeniería seria detrás. El modelo Markdown-en-disco, la captura silenciosa por hooks y los handoffs-como-protocolo lo hacen el default que elijo cuando los agentes de código necesitan recordar entre vendors.

Empezá con Docker en loopback, conectá un CLI y probá el handoff (cerrá un agente a mitad de tarea, retomá en otro) antes de escalarlo al equipo. Si alguna vez le re-explicaste tu arquitectura a un segundo CLI en la misma semana, ai-memory se paga solo en días.

ai-memory: Memoria de Largo Plazo para tus CLIs de Código