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, vincula MCP y hooks en los clientes soportados y muestra dónde residen los datos. El siguiente guion está actualizado para la versión 2.6.3.
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 observaciones saneadas y limitadas de prompts y herramientas — no una transcripción completa. El servidor produce resúmenes y puede consolidar el material en páginas Markdown; la consulta y los handoffs están disponibles por MCP. La wiki en archivos .md es la fuente de verdad de las páginas. SQLite mantiene índices derivados y también estado operativo, como sesiones, observaciones y handoffs. 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.
Qué cambia para quien instala 2.6.3
La serie 2.6 añadió perfil de preferencias entre proyectos, copia de seguridad de la configuración de los agentes, controles de handoff y el exportador opcional ai-memory-wikisync. Los parches siguientes corrigieron problemas de captura, privacidad y enrutamiento. Para este tutorial, estos son los puntos prácticos:
- Alcance MCP explícito: en clientes estáticos, informe
workspaceeproject; no asuma que los hooks también identifican la sesión en las llamadas MCP. - Reaplicar los hooks: las integraciones TypeScript generadas recibieron correcciones de retención de eventos cuando el servidor responde con fallos temporales.
- Revise el perfil antiguo: las correcciones en la identificación de preferencias no eliminan automáticamente entradas ya admitidas.
- Servidor y clientes son procesos distintos: sustituir el binario no reinicia el servicio ni recarga plugins de agentes ya abiertos.
Consulte el changelog fijado en 2.6.3. El ai-memory-wikisync es una exportación unidireccional de familias de páginas permitidas; no es sincronización bidireccional y no es necesario para esta instalación.
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.6.3. En Fedora, la release también publica RPMs para x86_64 e aarch64, instalables con sudo dnf install ./ai-memory-2.6.3-1.<arq>.rpm; el paquete trae los archivos de servicio systemd del proyecto. Esta guía continúa con el tarball Linux; consulta la arquitectura soportada y valida el ejecutable en tu distribución.
command -v curl sha256sum tar systemctl
uname -m
mkdir -p ~/.local/bin ~/.config/ai-memory ~/.local/share/ai-memory ~/.config/systemd/userDescargando y verificando el binario nativo
Descarga siempre el archivo .sha256 publicado junto al tarball e interrumpa la instalación si la suma no coincide. El bloque siguiente selecciona la arquitectura, utiliza la release v2.6.3 y preserva los hooks que vienen en el paquete.
set -euo pipefail
VER=2.6.3
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.new"
mv -f "$HOME/.local/bin/ai-memory.new" "$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 --versionSi 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" \
initTras 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 las sesiones, observaciones, handoffs y auditoría también viven en la base de datos. Para una copia completa, use la copia de seguridad del propio ai-memory después de iniciar el servidor, como se muestra en la siguiente sección.
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 --enable-web
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-pagerEn 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 statusCon el servidor activo, cree una copia de seguridad completa de la memoria. Este comando depende de la API del servicio; no funciona antes de iniciarlo:
mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M).tar.gz"LLM opcional: configúrelo y pruébelo por separado
La captura, búsqueda textual y handoff no dependen de una LLM generativa. La consolidación con proveedor externo envía contenido seleccionado fuera de la máquina: evalúe privacidad, disponibilidad y límites antes de habilitarla.
El proveedor openai-oauth del ai-memory usa inicio de sesión propio y almacena el token en <data_dir>/auth.json. No es lo mismo que codex, que reutiliza el acceso administrado por el Codex CLI. La documentación de la release indica gpt-5.5 como estándar de openai-oauth; la disponibilidad depende de la cuenta y del servicio. No confunda este ejemplo con la configuración histórica de este laboratorio, que utilizaba gpt-6-luna con effort high.
ai-memory auth login openai-oauth
ai-memory auth status
ai-memory llm-test \
--provider openai-oauth \
--model gpt-5.5 \
--prompt 'Responda somente: OK'Inicie sesión con el mismo usuario y directorio de datos del servicio. No publique tokens ni el archivo auth.json. Solo continúe si la prueba funciona con su cuenta. Después, para una instalación nueva, cree el drop-in:
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.5
Environment=AI_MEMORY_CONSOLIDATE_ON_SESSION_END=true
EOF
systemctl --user daemon-reload
systemctl --user restart ai-memory.service
ai-memory statusEn un servicio ya configurado, edite el drop-in existente en lugar de sobrescribirlo. Las variables de systemd no se exportan a su terminal. Si elige otro modelo o AI_MEMORY_LLM_REASONING_EFFORT, valide la combinación con llm-test; más razonamiento no garantiza una mejor consolidación. La prueba de esta revisión verificó el binario y los comandos, no rehízo la autenticación ni una llamada de pago al proveedor.
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.6.3/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-rootReinicia 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 ser reiniciado. En Grok, la salida estándar de SessionStart sigue descartándose; desde la 2.5.0, el handoff pendiente se entrega como contexto en el primer uso de herramienta de la sesión. Si la sesión no llama a ninguna herramienta, pida al agente que llame a memory_handoff_accept. En Codex CLI 0.145.0 o más nuevo, el evento SessionEnd finaliza la sesión y, si la creación automática está habilitada, crea el handoff para la siguiente sesión. En versiones antiguas, o cuando ese evento no esté disponible, el evento Stop no cierra la sesión: ejecute ai-memory finalize-session --agent codex al concluir una tarea importante.
Alcance por repositorio y reglas de privacidad
Sin configuración, a partir de la 2.5.0 el proyecto de un checkout con remoto Git se identifica por el repositorio (remoto upstream, si no origin), no por el nombre de la carpeta: dos clones del mismo repositorio en carpetas distintas caen en el mismo proyecto, y dos repositorios distintos con la misma carpeta no se mezclan. Los proyectos existentes compatibles pueden reutilizarse. En la línea 2.6, los clientes actuales envían por defecto identity_style = "path": el nombre deriva de la ruta completa del remote, sin el host. Una captura o escritura autorizada puede promover un nombre compatible, preservando el UUID; las consultas no renombran proyectos y las ambigüedades se rechazan. Comprueba el resultado con ai-memory doctor e ai-memory list-projects. Sin remote, se usa el nombre del directorio. 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. Un project declarado en el marcador sigue teniendo prioridad sobre el remoto Git. 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 allowlistLos hooks no garantizan el alcance en las llamadas MCP
Un cliente solo es session-aware cuando reenvía el ID real de la sesión de lifecycle en cada llamada MCP. Tener hooks instalados, por sí solo, no lo hace. En el cliente estático, el agente debe leer los nombres exactos del .ai-memory.toml y pasar los dos argumentos en cada operación de proyecto:
{"workspace": "pessoal", "project": "site-linuxpro"}Estos nombres son solo los del ejemplo anterior. No deduzca el alcance por el nombre de la carpeta ni por el último proyecto activo del servidor. En la 2.6.3, memory_message_send, memory_message_pop e memory_message_cancel rechazan alcance inferido sin vínculo a la sesión; memory_message_list informa cómo se resolvió el alcance. El rechazo evita actuar en la caja de otro proyecto.
Para Claude Code, existe el puente opcional ai-memory install-mcp --client claude-code --session-aware --apply. Comprueba su funcionamiento antes de depender de la selección automática. Para consultas globales, usa global=true sin mezclarlo con workspace, project o scopes.
Perfil compartido: comprueba lo que cruza entre proyectos
Desde la 2.6.0, el perfil puede aprender preferencias a partir de sus solicitudes y de páginas seleccionadas. No confunda este recurso con aislamiento absoluto entre proyectos: en una instalación de un único operador, comparte patrones de trabajo entre espacios de trabajo. Inspeccione el contenido antes de adoptarlo en trabajos de clientes:
ai-memory profile status
ai-memory profile list
ai-memory profile reviewPara impedir que un proyecto contribuya o reciba ese perfil, añade a su .ai-memory.toml, sin borrar las configuraciones existentes:
[profile]
contribute = false
consume = falseAl actualizar desde la 2.6.0: profile rebuild relee la base, pero no elimina entradas antiguas ni reclasifica a todos los candidatos ya registrados. Revise las evidencias con profile review y elimine individualmente una preferencia incorrecta con ai-memory profile forget CAMINHO_DA_ENTRADA, utilizando la ruta mostrada en el listado. No ejecute eliminaciones masivas sin revisar. La memoria recuperada nunca autoriza comandos ni sustituye sus instrucciones actuales.
Estas opciones controlan el perfil; no desactivan los hooks ni sustituyen [capture]. Consulte la documentación do perfil para revisar, eliminar preferencias y configurar el comportamiento del servidor.
Handoff sin consumo automático
Si abrir una sesión no debe consumir el contexto reservado para otra tarea, ajuste la siguiente sección en el archivo de configuración que utiliza el servidor. Conserve el resto de secciones y reinicie el servicio:
[handoff]
claim_on_session_start = false
create_on_session_end = falseCon la primera opción, la apertura muestra un aviso con el ID del handoff, sin reclamarlo. El agente puede listar los pendientes con memory_handoff_list y aceptar el elegido por ID. La segunda desactiva la creación automática al cerrar sesiones no gestionadas; los resúmenes y la consolidación continúan. Los handoffs explícitos y las ejecuciones gestionadas no se desactivan. Ambas son opciones globales del servidor y se mantienen true por defecto.
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 doctor
ai-memory lintDentro 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
Antes de sustituir el ejecutable, haga una copia de seguridad. La instalación manual anterior también sirve para actualizar; no es necesario recrear la base, el servicio ni las credenciales.
mkdir -p "$HOME/backups/ai-memory"
ai-memory backup --to "$HOME/backups/ai-memory/ai-memory-$(date +%Y%m%d-%H%M%S).tar.gz"Saliendo de 2.4.x o 2.5.x: prefiera el bloque manual de esta guía, con VER=2.6.3. La 2.4.x no tenía upgrade; el actualizador de la 2.5.x podía rechazar archivos auxiliares del paquete oficial. La corrección de este segundo problema llegó en la 2.6.0 — no está en el binario antiguo que intenta actualizar.
Instalación nativa por release, ya en la 2.6.0 o posterior: use el actualizador con versión explícita. Las instalaciones AUR, RPM, Homebrew u otros gestores deben seguir el método de actualización correspondiente, no este comando.
ai-memory upgrade --version 2.6.3
systemctl --user restart ai-memory.service
systemctl --user is-active ai-memory.service
ai-memory --version
ai-memory statusLa CLI y el servidor deben indicar la versión esperada. Si el servicio aún se está iniciando, consulte journalctl --user -u ai-memory.service -n 80 --no-pager y repita la consulta. La actualización vuelve a aplicar los hooks registrados, pero los clientes abiertos deben reiniciarse.
En la actualización manual, vuelva a aplicar los hooks usando los archivos de la nueva release. Hágalo solo para los agentes que utiliza. Las integraciones generadas, como OpenCode, también deben regenerarse para recibir las correcciones de entrega de la 2.6.3:
HOOKS_DIR="$HOME/.local/share/ai-memory/release-2.6.3/hooks"
# Exemplo após download manual:
ai-memory install-hooks --agent codex --hooks-dir "$HOOKS_DIR" --apply
# Se utiliza OpenCode:
# ai-memory install-hooks --agent open-code --apply
# Na raiz de cada projeto, renove instruções e skills gerenciadas:
ai-memory install-instructions --target AGENTS.md --skills-agent agents
# Claude Code: --target CLAUDE.md --skills-agent claude-code
systemctl --user restart ai-memory.service
ai-memory doctorEl instalador de instrucciones preserva el texto fuera del bloque gestionado. Reaplicar hooks sin --project-strategy mantiene la estrategia ya registrada. Reinicie los clientes MCP, abra una sesión de prueba y compruebe que la captura y la consulta usen el proyecto correcto. No basta con verificar solo ai-memory --version.
Validación de esta revisión: en 10/10/2026, el tarball Linux x86_64 de 2.6.3 pasó el sha256sum -c y el ejecutable extraído informó ai-memory 2.6.3. La sintaxis de los principales subcomandos fue verificada por el --help. No hubo actualización del servicio de esta estación ni prueba de extremo a extremo de todos los clientes en esta revisión editorial.
La copia de seguridad de la memoria no es la copia de seguridad de los agentes
ai-memory backup preserva la wiki y el estado de SQLite, incluyendo sesiones, observaciones y handoffs. El siguiente comando cubre otro conjunto: configuraciones, skills, plugins e instrucciones de los agentes. Consulta primero el plan y luego genera el archivo:
ai-memory backup-agents --dry-run --to "$HOME/backups/ai-memory/agentes.tar.gz"
ai-memory backup-agents --to "$HOME/backups/ai-memory/agentes-$(date +%Y%m%d-%H%M%S).tar.gz"El saneado por defecto cubre texto de configuración MCP, no todo el archivo: el resto de contenidos se copian íntegros y pueden contener secretos. Protege el archivo y no lo publiques en Git. Antes de recuperar datos, consulta ai-memory restore --help o ai-memory restore-agents --help, según el tipo de copia de seguridad. En migraciones, guarda también la versión anterior del binario; no intentes hacer downgrade contra una base de datos ya migrada sin un plan de restauración.
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.