APARTADO ESPECIAL · LA MEMORIA
No es un chat
que recuerda.
La memoria no es un chat que recuerda: son dos formas de recordar —semántica y estructural— que coexisten porque resuelven preguntas distintas, más un conjunto de ficheros con teoría propia: specs, ADRs, lecciones y diario.
Dos memorias, una regla
La semántica responde «¿qué sé sobre esto?». La estructural responde «¿en qué estado está esto?». La primera sugiere con citas; la segunda verifica con hechos.
Regla práctica del sistema: un resultado de búsqueda JAMÁS prueba que una tarea está hecha — eso lo dice el spec con su evidencia. Y un spec no te enseña CÓMO se hizo — eso lo dice la biblioteca con sus citas.
Cómo se inyecta conocimiento externo ↗MEMORIA SEMÁNTICA · LA BIBLIOTECA
Recordar por significado
La memoria semántica es la BIBLIOTECA: una base local de fragmentos (según el documento, 52.167) donde cada fragmento tiene también su vector en Qdrant — una representación de su SIGNIFICADO, no solo de sus palabras.
- Palabras exactas
- FTS5: encuentra «PaymentRepository» porque coincide el token. Es la búsqueda para nombres, rutas de fichero, identificadores.
- Significado
- Vectores: «reintentos» encuentra «retry/backoff» aunque esté en inglés. Es la búsqueda para conceptos y técnicas.
- ~92 ms, en local
- Las dos búsquedas corren A LA VEZ sobre la misma base, en tu PC, sin internet. La nube nunca está en el camino.
- Citado siempre
- La respuesta llega con fichero y página — nunca «me pareció que…». Si no lo encuentra, lo dice; no inventa.
¿Para qué se usa?
- El builder duda de un patrón. «¿cómo hicimos el adapter de email?» — NO adivina: busca en la biblioteca y recupera el patrón con su fuente.
- El scout prepara una fase. Busca «pagos anteriores» y recupera el ADR-0004 (el webhook ya se decidió), la skill-pagos y 3 learnings del proyecto.
- Buscar por significado O por estructura. El panel permite buscar en la memoria de cualquier proyecto de las dos formas: qué QUIERE DECIR tu pregunta o qué ESTRUCTURA tiene (fichero, tipo, fase).
Lo que la semántica NO puede hacer: decirte el ESTADO de algo. Que exista un fragmento sobre reembolsos no significa que los reembolsos estén hechos. Para eso está la memoria estructural.
MEMORIA ESTRUCTURAL · LOS REGISTROS
Recordar por estado
La memoria estructural es el sistema de REGISTROS: un almacén DuckDB por proyecto (memory.duckdb) con tablas de forma fija y estado verificable. No se «busca por parecido»: se CONSULTA con SQL, y su respuesta es un hecho.
- DuckDB
- El motor donde viven los registros: tablas de projects, tasks, sessions, learnings y decisions en ~/.canary/projects/<repo>/memory.duckdb — un almacén central compartido por todos los worktrees del mismo repositorio.
- OLAP, no OLTP
- DuckDB está elegido para CONSULTAR la historia (analítica sobre miles de filas del diario y las sesiones), no para transacciones: por eso la integridad referencial se aplica en la capa de aplicación, no con FKs de base de datos.
- Escribir es explícito
- Ninguna columna lleva valores por defecto: quien escribe pasa el timestamp y el contexto explícitos. Cada fila dice de dónde viene y cuándo — sin relojes ocultos.
- Un proyecto, una base
- La base se aísla por repo_identity: dos worktrees del mismo repo comparten la misma memoria estructural automáticamente — nunca dos verdades paralelas del mismo proyecto.
¿Para qué se usa?
- Saber dónde quedó el trabajo. «sigue con lo de reembolsos» → el spec f2 dice PENDIENTE. Es un hecho consultable, no una recuperación aproximada.
- Saber qué se decidió y por qué. El architect comprueba si elegir Stripe ya se decidió (ADR-0004) y lo REUTILIZA en lugar de re-decidir.
- Saber qué pasó de verdad. El delegation_journal registra cada dispatch con su hash: la cadena cuadra o alguien manipuló el pasado.
- Medir sin apuntar a mano. La tabla sessions guarda agente, duración y tokens de cada sesión: los KPIs del panel derivan de ahí, no de un registro manual.
Lo que la estructura NO puede hacer: encontrar conocimiento por parecido. Una tabla no responde a «¿cómo hicimos los reintentos?» — para eso está la semántica.
¿POR QUÉ COEXISTEN?
Porque se corrigen la una a la otra
Preguntan cosas distintas
La semántica responde «¿qué sé sobre esto?» (conocimiento, con citas). La estructural responde «¿en qué estado está esto?» (hechos, verificables). Ninguna cubre a la otra.
Sus fallos son opuestos
La búsqueda semántica es aproximada: puede no encontrar, o encontrar algo parecido — por eso CITA y nunca afirma estado. La estructural es exacta pero muda: solo responde si sabes QUÉ fichero preguntar. Juntas se corrigen: la semántica sugiere, la estructura verifica.
El flujo del run las encadena
Scout consulta la semántica (patrones, decisiones previas) → el architect verifica contra la estructural (ADRs, specs) → release escribe de vuelta en la estructural (evidencia, lecciones) y sus fragmentos alimentan la semántica. Cada vuelta deja la memoria más rica.
LA TEORÍA DE CADA FICHERO
Qué es cada cosa
y por qué tiene esa forma.
Cuatro ficheros, cuatro compromisos
Cada tipo de fichero existe para que una pregunta concreta tenga siempre la misma respuesta verificable — y para que nada dependa de la memoria de un modelo.
SPECS · EL CONTRATO DE CADA FASE
Specs
Un spec es el documento de UNA fase de la obra: lo que se promete hacer y CÓMO SE COMPRUEBA que se hizo. Nace BORRADOR (no vale nada hasta que tú lo validas) y solo pasa a CERRADA grabando evidencia con números.
- Criterios verificables
- Cada spec lleva su lista de comprobación: «[ ] suite billing verde · [ ] webhook replay idempotente». Un criterio que no se puede verificar con un comando no es un criterio: es una opinión.
- f0 = el punto de partida
- specs/f0 describe lo que hay HOY, medido. Las fases siguientes se construyen sobre esa foto, no sobre impresiones.
- f1, f2… = el alcance por partes
- La migración se parte en specs/f1 (pasarela + webhook) y specs/f2 (reembolsos). Cada fase cierra la suya con su evidencia.
- Sin números, no hay cierre
- Si algo no tiene número grabado, la fase queda ABIERTA — sin trampas. El spec f2 queda PENDIENTE y la próxima tarea empieza ahí.
ADRS · LAS DECISIONES CONGELADAS
ADRs
Un ADR (Architecture Decision Record) documenta una decisión CON CALADO: una que condiciona trabajo futuro y que no quieres re-decidir por accidente. La regla de oro: un ADR está congelado — se REEMPLAZA con uno nuevo, nunca se reescribe.
- Por qué existe
- Para que «elegir Stripe» se decida UNA vez. El ADR-0004 ya lo resolvió: el scout lo recupera y el architect lo reutiliza en lugar de reabrir el debate.
- Cuándo NO se crea
- ADR-0033 solo se propone si hay una decisión nueva con calado. Decidir lo ya decidido no genera ADR: genera ruido.
- Congelado, no eterno
- Si una decisión deja de valer, se escribe un ADR nuevo que la sustituye y explica por qué. El historial de decisiones queda íntegro: las decisiones tienen edad, no se retocan.
- Qué contiene
- La decisión, su contexto y sus consecuencias. Suficiente para que un agente (o tú, en seis meses) entienda el porqué sin re-derivarlo.
CUADERNO DEL PROYECTO · LOS HECHOS DEL DÍA A DÍA
Cuaderno del proyecto
El cuaderno guarda HECHOS y LECCIONES del proyecto en fichas estructuradas: «adapter Stripe: reintentos con JobLock». Es distinto de la biblioteca del owner (conocimiento): el cuaderno responde QUÉ pasó aquí; la biblioteca, QUÉ SÉ sobre esto.
- Lecciones, no diarios en prosa
- Una lección es accionable y corta: técnica + resultado. El builder la consulta antes de repetir un error caro.
- Promoción a biblioteca
- Lo aprendido que vale más allá del proyecto se promociona a la biblioteca del owner como patrón — con su procedencia.
- No es una segunda verdad
- El cuaderno describe lo ocurrido; el ESTADO canónico de una fase sigue siendo su spec. Nada deriva del cuaderno.
JOURNAL · EL DIARIO FIRMADO
Journal
El delegation_journal es una tabla append-only en DuckDB: cada paso se escribe ANTES de ejecutarse (evento «dispatch» precede a la acción) y cada fila lleva el prev_hash — el sha256 de la fila anterior: editar una fila del pasado rompe TODA la cadena posterior → corrupción detectable. Además guarda el constraints_hash: qué versión de las reglas aplicaba ese día.
- Eventos con vocabulario cerrado
- dispatch, complete, blocked, gate, override — nada más entra al diario. Cada veredicto del auditor queda firmado y nada se pierde.
- Tinta, no lápiz
- Por contrato ningún módulo borra ni reescribe filas del diario: es INSERT-only. Como un cuaderno de obra sellado.
- Honesto por diseño
- La cadena DETECTA corrupción; no es infalsificable contra quien tiene acceso de escritura a la base. El sistema no promete criptografía: promete que el descuido se ve.
- Única fuente de las métricas
- Tiempos, tokens y KPIs de skills derivan del propio diario y de sessions (session recorder): no existe una segunda verdad con la que discrepar.
MEMORIA = CONTINUIDAD
La próxima vuelta
empieza con ventaja.
La próxima vuelta empieza donde quedó
«sigue con lo de reembolsos»: el sistema encuentra la fase f2 PENDIENTE en su spec y todo el contexto — sin que se lo expliques otra vez.
El sistema mejora cada vuelta
Riesgo aprendido, skills más usadas, prior art consultable. La memoria no solo recuerda: hace que la siguiente tarea parta con ventaja.
Local primero
Toda la consulta ocurre en tu PC, sin internet. La nube es solo un espejo de respaldo: JAMÁS está en el camino de las consultas.