OpenMemory

The Open Memory protocol (draft 0)

Last verified against the code: 2026-10-21 (first commit). Only §1 is implemented (lessons.jsonl); the rest is the design from the paper §5, written down so it can be argued with.

The protocol is what makes Open Memory open: the format of a lesson, how it moves, and the rule by which it becomes common knowledge. It is meant to be small enough to fit on one page and strict enough to be safe.

1. The lesson (implemented)

One JSON object per line, UTF-8, in lessons.jsonl:

Field Type Meaning
id string Local identifier
text string The lesson. An observation, never an instruction.
kind error | correction What kind of surprise it came from
seen integer How many surprises it has absorbed
strength number Its current weight
updated ISO 8601 When it last changed

Readers ignore unknown fields; writers never remove or rename one. Nothing from the raw stream appears: no transcript text, paths, commands, names or outputs beyond what the lesson sentence itself says.

2. Provenance (designed)

Fields a shared lesson adds:

Field Meaning
hash BLAKE2b of text + the sorted hashes of its source episodes: the lesson's identity across agents
origin The publishing agent's public key fingerprint
sig The origin's signature over hash, text, kind, updated
parents Hashes of lessons this one merged from, when two lessons were found to be the same

Two agents that meet the same surprise and write the same sentence produce the same hash: the commons deduplicates by content, and the second agent's publication is a verification, not a new lesson.

3. The merge rule (designed)

A lesson has a state in the commons:

State Meaning Transition
candidate Published by one agent → common after N independent confirmations (N = 3 proposed)
common Verified → fading when confirmations stop for W days (W = 90 proposed)
fading Losing strength → removed, or back to common on a new confirmation
revoked Withdrawn by its origin, or by a quorum Propagates like a lesson; every holder drops it

A confirmation is an agent's sleep reporting that a prediction made from the lesson was confirmed by that agent's own sessions, where that agent did not itself publish the lesson and had not met the surprise before receiving it. The verification is the normal verify pass; it costs nothing extra.

4. Safety rules (designed, the first one implemented)

  1. A lesson is an observation, never an instruction. Imperative lessons are rejected at write, at receive and at merge. No agent ever acts because a lesson says to; it acts because it decided to, with the lesson in mind.
  2. Nothing raw moves. Episodes, transcripts and screens never leave the machine. Lessons are published only by opt-in, per project.
  3. Everything is signed and hashed. A lesson without a valid signature is dropped. A revocation is signed by the origin or by a quorum of confirmers.
  4. The personal layer is sovereign. Lessons about the person (corrections) are never published by default; only error lessons are. The commons is what everyone knows; who an agent is stays its own.
  5. Readable all the way down. Any holder can show a person every lesson it holds, where each came from, and who confirmed it.

5. Transport (designed)

Lessons move as files first (lessons.jsonl copied between machines or checked into a repository), then by gossip: each agent exchanges its new lessons and confirmations with a few peers on each sleep. Logarithmic in the number of agents; no center required. A directory of peers is a convenience, not a dependency.

6. Composition (designed)

An agent runs with layers, each a lessons.jsonl: common → domain (a language, a tool, a codebase) → personal. Higher layers never overwrite lower; an agent sees the union and the strongest instance of a duplicate.

7. What is deliberately not in the protocol