M5.2: agent memory

remember(name, description, fact) and forget(name, why): control tools for
the driver (before the go-ahead too) and conversations, writing only the
agent's own vault folder, one note per fact with its provenance. No one
agrees first; each change is a line in the thread. The harness keeps the
index and puts it into the transcript once per item, with a hash.

At an item's close, completed or abandoned, a bounded memory pass (the
driver's model, its own transcript and view) records what was decided and
learned; it never holds the close up (tuning.memory.max_turns).

With the operator: corrections may be paraphrased (L6 changed), the model
forgets on its own, and nothing limits what may prompt a note. The walk
remembers and forgets, and checks nothing lands outside the agent's folder.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01J5Utyfzw7gF7UhjRDEtjTk

docs/Architecture.md

@@ -346,17 +346,21 @@ work-item start, with the repository as the authority; for infrastructure, the
 world model in the vault (L10).
 
 **4. Agent memory:** the agent's own notes (the operator's preferences, lessons,
-recurring decisions and their reasons), one note per fact with an index, in its
-folder under `memory/` in the vault (L10). Read at work-item start and before
-decisions the notes cover. Visible to the operator, who corrects it through
-conversation.
+recurring decisions and their reasons), one note per fact with an index the
+harness keeps, in its folder under `memory/` in the vault (L10). The model
+writes, updates and forgets them itself, without asking; each change is said in
+the thread. The index is put into the transcript at a work item's start; a note
+is read before decisions it covers. Visible to the operator, who corrects it
+through conversation, not by editing it.
 
 **5. Never memory:** Matrix history, provider-side session state, build artifacts,
 a previous task's workspace.
 
-**Writing memory:** at work-item close (what was done and decided, into scope memory
-or agent memory as it belongs); when a fact is learned, with its source and time;
-operator corrections verbatim, with attribution, never paraphrased.
+**Writing memory:** when a fact is learned, with its source and time; at work-item
+close, by a bounded pass of its own (what was decided and learned, into scope memory
+or agent memory as it belongs), so it never depends on the model thinking of it;
+operator corrections faithfully, with attribution. Paraphrase is fine: after a
+back-and-forth, the gist is what matters.
 
 **Using memory:** everything read is snapshotted into the transcript with its
 provenance (source, revision or content hash, time), once per item. **Memory is a

docs/Development-Plan.md

@@ -489,8 +489,30 @@ tools, atomic writes and provenance (L10).
 - Per-agent mounts are the container's (M6.1); until then the folder map and
   path checks hold in code.
 
-**M5.2 Agent memory** (*needs discussion*) and **M5.3 scope memory**
-(*pre-approved*): when notes are written and read, verbatim corrections (L6).
+**M5.2 Agent memory.** *Discussed with the operator.* **Done** (this PR). When
+notes are written and read (L6.4).
+- `remember(name, description, fact)` and `forget(name, why)`: control tools for
+  the driver (before the go-ahead too) and conversations, writing only the
+  agent's folder (`memory/nisse-dev`, read-write in the vault configuration).
+  No one agrees first, the model may forget on its own, and each change is a
+  line in the thread ("Remembered: …", "Forgot: …").
+- One note per fact (`<name>.md`: a one-line description, the fact, and
+  provenance: work item, thread, time). The harness keeps `index.md`, one line
+  per note, after every change; the model never writes it.
+- The index goes into the transcript once per item and conversation, with its
+  path and a hash (L6); notes are read with `read_note`. The prompt says memory
+  is a cache: check against the live system, fix a note a check contradicts.
+- At an item's close, completed or abandoned, a **memory pass**: the driver's
+  model in a transcript of its own (the item's narration, as the toolchain step
+  sees it), with the note and memory tools and `memory_done`, bounded by
+  `tuning.memory.max_turns` (10). It never holds the close up.
+- Decided with the operator: corrections may be paraphrased (L6 changed); no
+  confirmation; no limit on what may prompt a note (a lesson often comes from
+  tool output), each recording what did. Conversations get no closing pass.
+- The walk remembers and forgets, and checks that nothing lands outside the
+  agent's folder.
+
+**M5.3 Scope memory.** *Pre-approved.* Scope memory outliving work items (L6.3).
 
 **M5.4 The operator's view.** *Pre-approved.* SilverBullet in its own container on
 the vault: the operator's folders read-write, the agents' read-only (L10), behind

docs/Tuning-Guide.md

@@ -566,6 +566,16 @@ reply in its thread starts a new conversation linked to it.
   again from its summary.
 - **Too high:** idle conversations pile up in `status` and in the queue.
 
+### `tuning.memory.max_turns` — default 10
+
+Model calls the memory pass at a work item's close may make (architecture L6):
+reading notes, remembering, forgetting, then `memory_done`. Running out leaves
+what it wrote and is noted; the close never waits on it.
+
+- **Too low:** a long item's lessons are cut short.
+- **Too high:** a model that keeps rereading notes costs calls at every close.
+- **Deciding:** a few notes per item is typical; each costs about one call.
+
 ### `tuning.build_vm.retry_s` — default 300
 
 How often a build VM that can't be reached is tried again (architecture D3).