Skip to content
memsys3

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

Section titled “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 — sintetiza toda la memoria del proyecto en un unico context.yaml (~3K tokens) usando criterio inteligente.
  • 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

Section titled “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.
  • Lee TODO primero, despues filtra con criterio.
  • Sistema de 5 tiers de ingesta hasta 150K tokens: memory/full obligatorio, README, backlog completo, docs contextuales y git log reciente.
  • Se ejecuta con @memsys3/prompts/compile-context.md.

Sessions

Section titled “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)

Section titled “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

Section titled “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.

Backlog

Section titled “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

Section titled “Prompts del sistema”

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

PromptProposito
newSession.mdCargar contexto al empezar a trabajar.
endSession.mdDocumentar la sesion (sessions, status, gotchas, canonizacion anti-CDC).
compile-context.mdRegenerar context.yaml desde cero.
deploy.mdDesplegar memsys3 en un proyecto nuevo.
actualizar.mdActualizar memsys3 en un proyecto existente (con backups, deteccion de estructura antigua y sustitucion diferencial).
adr.mdGestionar Architecture Decision Records.
backlog.mdGestionar el backlog estructurado.
github.mdLectura obligatoria antes de operaciones git (commits, tags, push).

Mecanismos de proteccion

Section titled “Mecanismos de proteccion”

Rotacion automatica (>1800 lineas)

Section titled “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 todos los archivos rotados hasta detectar >150K tokens.

Plan de Contingencia (>150K tokens)

Section titled “Plan de Contingencia (>150K tokens)”

Cuando el contexto compilado supera 150K tokens, el Context Agent archiva datos antiguos a memsys3/memory/history/ (que NO se lee). Reduce a ~120K tokens preservando los datos.

file_version por archivo

Section titled “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

Section titled “Memoria agnostica multi-modelo”

memory.yaml agnostico + bridge MEMORY.md opcional para Claude (y equivalentes para otras herramientas via AGENTS.md). El contenido de memoria es portable entre Claude Code, Gemini CLI, Codex CLI y otros agentes.

Stack

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

Mas informacion

Section titled “Mas informacion”