chore(v3.1): release prep — version 3.1.0, changelog, working release archives

[RichardHightower]

Phase 58 launch prep. Everything here is the code-and-docs half; the tag, the repo settings, the demo, and the public posts are yours.

The version now matches

workspace.package.version was still 2.7.0 — it never moved through v3.0 or v3.1, and the repo has no tags at all. Now 3.1.0. memory-adapters was pinning its own literal 2.7.0 instead of inheriting; it now uses version.workspace = true, so there is one source of truth for the next bump.

The release it would have cut was broken

Two things, both found by reading release.yml against the README rather than assuming:

1. The archive shipped memory-daemon and memory-ingest only. memory — the CLI the quickstart uses for memory add and memory search — and memory-installer were never in it. A user who took the "prefer not to compile?" path could not follow the quickstart at all. All four binaries now ship, and a missing one fails the release job instead of producing a quietly partial archive.
2. Assets are renamed agent-memory-<version>-<platform>. The archive stopped being just the daemon. No releases exist yet, so nothing breaks.

docs/setup/quickstart.md was rewritten to match reality. The old instructions were wrong three ways: they fetched per-binary tarballs that the workflow never produced, omitted the version from the asset name, and untarred into ~/.local/bin when the tarball carries its own directory prefix — so the chmod +x ~/.local/bin/memory-daemon on the next line would have failed even if the download had worked.

A correction to something this milestone shipped

Phase 57's README said BM25 indexes built before v3.1 could be rebuilt to get event previews. That is not true, and I wrote it. Verified against the code this time:

• admin rebuild-bm25 is a prune, not a rebuild — it removes documents below --min-level (default day, which would delete your segment and grip documents) and re-indexes nothing
• admin rebuild-indexes re-indexes TOC nodes and grips from storage, not raw events
• admin clear-index --index bm25 deletes the index directory but leaves the indexing checkpoint in RocksDB, so the outbox drain will not revisit processed events

There is no backfill path. README and UPGRADING now say that plainly, and rebuild-bm25's help text and banner stop calling a prune a rebuild — the misleading name was one default flag away from deleting a user's segment documents.

Documentation

• CHANGELOG.md — new. Honest v3.1.0 entry: what was added, what was fixed, what now fails loudly instead of silently, what was removed (breaking), the retracted 64.6s benchmark, and a known-gaps section.
• docs/UPGRADING.md — v2.7.0 → v3.1.0 section covering the breaking OpenCode removal, rebuild-toc now exiting non-zero, the index-directory behaviour change, and the backfill gap above.
• docs/launch/v3.1-blog-post.md — Substack draft. The harness-engineering story: verification by existence vs. by execution, the four rules that replaced it, and what four phases of enforcement actually turned up — ending on the Phase 57 quickstart that returned zero results with exit code 0.
• docs/launch/launch-copy.md — Show HN, r/rust and r/LocalLLaMA drafts, plus a pre-post checklist. Nothing has been posted.

Planning

.planning/MILESTONES.md gets the v3.1 shipped entry (including the known gaps and the defects found by executing docs rather than reading them), ROADMAP marks v3.1 shipped with Phase 58 broken into done vs. maintainer-only, and STATE moves to Phase 58.

Validation

Run on a cleared target/, since the version bump invalidates the cache anyway:

Check	Result
cargo fmt --all -- --check	clean
cargo clippy --workspace --all-targets --all-features -- -D warnings	clean (5m28s)
cargo test --workspace --all-features --exclude e2e-tests	1205 passed, 0 failed
cargo test -p e2e-tests --all-features	60 passed, 0 failed
RUSTDOCFLAGS="-D warnings" cargo doc	clean
all four workflow YAMLs	parse

What's left for you after this merges

1. Tag v3.1.0 — publishes public binaries, so I've left it to you
2. Repo description, topics (ai-agents, memory, rust, claude-code, local-first), Discussions
3. Record the demo
4. Post the blog and the launch threads — checklist at the bottom of docs/launch/launch-copy.md

---

🤖 Generated with Claude Code

https://claude.ai/code/session_014nSJ2c7F9mpmRCxfTAi214

---

Generated by Claude Code