Memory Manager — Sistema de Memoria Persistente de Levy

La memoria vive en .claude/memory/ dentro de tu repo (${ARBRAIN_HOME}). Versionada en git. Tú, el dueño, tienes control total. La auto-memory nativa de Claude Code queda DESACTIVADA. La via legitima de escritura es CONVERSACIONAL, con esta skill: Levy propone y escribe, el dueño lo ve en el diff de git y puede revertirlo. Si algun dia activas un proceso nocturno que destile memorias, debe limitarse a CREAR archivos nuevos con su linea de indice; editar o consolidar memorias existentes sigue siendo territorio de esta skill y lo firma el dueño. NADIE borra memorias: se consolidan.

Arquitectura

.claude/memory/
├── MEMORY.md              ← ESENCIA importada siempre: quién eres y reglas transversales compactas
├── RETRATO.md             ← Retrato del dueño, importado siempre: quién es, meta, cómo decide, lo firmado
├── MEMORY-user.md         ← Índice de identidad a demanda (entradas de user/), consultado por el recall
├── MEMORY-indice.md       ← Indice completo project/feedback/reference (NO importado; lo sirve el
│                            hook .claude/hooks/memory-recall.py por triggers; max 400 chars/entrada)
├── MEMORY-archivo.md      ← Capa rotada (project/ >90 dias; el hook tambien la matchea)
├── user/                  ← Sobre el dueño (rol, preferencias, como trabaja)
│   └── forma-de-trabajar.md
├── feedback/              ← Correcciones del dueño (que hacer/no hacer y POR QUE)
│   └── formato-de-respuestas.md
├── project/               ← Estado de iniciativas en curso (fechas absolutas)
│   └── lanzamiento-oferta.md
└── reference/             ← Donde encontrar cosas en sistemas externos
    └── proveedor-de-pagos.md

Los nombres de ejemplo son ilustrativos: tu memoria empieza vacía y crece contigo. La carpeta ES el tipo. No se usa frontmatter.

El retrato del dueño (RETRATO.md)

Para que respondas como él lo haría aunque no nombre el tema. Nace «Pendiente» con sus secciones (cómo usarlo, quién es, su meta y su porqué, cómo decide, qué odia que hagas, lo firmado, abierto). Cómo mantenerlo:

• Llenarlo: con su expediente (user/expediente.md, project/meta-90-dias.md) y lo que te cuente, una sección a la vez; enséñale lo que escribiste. Al llenar una sección, borra su texto de guía; cuando ya no quede ninguna vacía, quita la línea «Pendiente…».
• Al día: cuando firme algo, te corrija o cambie su meta, actualiza la línea del retrato en el mismo turno en que guardas el archivo de detalle. Si una fuente cambia, manda la fuente.
• Corto: máximo unas 60 líneas; el detalle va en user/, project/ o feedback/ y aquí solo la línea con su enlace. Textual suyo entre «», tu lectura marcada «(Levy)». Nunca una frase, cifra o fecha inventada.
• Borrador sembrado: si conectó su cerebro con arbrain.ai, al llegar su expediente Arbrain escribe un borrador (primera línea arbrain:retrato borrador sha256=…) con sus respuestas textuales y nada firmado. Revísalo con él una sección a la vez y, al terminar, quita esa primera línea: desde entonces es suyo y Arbrain no lo vuelve a tocar. Paso a paso, la propiedad y la verificación: arbrain/cerebro/manuales/retrato.md.

Las capas de la memoria, los disparadores y cómo rotar, explicados para el dueño: arbrain/cerebro/manuales/memoria.md.

Un solo cerebro entre runtimes

Claude Code y Codex leen y escriben estos MISMOS archivos. AGENTS.md enlaza a CLAUDE.md; .agents/skills enlaza a .claude/skills; .codex/memory es un alias de compatibilidad. Crear/editar SIEMPRE en .claude/, nunca clonar ni traducir rutas por proveedor. Codex carga la esencia mediante SessionStart y usa el mismo memory-recall.py con cada mensaje. Operación y verificación: .claude/references/cerebro-compartido.md.

Cuando CONSULTAR Memoria

Automatico (sin que el dueño lo pida)

• Inicio de sesion: Leer MEMORY.md para orientarte. Si un tema del indice es relevante al trabajo actual, leer el archivo de detalle.
• Tema recurrente: Si el dueño menciona algo que suena a una correccion o decision pasada, buscar en memoria antes de responder.
• Antes de proponer algo: Si vas a sugerir una arquitectura, flujo, o decision, verificar que no contradiga una decision guardada.

Cuando el dueño lo pide

• "Te acuerdas de...?" / "En que quedamos con...?" / "Que sabes de...?"
• Buscar en MEMORY.md primero, luego en archivos de detalle si hay match.

Como consultar

1. Las entradas cuyo trigger tocaste llegan INYECTADAS por el hook memory-recall.py en el turno. Si no llego nada: rg -i "<tema>" .claude/memory/MEMORY-{indice,user,archivo}.md
2. Si hay un archivo de detalle relevante, leerlo COMPLETO antes de opinar
3. Si no encuentras nada, decirlo honestamente: "No tengo eso en memoria"

