Remem by Acific Labs

The Remem protocol (draft 0)

Last verified against the code: 2026-11-13 (0.9.0). Implemented: §0 events, §1 lessons, §2 provenance with Ed25519 signatures, §3 the merge rule within one memory (candidates, corroboration, confirmations, revocation), §4 rule 1, §5 the folder and commons transports. The rest is the design from the paper §5, written down so it can be argued with.

The protocol is what makes Remem 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.

0. The event (implemented, 0.3.0)

How any agent, model or tool reports a surprise to Remem. One JSON object; JSON Lines for many. Sent through the MCP remember tool, POST /memory/remember on the proxy, remem ingest --events, or appended to ~/.remem/inbox.jsonl.

Field Type Meaning
kind correction | error | environment | surprise | note Required
said string A correction: the person's words, verbatim. Never paraphrased
agent_did string A correction: what the agent had just said or done (an offer to act is recognised in it)
title string An error: the call that failed
expected, happened string What the agent expected, and what it met
text string A note
agent, session, cwd, at string Who, which conversation, which project, when (ISO 8601)

An event is stored once (the same agent, session, kind and title); readers ignore unknown fields. An event is raw stream: it stays on the machine. Only lessons (§1) ever move.

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 | surprise 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 (implemented: 0.4.0, signatures 0.5.0)

Fields a shared lesson adds, and the other records on the wire (remem share):

Field Meaning State
v Wire version, 1 implemented
hash BLAKE2b-128 of kind + the lowercased, space-normalised text: the lesson's identity across agents. A receiver recomputes it and refuses a mismatch implemented
origin The publishing memory's id: the first 8 bytes of SHA-256 of its Ed25519 public key, hex (16 characters) implemented
key The publishing memory's Ed25519 public key, hex implemented
sig Ed25519 signature, hex, over the record without sig, serialised as JSON with sorted keys, no spaces, UTF-8. Records travel as exactly that line with sig included, so a verifier can cut sig out of the bytes it received instead of re-serialising implemented
parents Hashes of lessons this one merged from designed
{"confirm": hash, "origin"} A record saying a lesson came true in the sending memory, which did not publish it implemented
{"revoke": hash, "origin"} The origin withdraws its lesson; holders drop it implemented

Source episodes are not in the hash (implemented): two memories never share episodes, and the same sentence written by two of them must be one lesson.

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 (implemented locally in 0.4.0; the commons states designed)

Implemented: a received lesson is a local candidate (strength 0.5, always predicting); its confirmation in the receiving memory's own sessions raises it and is sent back; a corroboration (the same hash, or the same meaning by average linkage, from another origin) raises the local lesson. Designed: the commons-wide states below.

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 (folder and commons implemented, gossip designed)

Implemented: a folder (DIR/<origin>.jsonl, carried by anything that syncs files) and the commons (https://remem.acific.com/commons/): PUT /commons/<origin>.jsonl replaces a memory's file and is accepted only when every line is signed by the key whose fingerprint is <origin>; GET /commons/<origin>.jsonl reads one; GET /commons/index lists {origin, updated, records}. At most 1,000 records and 256 KB per memory. A bearer token is required until launch. Receivers check every record themselves (§4); the server only checks who wrote it.

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