v0.23.0 release readiness: scope, testing, docs, ship checklist

[phernandez]

Single tracking issue for everything between here and just release v0.23.0. Milestone ledger: 111 closed items; feature work is complete — what remains is one validation build-out (#1248), scope decisions, changelog refresh, verification, and choreography.

1. Scope decisions (settle first)

• FastEmbed provider never applies query/passage asymmetry, silently breaking asymmetric models (multilingual-e5) #1264 / Apply E5 query/passage prefixes via the prefixing provider defaults (FastEmbed asymmetry) #1284 — FastEmbed E5 asymmetry: recommend defer to v0.23.1. The fix rides provider-identity + reindex machinery (risky to rush); the semantic_embedding_query_prefix/document_prefix config workaround exists today — document it in known issues instead.
• feat(mcp): adopt FastMCP 4 beta and validate hosted MCP Apps #1181 — FastMCP 4 beta: recommend move off milestone (blocked on cloud; already flagged as likely to move).
• ChatGPT import fails with KeyError 'create_time' on conversations missing that field #1276 — ChatGPT import KeyError create_time: recommend bring in — small importer guard, low risk, real user-facing crash.
• [BUG] Hermes install docs use unsupported --path and fail on latest stable #1280 — Hermes install docs --path: recommend bring in — docs-only fix.
• [BUG] Prose list items still mint typed relations: a capitalized word before a wikilink becomes the relation type #1260 / file_path lookups are byte-wise, so NFC/NFD filename variants create duplicate entities (macOS + Syncthing) #1275 / [BUG] Case-only renames on macOS (case-insensitive APFS) fail via move_note and create duplicate index entries #1281 (prose-relation false positives; NFC/NFD duplicate entities; macOS case-only rename duplicates): recommend v0.23.1 — all touch parser/file-identity right before release. List under known issues.
• Claude Code plugin hooks silently no-op on current release: hook CLI verb only exists on main (not in 0.22.1) #1210 — no action needed; the release itself fixes it (bm hook ships in 0.23). Close on release.

Landed 2026-08-21 during make-ready: #1290 (ChatGPT import, closes #1276 — codex loop hardened it 4×: Windows CRT sentinel, deterministic epoch, UTF-8 400s, immutable message-time rung), #1291 (prose-tail relations, the #1260 slice), #1292 (dev-release pipeline), #1289 (changelog). Benchmark driver: basic-memory-benchmarks PR #42, small-scale validated; its first catch — acknowledged edit_note appends lost to LWW across concurrent MCP sessions — is flagged on #1248 for a product decision.

2. Remaining build item

• Comprehensive v0.23 benchmark: indexing at scale, Redis reads, reranked search #1248 — comprehensive benchmark: indexing at scale + Redis reads + reranked search + multi-agent composite, v0.22.1 vs v0.23 (needs concurrent-writer driver in basic-memory-benchmarks). Honest claims only: MRR 0.616→0.719 (+17%) rerank-on and correctness under concurrency (v0.22.1 deadlocks/duplicates). Do NOT claim ">50% faster" for v0.22.1→v0.23.

3. Testing / verification

• Full CI matrix green on main (SQLite + Postgres, 3 OS) — continuously green through the 2026-08-20 merge batch (fix(cli): run Team push/pull over WebDAV instead of storage credentials #1263, fix(core): count non-Latin tokens when relaxing full-text queries #1269, fix(core): reject transcript timestamp ranges #1271, fix(core): resolve root wikilinks by filename #1272, fix(core): traverse subdirectories in glob-filtered directory listings #1285, test(mcp): add concurrent write_note MCP integration tests #1286)

• Live-Postgres search relaxation suites (post-fix(core): count non-Latin tokens when relaxing full-text queries #1269)

• just package-check (Claude Code plugin, skills, Hermes, OpenClaw — Hermes changed in fix(integrations): preserve Hermes registration ownership #1274/docs(integrations): clarify Hermes monkeypatch by version #1278)

• just doctor — passed 2026-08-20

• just test-smoke — passed 2026-08-20

• Live Team push/pull smoke vs production (fix(cli): run Team push/pull over WebDAV instead of storage credentials #1263 + deployed cloud#1758): push new files → verify cloud-side; pull back; overlapping-edit aborts under default --on-conflict fail; keep-local/keep-cloud resolve correctly. The PR's tests are fixture-based by design — nobody has exercised the deployed server yet.

• Claude Code plugin hooks end-to-end on a 0.23 build — PASS (SessionStart brief + PreCompact checkpoint verified harness-style); stable-release no-op confirmed live, re-verify shim path after release (validates the Claude Code plugin hooks silently no-op on current release: hook CLI verb only exists on main (not in 0.22.1) #1210 fix path against a real harness session)

• Embedding smoke, local half: FastEmbed reindex + semantic/hybrid queries — PASS (5 entities embedded, semantic retrieval verified with zero-lexical-overlap query); remote-provider half still open

• just release-dry-run v0.23.0 — clean, all 11 manifests update; /release-check pre-flight still to run release-day

• Dev-release pipeline repair (ci(core): fix the silently-skipped dev release publish #1292) — merged; gate+build proven live. Publish still fails: PYPI_TOKEN no longer exists, the action falls back to OIDC, and PyPI has no trusted publisher for dev-release.yml (stable releases attest via the release.yml publisher). Cleanup PR ci(core): publish dev releases via trusted publishing #1293 makes OIDC explicit.

• PAUL: register the PyPI trusted publisher for dev builds — PyPI → basic-memory → Settings → Publishing → Add GitHub publisher: owner basicmachines-co, repo basic-memory, workflow dev-release.yml, environment blank. Next main merge then publishes 0.22.2.devN. — found during hooks verification: no dev build has published since the 0.22.1 bump (broken version gate + PyPI-rejected local version segments). Merge ci(core): fix the silently-skipped dev release publish #1292 and confirm its merge commit publishes 0.22.2.devN.

4. Docs

• Changelog refresh PR — merged as docs(core): cover post-entry merges in the v0.23.0 changelog #1289 (14 missing entries + fix(core): guard ChatGPT import against missing create_time #1290/fix(core): stop minting typed relations from prose tails #1291), reviewed line-by-line; — the merged v0.23.0 entry (docs(core): add v0.23.0 changelog entry #1244) predates 14 merged PRs, all currently missing: fix(core): reconcile stale search index rows on reindex #1247, feat(cli): add inspect chunks note-level retrieval view #1249, feat(core): add inspect query retrieval execution trace #1250 (retrieval inspector — headline), perf(mcp): optimize semantic note reads #1255, fix(sync): guard project-index deletes against materialization #1258, fix(cli): run Team push/pull over WebDAV instead of storage credentials #1263 (Team WebDAV push/pull — headline), feat(mcp): add directory listing sorting #1268, fix(core): count non-Latin tokens when relaxing full-text queries #1269, fix(core): reject transcript timestamp ranges #1271, fix(core): resolve root wikilinks by filename #1272, fix(core): preserve repeated default project selection #1273, fix(integrations): preserve Hermes registration ownership #1274, docs(integrations): clarify Hermes monkeypatch by version #1278, fix(core): traverse subdirectories in glob-filtered directory listings #1285. Land via normal PR; leave the 2026-08-XX date placeholder for release day.
• Update the v0.23 release documentation: comprehensive change review (v0.22.1 → main) #1243 change-review comment — posted 2026-08-21; for the post-Aug-12 merges (no new config keys; feat(mcp): add directory listing sorting #1268 adds MCP tool args only)
• Audit docs/v0.23 branch — done 2026-08-21: rebased on main, retrieval-inspector docs added, Team WebDAV setup note corrected, sort/non-Latin mentions, known-issues section (FastEmbed provider never applies query/passage asymmetry, silently breaking asymmetric models (multilingual-e5) #1264/file_path lookups are byte-wise, so NFC/NFD filename variants create duplicate entities (macOS + Syncthing) #1275/[BUG] Case-only renames on macOS (case-insensitive APFS) fail via move_note and create duplicate index entries #1281); npm run check:docs + full Nuxt build pass. NOTE: live repo is docs.basicmemory.com (worktree docs.basicmemory.com-v023), not the dead basic-memory-docs. Release-notes framing wants an author read before merge (docs repo, staged NOT merged) for coverage of the retrieval inspector (bm inspect) and Team WebDAV push/pull; add known-issues section for the deferred bugs. Merge at release (Milvus + local-Postgres documentation gaps from tire-kick session #1238).

5. Release day (in order)

• Scope decisions above resolved; milestone shows only this issue open
• Set changelog date via PR
• just release v0.23.0 (recipe handles version manifests, release PR, tag; never bare git tag)
• Merge docs/v0.23 in the docs repo (main auto-deploys)
• Close Claude Code plugin hooks silently no-op on current release: hook CLI verb only exists on main (not in 0.22.1) #1210, Milvus + local-Postgres documentation gaps from tire-kick session #1238, v0.23 release documentation: comprehensive change review (v0.22.1 → main) #1243, Comprehensive v0.23 benchmark: indexing at scale, Redis reads, reranked search #1248, and this issue

6. Post-release

• basic-memory-cloud: re-pin the basic-memory git rev to the released tag
• docs.basicmemory.com: What's New page under content/2.whats-new/ + version badge in content/index.md
• MCP Registry: mcp-publisher publish from repo root
• Verify Homebrew formula + OpenClaw npm publish (automated; confirm)
• Announcement: Discord; optional blog post on basicmemory.com (significant release — reranking, retrieval inspector, concurrency rebuild, Team sync)

[claude]

Claude finished @phernandez's task in 30s —— View job

---

Triage

Type: Enhancement (labeled enhancement) — this is a release-coordination/tracking issue, not a code defect, doc fix, or support question, so it maps to the closest available type.

Priority: High — it gates the v0.23.0 ship date and bundles real release-blocking work (scope calls on #1264/#1284, #1181, #1276, #1280, #1260/#1275/#1281; the #1248 benchmark build-out; and the outstanding verification/docs checklist).

Component: No single repository component label applies — the checklist spans CLI (just release, just doctor), MCP tooling, sync/Team push-pull, Cloud (Team WebDAV smoke, cloud re-pin), docs (changelog, docs.basicmemory.com), and CI/testing. Labeled component:none per the triage taxonomy, with the cross-cutting scope noted here in prose.

Complexity: Complex — not because any single line item is hard, but because it's a coordination artifact with ~30 checklist items across scope decisions, one remaining feature-adjacent build item (#1248), a full verification pass, docs, and release-day choreography. Several items already reference and depend on other tracked issues (#1210, #1238, #1243, #1248, #1263, #1269).

Duplicates: None found — this is the only open issue matching "v0.23.0 release readiness" / "release readiness" in the repo.

No reproduction steps or clarifying questions are needed; this is a well-specified tracking issue authored by the maintainer. No implementation action taken, per triage scope.

[AutomaticLasagna]

hook session-start brief duplicates one open decision and omits another

Testing the v0.23 hook path (installed from main via uv tool install --from git+..., since the hook verb isn't on PyPI yet, per #1210), the SessionStart brief renders the open-decisions list incorrectly.

Project contains exactly four notes with type: decision, status: open. Verified two ways:

• On disk: four distinct files, each with status: open in frontmatter.
• Via the API: search_notes(type=decision, status=open) returns exactly 4 results, each with a distinct external_id.

The brief renders:

## Open decisions (5)
- Open decision: entity type for the Order · atlantis/decisions/open-decision-entity-type-for-the-order
- Open decision: name used on incorporation paperwork · atlantis/decisions/open-decision-name-used-on-incorporation-paperwork
- Open decision: treatment of pre-entity spend · atlantis/decisions/open-decision-treatment-of-pre-entity-spend
- Open decision: treatment of pre-entity spend · atlantis/decisions/open-decision-treatment-of-pre-entity-spend
- Open decision: treatment of pre-entity spend · atlantis/decisions/open-decision-treatment-of-pre-entity-spend

Count reads 5 for 4 notes, one note repeats three times with an identical permalink, and the fourth never appears. Deterministic across four consecutive runs.

Environment: Windows 11, basic-memory built from main, invoked as the harness does (hook JSON on stdin, CLAUDE_PROJECT_DIR set).

Separately, basic-memory doctor --local fails on this build with Doctor failed: API note file missing: doctor/Doctor API Note.md after creating a doctor-<hash> project.