proto: memory, the arguments of recall and memory and eight message kinds

Implemented-By: OpenCode session (model recorded in docs/implementer-log.md)

crates/brokerd/src/broker.rs

@@ -88,7 +88,7 @@ impl Broker {
     }
 }
 
-/// The snake_case wire name of a message: all eighteen kinds, none with a leading underscore.
+/// The snake_case wire name of a message: all twenty-six kinds, none with a leading underscore.
 pub fn kind(msg: &Message) -> &'static str {
     match msg {
         Message::ToolRequest(_) => "tool_request",
@@ -109,6 +109,14 @@ pub fn kind(msg: &Message) -> &'static str {
         Message::ApprovalPosted(_) => "approval_posted",
         Message::ApprovalReply(_) => "approval_reply",
         Message::ApprovalOutcome(_) => "approval_outcome",
+        Message::MemoryBlock(_) => "memory_block",
+        Message::MemoryBlockReply(_) => "memory_block_reply",
+        Message::SessionUpdated(_) => "session_updated",
+        Message::MemoryCall(_) => "memory_call",
+        Message::Reindex(_) => "reindex",
+        Message::Reindexed(_) => "reindexed",
+        Message::MemoryAdmin(_) => "memory_admin",
+        Message::MemoryAdminReply(_) => "memory_admin_reply",
     }
 }
 

crates/proto/src/lib.rs

@@ -11,6 +11,7 @@ pub mod hash;
 pub mod hosts;
 pub mod ids;
 pub mod log;
+pub mod memory;
 pub mod sha1;
 pub mod tools;
 pub mod wire;
@@ -29,6 +30,10 @@ pub use grant::{Constraints, Grant, Mode};
 pub use hash::{HashError, Sha256, sha256};
 pub use ids::{CallId, Epoch, Hash32, SessionId, Timestamp, ValueError};
 pub use log::{LogRecord, ToolCall, Usage};
