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. Extracted from a working implementation, not designed on a whiteboard.

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 it accumulates anywhere you can take with you. Email had the same problem and solved it with open formats (mbox, Maildir, IMAP). The memoir format is that seat for AI working context.

What it covers

A memoir store is a directory of markdown entry files plus one session state file. Six entry types, each keyed to what a tool should do with it on load:

# entry types
fact         # stable truth about the user/project
preference   # how the user wants things done
decision     # what was chosen — with why + the rejected alternative
lesson       # trigger + how_to_apply; a mistake that must not repeat
goal         # current objective
next_action  # work item; done_at tombstones survive merges

The normative core is the merge semantics: union by text, newest wins, and two deliberately different tombstone classes -- learned from production resurrection bugs, not invented. Plain markdown and JSON on disk is a feature: human-readable, git-diffable, owned by the user.

Read it, validate against it

The full specification, JSON Schemas, and conformance levels (Reader → Writer → Full) live in the repository:

# the spec and schemas
github.com/camgitt/memoir → docs/SPEC.md

# validate any store against it
npx memoir-cli validate

Status

Draft v0.1, seeking implementations and critique. Where the document and shipped behavior disagree, that is a bug in the document -- file it. The reference implementation is memoir (MIT).