Memoria persistente para Claude Code: arquitectura en siete capas

Claude Code de fábrica te olvida en cada sesión nueva. Cada conversación empieza de cero: las decisiones tomadas la semana pasada no existen, los clientes que cubres son desconocidos, los matices que negociaste se pierden. Es como contratar de cero a un ingeniero brillante cada mañana, sin transferencia de conocimiento.

Eso convierte una herramienta excelente en un ayudante con amnesia.

La buena noticia: la memoria no viene en la herramienta, viene en cómo montas la carpeta donde trabajas. Lleva una tarde y cualquiera puede hacerlo. Aquí va la arquitectura que uso yo, capa por capa, y el prompt completo que la monta desde cero en una carpeta vacía.

El problema concreto

Sin memoria persistente pasan tres cosas predecibles:

1. Repetición. Cada decisión hay que volverla a explicar. “Sí, ya decidimos no usar X la última vez por Y razón”. Pero el agente no lo sabe.
2. Pérdida de contexto del cliente. Si gestionas varios proyectos o varios clientes desde la misma herramienta, cada nueva conversación arranca sin saber con quién está hablando.
3. Falta de criterio acumulado. El agente no aprende qué te funciona, qué prefieres, qué evitas. No mejora contigo.

La memoria es lo que convierte un agente útil en un agente que se vuelve más útil con el tiempo.

Las siete capas

Capa 1: CLAUDE.md en la raíz

Un archivo en la raíz del proyecto que Claude Code lee automáticamente al iniciar cada sesión. Aquí va lo que el agente necesita saber siempre: quién eres tú, qué es este proyecto, qué reglas duras se aplican, dónde vive cada cosa.

Es el contrato fundacional. Si el agente lo lee, sabe operar en este espacio sin entrevistar al usuario en cada conversación.

Capa 2: Auto-memoria entre sesiones

Claude Code mantiene una carpeta persistente fuera del proyecto donde guarda preferencias, correcciones y referencias aprendidas contigo. Un archivo MEMORY.md sirve de índice, y cada archivo individual contiene una unidad: “este usuario prefiere X”, “este usuario odia Y”, “este proyecto tiene Z restricción”.

A diferencia de CLAUDE.md, que es estático y lo escribes tú, esta capa es dinámica: el agente añade entradas cuando aprende algo que merece sobrevivir entre sesiones.

Capa 3: Wiki estructurado por dominio

Un sistema de carpetas en el proyecto donde cada tipo de información tiene un sitio canónico. Carpetas knowledge, clients, company, marketing. Sin Notion, sin SaaS, sin lock-in: solo archivos markdown que cualquier herramienta puede leer.

Esta es la memoria curada de largo plazo. Aquí viven los patrones reutilizables, los clientes activos, las decisiones estratégicas, los playbooks. Crece despacio pero nunca se pierde.

Capa 4: Journal append-only

Una nota por día con tres secciones: decisiones tomadas, lo que pasa mañana, lo que no sabes dónde clasificar todavía. Solo se añade contenido, nunca se borra ni se reescribe.

Esta es la memoria episódica: el “qué pasó hoy”. Si dentro de tres meses necesitas saber por qué tomaste una decisión en mayo, esta capa la archiva.

Capa 5: Status por área

Cada frente abierto de trabajo tiene su propio archivo status.md. Hay un dashboard global, pero solo apunta a los detallados, no los duplica.

Esto evita la fricción típica de “tengo que actualizar el status global cada vez que cambia algo” y permite que cada área evolucione a su ritmo, con su propio nivel de detalle.

Capa 6: Recall full-text con cero tokens

Un índice de búsqueda full-text (FTS5 sobre SQLite, en mi caso) que cubre todas las sesiones anteriores con el agente. Le hago una pregunta del tipo “qué decidí sobre X hace tres meses” y aparece la frase exacta de la conversación original.

Lo importante: este recall no entra al contexto del agente automáticamente. Se consulta cuando hace falta. Por eso cuesta cero tokens: el índice vive aparte, se busca, se trae solo lo relevante.

Capa 7: Sensores multicanal

Emails entrantes, transcripciones de reuniones, mensajes de canales externos: todo se ingiere al mismo índice. Una sola memoria que cruza canales. La separación email-vs-chat-vs-reunión desaparece: para el agente, todo es texto buscable.

La disciplina importa más que la arquitectura

Las siete capas son fáciles de montar. Lo difícil es la disciplina de uso.

La regla central que aplico es esta: cuando aparece información durable en una conversación, se clasifica al sitio canónico en el momento. No al final del día. No al cierre de sesión. Ahora.

Sin disciplina, la arquitectura se convierte en un cementerio de carpetas vacías y archivos huérfanos. Con ella, el sistema se mantiene útil sin trabajo añadido.

Por debajo de todo, dos capas estilo Andrej Karpathy

Karpathy ha hablado en varias ocasiones de cómo gestiona su memoria como knowledge worker. La idea que adopté:

• Capa curada (wiki): lo que sí merece la pena conservar y enlazar.
• Capa fría (base de datos vectorial local): la cola larga, lo que puede que necesite recuperar pero no merece curación manual.

Las primeras cinco capas que describí encajan en la primera. La búsqueda full-text y los sensores multicanal encajan en la segunda. La combinación da tokens controlados (no metes todo al contexto) y recall efectivo (encuentras lo que necesitas).

El prompt que monta esto en una carpeta vacía

He destilado las cinco primeras capas en un prompt autocontenido. Lo pegas en Claude Code dentro de una carpeta vacía, te entrevista con cuatro preguntas mínimas y monta toda la estructura: CLAUDE.md adaptado a tu rol, STATUS.md, journal del día, carpetas knowledge / clients / company, routing de información y protocolo de sesión.

