Conceptos

memsys3 organiza la memoria de un proyecto en archivos YAML, los compila mediante agentes especializados y los expone a tu AI agent mediante prompts en Markdown.

Los tres agentes

memsys3 define tres roles agenticos canonicos:

• Main Agent — implementa features, resuelve bugs, trabaja en el dia a dia. Lee el contexto compilado al empezar y documenta al acabar.
• Context Agent — mantiene al dia un unico context.yaml compacto usando criterio inteligente. Compila de forma incremental (lo nuevo desde la ultima compilacion) y mantiene ligera la memoria del usuario.
• Setup Agent — gestiona el lifecycle de memsys3: deploy inicial, actualizacion y cleanup. Es el unico autorizado a tocar infraestructura (prompts/, agents/, templates/).

Cada rol tiene sus propias restricciones declaradas en agents/*.yaml.

Context Agent

Filosofia: “Que debe saber CUALQUIER agent descontextualizado para trabajar aqui?”.

• Limite unico: maximo 2000 lineas en context.yaml.
• No hay limites arbitrarios por ADRs o sessions.
• Incremental por defecto (ADR-033): el context.yaml anterior es su primera entrada; solo lee enteras las sesiones, ADRs e items posteriores a ultima_compilacion, hereda lo vigente y poda lo superado. Recompilar desde cero solo si se lo pides.
• Sistema de 5 tiers de ingesta con presupuesto medido en bytes (~300 KB en espanol, ~600 KB en ingles, unos 150K tokens): memory/full, README, backlog, docs contextuales y git log.
• Mantiene memory.yaml: fusiona familias de reglas repetidas en la capa ligera, de forma trazable (la linea fusionada conserva los ids que absorbe) y solo con tu OK.
• Se ejecuta con memsys3/prompts/compile-context.md. Al cerrar sesion con 5 o mas sesiones sin compilar, endSession te ofrece lanzarlo en un agente fresco.

Sessions

memsys3/memory/full/sessions.yaml registra que se hizo en cada sesion: decisiones, cambios, proximos pasos. Se documenta al final de cada sesion con:

@memsys3/prompts/endSession.md

Cuando supera las 1800 lineas se rota automaticamente a sessions_N.yaml.

ADRs (Architecture Decision Records)

memsys3/memory/full/adr.yaml registra decisiones arquitectonicas significativas: que se decidio, por que, alternativas consideradas, consecuencias.

Se gestiona con:

@memsys3/prompts/adr.md

Tambien rota automaticamente a adr_N.yaml cuando supera 1800 lineas.

Project Status

memsys3/memory/project-status.yaml es la fuente de verdad sobre el estado actual: fase, ultima feature, siguiente milestone, pendientes prioritarios. Se actualiza durante endSession.

Es solo estado vivo y debe caber en una lectura (ADR-033): no lleva historico de sesiones (eso es sessions.yaml) y pendientes_prioritarios es un indice — una linea corta por tarea con fecha, tema y un puntero al detalle (README del expediente, item del backlog o memory/full/tasks.yaml). Lo cerrado se quita del indice; endSession hace esa limpieza sin preguntar y newSession agrupa en una sola pregunta los pendientes con fecha pasada.

Memoria del usuario en dos capas

memsys3/memory/memory.yaml guarda quien eres y las reglas que tu agente ha aprendido de ti (correcciones, preferencias, referencias). Desde ADR-033 vive en dos capas enlazadas por id:

• Capa ligera (memory/memory.yaml): una linea por regla, condensada. Es lo unico que se lee al arrancar.
• Capa completa (memory/full/memory_full.yaml): la misma regla con su contexto y el caso que la origino. No se lee al arrancar; se consulta por id cuando hace falta el porque.

Medido en un proyecto real: el arranque paso de ~245K a ~140K tokens el mismo dia.

Backlog

memsys3/backlog/ (opcional) gestiona trabajo futuro estructurado con prefijos:

• ISSUE-XXX — bugs y problemas.
• FEATURE-XXX — nuevas funcionalidades.
• IMPROVEMENT-XXX — mejoras incrementales.
• SPEC-XXX — especificaciones tecnicas.
• BLUEPRINT-XXX — disenos de alto nivel.
• EXPLORATION-XXX — investigacion y prototipos.

Se gestiona con @memsys3/prompts/backlog.md (3 operaciones: consultar, crear, actualizar). Los items completados se archivan en backlog/archive/.

Prompts del sistema

Los prompts viven en memsys3/prompts/ y se invocan con @-mentions:

Prompt	Proposito
newSession.md	Cargar contexto al empezar a trabajar.
endSession.md	Documentar la sesion (sessions, status, gotchas, canonizacion anti-CDC).
compile-context.md	Actualizar context.yaml (incremental; desde cero a peticion) y mantener ligera la memoria del usuario.
deploy.md	Desplegar memsys3 en un proyecto nuevo.
actualizar.md	Actualizar memsys3 en un proyecto existente (con backups, deteccion de estructura antigua y sustitucion diferencial).
adr.md	Gestionar Architecture Decision Records.
backlog.md	Gestionar el backlog estructurado.
github.md	Lectura obligatoria antes de operaciones git (commits, tags, push).

Mecanismos de proteccion

Rotacion automatica (>1800 lineas)

Cuando sessions.yaml o adr.yaml superan 1800 lineas, se rotan a sessions_N.yaml / adr_N.yaml. Los datos se preservan; el Context Agent lee los rotados que necesite.

Plan de Contingencia (presupuesto en bytes)

Cuando lo que el Context Agent tiene que leer supera su presupuesto (~300 KB en espanol / ~600 KB en ingles, unos 150K tokens — se mide con wc -c, no se estima), archiva datos antiguos a memsys3/memory/history/ (que NO se lee) hasta quedar en ~80%, preservando los datos. Si project-status.yaml crece mas de ~30 KB, endSession mueve a history/ lo que no sea estado vivo.

Todo lo que lee el arranque cabe en una lectura

Corolario anti-CDC (ADR-033): si un archivo de arranque no cabe en una lectura, el agente lo trocea con filtros y cada sesion ve un estado distinto. Por eso memory.yaml, project-status.yaml y context.yaml se mantienen ligeros por diseno: se rotan o se reparten en capas, nunca se trocean al leer.

file_version por archivo

Cada archivo de infraestructura (prompts, agents, templates) lleva su propio file_version. Sólo actualizar.md puede modificarlo. Esto permite versionado independiente y sustitucion diferencial al actualizar.

Memoria agnostica multi-modelo

memory.yaml agnostico + AGENTS.md en la raiz + bridge MEMORY.md opcional que ocupa el sitio de la convencion de memoria en raiz. El contenido de memoria es portable entre Claude Code, Gemini CLI, Codex CLI y otros agentes.

Stack

• Almacenamiento: YAML files. Sin base de datos.
• Distribucion: Git + clonado local.
• Lenguaje: YAML + Markdown.
• Compatibilidad: agnostico de modelo de IA.

Mas informacion

• Principios sistemicos — los 10 principios canonicos.
• Workflow — flujo dia a dia.
• README en GitHub
• CHANGELOG
• Releases