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

.github/workflows/release.yml

@@ -124,17 +124,25 @@ jobs:
         shell: bash
         run: |
           VERSION=${{ steps.version.outputs.version }}
-          ARCHIVE_DIR="memory-daemon-${VERSION}-${{ matrix.name }}"
+          ARCHIVE_DIR="agent-memory-${VERSION}-${{ matrix.name }}"
           mkdir -p "dist/${ARCHIVE_DIR}"
 
-          # Copy binaries
+          # Copy binaries. All four are required: the README quickstart uses
+          # `memory` for search and `memory-installer` for hook setup, so an
+          # archive missing either is a broken release, not a partial one.
           if [[ "${{ runner.os }}" == "Windows" ]]; then
-            cp target/${{ matrix.target }}/release/memory-daemon.exe "dist/${ARCHIVE_DIR}/"
-            cp target/${{ matrix.target }}/release/memory-ingest.exe "dist/${ARCHIVE_DIR}/" || true
+            EXT=".exe"
           else
-            cp target/${{ matrix.target }}/release/memory-daemon "dist/${ARCHIVE_DIR}/"
-            cp target/${{ matrix.target }}/release/memory-ingest "dist/${ARCHIVE_DIR}/" || true
+            EXT=""
           fi
+          for bin in memory-daemon memory-ingest memory memory-installer; do
+            src="target/${{ matrix.target }}/release/${bin}${EXT}"
+            if [[ ! -f "$src" ]]; then
+              echo "::error::release archive would be missing ${bin}${EXT} for ${{ matrix.name }}"
+              exit 1
+            fi
+            cp "$src" "dist/${ARCHIVE_DIR}/"
+          done
 
           # Copy documentation
           cp LICENSE "dist/${ARCHIVE_DIR}/" || true
@@ -145,7 +153,7 @@ jobs:
         shell: bash
         run: |
           VERSION=${{ steps.version.outputs.version }}
-          ARCHIVE_DIR="memory-daemon-${VERSION}-${{ matrix.name }}"
+          ARCHIVE_DIR="agent-memory-${VERSION}-${{ matrix.name }}"
           cd dist
           tar -czvf "${ARCHIVE_DIR}.tar.gz" "${ARCHIVE_DIR}"
           rm -rf "${ARCHIVE_DIR}"
@@ -155,7 +163,7 @@ jobs:
         shell: pwsh
         run: |
           $VERSION = "${{ steps.version.outputs.version }}"
-          $ARCHIVE_DIR = "memory-daemon-${VERSION}-${{ matrix.name }}"
+          $ARCHIVE_DIR = "agent-memory-${VERSION}-${{ matrix.name }}"
           cd dist
           Compress-Archive -Path $ARCHIVE_DIR -DestinationPath "${ARCHIVE_DIR}.zip"
           Remove-Item -Recurse -Force $ARCHIVE_DIR

.planning/MILESTONES.md

@@ -1,5 +1,67 @@
 # Project Milestones: Agent Memory
 