Las dos capas avanzadas (recall full-text y sensores multicanal) requieren código adicional y se añaden en fase 2, cuando el sistema básico ya está rodado.

Aquí va el prompt completo:

Quiero montar en esta carpeta un sistema de memoria para Claude Code estilo "company brain". Tu trabajo es ejecutar los pasos en orden y parar a preguntar solo donde te indico.

PASO 0 — Entrevístame con estas preguntas mínimas y espera mi respuesta antes de continuar:
  1. ¿Qué rol tengo y a qué me dedico? (1-2 frases)
  2. ¿Voy a usar esta carpeta para un proyecto único o para gestionar varios frentes? (uno / varios)
  3. ¿Idioma del contenido? (es / en / otro)
  4. ¿Qué nombre quieres que use para referirme a ti en CLAUDE.md? (ej. "el CEO", "el founder", tu nombre, etc.)

PASO 1 — Crea esta estructura de carpetas vacías (con un README.md de una línea en cada una explicando qué va dentro):
  knowledge/projects/
  knowledge/playbooks/
  knowledge/integrations/
  clients/
  journal/
  inbox/
  inbox/archive/
  company/
  .secrets/

Crea también un .gitignore en la raíz que excluya .secrets/ y cualquier archivo .env.

PASO 2 — Escribe CLAUDE.md en la raíz con estas secciones, adaptadas a las respuestas del PASO 0:

  ## Identidad
  Una sección que defina quién soy yo en este vault y qué reglas duras se aplican (basado en mi respuesta a 0.1 y 0.4).

  ## Mapa del vault
  Árbol de carpetas con una línea descriptiva cada una.

  ## Protocolo de sesión
  - AL INICIAR: leer STATUS.md, leer el último archivo de journal/, escanear inbox/.
  - DURANTE: filing activo en tiempo real. Cuando emerja información durable en conversación (hecho, decisión, regla, integración), clasificarla con la tabla de routing y guardarla en su sitio canónico inmediatamente. No acumular en buffers.
  - AL CERRAR: actualizar status del frente tocado si hubo cambios, mover mensajes procesados a inbox/archive/, completar el journal del día.

  ## Routing de información
  Tabla mínima con estos casos. Adapta los destinos a la estructura real:
    | Cuando emerja... | Va a... |
    |---|---|
    | Decisión o entregable de un cliente | clients/<slug>/ |
    | Avance o hito de un proyecto estratégico | knowledge/projects/<slug>/status.md |
    | Regla operativa repetible | company/tacit.md |
    | Integración técnica nueva | knowledge/integrations/<servicio>.md |
    | Playbook (proceso repetible) | knowledge/playbooks/<proceso>.md |
    | Apunte cronológico del día | journal/<YYYY-MM-DD>.md |
    | Información durable en duda | journal/<YYYY-MM-DD>.md ## Extract (buffer hasta clasificar) |

  ## Reglas duras
  - Naming: kebab-case para archivos y carpetas.
  - Idioma: EN para estructura y filenames, idioma elegido en PASO 0.3 para contenido.
  - Fechas en filename: prefijo ISO 8601 YYYY-MM-DD cuando sea time-based.
  - Mayúscula solo en archivos de orientación (CLAUDE.md, README.md, INDEX.md, STATUS.md).
  - Secretos: jamás citar, copiar o resumir valores de .secrets/. Solo nombres de variables.

PASO 3 — Escribe STATUS.md en la raíz con esta plantilla:

  # STATUS
  Última actualización: <fecha de hoy>

  | Frente | Estado | Próxima acción | Detalle |
  |---|---|---|---|

  > Actualizar solo cuando un frente cambie de estado (abrir, cerrar, fase). No con micro-progreso.

PASO 4 — Escribe journal/<fecha-de-hoy>.md (formato YYYY-MM-DD.md) con esta plantilla:

  # <fecha>

  ## Decisions

  ## Tomorrow

  ## Extract

PASO 5 — Escribe company/identity.md con un placeholder a rellenar:

  # Identidad
  > Quién soy yo, qué hace esta empresa, qué clientes/dominio cubro.
  > Rellenar cuando tenga claro el posicionamiento.

PASO 6 — Repórtame en una respuesta corta:
  - Qué creaste (lista de archivos y carpetas).
  - Dónde está la auto-memoria nativa de Claude Code (~/.claude/projects/.../memory/) que sobrevive entre sesiones, y cómo usarla con MEMORY.md como índice.
  - Cuál es mi primera acción esperada para empezar a trabajar.

Restricciones:
- NO añadas nada que no haya pedido. Sin emojis, sin docstrings, sin código de ejemplo si no lo solicito.
- NO toques git ni instales dependencias.
- Si dudas en algún paso, para y pregunta antes de actuar.

Si quieres montar el tuyo

Si manejas un proyecto largo, varios clientes o varios frentes desde tu Claude Code, esta arquitectura suele compensar. La inversión es una tarde, el beneficio se nota desde la segunda semana: dejas de explicar las mismas cosas, las decisiones quedan archivadas donde toca, el agente se vuelve más útil conforme pasa el tiempo.

Hay dos formas de seguir desde aquí:

• Diagnóstico rápido (5 minutos, sin llamada). Te pregunto cuatro cosas y te digo si tu caso encaja con esta arquitectura o conviene plantearlo distinto. Empezar el diagnóstico →
• Discovery (30 minutos por videollamada). Charla más a fondo sobre cómo aplicarlo a tu caso concreto, con cifras y plan de acción al final. Reservar discovery →