Mneme — agent memory protocol
Mneme is a plain-text format for an agent's persistent, cross-session memory. A memory
file (*.mneme) is a list of cells (one decision/fact/preference each, self-contained),
and a derived spine (one line per cell: id + state + gist). Full spec: https://github.com/casperkwok/mneme.
Core rule — content is immutable, state is mutable. A cell's gist/body/cue is a fact
about the past, never edited. Its state/seen/conf is its relation to now, updated as
reality moves. To change content, add a new cell that supersedes the old.
When to use
- A
*.mneme file exists in the project → it is the memory; follow this protocol.
- The user wants durable memory ("remember this across sessions", "记住这个决策/偏好/踩坑").
- You just produced something a future session would be wrong or redo without.
Cell format
@ DEC-0042 storage/cache # @ ID(PREFIX-NNNN, unique, never reused) + topic-path
gist Local cache uses SQLite, not JSON # one self-contained line; promoted into the spine
state live conf high since 2026-06-03 seen 2026-06-03
cue concurrent writes / cache corruption / local storage choice # recall keywords
> why / cost / context (free prose, may span multiple > lines)
link supersedes DEC-0031 # typed relation, repeatable
- state:
proposed (not yet authoritative) · live (current/authoritative) ·
stale (maybe expired, verify first) · superseded (replaced) · retired (dead, audit only).
Spine/working-memory shows only live + stale.
- ID prefixes:
DEC decision · OKR goal · PREF preference · GOTCHA pitfall ·
FACT fact/constraint · TODO long-lived todo. Extensible.
- link relations:
supersedes/superseded-by (pair them), relates, depends-on,
blocks, refines.
- Line-oriented, no nesting; unknown lines are ignored;
# lines are comments.
Protocol (SOP)
- Boot — when project context matters, read only the spine, not whole files:
python scripts/mneme_tool.py spine <file> (or grep '^@\|^gist\|^state'). Keep it resident.
- Recall — before acting, match the task topic against each cell's
cue and topic-path;
expand only the cells that hit. Recall generously, then judge relevance by content.
- Trust —
live + conf high + recent seen → use directly. stale / conf low / old
seen → verify against the real source first, then bump seen to today (raise state/conf
if warranted). proposed → not a conclusion; don't act on it unless the task is to advance it.
- Write — when something durable is produced, append a new cell: next id via
python scripts/mneme_tool.py new-id PREFIX <file> (never hand-count), self-contained gist,
set state/conf, since = seen = today, write cue (which future topics should recall it —
don't skip), > for the why, link as needed. Append to end; never silently edit an old cell.
Test: would a future session be wrong or redo work without this? If yes, write it.
- Supersede — to revise a belief: new cell + old cell set
superseded + mutual link
(supersedes/superseded-by). To merely reaffirm: only bump the old cell's seen. Content
is never edited in place.
- Conflict — two
live cells disagree → prefer higher conf, then newer seen, and tell
the user explicitly; then supersede the loser.
- Hygiene — one claim per cell; gist self-contained; long content external (link/path only);
ids never reused.
Tooling (don't rely on agent discretion)
scripts/mneme_tool.py (zero deps):
spine <file> — derive the spine (live/stale).
lint <file> — health-check: duplicate ids, missing required fields, asymmetric/dangling
supersede links, bad dates, and live cells whose seen is older than 45 days (decay).
Exit code 1 on errors — wire into a git pre-commit hook so lifecycle metadata can't silently rot.
new-id PREFIX <file> — allocate the next collision-free id.
Don't use Mneme for
High-frequency precise queries / transactions (use a DB), large blobs (store externally, link
only), throwaway within-session scratch, or things that belong in code/docs. Mneme holds the
why — decisions, constraints, lessons, preferences — not every what.
1---2name: mneme3description: Maintain persistent cross-session agent memory in the Mneme plain-text format (.mneme files) — decisions, facts, preferences, gotchas, goals. Use when an .mneme file is present, when the user wants durable long-term agent memory, or asks to remember a decision/preference/gotcha across sessions. Read via the spine, recall by cue, write/supersede cells (content immutable, state mutable), calibrate trust by state/seen, and lint with the bundled tool.4version: 0.1.05metadata:6 source: https://skillmd.com/skills/lord1egypt/mneme7---89# Mneme — agent memory protocol1011Mneme is a plain-text format for an agent's **persistent, cross-session memory**. A memory12file (`*.mneme`) is a list of **cells** (one decision/fact/preference each, self-contained),13and a derived **spine** (one line per cell: id + state + gist). Full spec: <https://github.com/casperkwok/mneme>.1415**Core rule — content is immutable, state is mutable.** A cell's `gist`/body/`cue` is a fact16about the past, never edited. Its `state`/`seen`/`conf` is its relation to *now*, updated as17reality moves. To change content, add a new cell that supersedes the old.1819## When to use20- A `*.mneme` file exists in the project → it is the memory; follow this protocol.21- The user wants durable memory ("remember this across sessions", "记住这个决策/偏好/踩坑").22- You just produced something a future session would be wrong or redo without.2324## Cell format25```26@ DEC-0042 storage/cache # @ ID(PREFIX-NNNN, unique, never reused) + topic-path27gist Local cache uses SQLite, not JSON # one self-contained line; promoted into the spine28state live conf high since 2026-06-03 seen 2026-06-0329cue concurrent writes / cache corruption / local storage choice # recall keywords30> why / cost / context (free prose, may span multiple > lines)31link supersedes DEC-0031 # typed relation, repeatable32```33- **state**: `proposed` (not yet authoritative) · `live` (current/authoritative) ·34 `stale` (maybe expired, verify first) · `superseded` (replaced) · `retired` (dead, audit only).35 Spine/working-memory shows only `live` + `stale`.36- **ID prefixes**: `DEC` decision · `OKR` goal · `PREF` preference · `GOTCHA` pitfall ·37 `FACT` fact/constraint · `TODO` long-lived todo. Extensible.38- **link relations**: `supersedes`/`superseded-by` (pair them), `relates`, `depends-on`,39 `blocks`, `refines`.40- Line-oriented, no nesting; unknown lines are ignored; `#` lines are comments.4142## Protocol (SOP)431. **Boot** — when project context matters, read only the *spine*, not whole files:44 `python scripts/mneme_tool.py spine <file>` (or `grep '^@\|^gist\|^state'`). Keep it resident.452. **Recall** — before acting, match the task topic against each cell's `cue` and `topic-path`;46 expand only the cells that hit. Recall generously, then judge relevance by content.473. **Trust** — `live + conf high + recent seen` → use directly. `stale` / `conf low` / old48 `seen` → verify against the real source first, then bump `seen` to today (raise `state`/`conf`49 if warranted). `proposed` → not a conclusion; don't act on it unless the task is to advance it.504. **Write** — when something durable is produced, append a new cell: next id via51 `python scripts/mneme_tool.py new-id PREFIX <file>` (never hand-count), self-contained `gist`,52 set `state`/`conf`, `since = seen = today`, write `cue` (which future topics should recall it —53 don't skip), `>` for the why, `link` as needed. **Append to end; never silently edit an old cell.**54 Test: *would a future session be wrong or redo work without this?* If yes, write it.555. **Supersede** — to revise a belief: new cell + old cell set `superseded` + mutual `link`56 (`supersedes`/`superseded-by`). To merely reaffirm: only bump the old cell's `seen`. Content57 is never edited in place.586. **Conflict** — two `live` cells disagree → prefer higher `conf`, then newer `seen`, and tell59 the user explicitly; then supersede the loser.607. **Hygiene** — one claim per cell; gist self-contained; long content external (link/path only);61 ids never reused.6263## Tooling (don't rely on agent discretion)64`scripts/mneme_tool.py` (zero deps):65- `spine <file>` — derive the spine (live/stale).66- `lint <file>` — health-check: duplicate ids, missing required fields, asymmetric/dangling67 supersede links, bad dates, and **`live` cells whose `seen` is older than 45 days** (decay).68 Exit code 1 on errors — wire into a git `pre-commit` hook so lifecycle metadata can't silently rot.69- `new-id PREFIX <file>` — allocate the next collision-free id.7071## Don't use Mneme for72High-frequency precise queries / transactions (use a DB), large blobs (store externally, link73only), throwaway within-session scratch, or things that belong in code/docs. Mneme holds the74*why* — decisions, constraints, lessons, preferences — not every *what*.