# The memoir format, v0.1.2 (draft) **Status:** Draft. Version 0.1.1. Seeking implementations and critique. This document specifies the memoir format: an open, portable, plain-text format for an AI assistant's accumulated working context — what it has learned, decided, been corrected on, and is in the middle of doing. The format is extracted from a working implementation ([memoir-cli](https://github.com/camgitt/memoir), MIT), not designed on a whiteboard. Where this document and shipped behavior disagree, that is a bug in this document; please file it. Normative words (MUST, SHOULD, MAY) are used in the RFC 2119 sense. --- ## 1. Why an open format Every AI vendor is shipping memory, and every one of them is shipping it locked in. Memory is the strongest lock-in there is, because it compounds: the assistant that knows your preferences, your past decisions and their reasons, and the mistakes it must not repeat is worth more every week — and none of that accumulates anywhere you can take with you. Email had the same problem, and solved it with open formats and protocols (mbox, Maildir, IMAP): your mail is yours, in files and mailboxes any client can read, and clients compete on experience rather than on holding your archive hostage. The memoir format is that seat for AI working context. It deliberately covers *experience*, not just facts: a decision with its rationale and the alternative that was rejected; a lesson with the trigger that should fire it and the behavior change it demands; the live working set of goals and next actions that lets a different tool — or the same tool on a different machine — pick up mid-thought. It is plain markdown and JSON on disk, owned by the user, versioned however the user versions files. Any tool that can read a directory can read it. That is the whole point. ## 2. The store A **memoir store** is: 1. a directory of **entry files** — one entry per file, markdown with YAML frontmatter (section 3), and 2. a **session state file** — a single JSON document holding the live working set (section 5). ``` / memory/ decision_local-db-choice.md lesson_migrations-staging-first.md preference_commit-style.md fact_staging-endpoints.md ... session.json ``` The reference implementation currently keeps these in two places for tool-compatibility reasons (entry files where the host assistant reads its memory, e.g. `~/.claude/projects//memory/`; session state at `~/.config/memoir/session.json`). The format does not care where the store lives. A store MAY be a git repository; the format is designed so that it diffs and merges well when it is (section 4.2). Entry filenames SHOULD be lowercase slugs and SHOULD carry the entry type as a prefix (`decision_`, `lesson_`, ...), purely for human scanability. The filename (without `.md`) is the entry's **link name**: other entries reference it with `[[wikilinks]]` in their body text. ## 3. Entry files ### 3.1 File format An entry file is UTF-8 markdown. It SHOULD begin with a YAML frontmatter block delimited by `---` lines. Everything after the closing `---` is the **body**: free markdown, as long or short as the entry deserves. Plain text is a feature, not a compromise, and implementations MUST NOT "upgrade" the store to a database as the canonical form: - **Human-readable.** The user can open, audit, and edit their AI's memory with any editor. Memory the user cannot read is memory the user cannot trust or correct. - **Git-diffable.** One entry per file means a change to one memory is a one-file diff. History, blame, review, and rollback come free from tools the user already has. - **Mergeable.** Text files union across machines with well-understood conflict surfaces (section 4). A database file is an opaque blob that can only be replaced wholesale — which is exactly the failure mode this format exists to avoid. - **Durable.** Markdown will be readable in twenty years by tools that have never heard of memoir. Implementations MAY build derived indexes (embeddings, full-text, SQLite caches) but these are caches: the files are the truth, and a conforming implementation MUST be able to rebuild any index from the files alone. The frontmatter is restricted to a simple YAML subset so that it can be parsed without a full YAML engine: scalar `key: value` pairs, one level of nested mapping, and simple `- item` string lists. Writers MUST NOT emit anchors, multi-line block scalars, or deeper nesting in frontmatter; prose belongs in the body. ### 3.2 Common frontmatter fields | Field | Requirement | Meaning | |---|---|---| | `type` | REQUIRED | One of the six entry types (3.3). | | `name` | REQUIRED | Human-readable title (or slug) for the entry. | | `description` | SHOULD | One line. Indexes and pickers render this; an entry without one is invisible in lists. | | `created` | SHOULD | ISO 8601 date or date-time the entry was first written. | | `updated` | MAY | ISO 8601 date or date-time of last substantive edit. | | `schema_version` | MAY | Integer. Absent means `1`. See section 6. | | `project` | MAY | Project this entry is scoped to; absent means global. | | `tags` | MAY | List of strings. | | `aliases` | MAY | List of strings: other names, nicknames, or phrasings a reader might search for this entry under (e.g. an entry about a "vertical swipe feed" surface: `tiktok`, `reels`, `/tape`). Retrieval SHOULD weight this field above body prose. Concept-level recall in a plain-text format is a write-time job — the writer knows what else the thing is called; a substring search later does not. | | `origin` | MAY | Mapping with any of `tool`, `session_id`, `machine_id` — where the entry came from. | Readers MUST ignore fields they do not recognize. Writers MUST preserve fields they do not recognize when rewriting an entry. (Unknown fields are how the format extends without breaking deployed tools.) ### 3.3 Entry types Six types. A type answers the question "what should a tool *do* with this entry when it loads?" — inform (fact), constrain style (preference), prevent relitigation (decision), change behavior (lesson), orient (goal), or resume work (next_action). Machine-readable versions of every constraint in this section are in [`schema/entry.schema.json`](../schema/entry.schema.json). #### 3.3.1 `fact` Something true about the world, the project, or the environment, worth loading into future context. Facts are the baseline type: when in doubt, an entry is a fact. Extra fields: `source` (MAY) — where the fact was established. ```markdown --- type: fact name: Staging API endpoints description: Base URLs and auth mode for the staging environment created: 2026-05-14 project: acme-api --- Staging runs at `https://staging.api.example.com`, bearer-token auth, tokens minted by `scripts/mint-token.sh`. Rate limit is 60 req/min and it is enforced. See [[decision_local-db-choice]] for why staging has no Postgres. ``` #### 3.3.2 `preference` How the user wants things done. Preferences are standing instructions: tone, formatting, workflow, tooling defaults. Extra fields: `scope` (MAY) — `global` or `project`. ```markdown --- type: preference name: Commit message style description: Imperative mood, no trailers, reference the issue number scope: global --- Commit subjects in imperative mood ("Add retry", not "Added retry"). No generated trailers. Reference the issue as `(#123)` at the end of the subject when one exists. ``` #### 3.3.3 `decision` Something that was decided, recorded so it does not get silently relitigated three sessions later. A decision's value is almost entirely in its `why` and its `rejected` alternative — "we use Postgres" is trivia; "we use Postgres *because X*, and we rejected SQLite *because Y*" is experience. Extra fields: | Field | Requirement | Meaning | |---|---|---| | `date` | SHOULD | When it was decided (ISO 8601). Merge recency key (4.2). | | `why` | SHOULD (strongly — see below) | The rationale. | | `rejected` | SHOULD | The alternative considered and rejected, and why it lost. | | `hidden` | MAY | `true` marks an absolute tombstone (4.3.1). | | `hidden_at` | MUST when `hidden: true` | When it was tombstoned. | | `superseded_by` | MAY | Link name of the decision that replaced this one. | `why` and `rejected` are *required-encouraged*: their absence is not a validation error (auto-captured decisions legitimately lack them at capture time), but interactive writers SHOULD prompt for both, and a decision entry without a `why` SHOULD be flagged by validators as a warning. A decision without a why is half a decision. > Naming note: the field is `rejected`, not `rejected_alternative` — this > matches every deployed store and the reference implementation's session > records. The longer name lost to reality. ```markdown --- type: decision name: Local store is SQLite, not Postgres description: Single-file embedded DB for the local cache; Postgres rejected date: 2026-05-02 why: Zero-dependency install matters more than concurrent writers for a per-user local cache. rejected: Postgres — better concurrency, but a daemon dependency in a CLI install is a support burden we measured and declined. --- Applies to the local derived cache only; the canonical store stays plain files per [[fact_staging-endpoints]] discussion. ``` #### 3.3.4 `lesson` A behavior correction learned from experience — usually from a mistake. A lesson is the format's most valuable and most structured type: it must say *when it applies* (`trigger`) and *what to do differently* (`how_to_apply`), or it is an anecdote, not a lesson. Extra fields: | Field | Requirement | Meaning | |---|---|---| | `trigger` | REQUIRED | The situation that should fire this lesson ("before deleting a directory", "when a test needs `$HOME`"). | | `how_to_apply` | REQUIRED | The concrete behavior change. | | `fired_count` | MAY | Integer ≥ 0. Times this lesson demonstrably fired and changed behavior. | | `last_fired` | MAY | ISO 8601 date-time it last fired. | `fired_count` / `last_fired` are the hook for the feedback loop (a later phase of this spec's roadmap): once tools report firings, lessons acquire an outcome record — which lessons actually prevent repeats, and which are dead weight a consolidation pass can retire. Writers MAY maintain them; readers MUST NOT require them. The body SHOULD carry the evidence: what happened, what it cost, why the rule is what it is. Established convention (predating this spec) renders these as bold-label sections — `**Why:**` and `**How to apply:**` — in the body; validators MUST accept `how_to_apply` expressed as a `**How to apply:**` body section in legacy entries (Appendix A). ```markdown --- type: lesson name: Rehearse destructive migrations on a copy first description: Never run a schema migration against the only copy of the data trigger: About to run a migration that drops, renames, or rewrites columns how_to_apply: Restore the latest backup to a scratch database and run the full migration train there first; only then touch the real one. created: 2026-04-11 --- **Why:** A rename-and-backfill migration was run directly against the only database; the backfill had an off-by-one and the pre-rename column was already gone. Recovery took a day. A five-minute rehearsal on a restored copy would have caught it. **How to apply:** Restore latest backup → scratch DB → run the FULL migration train → verify row counts → only then run for real. ``` #### 3.3.5 `goal` What the work is currently *for* — the standing objective that orients sessions. Goals are few (the reference implementation caps the live set at 3) and change rarely. Extra fields: `set_on` (SHOULD, ISO 8601 — merge recency key), `done_at` (MAY — temporal tombstone, same semantics as next_action, 4.3.2). ```markdown --- type: goal name: Ship v1 of the importer description: End-to-end import from the three legacy formats, behind a flag set_on: 2026-06-01 --- Done means: all three legacy formats round-trip in CI and the flag defaults on for new installs. ``` #### 3.3.6 `next_action` A concrete, resumable piece of work. Next actions are the handoff unit: the thing a different machine or session picks up. Extra fields: | Field | Requirement | Meaning | |---|---|---| | `added` | REQUIRED | ISO 8601 date-time the action was added. The temporal-tombstone comparison (4.3.2) is against this field; without it, completion semantics are undefined. | | `done_at` | MAY | ISO 8601 date-time it was completed. Presence marks the entry a temporal tombstone. | | `machine_id` | MAY | Machine that added it. | ```markdown --- type: next_action name: Add retry with backoff to the sync client description: Sync fails hard on transient 5xx; wrap in 3-try exponential backoff added: 2026-06-12T09:30:00Z --- Touch only `src/sync/client.js`. The failing case is a 503 mid-upload; there is a repro in `test-fixtures/sync-503.json`. ``` ### 3.4 Body conventions - `[[wikilinks]]` reference other entries by link name (filename without `.md`). Readers SHOULD resolve them within the store; unresolvable links are not an error. - Bold-label lines (`**Why:**`, `**How to apply:**`) are established body structure for lessons and MAY be used generally. They are convention, not syntax: readers MUST NOT require them (except as the legacy fallback in Appendix A). - Entries SHOULD NOT contain secrets. That rule's enforcement (scanning, redaction) is an implementation concern, not a format concern. ## 4. Session state file ### 4.1 Shape The session state file (`session.json`) is a single JSON document: the live working set plus a bounded history. It is the "hot" half of the store — small, rewritten atomically as a whole, merged structurally (never line-by-line). This section describes exactly what the reference implementation reads and writes; the machine-readable version is [`schema/session.schema.json`](../schema/session.schema.json). ```json { "version": 1, "created_at": "2026-04-18T08:22:36.703Z", "updated_at": "2026-08-06T21:10:03.001Z", "machines": { "": { "label": "work-laptop", "last_seen": "2026-08-06T21:10:03.001Z" } }, "current": { "goals": [ { "text": "...", "machine_id": "...", "set_on": "..." } ], "next_actions": [ { "text": "...", "machine_id": "...", "added": "..." } ], "parked_actions": [ { "text": "...", "machine_id": "...", "added": "...", "parked_at": "..." } ], "completed_actions": [ { "text": "...", "done_at": "..." } ], "completed_goals": [ { "text": "...", "done_at": "..." } ], "open_questions": [ { "text": "...", "machine_id": "...", "asked": "..." } ], "decisions": [ { "text": "...", "why": "...", "rejected": "...", "hidden": true, "hidden_at": "...", "machine_id": "...", "date": "..." } ] }, "history": [ { "date": "...", "machine_id": "...", "summary": "...", "files_touched": ["..."], "duration_min": 42, "session_id": "..." } ] } ``` Field notes: - `version` — integer schema version of this file (section 6). Note the asymmetry with entry files' `schema_version`; both names are kept because both are deployed. - `machines` — map of stable machine UUID → `{ label, last_seen }`. Machine identity is a UUID persisted per machine, paired with a human label (hostname) for display. Labels may change; UUIDs MUST NOT. - `current.*` — every item carries `text` (the identity key, 4.2) and the list's date field (`set_on` / `added` / `asked` / `date`). `machine_id` SHOULD be stamped by writers. - `completed_actions` — temporal tombstones for `next_actions` (5.3.2): `{ text, done_at }`. This list MAY be absent in files written before any completion occurred; readers MUST treat absence as empty. - `parked_actions` (v0.1.2) — the overflow of `next_actions`. When the live list is at its cap, the oldest actions (by `added`) move here rather than being discarded. A parked action is still *open*: it MUST be rendered (it may be rendered more compactly), it MUST be completable (completing it records the same `completed_actions` tombstone), and adding an action whose identity is parked MUST return it to `next_actions` rather than create a duplicate. `parked_at` records when it overflowed; `added` is unchanged and remains the merge and tombstone comparison key. This list has its own, larger cap; only when *it* overflows may an action be dropped, and an implementation SHOULD log that it did. MAY be absent. - `completed_goals` (v0.1.2) — temporal tombstones for `goals`, exactly as `completed_actions` are for `next_actions`, compared against `set_on` (5.3.2). Without them a retired goal returns on the next merge with any replica still carrying it. MAY be absent. - `open_questions` — captured questions awaiting an answer. (Draft note: there is deliberately no `question` *entry type* in v0.1 — questions have so far only proven useful in the live working set. If a portable form earns its keep, it becomes a seventh type in a later version.) - `history` — bounded roll-up of past sessions, newest first, deduplicated by `session_id` when present (v0.1.2; the same session updates its own row in place instead of adding one per write), otherwise by `(date, machine_id, summary)`. - **Bounded lists.** The live lists are capped (reference implementation: goals 3, next_actions 8, parked_actions 20, open_questions 5, recent decisions 10, completed tombstones 50, history 30). Caps are implementation-chosen QUALITY parameters, not format constants — but *some* cap is normative: the working set must stay loadable-into-context small, with rotation oldest-by-date-out. Rotation out of `next_actions` MUST go to `parked_actions`, not to nowhere (v0.1.2): the reference implementation silently discarded the oldest action for five months, and the loss was only noticed when three live items vanished in one week. A cap on the *visible* list is a rendering budget; it is not permission to forget. In particular the completed-tombstone retention MUST be large enough to outlive any stale replica that might still carry the completed item, or completions resurrect (5.3.2). Writers MUST write the file atomically (write temp file, rename) and MUST serialize concurrent read-mutate-write cycles (e.g. a lock file). Locking only the write is insufficient: two processes can both read the same stale snapshot before either writes. The entire read → mutate → write cycle is the critical section. Readers encountering unparseable JSON MUST NOT discard the file silently: quarantine the original (e.g. copy to a timestamped backup), then degrade to a safe empty state. ## 5. Merge semantics (normative) This section is the hard-won part of the format. Every rule here exists because its absence produced a real data-loss or data-resurrection bug in production. Implementations claiming Full conformance (section 8) MUST implement this section exactly. ### 5.1 Identity The identity of a session-list item is its **normalized text**: `text`, whitespace-trimmed, case-folded. Two items with the same normalized text are the same item. A purged decision tombstone (5.3.1) carries that identity as `text_hash` (SHA-256 of the normalized text) instead of the text. The identity of an entry file is its link name (filename). ### 5.2 Union, newest wins Merging two replicas (local and remote) of a session list: 1. **Union by identity.** The merged list contains every distinct identity from both sides. A merge MUST NOT drop an item merely because the other side lacks it — "never clobber." The only way items leave is cap rotation (oldest by date field, off the end) and tombstoning. For `next_actions` (v0.1.2) the union pools the live *and* parked lists of both sides, applies the tombstones, then re-splits: the newest N by `added` are live, the rest are parked (keeping any existing `parked_at`). A capped union of the live list alone evicts on merge exactly as silently as a capped append does. 2. **Newest wins per identity.** When both sides carry the same identity, the copy with the newer value in the list's date field (`set_on`, `added`, `asked`, `date`) wins wholesale. A missing or unparseable date compares as the epoch (loses to any real date). 3. `machines` merges per-UUID, keeping the entry with the newer `last_seen`. 4. `history` unions, deduplicates by `(date, machine_id, summary)`, sorts newest-first, and caps. 5. `created_at` takes the earlier of the two; `updated_at` the later. Entry files merge by the same principle at file granularity: union of files; same filename on both sides resolves by newest (`updated`, falling back to `created`), or by the user's VCS if the store is under one. v0.1 does not define intra-file three-way merge for entry bodies; that is what git is for. ### 5.3 Tombstones are sticky Deletion under union-merge is the hard problem: plain removal does not survive, because any replica still holding the removed item re-unions it straight back on the next merge. A conforming implementation MUST therefore represent removals as tombstones, and tombstones MUST be *sticky* — they propagate through merges. There are two classes, and the difference between them is deliberate. #### 5.3.1 Absolute tombstones (`hidden`) — decisions Setting `hidden: true` (with `hidden_at`) on a decision suppresses it permanently: hidden decisions are excluded from rendering and lookup but retained in the data so the tombstone keeps propagating. **Stickiness rule:** hidden is monotonic. If *any* copy of an identity on *either* side of a merge carries `hidden: true`, the merged copy carries `hidden: true` (and that copy's `hidden_at`) — **regardless of the date comparison in 5.2**. The winner-by-date inherits the tombstone from the loser if it lacks one. **Purged form.** A hidden decision MAY additionally have its `text` replaced by the literal `[purged]` (and `why` / `rejected` removed) and carry `text_hash`: the lowercase hex SHA-256 of the identity it replaces (the normalized text, 5.1). This exists for the case where the text itself must leave the file — a pasted credential, a client name — not merely leave the render. Readers MUST treat a purged tombstone as matching every decision whose identity hashes to `text_hash`, and on merge the purged form MUST win over any un-purged copy of the same identity regardless of `date`, so the redacted text never returns via a stale replica. Implementations MUST NOT purge without hiding; the hash is not an identity for a live decision. The date-independence is not an optimization; it is the correctness condition. Tombstoning legitimately does not touch the item's `date` (the tombstoned copy may well *lose* the newest-wins comparison), and a replica that has not yet pulled the tombstone holds an older un-hidden copy that would otherwise win or re-union. If hiding were just another field on whichever copy has the newer date, every un-synced replica would resurrect the item on its next merge, and the same junk would need re-hiding on every machine forever. Suppression must be monotonic or it is not suppression. #### 5.3.2 Temporal tombstones (`done_at`) — next actions Completing a next action removes it from `next_actions` AND records `{ text, done_at }` in `completed_actions`. Removal alone is insufficient for exactly the resurrection reason above — any stale replica (another machine, a backup, a long-lived process's in-memory copy) re-unions the finished item on merge. **Merge rule.** After the 5.2 union: 1. Union `completed_actions` from both sides by identity, keeping the newest `done_at` per identity, capped (newest-first). 2. Filter the merged `next_actions`: an action is suppressed if a tombstone with its identity exists **and** the action's `added` is not later than the tombstone's `done_at`. Unlike `hidden`, this tombstone is *temporal on purpose*: a copy whose `added` postdates `done_at` is not a stale straggler — it is a deliberate re-add of the same text after completion, and it MUST survive. "Fix the flaky test" can legitimately be finished and later added again. Decisions get absolute tombstones because a suppressed decision text is junk forever; actions get temporal ones because finished work can recur. Implementations MUST NOT substitute one class for the other. The same `done_at`-vs-`added`/`set_on` comparison applies to `goal` and `next_action` *entry files* that carry `done_at`, and (v0.1.2) to the session's `goals` list against `completed_goals`, compared on `set_on`. ### 5.4 Merge invariants (summary) For any replicas A and B: - **No silent loss:** every identity in A ∪ B is in merge(A, B), as a live item or a tombstone-suppressed one (up to cap rotation). - **Convergence:** merge is commutative and idempotent up to ordering — merge(A, B) and merge(B, A) render identically, and merging a replica with itself is a no-op. - **Monotone suppression:** once hidden everywhere-merged, hidden in every future merge; a completed action stays completed against every copy whose `added` predates its `done_at`. - **Unknown fields pass through (v0.1.2):** a merge MUST carry every key under `current` (and every top-level key) that it does not recognise, taking the local copy when both sides have one. A merger rebuilt from the keys it knows erases whatever a newer writer added — the reference implementation lost two goal retirements and a parked action minutes after those fields existed, to a push still running the previous version. Forward compatibility of the *file* (section 6) is not enough; the merge has to be forward compatible too. ## 6. Versioning - Entry frontmatter MAY carry `schema_version` (integer; absent = 1). The session file MUST carry `version` (integer). Both are governed by the same rules below. - This spec is v0.1 and describes data schema version **1**. - **Backward:** implementations MUST migrate older versions forward through a per-version ladder (a pure step from N to N+1 for each N), filling defaults for missing fields. Migration MUST NOT throw on malformed input; the worst case is a fresh empty state, with the original quarantined. - **Forward (normative — quarantine and degrade, never guess):** an implementation encountering a version **newer** than it understands MUST NOT attempt to interpret the data. It MUST preserve the original (quarantine — e.g. a timestamped backup copy), MUST degrade to safe behavior (an empty-but-valid state, or read-only), and SHOULD tell the user once to upgrade. A newer schema's fields may have semantics — tombstones especially — that an old reader would destroy by "mostly understanding" them. Merging is the dangerous path: a degraded read MUST contribute nothing to a merge rather than contribute a misreading. - Unknown *fields* at a known version are the extension mechanism and are NOT a version violation: readers ignore, writers preserve (3.2). ## 7. What this spec does not cover Deliberately out of scope — these are implementations' business, and competing on them is the point of an open format: - **Sync transport.** Git, object storage, a vendor cloud, a USB stick. The format defines what a correct merge produces, not how bytes move. - **Encryption at rest and in transit.** Stores are plain text; protecting them (client-side encryption before upload, disk encryption) is an implementation/deployment concern. - **Cloud services.** Accounts, auth, storage tiers, sharing links. - **Capture quality.** What is *worth* remembering, secret scanning, consolidation/deduplication passes, relevance ranking, embeddings. - **Rendering.** How entries and the working set are surfaced into an assistant's context (pinned blocks, system prompts, retrieval) is a competitive surface, not a format rule. ## 8. Conformance levels Three levels, cumulative. - **memoir Reader.** Can parse and render a store: frontmatter + body of every entry type, and the session file. MUST ignore unknown fields, MUST tolerate unknown entry types (render as opaque), MUST honor tombstone visibility (never display `hidden` decisions or completed actions as live), and MUST apply the forward-version rule (6) on read. - **memoir Writer.** Reader, plus can add and edit entries without corrupting the store: atomic session writes with a locked read-mutate-write cycle, preserves unknown fields on rewrite, stamps identity and date fields (`added`, `set_on`, `date`, `machine_id`), and never rewrites entries it was not asked to touch. - **memoir Full.** Writer, plus implements section 5 exactly: union-by-text with newest-wins, both tombstone classes with their stickiness rules, and the merge invariants of 5.4. A conformance claim names its level: "memoir Reader (v0.1)". ## 9. Security and privacy considerations A memoir store aggregates exactly the information an attacker would want: project internals, decision history, environment facts. Implementations SHOULD scan for and warn about secrets before any entry leaves the machine, and MUST NOT transmit store contents anywhere without explicit user configuration. The format's plain-text nature is a privacy *feature* — the user can always audit precisely what their AI knows — and implementations should preserve that auditability rather than obscure it. --- ## Appendix A: Legacy dialects (informative) The format formalizes a convention that grew in the wild, and existing stores predate it. A survey of one long-lived production store (326 entry files, April–August 2026) found: - **Two frontmatter dialects.** About half the files carry `type` as a top-level key; the other half nest it as `metadata.type` (often with `metadata.node_type: memory`). `originSessionId` likewise appears both top-level and nested. - **Bare files.** ~6% have no frontmatter at all — plain markdown with an `# H1` title. - **Legacy type vocabulary.** Deployed values are `user`, `feedback`, `project`, `reference` — not the six types of this spec. - **Body-borne lesson fields.** Legacy `feedback` entries carry the trigger in `description` and the application rule as a `**How to apply:**` body section, not as frontmatter keys. Conforming Readers SHOULD apply these compatibility rules when reading pre-v0.1 stores, and validators SHOULD downgrade the corresponding errors to warnings for legacy-dialect files: | Legacy | Read as | |---|---| | `metadata.type: X` | `type: X` | | top-level `originSessionId` / `metadata.originSessionId` | `origin.session_id` | | `type: user` | `preference` | | `type: feedback` | `lesson` (trigger ← `description`; how_to_apply ← `**How to apply:**` body section) | | `type: reference` | `fact` | | `type: project` | no atomic mapping — a project *dossier* aggregates many would-be entries in one file; read as an opaque legacy entry | | no frontmatter | opaque legacy entry; `name` ← first `# H1` | Writers MUST NOT emit legacy dialects for new entries. Rewriting legacy files into canonical form is an implementation choice (a consolidation pass), not an obligation — a Reader must handle both indefinitely. ## Appendix B: Relationship to the reference implementation (informative) memoir-cli (npm) implements: session state exactly as section 4 at `~/.config/memoir/session.json` (schema version 1); the merge semantics of section 5 in its cross-machine sync (`mergeSessions`); the forward-version quarantine of section 6 (`.pre-migration-` backups, degrade to empty); and `memoir validate`, a structural checker for both file kinds against this spec. Entry-file writing currently passes agent-authored markdown through verbatim — validation, not generation, is where the convention is enforced. ## Appendix C: Changes - **v0.1.2 (2026-09-04)** — additive. `parked_actions`: overflow from the live next-action list is parked, rendered and completable, never dropped (4.1); merge pools live + parked and re-splits (5.2). `completed_goals`: temporal tombstones for goals (5.3.2). `history[].session_id` for in-place session rows (4.1). New invariant: unknown fields pass through a merge (5.4). Shipped in memoir-cli 3.13.x. Motivation, all first-party: three live next-actions silently evicted in one week by a `slice(-8)`; a goal set in June still pinned in September because nothing could retire it; and the new fields themselves erased by an older build's merge on the day they shipped. - **v0.1.1 (2026-08-18)** — additive. `aliases` common frontmatter field (3.2). Purged form of the absolute decision tombstone: `[purged]` + `text_hash`, hash-matched and merge-winning (5.1, 5.3.1). Both shipped in memoir-cli 3.12.0 (`memoir_remember aliases:`; `memoir forget [--purge]`). Motivation for the first: a real retrieval failure where a shipped surface was findable only by the exact words its one memory happened to use. For the second: nothing shipped could create an absolute tombstone at all (thanks to the agent-memory-atlas review for stating it that plainly). - **v0.1 (2026-08-06)** — first public draft. Extracted from memoir-cli 3.10.x behavior. Seeking implementations and critique: https://github.com/camgitt/memoir/issues