ai-memory: instala memoria persistente para agentes en Linux

Cambiar de Claude Code a Codex, OpenCode, Cursor o Grok a mitad de tarea normalmente cuesta contexto: hay que volver a explicar la arquitectura, los intentos que fallaron y el siguiente paso. La ai-memory resuelve ese problema con memoria persistente compartida entre agentes. Esta guía instala la versión nativa en Linux, crea un servicio systemd --user, conecta MCP y hooks en los clientes compatibles y muestra dónde se guardan los datos. La versión 2.0 también hizo la memoria más portátil y preparada para uso concurrente.

Qué guarda ai-memory — y qué no

ai-memory es un servidor de memoria a largo plazo para agentes de programación. Los hooks registran eventos de la sesión; el servidor consolida ese material en páginas Markdown y permite recuperar contexto y handoffs mediante MCP. La fuente de verdad es una wiki en archivos .md; SQLite es un índice derivado. Esto hace que la memoria sea inspeccionable, versionable y recuperable sin depender de una base de datos vectorial opaca.

La ruta por defecto no requiere clave de API ni llamadas a un LLM: captura, búsqueda textual y handoff siguen disponibles. En la primera ejecución del servidor, ai-memory descarga el modelo local all-MiniLM-L6-v2 para embeddings; no necesita clave de API. Un LLM es opcional para funciones de consolidación y recuperación. Para desactivar los embeddings locales, defina embedding_provider = "none" en la configuración. Antes de activar hooks, evalúa lo que puede entrar en el historial del proyecto. Para áreas sensibles, usa una política de captura y mantén la instancia solo en el loopback.

Qué cambió en la línea 2.x

El anuncio de la ai-memory 2.0 ayuda a entender por qué este no es solo un gestor de resúmenes. La wiki pasó a usar el Open Knowledge Format (OKF): páginas Markdown con metadatos estandarizados. En otras palabras, la memoria sigue siendo legible fuera del servidor: puedes inspeccionarla, versionarla en Git o llevarla a otra herramienta compatible.

Al migrar una instalación 1.x, la 2.0 crea y verifica una copia de seguridad del directorio de datos antes de cambiar el formato. No descarte esa copia de seguridad hasta revisar la wiki y las consultas después de la actualización. Los embeddings locales siguen siendo la ruta por defecto: no exigen clave de API ni envían el contenido de la memoria a un proveedor externo.

El otro cambio práctico es la concurrencia. Claude Code, Codex, OpenCode y otros harnesses pueden trabajar en el mismo checkout sin compartir un puntero global de “proyecto actual”. Las escrituras pasan por una cola única y las páginas reciben versiones, para que una actualización posterior no borre silenciosamente la anterior. En una instalación compartida, las páginas pueden servir a todo el equipo; los handoffs, en cambio, siguen siendo personales y solo pueden ser aceptados una vez por el dueño de la sesión.

Esto no significa que una conversación ya abierta se interrumpa para recibir una anotación nueva: la verá en la siguiente consulta o en una sesión siguiente. Para equipos, mantén autenticación y HTTPS antes de exponer el servicio fuera de la máquina local.

Requisitos previos y elección de la instalación

El proyecto ofrece binarios Linux para x86_64 e aarch64. La alternativa recomendada por el propio proyecto para instalaciones nativas es mise use -g github:akitaonrails/ai-memory; a continuación usaremos el tarball de la release para dejar versión, checksum, binario y hooks explícitos.

No uses cargo install ai-memory: ese nombre ya pertenece a otro crate en crates.io. Para compilar, usa el workspace del repositorio; para operar normalmente, prefiere un binario de la release v2.1.1.

command -v curl sha256sum tar systemctl
uname -m
mkdir -p ~/.local/bin ~/.config/ai-memory ~/.local/share/ai-memory

Descargando y verificando el binario nativo

Descarga siempre el archivo .sha256 publicado junto al tarball e interrumpe la instalación si la suma no coincide. El bloque siguiente selecciona la arquitectura, usa la release v2.1.1 y preserva los hooks que vienen en el paquete.

set -euo pipefail

