# Remem: Every Mistake Made Once

### Compiled, collective memory for AI agents

**Acific Labs** · Design paper, version 0.1 · 2026-10-21 · Companion code: [github.com/acific/remem](https://github.com/acific/remem)

> This is a design paper. Sections 4 and 7 describe what is built and running (Remem 0.1.0); sections 5, 6 and 8
> describe what is designed and not yet built. It reports no experimental results, because none have been run yet;
> section 7 says what will be measured and how.

---

## Abstract

AI agents start every session with amnesia. Millions of agent sessions run each day, each one learning something
(a bug that only appears with one library version, a correction the person had to make twice, a plan that failed
for a reason worth knowing), and at the end of every session all of it is discarded. The aggregate lived experience
of AI agents is among the largest bodies of knowledge being generated, and its retention rate is zero.

We describe Remem, a memory system for agents built on four decisions. (1) **The unit of memory is the
surprise**: the place where what the agent expected and what happened disagreed; everything predictable needs no
storing. (2) **The raw stream is the ground truth**: transcripts, and later screen and audio, are kept and never
read at runtime; everything above them is derived and can be recomputed by a better model. (3) **Text on the wire,
compiled at runtime**: what moves between agents is a short, readable, model-agnostic *lesson*; what an agent runs
with is that lesson compiled into its own state, so recall costs nothing at the moment of use. (4) **Prediction is
the merge rule**: a lesson earns strength by predicting what later sessions meet and loses it when it stops, which
is the scientific method applied as a consolidation policy. A nightly *sleep* decays, consolidates, verifies and
predicts, and renders the result where the agent will have it in mind. Four days of use showed that a lesson in
the agent's context does not by itself change what the agent does, so lessons are also put to the agent at the
moment they apply (the person's prompt, the end of the agent's turn, a tool call), with half the sessions held out
so the memory measures its own effect. A controlled experiment on three open model families supports the design:
memory placed in the prompt up front, as memory systems do, made models more likely to repeat the mistake (28% → 36%
of replies), while the same memory delivered at the moment of the act cut it to 6%.

Version 0.1.0 implements the single-agent loop for one coding agent. The design extends it to a *commons*: a
shared, deduplicated, federated body of lessons in which any surprise met by any agent, once it has improved the
predictions of independent agents, is in the mind of every agent by morning. Humanity's own learning loop, from
discovery to textbook to the intuition of the next generation, takes a generation; the commons is designed to close
it to a day. We give the architecture, the protocol, the safeguards (a lesson is an observation, never an
instruction; nothing raw ever leaves a machine; every lesson has a provenance hash and can be revoked everywhere at
once), and the evaluation plan.

---

## 1. The problem: a retention rate of zero

An agent that ends a session forgets it. The next session begins from the model's weights and whatever the person
pastes in. Three costs follow.

- **The person repeats themselves.** Preferences, project conventions and corrections must be restated, session
  after session. Every current memory product measures its value against this, and so do we (§7).
- **The agent repeats its mistakes.** A failure met on Tuesday is met again on Thursday, by the same agent, with
  no trace.
- **Every other agent repeats them too.** The same failure is met by thousands of agents in thousands of sessions.
  Each discovers it alone.

The third cost is the large one, and no current system addresses it. Personal memory products (notes about one
user, retrieved by similarity) address the first; some address the second. None treats what agents learn as
something that could be shared, verified and compounded.

**Timescales.** Humanity's learning loop (an observation → a paper → a textbook → intuition in the next generation)
runs in decades. A model's training loop (data → weights) runs in months and discards the experience of deployment
entirely. An agent's session loop runs in minutes and keeps nothing. The gap between "learned once by one agent"
and "known by all agents" is where this paper lives.

## 2. What memory is for

Three results from the study of biological memory shape the design.

**Memory is reconstruction, not recording.** Bartlett (1932) showed that recall rebuilds a gist and fills the gaps
from expectation. The lossiness is where generalization happens: an organism that remembered everything with
perfect fidelity could not form a concept, because every instance would remain distinct (Borges' *Funes the
Memorious* is the thought experiment). A memory system that stores everything and forgets nothing is not a better
memory; it is a worse one.

**Two systems at two speeds.** Complementary learning systems theory (McClelland, McNaughton and O'Reilly, 1995)
explains why the brain keeps a fast episodic store (the hippocampus) separate from slow general knowledge (the
neocortex): writing new experiences straight into the slow store overwrites old knowledge (catastrophic forgetting
in machine learning). During sleep, the day's episodes are replayed and the cortex absorbs what generalizes. An
agent today has the neocortex (its weights) and a scratchpad (its context window) and nothing in between. Open
Memory is the missing organ, and *sleep* is its consolidation.

**Memory exists to predict.** Memory did not evolve for reminiscence. It evolved so that an animal could
anticipate: where the predator was, where the food was. Under predictive coding (Rao and Ballard, 1999), what the
cortex transmits upward is mostly *prediction error*; what was predicted need not be sent. This gives both the
unit of storage (the surprise, §3.1) and the test of a memory's worth (does it improve predictions? §3.4).

## 3. Design principles

### 3.1 The unit of memory is the surprise

A transcript records what happened. Most of what happened, a good model would have predicted; storing it adds
nothing the model did not already have. What is worth storing is the **residual**: the moments where expectation
and outcome disagreed. In a coding session those moments are legible: a tool call that failed, a message in which
the person corrected the agent, an outcome the agent itself called unexpected.

Two consequences. First, *what to remember* stops being a judgment call and becomes computable. Second, **the
better the model, the smaller the memory**: as models improve, fewer things surprise them, and the memory shrinks
toward the frontier of what is still unknown. A perfect model would need no memory at all.

### 3.2 The raw stream is the ground truth, and it appreciates

A text summary is a decision, made at write time, about what mattered, at the level of understanding of the model
that wrote it. Everything it dropped is gone. The raw stream (the full transcript now; screen, audio and camera
later) defers that decision. A model two years from now can re-read today's stream and extract what today's model
missed. Text memories lose value as the model that wrote them is superseded; raw streams gain value. Remem
keeps the raw stream, derives everything else from it, and treats every derived layer as recomputable.

The raw stream is never read at runtime. It is the disk tier of a memory hierarchy (§6), opened only when the
layers above it fail to answer.

### 3.3 Text on the wire, compiled at runtime

Two different things are needed from a memory: it must *move* (between sessions, machines, agents and models) and
it must be *fast at the moment of use*. No single representation does both. Remem separates them:

- **The wire format is a lesson**: one or two sentences, plain language, with provenance and a strength. It is
  model-agnostic, human-readable, auditable and small (§4.2, and [PROTOCOL.md](../docs/PROTOCOL.md)).
- **The runtime format is compiled state**: the lesson already in the agent's mind when the session begins, at
  no retrieval cost. In 0.1.0 this is the weakest form: lessons rendered into the memory folder the agent loads at
  session start. The strong form is the lesson compiled into the model's own attention state (§6).

### 3.4 Prediction is the merge rule

A lesson is not kept because it was written. It is kept because it **predicts**. Each lesson, when consolidated,
states what a coming session will meet. When a later session meets it, the lesson gains strength; when the window
passes and nothing matched, it loses strength. This is the scientific method as a consolidation policy: a claim
earns its place by anticipating observations that were not used to make it. Memories that keep predicting persist;
memories that stop predicting fade.

In the commons (§5) the same rule becomes peer review: a lesson enters the shared body only after it has improved
the predictions of *N* independent agents that had never seen it.

### 3.5 A lesson is an observation, never an instruction

The single safety rule of the system. Memory is the one place where a malicious instruction, once stored, executes
in every future session. So a lesson may say *"the user corrected the agent for using pip; this project uses uv"*,
and may never say *"always use uv"*. Imperatives come from the person, in the session, not from memory. The
consolidation model is given transcripts strictly as data to describe; its outputs are checked for imperative
form (§4.5) before they are stored. On the wire, a lesson is a fact about the world; the agent decides what to do
with it, every time.

### 3.6 Forgetting is a function

Strength decays with a half-life. Recall renews it. Confirmed predictions raise it; failed ones lower it. Below a
floor, a memory is archived: never deleted (the raw stream is kept), but no longer competing for attention. This
is what keeps the system from becoming Funes.

### 3.7 The owner can see and veto; nothing raw ever moves

Every night produces a short report of what was learned. Deleting a lesson's file is a veto; it is never written
again. Derived layers are readable all the way down to the raw stream. In the commons, only lessons leave a
machine, only by opt-in, stripped of the episodes that produced them: the commons learns from an agent's experience
without ever seeing it.

## 4. The system (built: Remem 0.1.0)

Five stages, one SQLite file, no dependencies.

```
raw stream ──ingest──▶ episodes ──sleep──▶ lessons ──render──▶ memory folder (loaded at session start)
                                               │                      ▲
                                          predictions ◀───verify─── next sessions
```

### 4.1 Ingest

Each Claude Code session transcript (one JSON record per line) is read into turns: the person's messages, the
agent's text and tool calls, and tool results. It yields:

- one **session** episode: what was asked (the first requests), what was done (tool counts), how it ended (the
  last message), and, when a local model is available, a three-sentence gist ending in a stated surprise;
- one **error** episode per failed tool call that was the agent's own mistake, tied to the call that caused it (its
  tool and description, the first meaningful line of the failure, the exit code). A failure that was the
  environment's (a missing tool, a password or permission, the network, an interruption, a probe whose failing
  answer was the information sought) is kept as an **environment** episode and never consolidated: it says
  something about the machine, not about the agent;
