# Durable memory entry

Version: 1.0
Updated: 2026-10-02
Method: https://suhailmohebi.com/notes/the-cookbook/

Purpose: capture one durable, non-obvious fact so the next session starts from it instead of rediscovering it.

Output: one small memory file with the fact, its reason and how to apply it, plus one index line that makes it findable.

## Use when

A task surfaced something worth knowing next time — a root cause, a false alarm, a rejected approach, a preference and its reason — and nothing already records it.

## Quick start

1. Run the test in section 1. Most task notes fail it, and that is correct.
2. Search the index for an entry that already covers it; if one does, update that entry.
3. Otherwise write one fact per file in the format of section 2, with why it is true and how to apply it, and add one index line.

A memory is evidence of the past: re-verify any version, price, path or flag before acting on it.

## 1. Does it qualify?

Write an entry only when every line is true:

- [ ] Durable: still useful after this task ends.
- [ ] Non-obvious: a capable newcomer would not guess it.
- [ ] Not derivable: the code, docs, configuration and version history do not already say it.
- [ ] Actionable: it changes what someone does next time.

| Highest-value kind | Shape |
|---|---|
| Recurring false positive | “Alert X fires on Y; it is harmless because …; confirm with …” |
| Rejected approach | “Tried X; it failed because …; do not retry unless …” |
| Root cause | “Symptom X comes from Y, not Z.” |
| Preference with its reason | “Use X, not Y, because …” |

Never write:

- Transient task state: progress, to-do items, branch status. Those belong in a progress log or handoff packet.
- Secrets: tokens, keys, passwords, connection strings. Name where the credential lives instead.
- Personal data beyond working preferences a person shared for this purpose: no contact details, identifiers, health, finances or third-party details.
- Anything already recorded elsewhere. Link to it.

## 2. Memory file

One fact per file, named after its slug. Reasons are the first thing lost between sessions, so the **Why:** line is the point of the entry.

```markdown
---
name: [short-kebab-case-slug]
description: [one line, worded the way someone will later search or ask for it]
type: [user | feedback | project | reference]
---
[The fact in one to three sentences, with exact values and absolute dates (YYYY-MM-DD).]

**Why:** [the observation or incident that makes it true, and when it was seen]

**How to apply:** [what to do or check next time, and when the entry stops applying]

Related: [other-slug](other-slug.md)
```

| Type | Holds |
|---|---|
| user | Who the work is for and how they prefer it done, with reasons |
| feedback | Corrections and confirmed approaches about how to work |
| project | Decisions, constraints and context that outlive one session |
| reference | Where things live, and how tools and systems behave |

## 3. Index line

Keep one index file, for example `MEMORY.md`, and point every session at it from the agent’s instruction file. One line per entry, under about 150 characters:

```text
- [Title in a few words](slug.md) - the hook that says when it matters
```

The index is for discovery. The detail stays in the file.

## 4. Rules

- Update rather than duplicate: edit the entry that already covers the fact.
- One fact per file. Two facts get two files and a `Related:` link.
- Absolute dates only: 2026-10-02, never “yesterday” or “last week”.
- Delete an entry proven wrong, or rewrite it with the correction and its evidence.
- Bias toward the why and the never-again. The what is often derivable; the reason is not.

## 5. Staleness rule

A memory records what was true when it was written.

| Kind of fact | Before acting on it |
|---|---|
| Stable: a reason, root cause or rejected approach | Use it; re-check if the system around it changed |
| Volatile: a version, price, path, flag, endpoint or owner | Re-verify against the live source in the same session |
| Contradicted by what you observe now | Trust the observation; fix or delete the entry |

## 6. Pruning pass

Monthly, or whenever the index no longer fits on one screen:

- [ ] Every file has one index line, and every index line points to a file.
- [ ] Duplicates are merged into the better-reasoned entry.
- [ ] Volatile facts are re-verified and re-dated, or removed.
- [ ] Relative dates, secrets and personal data beyond shared working preferences are gone.
- [ ] Entries the code or docs now state are removed.

Read-only report, run inside the memory directory (change `MEMORY.md` if your index has another name):

```bash
for f in *.md; do
  [ "$f" = MEMORY.md ] && continue
  grep -qF "($f)" MEMORY.md || echo "not indexed: $f"
done
grep -oE '\([^()/ ]+\.md\)' MEMORY.md | tr -d '()' | while read -r f; do
  [ -f "$f" ] || echo "index points to a missing file: $f"
done
grep -nwiE 'yesterday|today|tomorrow|tonight|recently|this (morning|week|month)|(last|next) (week|month|year)|[0-9]+ (days|weeks|months) ago' -- *.md
find . -maxdepth 1 -name '*.md' -mtime +90 -print
```

The last command lists files not modified for 90 days; re-verify those first. A clone, checkout or copy resets that time; in a git-tracked store, `git log -1 --format=%cs -- FILE` gives the last real change.

## Worked example

A gotcha: link audits flag dozens of 403 errors on one documentation host, yet the pages load. It recurs, no code or doc reveals it, and it changes the next audit, so it qualifies.

```markdown
---
name: docs-host-403-false-positive
description: Link audits report 403 for docs.example.org; the pages load, so confirm with one GET before filing
type: reference
---
Link audits report 403 for every docs.example.org link. The host refuses HEAD requests;
a GET of the same URLs returns 200. Seen 2026-09-14 and 2026-09-30.

**Why:** on 2026-09-30, from one machine, `curl -sI` (HEAD) returned 403 and `curl -s` (GET)
returned 200 for all 41 flagged links.

**How to apply:** treat a 403 from this host as unverified, not broken; confirm with one GET
before filing a fix. A 404 or a timeout is still a real failure. Re-check after any change to
the host or the audit tool.

Related: [link-audit-runbook](link-audit-runbook.md)
```

Index line:

```text
- [Docs host 403s are false positives](docs-host-403-false-positive.md) - HEAD refused, GET fine; confirm before filing
```

## Stop if

- The entry would contain a secret, a token, or personal data beyond a shared working preference. Do not write it; if one is already in memory, tell the owner so it can be rotated or removed.
- An entry that records a person’s decision or preference contradicts what you now observe: ask before rewriting it.
- You cannot say why the fact is true, or the only evidence is the session that is ending: it is a guess, not a memory.
- The store is shared and the change would delete or rewrite another owner’s entries.