+## v3.1 Make It True (Shipped: 2026-08-31)
+
+**Delivered:** no new capabilities. Four phases closing the gap between what the
+project claimed and what it did, after a v3.0 verification document self-graded
+17/17 on a benchmark that had never been run and a crate no shipped binary could
+reach.
+
+**Phases completed:** 54, 54.5, 55, 56, 57 (5 phases, 14 plans + a cleanup phase)
+
+**Key accomplishments:**
+
+- `memory-orchestrator` made reachable: `RouteQuery` calls it, `memory search`
+  is a client of that RPC (`cargo tree -i` now shows a shipped dependent)
+- Hybrid retrieval actually fuses BM25 and vector; BM25 outbox drain no longer a
+  no-op; event documents store text so previews and LLM reranking work
+- Explainability reports what actually ran — a failed LLM rerank says
+  `rerank=heuristic`, `layers_attempted` lists only invoked layers, client stop
+  conditions reach the orchestrator instead of being echoed and ignored
+- Performance measurement split setup from query: the retired "64.6s TOC
+  navigation" figure was ingest-time rollup; warm query p50 is 0.13 ms.
+  Percentiles withheld below 10 (p90) / 30 (p99) samples
+- Honest benchmark harness: the substring metric is named `context_hit_rate`,
+  not "LOCOMO"; committed results are labelled mock-backend / mock-judge, and no
+  comparative accuracy claim ships anywhere
+- Root README, LICENSE, positioning writeup, CHANGELOG — the repo had none
+- Supported-surface tiering: Tier 1 (Claude Code, Codex) gates PRs, Tier 2
+  (Gemini, Copilot) runs weekly. OpenCode stub deleted rather than shipped
+- Release archives now contain all four binaries; previously the CLI the
+  quickstart depends on was not shipped at all
+
+**Process changes (bound to this milestone):**
+
+- Execution-evidence rule: run-dependent requirements must cite a committed
+  artifact produced by running them
+- Reachability rule: a new crate is not complete until `cargo tree -i` shows a
+  dependent binary, or it is explicitly declared dormant
+- `human_verification` items gating the milestone goal are blockers by default
+- The v3.0 retrospective was written: *the code is strong; the claims were not*
+
+**Defects found by executing documentation rather than reading it:**
+
+- First-run daemon created no index directories, so it accepted events and
+  answered every query with an empty result set — successfully
+- `admin rebuild-toc` printed a TODO and exited 0; `--dry-run` advertised a
+  rebuild that did nothing
+- `admin rebuild-bm25` is a prune, not a rebuild — relabelled rather than renamed
+
+**Known Gaps:**
+
+- No backfill for events indexed before v3.1 (`text_preview` stays empty)
+- No real-backend / real-judge LOCOMO run, so no comparative claim
+- Vector retrieval quality is not benchmarked
+- GitHub repo description, topics, Discussions, and a recorded demo are
+  maintainer actions, not code
+
+**Stats:**
+
+- 64,626 LOC Rust across 20 crates
+- Timeline: 2026-08-30 → 2026-08-31
+
+---
+
 ## v2.7 Multi-Runtime Portability (Shipped: 2026-03-22)
 
 **Delivered:** Rust-based multi-runtime installer that converts canonical Claude plugin source into runtime-specific installations for 6 targets, replacing 5 manually-maintained adapter directories with a single conversion pipeline.

.planning/ROADMAP.md

@@ -12,7 +12,7 @@
 - ✅ **v2.6 Cognitive Retrieval** — Phases 39-44 (shipped 2026-03-16)
 - ✅ **v2.7 Multi-Runtime Portability** — Phases 45-50 (shipped 2026-03-22)
 - **v3.0 Competitive Parity & Benchmarks** — Phases 51-53 + Phase 51.5 (in progress; Phase 51.5 merged 2026-04-28)
-- **v3.1 Make It True** — Phases 54-58 (in progress; Phases 54, 54.5, 55, 56 merged 2026-08-30, Phase 57 executing)
+- ✅ **v3.1 Make It True** — Phases 54-58 (shipped 2026-08-31)
 
 ## Phases
 
@@ -285,13 +285,22 @@ Close the claim/reality gap, then open the shop window. No new capabilities.
 - [x] 56-02: LOCOMO adapter v2 (real schema, mock vs llm-judge)
 - [x] 56-03: Smoke artifacts + HOLD comparison marketing
 
-### Phase 57: Shop Window & Positioning (3/3 plans) — IN EXECUTION 2026-08-30
+### Phase 57: Shop Window & Positioning (3/3 plans) — COMPLETE 2026-08-31 (PR #36)
 
 - [x] 57-01: Repo hygiene (root README, LICENSE, repository URL)
 - [x] 57-02: Positioning writeup vs Mem0 / Zep / MemMachine / Letta
 - [x] 57-03: Scope trim — Tier 1/Tier 2 surface; OpenCode stub deleted
 
-### Phase 58: Launch (side quest)
+### Phase 58: Launch (side quest) — IN EXECUTION 2026-08-31
 
