# Record Memory

> Use when you discover or confirm a durable fact, constraint, invariant, convention, sharp edge, footgun, or reusable workflow that a future agent would otherwise rediscover — capture it before it is lost to conversation context. Triggers at phase/slice wrap-up too.

- Skill: `davidlee/record-memory` (Agent Skill)
- Install (CLI): `npx skillmds@latest add davidlee/record-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/davidlee/record-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: davidlee (https://skillmd.com/u/davidlee)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/davidlee/record-memory

---


# 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

`fact` (atomic checkable truth) · `pattern` (repeatable recipe / command
sequence) · `system` (subsystem map + pointers, not a spec) · `concept` (stable
mental model / terminology) · `signpost` ("start here" navigation) · `thread`
(short-lived working set, expires fast).

⚠ **A `thread` is hidden from `find`/`retrieve` until verified** (SL-008 D6, §5).
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
`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`
(SL-008 D6). `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.

**Holdback caution:** `retrieve` suppresses low-trust ∧ high-severity memories
(non-bypassable). A high-severity claim you have not verified will be held back
until you raise its trust by attesting it — by design. Set trust to match reality.

## 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 find` scoped to the context a future agent will actually
query (see `--help`), and confirm the memory appears.

Exception: an unverified `thread` will **not** appear here even when recorded
correctly (§1/§5) — `verify` it first, or check `memory show` instead.