VER=2.1.1
case "$(uname -m)" in
  x86_64)  ARQ=ai-memory-linux-x86_64.tar.gz ;;
  aarch64|arm64) ARQ=ai-memory-linux-aarch64.tar.gz ;;
  *) echo "Arquitetura sem binário publicado: $(uname -m)" >&2; exit 1 ;;
esac

BASE="https://github.com/akitaonrails/ai-memory/releases/download/v${VER}"
TMP=$(mktemp -d)
trap 'rm -rf "$TMP"' EXIT

curl -fL "$BASE/$ARQ" -o "$TMP/$ARQ"
curl -fL "$BASE/$ARQ.sha256" -o "$TMP/$ARQ.sha256"
(
  cd "$TMP"
  sha256sum -c "$ARQ.sha256"
  mkdir release
  tar -xzf "$ARQ" -C release
)

install -m 0755 "$TMP/release/ai-memory" "$HOME/.local/bin/ai-memory"
install -d "$HOME/.local/share/ai-memory/release-$VER"
cp -a "$TMP/release/hooks" "$HOME/.local/share/ai-memory/release-$VER/"

export PATH="$HOME/.local/bin:$PATH"
ai-memory --version

Si ai-memory no aparece en una nueva terminal, añade export PATH="$HOME/.local/bin:$PATH" al archivo de inicialización del shell, como ~/.bashrc o ~/.zshrc.

Inicializando la base local

Mantendremos la configuración en ~/.config/ai-memory/config.toml y los datos en ~/.local/share/ai-memory, el estándar esperado en una instalación de usuario en Linux.

ai-memory 
  --data-dir "$HOME/.local/share/ai-memory" 
  --config "$HOME/.config/ai-memory/config.toml" 
  init

Tras el primer uso, la wiki queda en ~/.local/share/ai-memory/wiki/, el índice SQLite en ~/.local/share/ai-memory/db/memory.sqlite y los modelos locales en ~/.local/share/ai-memory/models/. La wiki es la fuente de verdad de las páginas, pero sesiones, observaciones, handoffs y auditoría también viven en la base de datos. Para una copia completa, usa el comando de copia de seguridad del propio ai-memory:

mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"

Levantando el servidor con systemd de usuario

El servidor MCP necesita estar ejecutándose para que los CLIs y los hooks se comuniquen con él. Este servicio de usuario escucha solo en 127.0.0.1:49374: no publiques ese puerto en la red.

cat > ~/.config/systemd/user/ai-memory.service <<'UNIT'
[Unit]
Description=ai-memory local MCP and lifecycle server
After=network.target

[Service]
Type=simple
WorkingDirectory=%h
ExecStart=%h/.local/bin/ai-memory --data-dir %h/.local/share/ai-memory --config %h/.config/ai-memory/config.toml serve --transport http --bind 127.0.0.1:49374
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=default.target
UNIT

systemctl --user daemon-reload
systemctl --user enable --now ai-memory.service
systemctl --user status ai-memory.service --no-pager

En una máquina que debe mantener el servicio activo incluso sin inicio de sesión gráfico, habilita linger una sola vez:

loginctl enable-linger "$USER"

Comprueba el proceso y los registros cuando algo no responda:

systemctl --user is-active ai-memory.service
journalctl --user -u ai-memory.service -n 80 --no-pager
ai-memory status

Usando ChatGPT/Codex como proveedor LLM

Sin proveedor, ai-memory sigue capturando sesiones, buscando en la wiki y creando resúmenes deterministas. Un LLM añade consolidación más rica, lint y mejoras en segundo plano. Para usar la suscripción ChatGPT Plus, Pro o Codex, selecciona openai-oauth: usa el backend ChatGPT/Codex mediante OAuth, no necesita OPENAI_API_KEY y guarda el token renovable en ~/.local/share/ai-memory/auth.json.

Para la consolidación, basta con un modelo económico. El ejemplo fija gpt-5.6-luna con medium: es el punto de partida más equilibrado cuando las sesiones implican decisiones técnicas, intentos fallidos y siguientes pasos. Crea un drop-in de systemd, en lugar de editar la unidad principal:

mkdir -p ~/.config/systemd/user/ai-memory.service.d