+pub use memory::{
+    ConsolidateEntry, EntryAction, MemoryAdmin, MemoryAdminReply, MemoryArgs, MemoryBlockReply,
+    MemoryCall, MemoryCommand, MemoryFile, RecallArgs, Reindexed, SessionUpdated,
+};
 pub use wire::{
     ApprovalList, Approve, ApproveResult, DenyReason, Empty, Envelope, ErrorCode, GrantProblem,
     GrantsReport, Message, PROTOCOL_VERSION, PendingApproval, Refuse, ToolRequest, ToolResponse,

crates/proto/src/memory.rs

@@ -0,0 +1,302 @@
+//! Memory: the arguments of `recall` and `memory`, their shape checks, and the messages `memoryd`
+//! exchanges with `loopd`, `brokerd` and `bxctl` (M5a spec, sections 5 and 7). Content rules (an
+//! entry matching the file, a file's limit, the check on characters) are `memoryd`'s.
+
+use serde::{Deserialize, Serialize};
+
+use crate::class::DataClass;
+use crate::ids::SessionId;
+use crate::wire::ToolRequest;
+
+/// The tool names.
+pub const RECALL: &str = "recall";
+pub const MEMORY: &str = "memory";
+
+/// The most characters a `recall` query may have.
+pub const MAX_QUERY: usize = 500;
+/// The most hits a `recall` may ask for, and how many it gets when it does not say.
+pub const MAX_K: u64 = 10;
+pub const DEFAULT_K: u64 = 5;
+/// The most characters a `note` may have.
+pub const MAX_NOTE: usize = 1_000;
+/// The most characters of any other entry: the larger file's limit.
+pub const MAX_ENTRY: usize = 2_200;
+/// The line that separates entries in `memory.md`, `user.md` and `notes.md`.
+pub const SEPARATOR: &str = "§";
+
+/// The arguments for `recall`.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RecallArgs {
+    pub query: String,
+    #[serde(default = "default_k")]
+    pub k: u64,
+}
+
+fn default_k() -> u64 {
+    DEFAULT_K
+}
+
+/// Which identity file an edit is for.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MemoryFile {
+    Memory,
+    User,
+}
+
+impl MemoryFile {
+    /// The file's name under `memory/`.
+    pub fn name(self) -> &'static str {
+        match self {
+            MemoryFile::Memory => "memory.md",
+            MemoryFile::User => "user.md",
+        }
+    }
+
+    /// The file's limit in characters.
+    pub fn limit(self) -> usize {
+        match self {
+            MemoryFile::Memory => 2_200,
+            MemoryFile::User => 1_375,
+        }
+    }
+}
+
+/// The arguments for `memory`: one action. `note` records experience; the others edit identity.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "action", rename_all = "snake_case", deny_unknown_fields)]
+pub enum MemoryArgs {
+    Add {
+        file: MemoryFile,
+        text: String,
+    },
+    Replace {
+        file: MemoryFile,
+        old: String,
+        text: String,
+    },
+    Remove {
+        file: MemoryFile,
+        old: String,
+    },
+    Consolidate {
+        file: MemoryFile,
+        entries: Vec<ConsolidateEntry>,
+    },
+    Note {
+        text: String,
+    },
+}
+
+/// One line of a `consolidate`: an existing entry (`old`) with exactly one of `keep`, `text`,
+/// `move`, `drop`; or a new entry (`text` alone).
+#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ConsolidateEntry {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub old: Option<String>,
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub keep: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub text: Option<String>,
+    #[serde(default, rename = "move", skip_serializing_if = "std::ops::Not::not")]
+    pub moved: bool,
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub drop: bool,
+}
+
+/// What a `consolidate` line does.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EntryAction {
+    Keep(String),
+    Rewrite { old: String, text: String },
+    Move(String),
+    Drop(String),
+    New(String),
+}
+
+impl ConsolidateEntry {
+    /// The line's action, or why it has none.
+    pub fn action(&self) -> Result<EntryAction, &'static str> {
+        let flags = usize::from(self.keep) + usize::from(self.moved) + usize::from(self.drop);
+        match (&self.old, &self.text, flags) {
+            (None, Some(text), 0) => Ok(EntryAction::New(text.clone())),
+            (None, _, _) => Err("an entry without old must have text and nothing else"),
+            (Some(old), Some(text), 0) => Ok(EntryAction::Rewrite {
+                old: old.clone(),
+                text: text.clone(),
+            }),
+            (Some(old), None, 1) => {
+                if self.keep {
+                    Ok(EntryAction::Keep(old.clone()))
+                } else if self.moved {
+                    Ok(EntryAction::Move(old.clone()))
+                } else {
+                    Ok(EntryAction::Drop(old.clone()))
+                }
+            }
+            (Some(_), _, _) => {
+                Err("an entry with old must have exactly one of keep, text, move or drop")
+            }
+        }
+    }
+}
+
+/// Why an entry's text is not a well-formed entry: empty once trimmed, too long, or holding a line
+/// that is only the separator. `None` when it is fine.
+pub fn entry_problem(text: &str, max: usize) -> Option<String> {
+    if text.trim().is_empty() {
+        return Some("an entry cannot be empty".to_string());
+    }
+    let chars = text.chars().count();
+    if chars > max {
+        return Some(format!(
+            "an entry has at most {max} characters; this has {chars}"
+        ));
+    }
+    for line in text.lines() {
+        if line.trim() == SEPARATOR {
+            return Some(format!(
+                "an entry cannot hold a line that is only {SEPARATOR}"
+            ));
+        }
+    }
+    None
+}
+
+impl RecallArgs {
+    /// The shape rules of `recall` (M5a spec, section 5).
+    pub fn check(&self) -> Result<(), String> {
+        if self.query.trim().is_empty() || self.query.chars().count() > MAX_QUERY {
+            return Err(format!("query must have 1 to {MAX_QUERY} characters"));
+        }
+        if self.k == 0 || self.k > MAX_K {
+            return Err(format!("k must be 1 to {MAX_K}"));
+        }
+        Ok(())
+    }
+}
+
+impl MemoryArgs {
+    /// The shape rules of `memory` (M5a spec, section 5): every text is a well-formed entry, and
+    /// every `consolidate` line has one action and the list is not empty.
+    pub fn check(&self) -> Result<(), String> {
+        match self {
+            MemoryArgs::Add { text, .. } => {
+                if let Some(problem) = entry_problem(text, MAX_ENTRY) {
+                    return Err(problem);
+                }
+            }
+            MemoryArgs::Replace { old, text, .. } => {
+                if let Some(problem) = entry_problem(old, MAX_ENTRY) {
+                    return Err(problem);
+                }
+                if let Some(problem) = entry_problem(text, MAX_ENTRY) {
+                    return Err(problem);
+                }
+            }
+            MemoryArgs::Remove { old, .. } => {
+                if let Some(problem) = entry_problem(old, MAX_ENTRY) {
+                    return Err(problem);
+                }
+            }
+            MemoryArgs::Note { text } => {
+                if let Some(problem) = entry_problem(text, MAX_NOTE) {
+                    return Err(problem);
+                }
+            }
+            MemoryArgs::Consolidate { entries, .. } => {
+                if entries.is_empty() {
+                    return Err("consolidate needs every entry of the file".to_string());
+                }
+                for line in entries {
+                    let action = line.action().map_err(|problem| problem.to_string())?;
+                    match action {
+                        EntryAction::Keep(old)
+                        | EntryAction::Move(old)
+                        | EntryAction::Drop(old) => {
+                            if let Some(problem) = entry_problem(&old, MAX_ENTRY) {
+                                return Err(problem);
+                            }
+                        }
+                        EntryAction::Rewrite { old, text } => {
+                            if let Some(problem) = entry_problem(&old, MAX_ENTRY) {
+                                return Err(problem);
+                            }
+                            if let Some(problem) = entry_problem(&text, MAX_ENTRY) {
+                                return Err(problem);
+                            }
+                        }
+                        EntryAction::New(text) => {
+                            if let Some(problem) = entry_problem(&text, MAX_ENTRY) {
+                                return Err(problem);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+}
+
+/// `memoryd` → `loopd`: the memory block for a new session's baseline.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MemoryBlockReply {
+    pub text: String,
+}
+
+/// `loopd` → `memoryd`: this session's log has new records.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionUpdated {
+    pub session: SessionId,
+}
+
+/// `brokerd` → `memoryd`: a decided `recall` or `memory` call, with the session's state when it
+/// was decided.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MemoryCall {
+    pub request: ToolRequest,
+    pub taint: DataClass,
+    pub untrusted: bool,
+}
+
+/// `memoryd` → `bxctl`: what a reindex read.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Reindexed {
+    pub logs: u64,
+    pub records: u64,
+    pub notes: u64,
+}
+
+/// The owner's memory commands (M5a spec, section 10).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum MemoryCommand {
+    Log,
+    Undo,
+    Pending,
+    Accept,
+    Reject,
+}
+
+/// `bxctl` → `memoryd`: one command; `arg` is the count for `log`, the edit or pending id for
+/// `undo`, `accept` and `reject`, and empty otherwise.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MemoryAdmin {
+    pub command: MemoryCommand,
+    pub arg: String,
+}
+
+/// `memoryd` → `bxctl`: the text to print.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MemoryAdminReply {
+    pub text: String,
+}