Cuando GUARDAR Memoria

Triggers de guardado (proactivo)

Triggers de guardado (cuando el dueño lo pide)

• "Guarda esto" / "No olvides" / "Recuerda que" / "Anotalo"

Que NO guardar (NUNCA)

• Cosas derivables del codigo actual (leer el repo es mejor)
• Git history (git log/blame es la fuente de verdad)
• Lo que ya esta en CLAUDE.md (no duplicar)
• Estado temporal de la conversacion actual (efimero)
• Soluciones de debugging (el fix esta en el codigo, el commit tiene el contexto)
• Secretos: llaves, contraseñas o tokens nunca entran a la memoria

Como GUARDAR

Paso 1: Verificar que no existe

Leer MEMORY.md y buscar en los índices. Si ya hay un archivo sobre ese tema, ACTUALIZAR en vez de crear uno nuevo.

Paso 2: Escribir/actualizar el archivo de detalle

Crear el archivo en la carpeta correcta segun el tipo:

Formato del archivo: Markdown plano. Sin frontmatter. Empieza con # Titulo. Nombre en minúsculas con guiones y, si el tema es fechable, la fecha al final: feedback/no-enviar-sin-revision-2026-03-12.md.

Enlace a la conversación. Toda memoria que nace de una conversación lleva, debajo del título, la línea **Conversación completa:** con el id de la conversación en la app Arbrain (si existe) y la ruta del transcript en ~/.claude/projects/<cwd-slug>/<session-id>.jsonl. La memoria resume; la conversación es la fuente íntegra. Si alguna de las dos no existe, decirlo en esa línea.

Paso 3: Actualizar el indice (MEMORY-indice.md o MEMORY-user.md, NO MEMORY.md)

Las entradas de project/, feedback/ y reference/ van en MEMORY-indice.md. Las entradas de user/ van a MEMORY-user.md, con el mismo formato y triggers. En MEMORY.md (importado siempre) solo quedan la esencia y las reglas transversales compactas. El recall consulta ambos índices y la capa rotada. El sensor memory-budget.sh limita la esencia a 6.000 caracteres y cada entrada a 400. No importar los índices al arranque: el contenido grande se recorta y cuesta tokens en cada conversación.

CONTRATO DURO (leer antes de escribir una sola linea):

El indice es un MAPA, no la memoria. No se importa al contexto: lo sirve el hook memory-recall.py matcheando los triggers de cada prompt, asi que los TRIGGERS son el mecanismo de recall y la descripcion es solo orientacion.

• Formato exacto, una sola linea por entrada: - `carpeta/archivo.md` — Una frase de que es. **T:** trigger1, trigger2, trigger3.
• Maximo 400 CARACTERES por entrada. No lineas: caracteres. Un limite medido en lineas deja que una sola entrada engorde sin violar nunca la regla. La unidad correcta son caracteres.
• PROHIBIDO en el indice: mediciones, porcentajes, citas textuales del dueño, narrativa del hallazgo, listas de defectos, adornos. Todo eso va en el ARCHIVO. Si sientes que el indice "necesita" ese detalle, es senal de que el archivo esta mal escrito.
• Los TRIGGERS son lo unico que se conserva integro (son el mecanismo de recall), pero deduplicados: 8-12 distintivos, no 30 sinonimos de lo mismo.
• Reglas Vivas: si la memoria trae una directiva que gobierna el comportamiento de Levy sin abrir el archivo (un "NO re-litigar", "no reconstruir sin firma", "no sermonear X"), agregarla ADEMAS a la seccion de reglas vivas de MEMORY.md (la esencia importada), a una linea con su puntero.
• Organizar por tema, no cronologicamente.

Verificar siempre despues de escribir: bash .claude/hooks/memory-budget.sh Si sale ⚠ o ✗, arreglarlo en el mismo turno. El techo NO se sube: se ROTA (mover entradas de project/ con mas de 90 dias a MEMORY-archivo.md, que no se importa). El actuador: python3 .claude/skills/memory-manager/scripts/rotar-indice.py muestra que rotaria y --aplicar lo escribe (integras, con sus disparadores: el recall las sigue encontrando como «rotada»). Si el indice sigue alto, consolidar.

Paso 4: Informar al dueño

Decir que guardaste y en que archivo. No pedir permiso (lo vera en el diff de git). Si el dueño revierte el cambio, respetar sin discutir.

Reglas de Oro

1. Consultar es gratis, guardar es caro. Lee memoria seguido. Escribe solo cuando el conocimiento sobrevive a la sesion actual.
2. Fechas absolutas siempre. "Jueves" → "2026-03-12". Las memorias se leen semanas despues.
3. Un archivo por tema. No mezclar. Si crece mucho, dividir.
4. El dueño manda. Puede borrar, editar o revertir cualquier memoria. Tu no borras memorias sin que lo pida.
5. Sin duplicados con CLAUDE.md. Si algo ya esta en el CLAUDE.md principal, no repetirlo en memoria.
6. Honestidad sobre limites. Si no tienes algo en memoria, dilo. No inventes.