-*Updated: 2026-08-30 — Phase 56 merged (#34); Phase 57 Shop Window in execution*
+- [x] Version bumped to 3.1.0 (was still 2.7.0 across v3.0 and v3.1)
+- [x] CHANGELOG.md and v3.1 upgrade notes
+- [x] Release archives ship all four binaries; assets renamed `agent-memory-*`
+- [x] Blog post and Show HN / reddit copy drafted in `docs/launch/`
+- [ ] Tag `v3.1.0` (maintainer — publishes public binaries)
+- [ ] Repo description, topics, Discussions (maintainer — repo settings)
+- [ ] Recorded demo (maintainer)
+- [ ] Post the blog and the launch threads (maintainer)
+
+*Updated: 2026-08-31 — Phase 57 merged (#36); v3.1 shipped; Phase 58 launch prep*
 

.planning/STATE.md

@@ -1,16 +1,16 @@
 ---
 gsd_state_version: 1.0
 milestone_name: Make It True
-status: in_progress
+status: shipping
 stopped_at: null
-last_updated: "2026-08-30T22:30:00.000Z"
-last_activity: 2026-08-30 — Phase 56 merged (#34); Phase 57 Shop Window & Positioning in execution
+last_updated: "2026-08-31T01:30:00.000Z"
+last_activity: 2026-08-31 — Phase 57 merged (#36); v3.1 shipped; Phase 58 launch prep (version 3.1.0, CHANGELOG, launch drafts)
 progress:
   total_phases: 6
-  completed_phases: 4
+  completed_phases: 5
   total_plans: 14
-  completed_plans: 11
-  percent: 79
+  completed_plans: 14
+  percent: 100
 ---
 
 # Project State
@@ -20,30 +20,33 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-22)
 
 **Core value:** Agent can answer "what were we talking about last week?" without scanning everything
-**Current focus:** v3.1 Phase 57 — Shop Window & Positioning (root README, LICENSE, positioning writeup, supported-surface tiering)
+**Current focus:** v3.1 Phase 58 — Launch (side quest): version 3.1.0, CHANGELOG, release archive fixes, launch drafts. The tag and the public posts are maintainer actions.
 
 ## Current Position
 
-Phase: 57 of 58 (Shop Window & Positioning)
-Plan: 01-03 implemented on `claude/phase-54-toolchain-drift-3k4fer`
-Status: Phases 54, 54.5, 55, 56 merged; Phase 57 in review
-Last activity: 2026-08-30 — #34 merged; Phase 57 README/LICENSE/positioning/scope-trim
+Phase: 58 of 58 (Launch — side quest, not a GSD phase)
+Status: all v3.1 GSD phases merged (54, 54.5, 55, 56, 57). Launch prep in review.
+Last activity: 2026-08-31 — #36 merged; version bumped 2.7.0 → 3.1.0
 
-Progress: [████████░░] 11/14 plans merged; Phase 57's 3 plans are implemented and in review
-(Phase 58 is a side quest, not a GSD phase)
+Progress: [██████████] 14/14 plans merged. v3.1 GSD work complete.
+
+Remaining launch steps are maintainer actions: tag `v3.1.0` (publishes public
+binaries), set the repo description/topics/Discussions, record the demo, and
+post the blog and launch threads.
 
 ## Out-of-band Work
 
 ### Open PRs
 
 | PR | What | Status |
 |---|---|---|
-| _(none open)_ | | |
+| _(Phase 58 launch prep)_ | version 3.1.0, CHANGELOG, release fix, launch drafts | Open |
 
 ### Recently Merged
 
 | PR | What | Merged |
 |---|---|---|
+| #36 | Phase 57 Shop Window & Positioning | 2026-08-31 |
 | #34 | Phase 56 Honest Benchmarks | 2026-08-30 |
 | #35 | Phase 54.5 truth leaks + rustc 1.97 pin | 2026-08-30 |
 | #33 | Phase 55 Performance Truth | 2026-08-30 |
@@ -64,3 +67,6 @@ Progress: [████████░░] 11/14 plans merged; Phase 57's 3 plan
 - Phase 57 tiering: Tier 1 = Claude Code + Codex CLI (PR gate); Tier 2 = Gemini + Copilot (weekly schedule)
 - Phase 57: OpenCode removed rather than archived — a converter whose methods return empty is a false success, not a gap
 - Phase 57: no comparative benchmark claim ships while the only committed results are mock-backend / mock-judge
+- Phase 58: version is 3.1.0 — it had been stuck at 2.7.0 through the whole v3.0 and v3.1 line, and there are no tags in the repo
+- Phase 58: release archives are `agent-memory-<version>-<platform>` and carry all four binaries; the CLI the quickstart needs was previously not shipped
+- Phase 58: `admin rebuild-bm25` is a prune, not a rebuild — relabelled rather than renamed, and there is no event backfill path

CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+Notable changes per release. Dates are the release date, not the merge date of
+the last commit.
+
+The guiding rule for this file, after the v3.0 retrospective: **a change is
+listed only if it is true of the shipped code.** Claims that turned out to be
+aspirational are recorded as retractions, not quietly dropped.
+
+## v3.1.0 — Make It True (2026-08-31)
+
+No new capabilities. This release closes the gap between what the project
+claimed and what it did.
+
+### Added
+
+- Root `README.md` and `LICENSE` (MIT) — the repository had neither
+- `docs/positioning/agent-memory-vs-competition.md` — head-to-head against
+  Mem0, Zep, MemMachine and Letta, with a claims ledger and the platform-risk
+  argument stated up front
+- `docs/verification/57-quickstart-transcript.md` — the quickstart executed on
+  a clean machine, including the three defects the first run exposed
+- `docs/benchmarks.md` — what the performance harness measures and what it does
+  not
+- Supported-surface tiering: Tier 1 (Claude Code, Codex CLI) gates every PR;
+  Tier 2 (Gemini, Copilot) runs on a weekly schedule
+- Release archives now ship all four binaries (`memory-daemon`,
+  `memory-ingest`, `memory`, `memory-installer`); previously the CLI the
+  quickstart depends on was not in the release at all
+
+### Fixed
+
+- **First-run daemon indexed nothing.** A fresh store had no `db/search` or
+  `db/vector`, so the outbox indexing job never registered and every query
+  returned an empty result set with no error. `start_daemon` now creates them
+- **`memory-orchestrator` was unreachable** from any shipped binary. `RouteQuery`
+  now calls it, and `memory search` is a client of that RPC
+- **Hybrid search was not hybrid** — it now fetches BM25 and vector results and
+  fuses them
+- **BM25 outbox drain was a no-op**; events are indexed, and misses warn and
+  increment a counter instead of passing silently
+- **BM25 stored no text for events**, so previews were empty and the LLM
+  reranker was judging blank bodies. New event documents are `TEXT | STORED`
+- **A successful LLM rerank was undone** by a salience re-sort afterwards
+- **Explainability misreported what ran**: a failed LLM rerank said
+  `rerank=llm`, `layers_attempted` listed layers that returned nothing, and
+  client `stop_conditions` / `mode_override` were echoed back while being
+  ignored. All now report and behave truthfully
+- Per-event grip full-scan on the BM25 drain (an O(n²) drain) removed
+- Retrieval fan-out is concurrent unless explicitly sequential
+- Query, prune and dedup share one HNSW handle; embedding dimension comes from
+  the embedder rather than a hardcoded 384
+- Lock poisoning is recovered and counted rather than panicking
+- CI pinned to Rust 1.97 via `rust-toolchain.toml`, after a floating-stable
+  Clippy lint reddened `main`
+
+### Changed — now fails loudly instead of silently
+
+- `memory-daemon start --background` exits non-zero with guidance; background
+  daemonization is not implemented
+- `memory-daemon admin rebuild-toc` exits non-zero; offline TOC rebuild is not
+  implemented and no longer prints a TODO and exits 0
+- `CrossEncoderReranker` returns an explicit `NotImplemented` error rather than
+  degrading quietly
+- An unknown `--rerank` value is rejected rather than falling back to heuristic
+- `admin rebuild-bm25` is relabelled: it prunes documents below `--min-level`
+  and re-indexes nothing, which is what it always did
+
+### Removed (breaking)
+
+- **OpenCode is no longer a supported runtime.** Every method of its converter
+  returned empty, so `memory-installer --agent opencode` exited 0 and wrote no
+  files. The converter, the `Runtime::OpenCode` variant, its tool mappings, its
+  bats suite and the archived plugin directory are gone. `--agent opencode` now
+  exits 2. The runtime-agnostic `memory-ingest --agent opencode` path is
+  unaffected. See [UPGRADING](docs/UPGRADING.md)
+
+### Benchmarks
+
+- The "64.6 second TOC navigation" figure is **retracted**. It timed
+  ingest-time summarization rollup and labelled it navigation. Warm query
+  `single.toc` p50 is 0.13 ms over 30 samples
+- Percentiles are withheld below 10 samples (p90) and 30 samples (p99) instead
+  of being interpolated from 3
+- Committed results in `benchmarks/results/` are **mock-backend and mock-judge**
+  and are labelled as such. No comparative accuracy claim ships anywhere in this
+  repository until a real-backend, real-judge run is committed beside it
+
+### Known gaps
+
+- No backfill for events indexed before v3.1 — their `text_preview` stays empty
+- Vector search requires the embedding model download on first daemon start;
+  with no network the daemon warns and runs BM25-only
+- Ingest to searchable is a ~1 minute scheduled outbox drain, not synchronous
+
+## Earlier releases
+
+Milestones v1.0 through v3.0 predate this file. Their scope is recorded in
+`.planning/MILESTONES.md` and `.planning/ROADMAP.md`, and upgrade notes for
+v2.0.0 through v2.2.0 are in [docs/UPGRADING.md](docs/UPGRADING.md).

Cargo.toml

@@ -24,7 +24,7 @@ members = [
 ]
 
 [workspace.package]
-version = "2.7.0"
+version = "3.1.0"
 edition = "2021"
 license = "MIT"
 repository = "https://github.com/SpillwaveSolutions/agent-memory"

README.md

@@ -86,6 +86,10 @@ cargo build --release -p memory-daemon -p memory-ingest -p memory-cli
 export PATH="$PWD/target/release:$PATH"
 ```
 
+Prefer not to compile? Each release ships one archive per platform containing
+all four binaries — see
+[docs/setup/quickstart.md](docs/setup/quickstart.md#option-b-prebuilt-binaries).
+
 ### 2. Start the daemon
 
 The daemon runs in the foreground. There is no built-in background mode — use
@@ -159,7 +163,7 @@ is experimental.
 | Passive hook capture → `memory-ingest` | **Solid** | Covered by the bats CLI suites on Linux + macOS |
 | TOC build and drill-down navigation | **Solid** | Year → Month → Week → Day → Segment → Grip |
 | Grips / provenance | **Solid** | Excerpts link back to the events they came from |
-| BM25 keyword search (Tantivy) | **Solid** | Exact tokens, no stemming (`jwt` does not match `JWTs`). Indexes built before v3.1 do not store text — rebuild to get event previews |
+| BM25 keyword search (Tantivy) | **Solid** | Exact tokens, no stemming (`jwt` does not match `JWTs`). Events indexed before v3.1 have empty `text_preview` and there is no backfill command — see [UPGRADING](docs/UPGRADING.md) |
 | Vector search (HNSW + Candle) | **Solid** | First daemon start downloads the embedding model; with no network the daemon warns and runs BM25-only |
 | Topic graph | **Works** | Clustering quality is not benchmarked |
 | Hybrid fusion + `RouteQuery` orchestration | **Works** | Wired end-to-end in Phase 54; explainability reports what actually ran |
@@ -215,6 +219,7 @@ unaffected by tiering.
 | [docs/verification/57-quickstart-transcript.md](docs/verification/57-quickstart-transcript.md) | The transcript of this quickstart being run on a clean machine, defects and all |
 | [docs/positioning/agent-memory-vs-competition.md](docs/positioning/agent-memory-vs-competition.md) | Head-to-head vs Mem0 / Zep / MemMachine / Letta |
 | [docs/UPGRADING.md](docs/UPGRADING.md) | Version-to-version migration notes |
+| [CHANGELOG.md](CHANGELOG.md) | What changed per release, including retractions |
 
 ## Contributing
 

crates/memory-adapters/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "memory-adapters"
-version = "2.7.0"
+version.workspace = true
 edition = "2021"
 description = "Agent adapter SDK for multi-agent memory integration"
 license = "MIT"

crates/memory-daemon/src/cli.rs

@@ -306,7 +306,8 @@ pub enum AdminCommands {
         dry_run: bool,
     },
 
-    /// Rebuild BM25 index with level filtering
+    /// Prune BM25 documents below a TOC level. Despite the name this does not
+    /// re-index anything -- it only removes documents below `--min-level`.
     RebuildBm25 {
         /// Minimum TOC level to keep: segment, day, week, month, year
         #[arg(long, default_value = "day")]