cat > ~/.config/systemd/user/ai-memory.service.d/llm-openai-oauth.conf <<'EOF'
[Service]
Environment=AI_MEMORY_LLM_PROVIDER=openai-oauth
Environment=AI_MEMORY_LLM_MODEL=gpt-5.6-luna
Environment=AI_MEMORY_LLM_REASONING_EFFORT=medium
Environment=AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true
EOF

systemctl --user daemon-reload

El último parámetro programa la consolidación con LLM después del cierre de una sesión; la captura y el handoff no se quedan bloqueados esperando la respuesta del modelo. El GPT-5.6 Luna está orientado a cargas de alto volumen y sensibles al coste y acepta none, low, medium, high, xhigh e max. Por lo tanto, none es una configuración válida, pero no es la única opción, ni la mejor elección predeterminada para consolidar sesiones técnicas.

¿Qué esfuerzo elegir para ai-memory?

Empieza con medium si el objetivo es preservar decisiones, causas de fallos y tareas pendientes de una sesión. Tiende a producir una consolidación más útil que un simple resumen, sin elevar tanto el coste y la latencia como los niveles más altos.

Effort	Cuándo usarlo en ai-memory
none	Extracción o resumen muy sencillos, cuando la menor latencia es prioritaria.
low	Buena opción para equilibrar velocidad y calidad en sesiones rutinarias.
medium	Recomendado como punto de partida para la consolidación de sesiones técnicas y handoffs.
high	Prueba solo para sesiones excepcionalmente complejas, si medium está dejando fuera decisiones importantes.
xhigh e max	Raramente necesarios para la consolidación automática; suba solamente tras evaluar la ganancia real de calidad.

En otras palabras: use low cuando quiera privilegiar la velocidad; use medium para el uso diario de proyectos con código, infraestructura y resolución de problemas. Solo suba a high si los handoffs y páginas consolidadas demostradamente siguen siendo superficiales.

Login OAuth y pruebas

Haga el login interactivo en el mismo usuario que ejecuta el servicio. El comando muestra una URL y un código temporal: abra la URL, entre en su cuenta ChatGPT/Codex e introduzca el código. No copie el archivo auth.json, ni pegue tokens en archivos de configuración.

ai-memory auth login openai-oauth

# depois de autorizar no navegador:
systemctl --user restart ai-memory.service
ai-memory auth status
ai-memory llm-test 
  --provider openai-oauth 
  --model gpt-5.6-luna 
  --prompt 'Responda somente: OK'

El test debe devolver OK. Si el login expira o es revocado, repita ai-memory auth login openai-oauth; para cambiar de cuenta, ejecute antes ai-memory auth logout openai-oauth. Consulte la documentación de proveedores de ai-memory para Anthropic, OpenAI por API, Gemini, Copilot y endpoints compatibles con OpenAI.

Registrando MCP y hooks en los agentes

MCP le da al agente herramientas como consulta de memoria y aceptación de handoff. Los hooks hacen la captura automática del ciclo de vida. Ambos son necesarios para la experiencia completa. Los comandos de abajo fusionan las entradas pertenecientes a ai-memory, sin exigir edición manual de los JSON y TOML de los clientes.

Define el directorio de hooks extraído en la instalación y ejecuta la pareja de comandos para cada cliente instalado:

export PATH="$HOME/.local/bin:$PATH"
HOOKS_DIR="$HOME/.local/share/ai-memory/release-2.1.1/hooks"

# Claude Code
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# OpenAI Codex
ai-memory install-mcp --client codex --apply
ai-memory install-hooks --agent codex --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# OpenCode
ai-memory install-mcp --client open-code --apply
ai-memory install-hooks --agent open-code --apply --project-strategy repo-root

# Cursor Agent CLI
ai-memory install-mcp --client cursor --apply
ai-memory install-hooks --agent cursor --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

# Grok Build CLI
ai-memory install-mcp --client grok --apply
ai-memory install-hooks --agent grok --hooks-dir "$HOOKS_DIR" --apply --project-strategy repo-root

