Un skill para Claude Code y Codex · v0.4.0
Tu agente olvida. Su memoria no tiene por qué.
Long-Term Memory for AI les da a los agentes de programación una memoria persistente que vive en un archivo SQLite local dentro de cada proyecto. Una ventana nueva, sin ningún contexto, arranca desde lo que se decidió, lo que está pendiente y lo que pasó, en lugar de reconstruirlo de conversaciones viejas o de notas sueltas.
El problema
Los agentes son buenos dentro de una conversación y olvidadizos entre una y otra.
Cada chat empieza en blanco
Las decisiones de ayer, sus razones y las preguntas abiertas desaparecen al abrir una ventana nueva.
Compactar pierde detalle
Las sesiones largas se resumen; las palabras exactas, las fechas y quién dijo qué son lo primero que se pierde.
Las notas en Markdown se desvían
Los archivos de notas crecen, se contradicen y no pueden responder "cuántos", "desde cuándo" ni "qué cambió".
Nadie puede auditarlo
Cuando un agente "recuerda" algo mal, no hay fuente, ni autor, ni historia que revisar.
Cómo funciona
Tres piezas: un skill que le enseña el protocolo al agente, un helper
(memory.py) que es la única entrada y salida, y un archivo SQLite por proyecto en
.memory/.
Empieza la sesión
Un hook inyecta el resumen: dueño, proyecto, decisiones vigentes, convenciones, preguntas abiertas, lecciones, pendientes y lo más reciente.
Trabajas como siempre
Le hablas al agente en tu idioma. Cuando necesita historia, consulta la memoria en lugar de adivinar.
El agente registra
Decisiones, respuestas, lecciones, hechos y eventos entran por el helper, con tus palabras literales como evidencia y el actor detrás.
Siguiente sesión, cualquier agente
Claude Code o Codex, hoy o dentro de un año, parten de la misma memoria, con todos los estados anteriores todavía legibles.
Un modelo genérico, sin tablas de dominio
Todo se guarda como entidades (una persona, un módulo, un caso, un capítulo), hechos en el tiempo (válidos desde, válidos hasta), eventos (una decisión, una entrega, una sesión de trabajo) con atributos y enlaces, y observaciones (lecturas de sensores o sistemas). La misma estructura se ha probado con un proyecto de software, una ventanilla de trámites cuyos procesos cambian en plena operación, un hotel, venta de lotes, una cadena de suministro y un autor que revisa cinco libros.
Nada se pierde
La memoria es sólo de agregado (append-only), y la base lo hace cumplir con triggers. Un hecho equivocado se retracta con su motivo, uno que terminó se cierra, un evento erróneo se anula, lo que cambia de nombre conserva el anterior y lo retirado conserva su historia. Puedes preguntar cómo estaba la memoria en cualquier fecha pasada.
Qué recuerda
| Tipo | Ejemplo |
|---|---|
| Decisiones y sus razones | "Una base por proyecto — porque las memorias nunca deben mezclarse entre proyectos." |
| Convenciones y preferencias | "Lo interno en inglés; responder en el idioma de la persona." |
| Preguntas abiertas y respuestas | Una pregunta de marzo y la respuesta que la cerró en mayo. |
| Lecciones | "Correr las pruebas con un intérprete limpio: el de siempre ocultaba un error de portabilidad." |
| Personas, roles y actores | Quién es dueño de qué, quién tiene un rol desde cuándo, qué sistema o sensor produjo un registro. |
| Pendientes y solicitudes | Una revisión esperando a la editora; un comentario esperando al autor hasta que se resuelva. |
| Hechos en el tiempo | Un estado, un responsable, un precio — cada uno con cuándo empezó y terminó. |
| Procesos y documentos | Flujos versionados con roles y excepciones; textos versionados párrafo por párrafo. |
Cómo ayuda
Arranques en frío que funcionan
Una ventana nueva responde "¿qué decidimos sobre X y por qué?" con registros guardados, no con una suposición.
Respuestas con respaldo
Cada registro lleva su texto fuente y su actor. El agente separa lo recuperado, las ausencias y sus propias inferencias.
Preguntas sin SQL
Totales, rankings y listados (aggregate, list), estados derivados, recetas guardadas, búsqueda recall y --as-of para cualquier fecha pasada.
Una memoria, dos agentes
Claude Code y Codex leen y escriben el mismo archivo con el mismo helper.
Privada por diseño
Un archivo local, excluido de Git, sin red, sin servicio, sin cuenta. Nada en qué registrarse.
Actualizaciones seguras
Los cambios de esquema llegan como migraciones: las aditivas se aplican al abrir, las transformadoras respaldan primero, y todo cambio queda registrado.
El agente no decide por ti
Decisiones, convenciones, retracciones y anulaciones deben venir de una persona. Lo que el agente nota por su cuenta queda marcado como observación suya.
Probada a escala
Probada con ~358,000 eventos, 1 millón de enlaces y 1.3 millones de atributos en una memoria de 1.5 GB: consultas selectivas de 70 a 190 ms y agregaciones completas en unos 3 s.
Limitaciones
La versión 0.4.0 ya es útil, y éstos son sus límites, dichos con honestidad.
Una máquina, un proyecto
La memoria es un archivo local. No hay sincronización, ni servidor, ni forma de compartirla entre compañeros o computadoras. No llega a claude.ai en el navegador.
Vale lo que se registra
El agente decide qué guardar siguiendo el skill. Puede omitir cosas o registrarlas imperfectamente; la evidencia y la historia lo hacen visible y corregible, no imposible.
Nada se puede borrar
Al ser sólo de agregado, un dato sensible no se puede eliminar con el helper; sólo corregir o retractar. No guardes secretos ni datos que podrían obligarte a borrar.
No está cifrada
Quien pueda leer la carpeta del proyecto puede leer el archivo de memoria. Protégelo como el resto de tu código.
Búsqueda por palabras, no semántica
recall usa la búsqueda de texto completo de SQLite (con singular y plural), no embeddings. Los sinónimos sólo aparecen si las palabras están.
Consume algo de contexto
El resumen se inyecta al iniciar cada sesión: los 8 elementos más recientes por sección, normalmente unos pocos miles de tokens. Los tipos de evento de alto volumen (importaciones, lecturas) se resumen en una línea por tipo. Cada mensaje suma un recordatorio de una línea.
Pensada para pocos escritores
SQLite soporta que unos cuantos agentes escriban a la vez (se esperan entre sí). No es un servidor de base de datos multiusuario.
Versión temprana
Los comandos y el esquema todavía pueden cambiar. Las actualizaciones migran las memorias existentes, y una memoria más nueva abierta por un helper más viejo queda en sólo lectura en lugar de dañarse.
Qué implica agregar el skill
Antes de instalarlo, esto es exactamente lo que cambia en tu máquina y en tus proyectos.
| Qué | Dónde | Detalle |
|---|---|---|
| El skill | ~/.claude/skills/project-memory/ o ~/.codex/skills/… | SKILL.md y scripts/ (helper, paquete, migraciones). Lo copia el instalador; reinstala para actualizar. |
| La memoria | <proyecto>/.memory/memory.sqlite | Se crea en el primer chat, después de que das tu nombre y tu clave. Trae su propio .gitignore. |
| Respaldos | .memory/backups/ o la carpeta que elijas | Los hace backup y también se hacen antes de migraciones transformadoras. Guardarlos en otro lugar te toca a ti. |
| Hooks (Claude Code) | <proyecto>/.claude/settings.json | Al iniciar la sesión corre brief; con cada mensaje, reminder. Ambos siempre terminan bien y nunca bloquean. |
| Instrucciones | CLAUDE.md o AGENTS.md | Un párrafo que le pide al agente leer primero la memoria y no usar archivos Markdown como memoria. |
| Comandos que corre el agente | Tu terminal | python …/memory.py <comando>. Tu agente puede pedir permiso cada vez; puedes autorizar el comando del helper en su configuración. |
| Red | Ninguna | El helper no hace llamadas de red. Lee y escribe un archivo. |
Tu parte
- Darle al agente tu nombre y una clave una vez (nunca los inventa).
- Decir cuándo algo es una decisión, y por qué. El agente la registra como tuya.
- Respaldar la memoria de vez en cuando (
backup); el resumen muestra la fecha del último respaldo. - Reinstalar el skill cuando actualices el repositorio.
Quitarlo
- Borra la carpeta del skill, los hooks y el párrafo de
CLAUDE.md/AGENTS.md. - El archivo de memoria se queda en
.memory/. Es tuyo: una base SQLite común que cualquier herramienta puede leer.
Empezar
Requisitos: Python 3.9+ disponible como python y SQLite con FTS5 (incluido en las
distribuciones habituales). En Windows, las zonas horarias con nombre requieren pip install tzdata; sin él,
la zona del sistema sigue funcionando.
1 · Instala el skill (una vez por máquina)
git clone https://github.com/howware/long-term-memory-for-AI
cd long-term-memory-for-AI
python tools/install_skill.py --target ~/.claude/skills/project-memory
python tools/install_skill.py --target ~/.codex/skills/project-memory2 · Indícale al proyecto que lo use
Agrega al CLAUDE.md o AGENTS.md del proyecto (puede ir en español; lo guardado seguirá en inglés):
## Memoria persistente
Este proyecto usa el skill `project-memory`. Al iniciar cada conversación,
ejecuta `brief` y sigue el arranque en frío antes de responder. La memoria
SQLite es la fuente de verdad; no reconstruyas desde el historial del chat lo
que puede consultarse ahí, y no uses archivos Markdown como memoria.3 · Agrega los hooks (Claude Code)
En <proyecto>/.claude/settings.json, combinado con lo que ya tenga:
{
"hooks": {
"SessionStart": [{
"matcher": "startup|resume|clear|compact",
"hooks": [{"type": "command", "timeout": 30,
"command": "python ~/.claude/skills/project-memory/scripts/memory.py brief --format hook"}]
}],
"UserPromptSubmit": [{
"hooks": [{"type": "command", "timeout": 10,
"command": "python ~/.claude/skills/project-memory/scripts/memory.py reminder"}]
}]
}
}4 · Abre un chat nuevo
El agente nota que todavía no hay memoria, te pide tu nombre y una clave como person:ana, y la crea.
Desde ahí, cada chat empieza con el resumen.
Cómo se ve
[project memory] Start-of-session brief: - Memory owner: Ana (person:ana) - Project: Billing service — invoices for the EU subsidiaries Decisions and agreements in force (3): · [decision:rounding] 2026-05-12 Round per line, not per invoice — why: the tax office checks line totals. Open questions (1): · [question:currency] 2026-06-02 Do credit notes keep the original exchange rate? Pending actions: 1 Last backup: 2026-06-20 tú › ¿por qué redondeamos por renglón? agente › Por decision:rounding (12 de mayo, de Ana): la autoridad fiscal revisa los totales por renglón. Sigue vigente; nada la ha reemplazado. tú › las notas de crédito conservan el tipo de cambio original. Recuérdalo. agente › Registrado como tu respuesta a question:currency, con tus palabras como evidencia. La pregunta quedó cerrada.
Preguntas frecuentes
¿Algún dato sale de mi computadora?
No. El helper no tiene código de red. El agente sigue enviando tu conversación a su proveedor de modelo como siempre; la memoria agrega a esa conversación el resumen y los resultados de las consultas que hace.
¿Puedo editar o borrar algo?
Se corrige en lugar de borrar: cerrar un hecho que terminó, retractar uno equivocado (con motivo), anular un evento, renombrar o retirar una entidad. La historia de cada cambio sigue legible.
¿Por qué SQLite y no Markdown o una base vectorial?
Porque las preguntas sobre un proyecto son sobre hechos, fechas, responsables, estados y conteos. SQLite las responde con exactitud, hace cumplir las reglas de sólo agregado, no necesita servidor y es un solo archivo portable.
¿Mi equipo puede compartir una memoria?
Todavía no. El archivo es local y está excluido de Git a propósito. Compartirlo requeriría sincronización y control de acceso por persona, que esta versión no ofrece.
¿Con qué agentes funciona?
Claude Code (con hooks) y Codex (con AGENTS.md). Cualquier agente que pueda leer un archivo de skill y ejecutar comandos puede seguir el mismo protocolo.
¿En qué idioma trabaja?
Todo lo guardado está en inglés para que cualquier agente lo lea; tus palabras literales se conservan como evidencia en su idioma original, y el agente te responde en el idioma que estés usando.