crates/proto/src/wire.rs

@@ -1,6 +1,9 @@
 use serde::{Deserialize, Serialize};
 
 use crate::gateway::{ApprovalOutcome, ApprovalPosted, ApprovalReply, ApprovalRequest};
+use crate::memory::{
+    MemoryAdmin, MemoryAdminReply, MemoryBlockReply, MemoryCall, Reindexed, SessionUpdated,
+};
 use crate::{CallId, DataClass, DecisionRecord, SessionId, Timestamp, Usage};
 
 pub const PROTOCOL_VERSION: u32 = 1;
@@ -40,6 +43,14 @@ pub enum Message {
     ApprovalPosted(ApprovalPosted),
     ApprovalReply(ApprovalReply),
     ApprovalOutcome(ApprovalOutcome),
+    MemoryBlock(Empty),
+    MemoryBlockReply(MemoryBlockReply),
+    SessionUpdated(SessionUpdated),
+    MemoryCall(MemoryCall),
+    Reindex(Empty),
+    Reindexed(Reindexed),
+    MemoryAdmin(MemoryAdmin),
+    MemoryAdminReply(MemoryAdminReply),
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]

crates/proto/tests/fixtures/wire/memory_admin.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"memory_admin","body":{"command":"undo","arg":"2026-09-24-0007"}}}

