mbailey 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. It is dry-run by default — it deletes your notmuch
Xapian index, so it does nothing until you say --execute:
# see exactly what it would do — writes nothing, changes nothing
"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-rebuild-proof"
# actually run the experiment (this DELETES and rebuilds the index)
"$CLAUDE_PLUGIN_ROOT/skills/mailbox-memory/scripts/session-mail-rebuild-proof" --execute
Exit 0 = the memory survived losing its own index. Exit 1 = it didn't —
a real falsification; don't paper over it. Exit 3 = nothing was done (a dry
run, --help, or an argument it refused): a dry run proves nothing, so it
never reports the proof's 0 on the experiment's behalf.
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.