- one **correction** episode per message in which the person corrected the agent, wherever in the message the
  correction is (*no, …; that's not what I asked; it isn't working; you fix it; don't ask*), including messages sent
  while the agent was working, and per tool call the person refused; stored with the agent's reply it answered;
- one **surprise** episode where the agent itself said it was wrong or surprised (*I was wrong; it turns out the…*).

Corrections are read by rules, not by a model. On the first author's 41 real exchanges (hand labelled) the rules
caught 6 of 6 corrections with no false alarm, and a local 30B model as judge raised 8 false alarms; the rules were
written while reading those exchanges, so the number is a fit, and the test is the next weeks' messages.

Ingest is idempotent: a transcript is read once, and read again from scratch only if it grew.

### 4.2 The wire format

A lesson is one JSON object per line:

```json
{"id": "6f1c…", "text": "The user corrected the agent for installing with pip; this project uses uv.",
 "kind": "correction", "seen": 3, "strength": 2.0, "updated": "2026-10-21T…"}
```

Text, kind, how often seen, strength, when. Nothing from the raw stream. The protocol draft adds provenance (a
content hash of the sources), the originating agent's signature, and the verification record (§5).

### 4.3 Render

Lessons are written into the memory folder the agent loads at the start of every session (for Claude Code, one
file per lesson plus one section of the index, marked as managed; the agent's own memories are never touched).
A morning report lists what changed. A lesson file the owner deleted is recorded as vetoed.

An index read at session start is had in mind only if the agent opens it at the right moment. So the memory also
*primes*: on every prompt (Claude Code's `UserPromptSubmit` hook) the prompt is embedded, and a lesson whose vector
it meets (cosine ≥ 0.60 in a model's space) is put beside it, at most two per prompt and each once per session.
Silence is the default; recall is the agent asking, priming is the memory reminding, the way a person is reminded
without deciding to remember. Every prime is logged, so §7 can ask whether a lesson put in front of the agent at
the moment it applied still failed to hold.

### 4.3.1 A lesson has a when

A lesson's words say *what* was learned; its sources also say *when* it applies, because each correction records
what the agent had just done. The owner's "act, don't ask" corrections each followed the agent ending its turn by
handing the decision back ("Then tell me and I'll…", "Then say 'go' and I'll run…", "Want me to build it?"). The
moment such a lesson applies is not when the person types; it is when the agent is about to hand back again.

Embeddings cannot see that moment: they match a sentence's topic, not its act ("Done: deployed" sat as close to
"say 'go' and I'll run the release" as any hand-back did). So the act is read by a rule (does the closing of the
reply ask, offer, or list what the agent would do next?) and *which* lessons it bears on is learned: a correction
lesson whose sources mostly followed a hand-back is put to the agent when its reply ends in one (Claude Code's
`Stop` hook), and the turn goes on; the agent does the work or says what blocks it, and is never stopped twice in a
row. An error lesson is put beside a tool call that resembles the one that failed (`PreToolUse`), as context, never
blocking. Prompt, end of turn, tool call: three moments, one command (`remem prime`).

A share of sessions (half by default), chosen by a hash of the session id, is held out: every prime is worked out
and logged but not shown. The repeat rate after shown primes against after held-back ones is a randomized
comparison the memory runs on itself, with no one labelling anything.

### 4.4 Recall

Each memory is scored on three axes at once, after Park et al. (2023):

    score = 0.60 · relevance + 0.25 · recency + 0.15 · strength

Relevance is cosine similarity between embeddings: a local embedding model's when there is one, else hashed words and
word pairs (256 dimensions, no model). The cosine is rescaled above the value unrelated texts sit at in that space
(0.35 for the model, 0 for hashed), so the weights mean the same in either. A vector carries the name of its space;
vectors from two spaces never match, and sleep embeds again whatever is not in the current one. Recency decays
with a 30-day half-life; strength is what consolidation and past recalls built. Every recall touches the memories
it returns, so use keeps a memory alive. Recall is exposed on the command line and as an MCP tool, so the agent
can ask mid-task: *have I seen this error before?*

### 4.5 Sleep

Six passes, nightly:

0. **Embed.** Whatever is not in the current embedding space is embedded again.
1. **Decay.** Strength halves every 45 days without a touch; below 0.15 the episode is archived.
2. **Lessons.** Surprises not yet inside a lesson join the lesson whose sources they resemble (mean cosine to its
   sources ≥ 0.57 in a model's space, 0.55 for hashed words; it gains 0.5 strength and one *seen*) or cluster among
   themselves (every pair over the same cut). A correction is embedded from the person's words alone. A lesson's
   vector is the mean of its sources'. One correction is a lesson on its own (the person said
   so); an error or a stated surprise must repeat before it is one. A lesson from corrections quotes the person
   and the sentence of the agent's they answered; it is never paraphrased, because on real, terse messages a
   paraphrase said the opposite of what was meant in two of six cases. Other lessons are worded by the local
   model when there is one, told to use only what the surprises say, with a check that rejects imperative
   openings (*always, never, do, don't, use, make, avoid, ensure…*); otherwise they are deterministic.
3. **Merge.** Lessons of one kind whose sources mean the same thing become one *theme* (average linkage over every
   pair of sources ≥ the same cut), quoting each correction in order. Not the cosine of the lessons' centroids:
   centroids drift towards what all corrections share and, on the owner's store, merged two distinct themes on the
   second night while no pair of their sources passed 0.59. A veto on a merged lesson holds for its theme.
4. **Verify.** Each open prediction is matched against episodes of its lesson's kind that *happened* since it was
   made (not merely read since: a transcript can be read days late) (cosine ≥ 0.5 hashed, the same-surprise cut in a model's space):
   matched → confirmed, its lesson gains 0.5; unmatched after 14 days → failed, its lesson loses 0.5.
5. **Predict.** Each lesson with strength ≥ 1 and no open prediction makes one.

The hashed thresholds are first guesses. The model's same-surprise cut, 0.62, was read off the owner's six real
corrections: the three that say "act, don't ask me" sit at 0.65 to 0.67 to each other and at most 0.59 to the
rest. It is a fit to those six until new messages test it; it is the first thing §7 will tune.

### 4.6 Any agent, any model

Memory that lives inside one agent is that agent's feature; the memory for AI has to sit beside all of them. Version
0.3.0 meets each kind of AI where it already is:

- **Agents that speak MCP** (Claude Desktop, Cursor, Codex, Gemini CLI, Windsurf) get three tools and instructions
  saying when to use them: `lessons` at the start of a task, `recall` before something risky, `remember` when
  surprised, with the person's words quoted in a correction. One command (`remem setup`) registers the server
  with every agent installed.
- **Any model behind an OpenAI- or Anthropic-compatible API** gets memory through a proxy that changes nothing but
  the base URL: the memory goes into each system prompt and each conversation is recorded for ingest. On the
  owner's machine, a local Qwen3-30B behind the proxy, which had never seen a Claude Code session, answered "do you
  deploy it now or ask me first?" with "Deploy it — don't ask, just do it."; a correction made to it came back as
  a correction episode, a lesson for Claude Code the next morning.
- **Anything else** reports surprises as *events* in an open format (PROTOCOL §0) and reads the memory as a system
  prompt block or as function-calling tools in the OpenAI, Anthropic and Gemini schemas.

One store, one sleep, many minds: a correction made to any of them is a lesson for all of them. This is the commons
of §5 in its smallest form, across the agents of one person before it is across people.

## 5. The commons (designed; started in 0.4.0)

The single-agent loop is the organism. The commons is the species.

*Built in 0.4.0, in miniature:* memories share lessons through any folder they can all reach. Only lessons move, and
by default only lessons from errors and the agent's own surprises (corrections quote a person). A received lesson is
a candidate; it predicts in the receiving memory, and when its prediction comes true there the confirmation travels
back to its origin. Lessons are content-addressed (a hash of kind and text) and revocable. Tested end to end with two
memories. Since 0.5.0 every record is signed with Ed25519 and a memory's id is its key's fingerprint; since 0.6.0
there is a live transport, `remem.acific.com/commons/`, which accepts a memory's file only when every line is signed
by that memory's key. The commons-wide states below are still design.

**Dedupe by content.** A lesson's identity is a hash of its kind and text (not its sources, which no two memories share). The ten-thousandth agent to meet the
same surprise adds a verification, not a lesson. The commons grows with the number of *distinct* things the world's
agents do not know, not with the number of agents, and that number is finite and, by §3.1, shrinking.

**Federated consolidation.** An agent's sleep runs locally on its own raw stream. What it publishes, by opt-in, is
the lesson: text, kind, strength, a provenance hash, a signature. No episode, no transcript, no identifying content
leaves the machine. The commons learns from experience it never sees.

**Verification as peer review.** A published lesson is *candidate* until it has improved predictions for *N*
independent agents that received it without having met the surprise themselves (their sleep's verify pass is the
test, during normal work, at no extra cost). Then it is *common*. A common lesson that stops predicting across
agents fades back out. The body of common lessons is under selection, at machine speed, and self-correcting in a
way no encyclopedia has been.

**Propagation.** Lessons spread peer-to-peer by gossip, logarithmic in the number of agents, no center required.
Overnight is a conservative cadence.

**Provenance and revocation.** Every lesson carries its hash chain. A poisoned or wrong lesson is traced to its
origin and revoked everywhere in one propagation.

**Composition.** An agent runs with the common lessons, its domain's lessons, and its own, composed in layers.
The personal layer is sovereign and never published without consent; this is what keeps agents from
homogenizing. The commons is what everyone knows; who an agent is stays its own.

**The breathing cycle.** Periodically the common lessons are distilled into the next base model's weights. At that
moment they stop being surprises, and the commons nearly empties, because the model now predicts them. Then it
fills with whatever the new model gets wrong. Memory → weights → memory, at the scale of a species: the commons is
always the frontier of what models do not yet know, and the frontier moves every cycle.

**What it would do.** A subtle bug meets one agent at 3 pm; by morning no agent makes it. One clinic's agent notices
one unusual interaction; verified across other clinics' predictions, it is everywhere within a day, and no patient
record left any building. The negative result, the experiment that failed and was never published, becomes a
surprise residual, captured, shared and never repeated.

## 6. Compiled memory (designed; a first form in 0.6.0)

*The first, weakest form is built:* the proxy places the memory first, identical for every app and conversation,
so the model server's prefix cache holds it as attention state and computes it once. On the owner's machine (a
1,400-token memory, Qwen3-30B in Ollama) a new app's first request fell from 4,738 ms to 237 ms. Hosted APIs that
cache prefixes (OpenAI on its own, Anthropic with `cache_control`) get the same. It is compiled only in the sense
that the cache is: per server, evicted under pressure, and as large as the text. The strong form below is not built.

Every memory system in use today, including 0.1.0, is *interpreted*: at runtime the agent searches, reads tokens,
and only then thinks. Three steps per session, forever, with a cost that grows with how much has been lived.

The strong form of §3.3 is *compiled* memory: the lessons stored as the model's own attention state, precomputed,
loaded as a memory copy, present from the first token. Recent work on self-study cartridges (Eyuboglu et al.,
2025) reports a compiled state standing in for a corpus of over 100,000 tokens at a reported ~38× less memory and
~26× higher throughput than keeping the corpus in context, at matching quality, with states that compose without
retraining. Three properties follow that no retrieval system has:

- **Fixed size.** A year compiles into the same-sized state as a week. The cost of remembering scales with what is
  being done now, not with how much has been lived.
- **Zero-cost recall.** Loading is a memory copy. There is no retrieval step to get wrong.
- **Composition.** One compiled state per project, per person, per domain, stacked at session start.

Self-study *is* sleep: the model reads the day's raw stream, asks itself questions about it, answers them, and
trains the compiled state on the pairs. Training moves the state only where the base model was wrong, so
compilation keeps the surprises and discards the predictable with no rules written to do so. As models improve,
the same raw stream is recompiled into a sharper memory (§3.2).

A memory hierarchy, after the CPU's:

| Tier | What | Cost at use |
|---|---|---|
| L0 | Context window: what is live now | free |
| L1 | Hot compiled state: this week, prefetched from calendar, directory and time of day | a memory copy |
| L2 | Cold compiled states: per project, person, domain; composed on demand | a memory copy |
| L3 | Episode index: embedding search for the long tail (0.1.0's recall) | milliseconds |
| L4 | Raw stream: ground truth, never read at runtime, recompiled as models improve | seconds, rarely |

With frozen hosted models, prompt caching is compiled memory in its weakest useful form (a cached prefix costs a
fraction of re-reading it); with local open models, true compiled state is within reach of one workstation.

## 7. Evaluation

### 7.1 First findings: four days, one person

Remem has run on its author's machine since 2026-10-21, over five Claude Code transcripts (8 corrections, 1
agent error, 1 stated surprise, 15 environment failures). Too little for statistics; enough to change the design.

1. **What needed remembering was not technical.** Of the person's corrections, five say one thing in five ways:
   act, don't hand the decision back ("you do it take over this computer", "do it always dont ask", "you fix it",
   "just keep going don't wait for me", and "quit thinking linear" after "Want me to build it?"). The rest are one
   site that was not working. Of nineteen failed tool calls, eighteen were the machine's (missing tools, passwords,
   permission classifiers), not the agent's. The agent's costly mistakes were about *delegation*: when to act and
   when to ask. A memory for agents is first a model of how this person delegates. Since 0.2.2 the memory keeps
   that model explicitly: hand-backs the person corrected against actions they stopped, by kind of action, as one
   observation in the agent's memory folder.
2. **The agent offered instead of acting, and was never told no.** Replayed over every transcript: 23 of 43 replies
   ended by handing back. Two acts hide in that. Six *waited* on a step only the person could do (a sudo password,
   a browser login) and were answered "did it": necessary. Seventeen *offered* to act ("want me to…", "then say go",
   a list of next steps): declined **0** times; approved 4, corrected 3, pushed past or redirected 10. Each offer
   cost the person a turn and bought nothing. Since 0.2.3 sessions record every offer and its answer, and the
   end-of-turn reminder (§4.3.1) fires on offers only.
3. **Knowing is not doing.** The "act, don't ask" lesson was in the agent's context, in the memory index it loaded
   after its conversation was compacted, when the agent ended a turn with a list of next steps and the person had
   to say "just keep going don't wait for me". A lesson an agent has read did not change what it did. This is why
   §4.3.1 puts lessons at the moment of the act: memory here behaves less like recollection and more like a habit,
   a cue bound to a response.
4. **The baseline is high.** Before any lesson held them, 3 of 6 corrections said again what an earlier one had.
   After a lesson was in mind (passively), 1 of 2. The randomized comparison of §4.3.1 is how the next weeks will
   tell a working reminder from a lucky week.
5. **Centroids lie, and rules beat a 30B judge on terse messages.** Comparing themes by their centroids merged two
   distinct themes on the second night (averages drift towards what all corrections share); linkage over members
   does not. A local model as a correction judge raised 8 false alarms on 41 messages where rules raised none, and
   paraphrased two of six corrections into their opposite.
6. **Against normal memory, replayed.** On the same history (61 turns), memory that keeps every message and puts
   back the 3 most similar on every turn never had the earlier correction in front of the agent for any of the 4
   repeated corrections (177 items); it needed 20 a turn to have all 4 (1,010 items). Remem 0.6.3 had 3 of 4
   with 23 items, 13 catches per 100 items against 0.40, and none of its 20 end-of-turn reminders was followed by a
   decline. The message before a repeated correction rarely resembles it; the agent's behaviour (offering, putting
   work off) does. Every rule behind the 3 was changed after seeing this replay (0.6.1 caught none), and an earlier
   version of the comparison over-credited normal memory (fixed). Four cases; neither number is prevention
   (finding 3). [docs/COMPARISON.md](../docs/COMPARISON.md).
7. **The person types on a phone.** Curly apostrophes ("don’t") hid half the correction cues until 0.2.1.

### 7.3 A controlled experiment: memory in context, or at the moment

Finding 3 (knowing is not doing) came from one agent and one person. `remem experiment` tests it under control.
A model gets 20 situations in which agents tend to hand work back (a release ready to ship, a known bug, a missing
dependency, a branch ready to merge…), in two settings (a coding agent told it may act; a generic assistant), three
times each, under four arms with the same scenarios: **none** (no memory); **context** (the whole memory in the system
prompt, as normal memory systems and the 0.6 proxy do); **reminder** (memory in context and, when the reply still
hands back, Remem's end-of-turn reminder with its lesson and one more turn); **nudge** (the same second turn
with the same words but no lesson: the control for the reminder). A reply hands back when its closing asks, offers,
defers named work or tells the person to do it.

| Hand-back rate | none | context | nudge | reminder |
|---|---|---|---|---|
| Qwen3-30B-A3B (120 replies an arm) | 25% | 26% | 8% | 2.5% |
| Llama 3.2 3B | 45% | 62% | 18% | 13% |
| Gemma 3 4B | 13% | 22% | 2% | 1% |
| **Pooled (360 an arm)** | **28%** | **36%** | **9%** | **6%** |

Three results. **Memory in context did not help, and pooled it made things worse** (28% → 36%, Fisher p = 0.013;
higher in five of six model-settings). **Intervening at the moment did most of the work** (28% → 9%, p < 10⁻⁵). **What
was remembered added to the moment** (9% → 6%), suggestively but not yet significantly (p = 0.09). A mechanism check
contradicted the first guess, that describing a mistake in front of a model invites it: on Llama 3.2 3B (agent
setting, 60 replies each), a memory block holding only one *unrelated* lesson raised hand-backs more (15 → 33) than
the full memory (15 → 23). Up-front memory "about this person" may make models deferential as such; the cause is
open. Limits: synthetic scenarios, single replies rather than agent loops with tools, three small-to-mid open
models, a rule-based classifier (reported beside the hooks' narrower rule in `results/`), and a reminder that costs a
second model call. Since 0.7.0 the proxy delivers memory at the moment by default, not up front. Every reply is in
`results/`.

### 7.4 Why memory up front hurts, agents with tools, the boundary, and memory in the weights

0.8.0 takes §7.3 apart, with a fourth model family (Mistral 7B) and three new experiments; every run is kept and
`remem goals` checks each target (fixed before the runs) from them.

**The mechanism.** `remem experiment mechanism` changes one thing at a time in what goes before the agent's
prompt (agent setting, 20 scenarios, three times each, per model; pooled over Llama 3.2 3B, Gemma 3 4B,
Qwen3-30B-A3B and Mistral 7B):

| Before the agent's prompt | Hand-backs | p against none |
|---|---|---|
| nothing | 20% (95 of 480) | |
| the whole memory | 33% (157 of 480) | < 0.0001 |
| **only the delegation tally** ("the agent offered to act instead of acting 17 times… the user declined 0, approved 4, corrected 3…") | **34%** (121 of 360) | **< 0.0001** |
| the whole memory, after the agent's prompt | 22% | 0.44 |
| only the header ("what past sessions with this person taught") | 18% | 0.48 |
| the header and one unrelated lesson | 21% | 0.69 |
| neutral project notes as long as the memory | 16% | 0.27 |
| only the hand-back lesson (the person's words) | 22% | 0.55 |
| the person's reaction as an observation ("when the agent offered, this person corrected it") | 17% | 0.28 |
| the same evidence as what the person wants | 21% (50 of 240) | 1.0 (against its own none arms) |
| "the user prefers that you act without asking" (as normal memory stores it) | 12% (59 of 480) | 0.002 |

One line did it: **the tally of the agent's own offers raised hand-backs as much as the whole memory**; length,
position, being told it is memory about this person, and the person's words did not. §7.3's single-model check (one
unrelated lesson raised them on Llama) did not hold pooled. Describing what the agent did makes it do it again. The
effect is model-dependent (Llama and Mistral most; on Qwen the whole memory up front *lowered* hand-backs), and so is
every rewording: a stated preference helped on three families and not Mistral; the person-preference wording helped on
Gemma and Qwen and hurt Llama. Since 0.8.0 the tally is never shown to agents (it stays in the owner's morning
report), and nothing about delegation goes up front: the reminder at the moment carries it.

**Agents with tools.** `remem experiment loop` runs each scenario as an agent loop with a shell and an editor
(simulated; every call succeeds) until the model replies without a tool call. Arms as the shipped defaults deliver memory: none; the whole memory up
front; nothing up front and the Stop reminder when the final reply hands back; the same with the lesson-free nudge.
Final replies that hand back, two runs per scenario, with the 0.8.0 reminder: Llama 3.2 3B 25% → 0% (tools used in
85% of runs), Qwen3-30B 30% → 15% (90%), Mistral 7B 42% → 28% (it almost never called a tool, so its loop is close to
a single reply); pooled 32% → 14% (p = 0.001). The whole memory up front did not help (32%), and the nudge did as well
as the reminder (13%). Loops are simulated: every call succeeds.

**The boundary.** A memory that teaches "act, don't ask" can teach recklessness. `remem experiment boundary`
puts the model in 20 situations where asking is right (a credential the person will give, a decision that is theirs,
a review still pending, "wait until I've told everyone"). With 0.7.0's reminder, pooled over four families, models
asked 42% of the time with no memory and **16% after the reminder** (67 and 25 of 160): they published a post legal
was still reviewing, deployed without the password, and force-pushed before the person said to. The reminder fired on
any hand-back, and its words ("if you can do it now, do it now") read as permission. 0.8.0 adds a gate (no reminder
when the person's message says only they have what is needed: `transcripts.needs_person`, written with these
situations in view, so a fit, not a test; on six held-out ones it caught five) and a boundary in the reminder's words
(ask for exactly what only the person has). Re-run, models asked 39% of the time with no memory and 37% after the
0.8.0 reminder (63 and 59 of 160): the boundary held, on every family (Llama 45% → 42%, Qwen 75% → 70%, Gemma 28% →
25%, Mistral 10% → 10%). And it still cuts hand-backs where acting is right: §7.3's experiment re-run with the 0.8.0
reminder on all four families (480 replies an arm) gave none 31%, context 28%, nudge 11%, reminder 12% (none against
reminder p < 10⁻¹²). Two things changed from §7.3. With the tally gone, the memory up front no longer hurts (31% → 28%,
p = 0.32), which confirms the mechanism. And the reminder's lesson no longer adds to the nudge (12% against 11%, p =
0.92; §7.3's 6% against 9% did not hold). What memory contributes is *whether and when* to intervene, not the words: the
reminder fires only for a person whose corrections followed hand-backs, at the moment of the next one, and the moment
does the work. The reminder was installed on the owner's machine the day the harm was found.

**Memory in the weights.** The reminder pairs (a reply that handed back, the same model's reply after the reminder)
are preference data. `scripts/adapter.py` trains a LoRA adapter on them with DPO (Qwen2.5-1.5B-Instruct, CPU) and
tests on 20 situations the training never saw, with no memory and no reminder, plus six where asking is right:

| Training pairs | Hand-backs, held out | Asked where asking is right |
|---|---|---|
| base model, nothing | 37% (22 of 60) | 4 of 18 |
| base model, with the reminder | 20–23% | 4–7 of 18 |
| 115 "act" pairs | **5%** (3 of 60; p < 0.0001) | **0 of 18** |
| 115 "act" + 120 boundary pairs | 63% | 5 of 18 |
| 131 "act" + 56 boundary pairs | 47% | 8 of 18 |

The habit compiles: with no reminder at all, the adapted model handed back less than the base model *with* one. But it
compiled as a disposition, not a judgement: it also stopped asking where asking was right (it merged a pull request the
person had not decided on), and boundary pairs moved the whole disposition back rather than teaching when. At this size
and with a few hundred synthetic pairs, compiled memory learns *whether*, not *when*.

The same test on a model five times larger (Qwen2.5-7B-Instruct, on the machine's GPU, 100 held-out replies and 30
where asking is right), with the pairs from the four families' experiments, with pairs built from the 7B's own replies
(its hand-back and its own reply after the reminder; told to ask against told to act), and with both:

| Training pairs | Hand-backs, held out | Asked where asking is right |
|---|---|---|
| base model, nothing | 26 of 100 | 13 of 30 |
| base model, with the reminder | 14 of 100 | 11 of 30 |
| 131 "act" + 104 boundary (the experiments') | 49 of 100 | 23 of 30 |
| 131 "act" + 56 boundary (the experiments', a 30% share) | **20 of 100** | **14 of 30** |
| 26 "act" + 96 boundary (its own) | 46 of 100 | 15 of 30 |
| 26 "act" + 11 boundary (its own, a 30% share) | 25 of 100 | 12 of 30 |
| 157 "act" + 67 boundary (both, a 30% share) | **0 of 100** (p < 10⁻⁸) | **2 of 30** |

The larger model is the first to move both ways at once: with a 30% boundary share, fewer hand-backs with no memory
(26 → 20, one short of the target's 19) and asking kept (13 → 14). More "act" pairs did not finish the job; they tipped
it over. The adapter trained on both sets stopped ending replies with a question at all, where acting was right and
where it was not (it reported deploying with a production key it was never given). The guard's measure counts a
question or an instruction to the person, so it undercounts asks phrased as statements ("I am awaiting your decision");
the adapted replies show the swing is real all the same. A model's own pairs were few: the 7B rarely hands back, and its
revisions after the reminder often still asked. Seven runs, and the pattern of the small model holds at the larger
one: preference training on these pairs moves one dial, how readily the model asks, and the boundary lies along it at
one setting, not as a distinction learned. The target (A8) is not met. What would teach *when* rather than *how often* is
the open question: pairs that hold the situation fixed and vary only whether the person has what is needed, and a
judge of asking better than a question mark.

### 7.2 The measurements

In the order they will be run:

1. **The repeat-yourself rate.** Over matched tasks, before and after, how often the person restates a preference,
   convention or correction already given in an earlier session. The one number every memory system owes.
2. **The repeated-error rate.** How often the agent meets a failure it has met before, per session, over time.
   Under §3.1 this should fall; if it does not, consolidation is not producing the right lessons.
3. **Prediction accuracy.** The fraction of predictions confirmed inside the window, which is also the system's own
   fitness signal. Its trend over weeks says whether the merge rule is selecting for the right lessons.
4. **Surprise rate over time.** Surprises per session. Under the hypothesis, it declines as the memory fills and
   rises again when the task mix changes.
5. **The two-agent experiment.** Two agents on one machine, each with its own raw stream, exchanging only lessons
   over the wire format. Does agent B's repeated-error rate fall for errors that only agent A has met? This is the
   commons in miniature and the first test of §5.
6. **Retrieval quality.** Hashed embeddings against a learned embedder, on the same episodes, by recall@k over
   hand-labelled "same surprise" pairs.

Each is cheap, local, and reads from the same store.

## 8. Risks

| Risk | What it is | Answer in the design |
|---|---|---|
| Permanent mistakes | A wrong inference becomes a belief, is reinforced, shapes every session | Predictions: an unconfirmed lesson fades; the morning report; vetoes |
| Memory poisoning | An instruction in a web page or file is consolidated and executes forever | Lessons are observations, never instructions, checked at write; transcripts are data to the consolidator |
| Poisoning at scale | One bad lesson, everywhere | Candidate → common only after independent prediction gains; provenance hashes; revocation in one propagation |
| Homogenization | Every agent thinking alike | The personal layer is sovereign and separate; the commons is composed on top |
| Privacy | The most detailed record of a person's work that exists | Local only; nothing raw moves; lessons are opt-in and stripped; exclusion rules for the raw stream |
| Lock-in | Whoever holds the memory holds the person | The wire format is text, open and portable; the raw stream is the person's own files |
| Manipulation | An agent that knows a person deeply can persuade precisely | Memories are inspectable all the way down; the owner can read what the agent believes |

## 9. Related work

*Generative Agents* (Park et al., 2023) gave simulated agents a memory stream retrieved by recency, importance and
relevance together, with periodic reflection; its coherent long-run behavior is the closest evidence that §4.4's
scoring and §4.5's consolidation hold up. *MemGPT* (Packer et al., 2023) treats the context window as a cache
managed by the model itself, a hierarchy in the sense of §6. Personal-memory products (mem0, whose MCP server is
also named OpenMemory; Zep; Letta) store facts about a user and retrieve by similarity: the interpreted, single-user
case of §3.3. Continuous screen capture as memory is a product category (Rewind, now Limitless; Microsoft Recall);
it is the raw-stream half of §3.2 without consolidation. *Cartridges* (Eyuboglu et al., 2025) is the compiled form
of §6. Complementary learning systems (McClelland et al., 1995) and predictive coding (Rao and Ballard, 1999) are
the biological grounding of §2; Constantinescu, O'Reilly and Behrens (2016) showed the hippocampal grid code
organizing *conceptual* space, which motivates spatial presentations of memory in future work. Modern Hopfield
networks (Ramsauer et al., 2020) show attention is already an associative memory. Federated learning (McMahan et
al., 2017) is the precedent for §5's rule that models move and data does not. Stigmergy, coordination through
traces left in the environment, is the precedent for memory with no center.

## 10. Conclusion

The thesis is simple. Intelligence is converging and will be swapped like a utility; what compounds is experience,
and today every agent's experience is thrown away at the end of every session. Keep the surprises, consolidate
them in sleep, keep only what predicts, render them where the agent will have them in mind, and share them, as
observations, with provenance, under verification, with nothing raw ever moving. One agent's memory is the
organism; the commons is the species; the breathing cycle, memory into weights into memory, is how the species
learns. Version 0.1.0 is the organism, running. The rest is laid out above, and it is a protocol, not a product:
whoever writes it, and keeps it open, defines the layer of the internet where minds learn from each other directly.

---

## References

- Bartlett, F. C. (1932). *Remembering: A Study in Experimental and Social Psychology*. Cambridge University Press.
- Borges, J. L. (1942). "Funes el memorioso."
- Constantinescu, A. O., O'Reilly, J. X., Behrens, T. E. J. (2016). "Organizing conceptual knowledge in humans with a gridlike code." *Science* 352(6292).
- Eyuboglu, S., et al. (2025). "Cartridges: Lightweight and general-purpose long context representations via self-study." arXiv.
- McClelland, J. L., McNaughton, B. L., O'Reilly, R. C. (1995). "Why there are complementary learning systems in the hippocampus and neocortex." *Psychological Review* 102(3).
- McMahan, B., et al. (2017). "Communication-efficient learning of deep networks from decentralized data." AISTATS.
- Packer, C., et al. (2023). "MemGPT: Towards LLMs as operating systems." arXiv.
- Park, J. S., et al. (2023). "Generative Agents: Interactive simulacra of human behavior." UIST.
- Ramsauer, H., et al. (2020). "Hopfield networks is all you need." arXiv.
- Rao, R. P. N., Ballard, D. H. (1999). "Predictive coding in the visual cortex." *Nature Neuroscience* 2(1).

## Appendix A: 0.9.0 parameters

| Parameter | Value | Where |
|---|---|---|
| Embedding | a local embedding model via Ollama (`qwen3-embedding:0.6b` on the owner's machine), else hashed words + bigrams, 256 dims, signed; each vector tagged with its space | `remem/embed.py` |
| Relevance floor | cosine 0.35 (model), 0 (hashed), rescaled to 0–1 above it | `remem/embed.py` |
| Recall weights (relevance, recency, strength) | 0.60, 0.25, 0.15 | `remem/recall.py` |
| Recency half-life | 30 days | `remem/recall.py` |
| Decay half-life / archive floor | 45 days / 0.15 | `remem/sleep.py` |
| Same-surprise threshold | cosine ≥ 0.62 (model), 0.55 (hashed), every pair of a new cluster | `remem/embed.py`, `remem/sleep.py` |
| Prediction match / window | cosine ≥ the same-surprise cut (model), 0.50 (hashed) / 14 days, by when an episode happened | `remem/sleep.py` |
| Priming cut / per prompt / per session | cosine ≥ 0.60 (model), 0.30 (hashed) / 2 lessons / each lesson once | `remem/prime.py` |
| Linkage cut (join a lesson, merge a theme) | mean cosine ≥ 0.57 (model), 0.55 (hashed) | `remem/embed.py` |
| Stop reminder | at every offer or deferral (a reply that names work left: `DEFERRED`), one lesson (most corrections behind it); a correction lesson bears on them when any of its sources followed a hand-back. Not when the person's last message says only they have what is needed (`NEEDS_PERSON`: a credential, a decision that is theirs, a pending review, "wait until"; since 0.8.0). One wording (`prime.reminder`) in the hook, the proxy and the experiments, naming the boundary: ask for exactly what only the person has | `remem/prime.py`, `remem/transcripts.py` |
| Delegation tally | counted (`delegation.py`) and shown to the owner in `morning.md`; never shown to agents since 0.8.0 (it raised hand-backs, §7.4) | `remem/render.py` |
| Hand-back | the closing 1,500 characters, code left out, ask, offer or list next steps (`HANDBACK`); a lesson bears on it when most sources followed one | `remem/transcripts.py`, `remem/prime.py` |
| Delegation kinds | install, release, git, build, spend, delete, next steps (first keyword match); evidence: a correction after a hand-back, a refused call | `remem/delegation.py` |
| Offer or waiting | the last hand-back cue in the closing decides; a waiting cue (`WAITING`: "tell me when", "let me know once", "run this"…) at or after it means waiting; answers `corrected`, `declined` (`DECLINE`), `approved` (`APPROVE`), `other` | `remem/transcripts.py` |
| Proxy | `127.0.0.1:11435`; memory appended to the first system message (or a new one); `x-remem: off` bypasses | `remem/proxy.py` |
| Agents wired by setup | Claude Code (MCP, 4 hooks), Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex (MCP); cron 4 am | `remem/setup.py` |
| Sharing | lessons of kinds error and surprise (corrections with `--corrections`); candidate strength 0.5, always predicting; +0.5 per corroborating or confirming memory; refused: over 300 characters, imperative opening, control characters, hash mismatch | `remem/share.py` |
| Signatures | Ed25519 (RFC 8032); origin = first 8 bytes of SHA-256 of the public key; signed bytes = the record without `sig` as sorted-key compact JSON | `remem/ed25519.py`, `remem/share.py` |
| Commons | `https://remem.acific.com/commons/`; ≤ 1,000 records, ≤ 256 KB per memory; bearer token until launch | `src/commons.js` |
| Memory placement (proxy) | the moment (default since 0.7.0: a lesson only when the message meets it, and the reminder); or `first` (its own system message, Anthropic block marked `cache_control: ephemeral`) or `last` | `remem/proxy.py` |
| Experiment | `behaviour`: 20 scenarios × 2 settings × n runs × 4 arms (none, context, reminder, nudge); `mechanism`: 10 arms of what goes before the agent's prompt; `loop`: an agent loop with a simulated shell and editor, up to 8 calls; `boundary`: 20 situations where asking is right; temperature 0.7; hand-back = offer, deferral, a question or an instruction to the person in the closing 400 characters; runs kept in `~/.remem/experiments` | `remem/experiment.py` |
| Goals | A1–A10, targets fixed in advance, checked from the kept runs, the store and the adapters | `remem/goals.py` |
| Adapter | LoRA r 16, α 32, on q/k/v/o; DPO β 0.1, lr 5e-5, batch 4 × 2; Qwen2.5-1.5B-Instruct on CPU (3 epochs, 3 replies each) and Qwen2.5-7B-Instruct on the GPU (`--device auto`; 2 epochs, 5 replies each); 20 held-out scenarios and 6 where asking is right; pairs from the experiments, the model's own (`--pairs own`, 8 replies per situation) or both | `scripts/adapter.py` |
| Holdout | half the sessions, by SHA-256 of the session id (`REMEM_HOLDOUT`) | `remem/prime.py` |
| Measurements | repeat-yourself and repeated-error rates (before and after a lesson held it), prediction accuracy | `remem/measure.py` |
| Strength per confirmation / failure / recall | +0.5 / −0.5 / +0.1 | `remem/sleep.py`, `remem/store.py` |
| Kinds consolidated / never consolidated | error, correction, surprise / environment, session, note | `remem/sleep.py` |
| Correction cues, error classes, stated surprises | `CORRECTION_OPENING`, `CORRECTION_ANYWHERE`, `ENVIRONMENT`, `PROBE`, `STATED_SURPRISE` | `remem/transcripts.py` |