crates/proto/tests/fixtures/wire/memory_admin_reply.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"memory_admin_reply","body":{"text":"undone: 2026-09-24-0007"}}}

crates/proto/tests/fixtures/wire/memory_block.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"memory_block","body":{}}}

crates/proto/tests/fixtures/wire/memory_block_reply.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"memory_block_reply","body":{"text":"# soul.md\nYou are Boxmaker.\n\n# memory.md (0 of 2,200 characters)\n(empty)\n\n# user.md (0 of 1,375 characters)\n(empty)"}}}

crates/proto/tests/fixtures/wire/memory_call.json

@@ -0,0 +1 @@
+{"v":1,"id":3,"final":true,"msg":{"kind":"memory_call","body":{"request":{"session":"mm-r0000000000000000000000001","call":3,"tool":"memory","arguments":"{\"action\":\"note\",\"text\":\"example.org says March.\"}"},"taint":"private","untrusted":true}}}

crates/proto/tests/fixtures/wire/reindex.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"reindex","body":{}}}

crates/proto/tests/fixtures/wire/reindexed.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"reindexed","body":{"logs":42,"records":1208,"notes":7}}}

crates/proto/tests/fixtures/wire/session_updated.json

@@ -0,0 +1 @@
+{"v":1,"id":1,"final":true,"msg":{"kind":"session_updated","body":{"session":"mm-r0000000000000000000000001"}}}

crates/proto/tests/memory_args.rs

