Convenciones de Engram¶

Engram es el sistema de memoria persistente del ecosistema: sobrevive entre sesiones y compactaciones, y funciona además como bus de delegación entre el orquestador y los sub-agentes. Esta página fija la convención de topic_key.

Fuente canónica

Migra de docs/shared/ENGRAM_CONVENTIONS.md (mitigación FMEA item F04). Helper: tools/engram_topics.py. Lint: tools/lint_engram_topics.py.

Por qué existe¶

Antes de F04 los topic_key divergían en formatos ad-hoc (architecture/auth-model, paper:{id} EXPLORE done, SUPREMACÍA: Belico.md). Dos mem_save apuntando al mismo topic lógico pero con keys distintas producían dos observaciones en vez de un upsert, fragmentando la memoria y rompiendo mem_search durante la recuperación post-compactación. Esta convención congela el formato. Es no-breaking para observaciones ya almacenadas.

Formato canónico¶

<namespace>/<category>/<identifier>[/<sub_identifier>]

Slot	Regla
`namespace`	Uno de los 9 namespaces (validado contra enum).
`category`	Slug-safe, lowercase. Típicamente paper id, tool name o topic.
`identifier`	Slug-safe. Lowercase salvo en `paper` y `finding`.
`sub` (opcional)	Slug-safe. Misma regla de caso que identifier.

Slug = [A-Za-z0-9][A-Za-z0-9._-]* — letras, dígitos, punto, guion, guion bajo. Sin espacios, sin slashes internos, sin slash inicial/final, sin slashes dobles.

Namespaces (enum)¶

Namespace	Para qué
`sdd`	Artefactos del pipeline SDD (proposal, spec, design, tasks, apply-progress, verify-report, archive-report, state)
`paper`	Eventos del pipeline de papers (EXPLORE..ARCHIVE)
`architecture`	Decisiones sobre el stack (FMEA items, convenciones, refactors)
`tool`	Decisiones y bugfixes por tool
`domain`	Decisiones por dominio (structural, water, air, ...)
`skill`	Registry de skills y updates
`risk`	Riesgos abiertos de un paper o del stack
`calibration`	Calibraciones numéricas (cambios de params, baselines)
`finding`	Hallazgos emitidos por sub-agentes simuladores

Ejemplos¶

sdd/icr-shm-ae/apply-progress
sdd/icr-shm-ae/verify-report
paper/icr-shm-ae/EXPLORE
paper/icr-shm-ae/IMPLEMENT-B2
architecture/fmea/f04
tool/rest_json/cache-integration
domain/structural/dependency-bump
finding/icr-shm-ae/reviewer_simulator/ai_prose
risk/icr-shm-ae/synthetic-data-no-validation
calibration/structure-mass/2026-04

Anti-patrones (el lint los marca)¶

Mal	Bien	Por qué
`paper:abc EXPLORE done`	`paper/abc/EXPLORE`	`:`/espacio mezclados, no parseable
`architecture/auth-model`	`architecture/auth-model/<id>`	Solo 2 segmentos
`SUPREMACÍA: Belico.md`	`architecture/belico/supremacia`	Free-form, sin namespace
`sdd/Foo Bar/baz`	`sdd/foo-bar/baz`	Espacios prohibidos
`random/foo/bar`	(elegí un namespace real)	`random` no está en el enum

Lint pre-compactación¶

Antes de mem_session_summary (o de dejar que el contexto compacte), el orquestador debe garantizar que cada mem_save de la sesión use una key canónica.

python tools/lint_engram_topics.py                   # solo warnings
python tools/lint_engram_topics.py --fix-suggestions # imprime sugerencias
python tools/lint_engram_topics.py --json            # output machine-readable

Exit codes: 0 todas canónicas · 1 al menos una no-canónica · 2 error de configuración.

Bus de delegación (5 pasos)¶

El orquestador no manda contenido inline a los sub-agentes — Engram es el canal:

Orquestador: mem_save("task: …", topic_key="jarvis/<flow>/<id>/<agent>").
Orquestador: lanza el sub-agente con prompt corto (sin copiar contenido).
Sub-agente: mem_search("task: …") → lee sus propios archivos → trabaja.
Sub-agente: mem_save("result: …", topic_key=same).
Orquestador: mem_search("result: …") → lee el resultado (no el output crudo).

Ver Belico.md y .agent/memory/README.md para el protocolo completo.