Record Memory
Conversation context does not persist. When knowledge would save a future agent
meaningful time, write a memory record immediately. Phase and slice wrap-up are
mandatory prompts: scan notes.md, the active runtime phase sheet, audit findings, and
fresh gotchas for durable guidance worth keeping.
Promote only durable guidance — repeatable workflows, sharp edges, invariants, subsystem facts. Not conversational state.
1. Choose the narrowest type that fits
See doctrine memory record --help for the --type values:
concept|fact|pattern|signpost|system|thread.
⚠ A thread is hidden from find/retrieve until verified.
If you want a working loop to resurface by scope, prefer a durable type
(pattern/system/concept) — or record the thread and verify it on a
clean tree. An unverified thread shows only in list/show, never in scope
ranking.
2. Record it
Record with doctrine memory record (ask --help for the flags; see
lib:reference/using-doctrine.md for the verb model). It scaffolds a TOML +
body under
.doctrine/memory/items/; the born git anchor is captured automatically —
do not hand-author it.
After recording
Suggested relations. record emits suggested relations on stderr when it
detects high-confidence matches against existing memories. Review these and
run doctrine link for matches you confirm — this builds the durable graph
edges a future agent traverses.
Graph vs body links. Use [[relation]] edges for durable graph structure
(typed, machine-traversable); use [[mem.…]] wikilinks in body prose for
contextual "see also" pointers. Relations surface in retrieve --expand;
wikilinks don't — they are for human readers.
--lifespan selection. Pick the narrowest lifespan that fits the
knowledge, from most to least durable:
| Lifespan | Rule of thumb |
|---|---|
identity |
Never ages — subsystem identity, invariant, canonical name |
semantic |
10:1 decay — design rationale, architecture constraints |
procedural |
3:1 decay — command recipes, build steps, workflows |
episodic |
Baseline — one-off findings, bug notes, session context |
working |
Fast decay — transient todo, short-lived hypothesis |
Defaults to episodic when omitted. Narrow scope + narrow lifespan together
keep retrieval relevant.
3. Scope it so it will be found
Scope a memory along four axes (the flags are in --help):
- path — exact file(s); strongest match.
- glob — subsystem relevance (e.g.
src/auth/**). - command — tied to a command flow (token-prefix).
- tag — stable categorization; do not overload tags as scope.
4. Set the risk axes
record defaults [trust] trust_level = "medium", [ranking] severity = "none", weight = 0. For risky or drift-prone memories, pass the flags at
record time or update later:
doctrine memory record ... --trust high --severity critical
Or adjust after the fact:
doctrine memory edit <REF> --trust low --severity medium
--trust= confidence:low(inferred, unvalidated) ·medium(derived from reasonable context — default) ·high(verified against code / specs / direct observation).--severity= how much it matters if wrong or ignored:critical·high·medium·low·none(default).
Calibrate honestly: creating a memory is authoring, not verification.
5. Attest if you verified it
doctrine memory verify <UID|KEY>
Stamps verified_sha against the working tree (refuses a dirty tree — no false
attestation). Unattested memories read as lower trust.
Threads require this to surface at all. thread_expiry drops any thread
that is not verified AND reviewed within 14 days from find/retrieve.
record always writes unverified, so a fresh thread is invisible
to scope ranking until you verify it — and verify refuses a dirty tree, so
attest from a clean tree. Other types are never gated this way.
See doctrine memory retrieve --help: retrieve applies the non-bypassable trust
holdback (low-trust + high-severity suppressed).
6. Keep the body short and executable
Put "do X" steps in bullets with exact command snippets. Reference related
artifacts and memories inline with [[uid]] / [[key]] (cheaper than relations).
If the item would become an ADR or an evergreen spec, STOP — doctrine adr new
or author a spec or ADR instead. Memory is a pointer/recipe layer, not canon.
7. Sanity-check surfaceability
Run doctrine memory search scoped to the context a future agent will actually
query (see --help), and confirm the memory appears. Search returns one page,
so a scoped browse can page it out: confirm with a query that uses the memory's
own terms (free text finds it by evidence), or page on with --page.
Exception: an unverified thread will not appear here even when recorded
correctly (§1/§5) — verify it first, or check memory show instead.