Memory types
Every active Engram memory has a type. The type controls routing, review, and how the memory is rendered to agents.
| Type | Use |
|---|---|
| Rule | user preference, correction, constraint, always/never guidance |
| Skill | repeatable workflow, checklist, procedure, runbook |
| Knowledge | objective project fact, decision, implementation detail |
New files use schema_version: 3. Rule and skill memories default to authority: instruction; knowledge defaults to authority: reference. revision starts at 1 and increments on updates. Trace IDs belong in evidence_refs, while session or source identities belong in derived_from.
Good memory
Good Engram memory is:
- stable enough to matter next week
- specific enough to route later
- short enough to load into an agent context
- safe enough to share with the intended scope
- written as a rule, workflow, or knowledge item
Bad memory is temporary chat noise, secrets, credentials, one-off speculation, or facts that nobody has approved.
Rule variants
Engram derives light, balanced, and strict rule wording at render time from the rule's ## Content (balanced is the Content verbatim), so new and rewritten rule files store only the Content. A ## Rule Variants section is kept only for custom wording a candidate supplies with LIGHT:/BALANCED:/STRICT:. Rule variant mode is a render lens for agent-facing memory:
- Strict helps lower-tier models stay controlled.
- Light or balanced wording usually helps stronger models so rules do not limit their reasoning.
When variants are off, Engram renders balanced rule wording by default. Tune with:
engram set-rule-variant strict|balanced|light|off
Compact output by default
When engram load "<task>" runs, the output is tiered and slimmed for AI agents by default:
| Aspect | Default (engram load) | Full (engram load --full) |
|---|---|---|
| Frontmatter | Not rendered; the body header is ### <id> [<type>, <authority>] plus requires: <ids> | Full schema v3 and legacy fields, including provenance, revision, supersession, and validity |
| Disclosure | Top load.expand_top hits as bodies, other hits as one-line cards (- <id> [<type>] <directive-or-summary>), then a fetch: hint | Every packed body |
| Rule body | One selected variant | The Content, plus the stored ## Rule Variants section only when the file has custom variants |
| Other sections | ## Context, ## Example, and ## Origin are not rendered | Same content, unchanged heading |
MCP engram_load and hooks use the tiered output by default. Pass full: true on the MCP tool or engram load --full "<task>" when broader legacy output is needed.
Optional routing fields
These frontmatter fields are optional; a memory without them behaves as before and schema_version stays 3.
| Field | Meaning |
|---|---|
directive | One line of at most 160 characters; shown on cards and weighted in ranking |
applies_to | Glob list; injects the memory when a matching file is read or edited and counts as a strong anchor |
tier | durable (default) or working (task-scoped, gitignored, expires) |
objective | Up to 200 characters; the objective a working memory was written for |
valid_until | Expiry date; a working memory gets today + load.working_ttl_days |
Evidence-backed memory
New files use schema_version: 3. Rule and skill memories default to authority: instruction; knowledge defaults to authority: reference. revision starts at 1 and increments on updates. Trace IDs belong in evidence_refs, while session or source identities belong in derived_from. Legacy v1 (Context + Content + Example) and v2 (Content, optional Origin) remain readable.
Next steps
Git author identity
Engram can store a global author and an optional workspace override. Resolution is workspace, global, then read-only Git fallback. Settings affect future memories only; a workspace override never changes global Git configuration. Use explicit plan and confirmation for global Git sync or legacy-memory migration.
engram author show
engram author set --name "Jane Doe" --email "jane@example.com"
engram author unset --scope workspace
engram author sync-git-global --plan
engram author sync-git-global --confirm
engram author migrate-memories --plan
engram author migrate-memories --confirm
Read the complete Git author settings guide.
Configuration upgrade inventory
After a package update, run engram upgrade --latest --plan before engram upgrade --latest. The shared inventory scans workspace and global Engram-managed memories, instructions, skillsets, configs, hooks, and plugins. User-authored bytes are preserved; ambiguous mixed files are reported as conflicts. See Configuration upgrades.