mailbox-memory

mailbox-memory

Companion plugin for the paper "The Mailbox Is the Memory": email as the durable memory and comms substrate for LLM agents. This skill walks you through provisioning it and sending yourself the first memory.

Scripts referenced below live inside this plugin — always invoke them through $CLAUDE_PLUGIN_ROOT (an installed plugin does not put its scripts on PATH):

• $CLAUDE_PLUGIN_ROOT/scripts/setup.sh — provisioning
• $CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-* — the mail verbs

1. The model, in one paragraph

A message is an immutable, frozen fact — once sent, it never changes. notmuch tags are mutable classification layered on top. Correcting or retracting something is never an edit; it's a new message that supersedes the old one (a retag, driven by a real Supersedes: header, not a silent mutation). Remembering is mailing yourself: write what you want to keep as a message to your own mailbox, and it's durable, searchable, and survives losing the search index (step 5 proves this).

2. Provision

Everything below needs notmuch installed and nothing else — no root, no postfix, no privileged paths (that's Tier 1; see step 7 for Tier 2). Always look at --dry-run first so you know what it's about to touch:

"$CLAUDE_PLUGIN_ROOT/scripts/setup.sh" all --dry-run
"$CLAUDE_PLUGIN_ROOT/scripts/setup.sh" all

all runs maildir + notmuch + autoindex: creates ~/.mail/agents/memory/{tmp,new,cur}, configures notmuch (header indexing, the query:memory saved search, and installs the post-new auto-tag hook), and sets up a launchd (macOS) / systemd --user timer (Linux) to run notmuch new on an interval. It's additive and idempotent — safe to re-run, and it never overwrites an existing new.tags/query.memory value without --force.

3. Send yourself a memory

"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-send" \
  memory --from you@yourhost "first PoC memory"

Every send reports its transport (postfix/SMTP or local file-drop) on stderr, and prints the message's Message-ID on stdout — note it, you'll use it if you want to supersede this message later.

4. Read it back

"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-list" memory
"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-read" memory 1

list is a low-context scan (one line per message); read opens the message at the index list printed. If you'd rather watch it arrive live, run this in a second pane before sending — it blocks until a message lands, then prints it and exits:

"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-wait" memory

5. Prove it survives losing the index

This is the paper's strongest claim (claim #2) made checkable in one command: delete the notmuch index, rebuild it from the maildir alone, and confirm a superseded memory stays superseded (the tag is a projection of the mail, not the record itself — it's rederived from the Supersedes: header at index time, so deleting the index can't erase a correction). Deliberately destructive of the index only; it dumps and restores your tags around the experiment, even on failure.

The proof needs a real superseded message to point at, and step 3 above only ever sent one message that's never been corrected — so correct it first, using the Message-ID step 3 printed to stdout:

"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-send" \
  memory --from you@yourhost --supersedes "<message-id-from-step-3>" "corrected PoC memory"

Quote the Message-ID — the angle brackets are real characters in the ID (<...>), but unquoted they're shell redirection and the command fails with something like no such file or directory: 1783991944...@yourhost.

Then run the proof:

"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-rebuild-proof"

Exit 0 = the memory survived losing its own index. Exit 1 = it didn't — a real falsification; don't paper over it.

If it instead exits 2 saying "no superseded message in this corpus" right after you just superseded one, the notmuch index hasn't caught up yet — session-mail-send's file-drop path indexes synchronously now, but if you're on the smtp/postfix path, or the autoindex timer's the only thing that's ever touched this box, run notmuch new by hand and try again (the timer that does this automatically runs every 5 minutes; see setup.sh autoindex).

6. Browse via query:memory

setup.sh notmuch (step 2) already wrote the saved search:

notmuch config set query.memory 'tag:memory and not tag:superseded'

so browsing current (non-superseded) memories is one command, from anywhere notmuch is configured:

notmuch search query:memory

7. Tier 2 — postfix (optional, cross-host / multi-agent)

You don't need this for the demo above. Everything through step 6 runs on local file-drop delivery alone. Tier 2 is for when you want mail to actually route through postfix — cross-host delivery, multiple agents addressable by name, the full <name>@<host> picture. It's genuinely system-level (writes under /etc/postfix, needs a running postfix) and is opt-in only — setup.sh all never touches it:

"$CLAUDE_PLUGIN_ROOT/scripts/setup.sh" postfix --dry-run

See references/mail-troubleshooting.md for the prerequisite, the map format, and how to trace a message end to end when Tier 2 delivery doesn't behave.