Engram conventions¶

Engram is the ecosystem's persistent-memory system: it survives across sessions and compactions, and also acts as the delegation bus between the orchestrator and the sub-agents. This page freezes the topic_key convention.

Canonical source

Migrates from docs/shared/ENGRAM_CONVENTIONS.md (FMEA item F04 mitigation). Helper: tools/engram_topics.py. Lint: tools/lint_engram_topics.py.

Why it exists¶

Before F04, topic_key strings drifted across ad-hoc formats (architecture/auth-model, paper:{id} EXPLORE done, SUPREMACÍA: Belico.md). Two mem_save calls aiming at the same logical topic but with different keys produced two observations instead of an upsert, fragmenting memory and breaking mem_search during compaction recovery. This convention freezes the format. It is non-breaking for observations already stored.

Canonical format¶

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

Slot	Rule
`namespace`	One of the 9 namespaces (validated against an enum).
`category`	Slug-safe, lowercase. Typically a paper id, tool name or topic.
`identifier`	Slug-safe. Lowercase except in `paper` and `finding`.
`sub` (optional)	Slug-safe. Same case rule as identifier.

Slug = [A-Za-z0-9][A-Za-z0-9._-]* — letters, digits, dot, hyphen, underscore. No spaces, no inner slashes, no leading/trailing slash, no double slashes.

Namespaces (enum)¶

Namespace	Use for
`sdd`	SDD pipeline artifacts (proposal, spec, design, tasks, apply-progress, verify-report, archive-report, state)
`paper`	Paper pipeline events (EXPLORE..ARCHIVE)
`architecture`	Decisions about the stack (FMEA items, conventions, refactors)
`tool`	Per-tool decisions and bugfixes
`domain`	Per-domain decisions (structural, water, air, ...)
`skill`	Skill registry and updates
`risk`	Open risks for a paper or the stack
`calibration`	Numeric calibrations (param changes, baselines)
`finding`	Findings emitted by simulator sub-agents

Examples¶

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-patterns (the lint flags these)¶

Bad	Good	Why
`paper:abc EXPLORE done`	`paper/abc/EXPLORE`	Mixed `:`/space, not parseable
`architecture/auth-model`	`architecture/auth-model/<id>`	Only 2 segments
`SUPREMACÍA: Belico.md`	`architecture/belico/supremacia`	Free-form, no namespace
`sdd/Foo Bar/baz`	`sdd/foo-bar/baz`	Spaces forbidden
`random/foo/bar`	(pick a real namespace)	`random` is not in the enum

Pre-compaction lint¶

Before mem_session_summary (or letting the context auto-compact), the orchestrator must ensure every mem_save in the session uses a canonical key.

python tools/lint_engram_topics.py                   # warnings only
python tools/lint_engram_topics.py --fix-suggestions # print suggestions
python tools/lint_engram_topics.py --json            # machine-readable output

Exit codes: 0 all canonical · 1 at least one non-canonical · 2 configuration error.

Delegation bus (5 steps)¶

The orchestrator never sends inline content to sub-agents — Engram is the channel:

Orchestrator: mem_save("task: …", topic_key="jarvis/<flow>/<id>/<agent>").
Orchestrator: launches the sub-agent with a short prompt (no copied content).
Sub-agent: mem_search("task: …") → reads its own files → works.
Sub-agent: mem_save("result: …", topic_key=same).
Orchestrator: mem_search("result: …") → reads the result (not raw output).

See Belico.md and .agent/memory/README.md for the full protocol.