@@ -0,0 +1,167 @@
+//! The arguments of `recall` and `memory`: decoding, unknown keys refused, and the shape checks
+//! (M5a spec, section 5). Do not edit.
+
+use proto::memory::{MAX_ENTRY, MAX_NOTE, entry_problem};
+use proto::{ConsolidateEntry, EntryAction, MemoryArgs, MemoryFile, RecallArgs};
+
+fn memory(json: &str) -> Result<MemoryArgs, String> {
+    serde_json::from_str::<MemoryArgs>(json).map_err(|e| e.to_string())
+}
+
+#[test]
+fn recall_decodes_with_a_default_k_and_checks_its_bounds() {
+    let args: RecallArgs = serde_json::from_str(r#"{"query":"launch window"}"#).unwrap();
+    assert_eq!(args.k, 5);
+    assert_eq!(args.check(), Ok(()));
+    for (json, ok) in [
+        (r#"{"query":"x","k":10}"#, true),
+        (r#"{"query":"x","k":11}"#, false),
+        (r#"{"query":"x","k":0}"#, false),
+        (r#"{"query":"   ","k":1}"#, false),
+    ] {
+        let args: RecallArgs = serde_json::from_str(json).unwrap();
+        assert_eq!(args.check().is_ok(), ok, "{json}");
+    }
+    let long = RecallArgs {
+        query: "é".repeat(500),
+        k: 1,
+    };
+    assert_eq!(long.check(), Ok(()), "500 characters, not bytes");
+    let longer = RecallArgs {
+        query: "é".repeat(501),
+        k: 1,
+    };
+    assert!(longer.check().is_err());
+    assert!(serde_json::from_str::<RecallArgs>(r#"{"query":"x","limit":3}"#).is_err());
+}
+
+#[test]
+fn every_memory_action_decodes() {
+    assert_eq!(
+        memory(r#"{"action":"add","file":"memory","text":"Owner prefers UTC."}"#),
+        Ok(MemoryArgs::Add {
+            file: MemoryFile::Memory,
+            text: "Owner prefers UTC.".to_string()
+        })
+    );
+    assert_eq!(
+        memory(r#"{"action":"replace","file":"user","old":"a","text":"b"}"#),
+        Ok(MemoryArgs::Replace {
+            file: MemoryFile::User,
+            old: "a".to_string(),
+            text: "b".to_string()
+        })
+    );
+    assert_eq!(
+        memory(r#"{"action":"remove","file":"user","old":"a"}"#),
+        Ok(MemoryArgs::Remove {
+            file: MemoryFile::User,
+            old: "a".to_string()
+        })
+    );
+    assert_eq!(
+        memory(r#"{"action":"note","text":"example.org says March."}"#),
+        Ok(MemoryArgs::Note {
+            text: "example.org says March.".to_string()
+        })
+    );
+    let consolidate = memory(
+        r#"{"action":"consolidate","file":"memory","entries":[{"old":"a","keep":true},{"old":"b","text":"B"},{"old":"c","move":true},{"old":"d","drop":true},{"text":"e"}]}"#,
+    )
+    .unwrap();
+    let MemoryArgs::Consolidate { file, entries } = consolidate else {
+        panic!("not a consolidate")
+    };
+    assert_eq!(file, MemoryFile::Memory);
+    let actions: Vec<EntryAction> = entries.iter().map(|e| e.action().unwrap()).collect();
+    assert_eq!(
+        actions,
+        [
+            EntryAction::Keep("a".to_string()),
+            EntryAction::Rewrite {
+                old: "b".to_string(),
+                text: "B".to_string()
+            },
+            EntryAction::Move("c".to_string()),
+            EntryAction::Drop("d".to_string()),
+            EntryAction::New("e".to_string()),
+        ]
+    );
+}
+
+#[test]
+fn unknown_actions_files_and_keys_are_refused() {
+    for json in [
+        r#"{"action":"forget","file":"memory"}"#,
+        r#"{"action":"add","file":"soul","text":"x"}"#,
+        r#"{"action":"add","file":"memory","text":"x","why":"y"}"#,
+        r#"{"action":"note","text":"x","file":"memory"}"#,
+        r#"{"action":"consolidate","file":"memory","entries":[{"old":"a","keep":true,"why":1}]}"#,
+        r#"{"file":"memory","text":"x"}"#,
+    ] {
+        assert!(memory(json).is_err(), "{json}");
+    }
+}
+
+#[test]
+fn a_consolidate_line_has_exactly_one_action() {
+    let line = |old: Option<&str>, keep: bool, text: Option<&str>, moved: bool, drop: bool| {
+        ConsolidateEntry {
+            old: old.map(str::to_string),
+            keep,
+            text: text.map(str::to_string),
+            moved,
+            drop,
+        }
+    };
+    for bad in [
+        line(Some("a"), false, None, false, false),
+        line(Some("a"), true, None, true, false),
+        line(Some("a"), true, Some("b"), false, false),
+        line(Some("a"), false, Some("b"), false, true),
+        line(None, false, None, false, false),
+        line(None, true, Some("b"), false, false),
+    ] {
+        assert!(bad.action().is_err(), "{bad:?}");
+    }
+    let empty = MemoryArgs::Consolidate {
+        file: MemoryFile::User,
+        entries: vec![],
+    };
+    assert!(empty.check().is_err());
+}
+
+#[test]
+fn entries_are_not_empty_not_too_long_and_hold_no_separator_line() {
+    assert_eq!(entry_problem("fine", MAX_ENTRY), None);
+    assert_eq!(entry_problem("two\nlines", MAX_ENTRY), None);
+    assert_eq!(entry_problem("a § in a line is fine", MAX_ENTRY), None);
+    assert!(entry_problem("", MAX_ENTRY).is_some());
+    assert!(entry_problem(" \n\t", MAX_ENTRY).is_some());
+    assert!(entry_problem("before\n§\nafter", MAX_ENTRY).is_some());
+    assert!(entry_problem("before\n  §  \nafter", MAX_ENTRY).is_some());
+    assert_eq!(entry_problem(&"é".repeat(MAX_ENTRY), MAX_ENTRY), None);
+    assert!(entry_problem(&"é".repeat(MAX_ENTRY + 1), MAX_ENTRY).is_some());
+    let note = MemoryArgs::Note {
+        text: "x".repeat(MAX_NOTE + 1),
+    };
+    assert!(note.check().is_err());
+    let rewrite = MemoryArgs::Replace {
+        file: MemoryFile::Memory,
+        old: "fine".to_string(),
+        text: "a\n§\nb".to_string(),
+    };
+    assert!(rewrite.check().is_err());
+}
+
+#[test]
+fn the_files_names_and_limits() {
+    assert_eq!(
+        (MemoryFile::Memory.name(), MemoryFile::Memory.limit()),
+        ("memory.md", 2_200)
+    );
+    assert_eq!(
+        (MemoryFile::User.name(), MemoryFile::User.limit()),
+        ("user.md", 1_375)
+    );
+}

crates/proto/tests/memory_wire.rs

@@ -0,0 +1,113 @@
+//! The eight memory messages against byte-exact fixtures, each refusing an unknown key (M5a spec,
+//! section 7). Do not edit these or the fixtures.
+
+use proto::{
+    CallId, DataClass, Empty, Envelope, MemoryAdmin, MemoryAdminReply, MemoryBlockReply,
+    MemoryCall, MemoryCommand, Message, Reindexed, SessionId, SessionUpdated, ToolRequest,
+};
+
+const SESSION: &str = "mm-r0000000000000000000000001";
+
+fn fixture(name: &str) -> String {
+    let path = format!("{}/tests/fixtures/wire/{name}", env!("CARGO_MANIFEST_DIR"));
+    let text = std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("{path}: {e}"));
+    text.trim_end_matches('\n').to_string()
+}
+
+/// The fixture must decode to `msg`, `msg` must encode to exactly the fixture's bytes, and the
+/// body must refuse an extra key.
+fn check(name: &str, id: u64, msg: Message) {
+    let want = Envelope {
+        v: 1,
+        id,
+        r#final: true,
+        msg,
+    };
+    let text = fixture(name);
+    let got: Envelope = serde_json::from_str(&text).unwrap_or_else(|e| panic!("{name}: {e}"));
+    assert_eq!(got, want, "{name}: decoded value");
+    assert_eq!(
+        serde_json::to_string(&want).unwrap(),
+        text,
+        "{name}: encoded bytes"
+    );
+    let extra = text.replacen("\"body\":{", "\"body\":{\"extra\":1,", 1);
+    assert!(
+        serde_json::from_str::<Envelope>(&extra).is_err(),
+        "{name}: an unknown key is refused"
+    );
+}
+
+#[test]
+fn the_eight_messages() {
+    check("memory_block.json", 1, Message::MemoryBlock(Empty {}));
+    check(
+        "memory_block_reply.json",
+        1,
+        Message::MemoryBlockReply(MemoryBlockReply {
+            text: "# soul.md\nYou are Boxmaker.\n\n# memory.md (0 of 2,200 characters)\n(empty)\n\n# user.md (0 of 1,375 characters)\n(empty)".to_string(),
+        }),
+    );
+    check(
+        "session_updated.json",
+        1,
+        Message::SessionUpdated(SessionUpdated {
+            session: SessionId::new(SESSION).unwrap(),
+        }),
+    );
+    check(
+        "memory_call.json",
+        3,
+        Message::MemoryCall(MemoryCall {
+            request: ToolRequest {
+                session: SessionId::new(SESSION).unwrap(),
+                call: CallId(3),
+                tool: "memory".to_string(),
+                arguments: r#"{"action":"note","text":"example.org says March."}"#.to_string(),
+            },
+            taint: DataClass::Private,
+            untrusted: true,
+        }),
+    );
+    check("reindex.json", 1, Message::Reindex(Empty {}));
+    check(
+        "reindexed.json",
+        1,
+        Message::Reindexed(Reindexed {
+            logs: 42,
+            records: 1208,
+            notes: 7,
+        }),
+    );
+    check(
+        "memory_admin.json",
+        1,
+        Message::MemoryAdmin(MemoryAdmin {
+            command: MemoryCommand::Undo,
+            arg: "2026-09-24-0007".to_string(),
+        }),
+    );
+    check(
+        "memory_admin_reply.json",
+        1,
+        Message::MemoryAdminReply(MemoryAdminReply {
+            text: "undone: 2026-09-24-0007".to_string(),
+        }),
+    );
+}
+
+#[test]
+fn every_command_has_its_name() {
+    for (command, name) in [
+        (MemoryCommand::Log, "log"),
+        (MemoryCommand::Undo, "undo"),
+        (MemoryCommand::Pending, "pending"),
+        (MemoryCommand::Accept, "accept"),
+        (MemoryCommand::Reject, "reject"),
+    ] {
+        assert_eq!(
+            serde_json::to_string(&command).unwrap(),
+            format!("\"{name}\"")
+        );
+    }
+}