Reinicia los clientes después del merge. En Codex, aprueba los hooks cuando el cliente pida confirmación. OpenCode carga los hooks como un plugin TypeScript en ~/.config/opencode/plugins/, por lo que también necesita reiniciarse. En Grok, la salida estándar del evento SessionStart no se inserta en el contexto; al reanudar el trabajo, pide al agente que llame a memory_handoff_accept. En Codex CLI 0.145.0 o más nuevo, el evento SessionEnd entrega el handoff automáticamente. En versiones antiguas — o cuando ese evento no esté disponible — el evento Stop no cierra la sesión: ejecuta ai-memory finalize-session --agent codex al concluir una tarea importante.

Alcance por repositorio y reglas de privacidad

Sin configuración, el proyecto se identifica por el nombre del directorio actual. El parámetro --project-strategy repo-root usado arriba evita que un cd para un subdirectorio cree una memoria separada. Para declarar el ámbito en el propio repositorio, crea .ai-memory.toml en la raíz:

workspace = "pessoal"
project = "site-linuxpro"

[briefing]
inject_on_session_start = "true"
max_chars = 4000

[capture]
ignore_paths = ["private/**", "~/.ssh/**"]

Los valores de workspace e project aceptan letras minúsculas ASCII, dígitos, punto, guion y guion bajo. La sección capture evita registrar eventos conocidos de herramientas de archivo bajo las rutas indicadas; no es una solución DLP completa para comandos del shell o contenido que tú mismo escribas en el prompt. Para máxima precaución, instala los hooks en modo allowlist y coloca el marcador solo en los repositorios que deben capturarse:

ai-memory install-hooks --agent claude-code --hooks-dir "$HOOKS_DIR" --apply --capture-mode allowlist

Consultando la memoria y entregando contexto

Tras trabajar normalmente con el agente, usa el MCP para pedir una búsqueda sobre decisiones, archivos o intentos anteriores. Al terminar, finaliza la sesión cuando sea necesario; el siguiente agente debe aceptar el handoff pendiente en lugar de comenzar desde cero.

# Útil principalmente após uma sessão do Codex:
ai-memory finalize-session

# Diagnóstico e manutenção local
ai-memory status
ai-memory lint

Dentro de Claude, Codex, OpenCode, Cursor Agent CLI o Grok, basta una instrucción sencilla: “busca en la memoria decisiones sobre autenticación de este proyecto” o “acepta el handoff pendiente”. El agente usa las herramientas MCP registradas; no hace falta copiar la wiki a la conversación.

Acceso remoto: no exponga el puerto crudo

El ejemplo de este artículo es local y no usa autenticación porque el bind es exclusivamente de loopback. Para atender a otra máquina, configura token bearer, allowed_hosts y HTTPS mediante un proxy inverso antes de cambiar el bind. La autenticación no cifra el tráfico. El proyecto mantiene una guía de proxy HTTPS con ejemplos para Caddy y Cloudflare Tunnel.

Actualizaciones y recuperación

Para actualizar una instalación por tarball, descarga la nueva release, valida el checksum, sustituye el binario, actualiza el directorio de hooks y reinicia el servicio. Después, ejecuta de nuevo install-hooks --apply para cada agente. Al cruzar la frontera a la línea 2.x, deja que la migración cree y verifique su backup antes de tocar los datos. No borres wiki/ ni db/ durante este proceso.

systemctl --user restart ai-memory.service
systemctl --user status ai-memory.service --no-pager

Si hay algún problema después de una actualización, restaure el archivo generado por ai-memory backup y examínelo journalctl --user -u ai-memory.service. Esta copia de seguridad incluye la wiki y el estado SQLite necesario para conservar también las sesiones, las notas y los handoffs.

Crédito al autor y licencia

El ai-memory es creado y mantenido por Fábio Akita, autor del repositorio akitaonrails/ai-memory. El archivo LICENSE de la release indica “Copyright (c) 2026 Fabio Akita” y pone el proyecto a disposición bajo la licencia MIT. Gracias a Fábio por ofrecer una alternativa abierta, local e interoperable para la memoria de los agentes.

Con el servicio local, MCP y hooks instalados, puedes cambiar de agente sin abandonar el historial técnico del proyecto. Para comparar otras opciones, consulta también las alternativas a Claude-Mem en Go, Rust y C y el artículo sobre memoria persistente para agentes en Linux.