docs: v0.23.0 release documentation

CLAUDE.md

@@ -179,7 +179,7 @@ pip install basic-memory
 When updating docs for a new Basic Memory release, update all of the following:
 
 1. **Welcome page What's New callout** — `content/0.welcome.md`: update the version text (e.g., `v0.22`) and the headline; the link stays `/whats-new/changelog`
-2. **Changelog page** — `content/2.whats-new/1.changelog.md`: add a section for the new minor/major version at the top, linking the GitHub release tag(s). Patch release: add a short bullet list under its minor version's section instead. The `::github-releases` block at the bottom auto-fetches full release notes from the GitHub API — no manual update needed there. There are no per-version pages — deep links to version-specific behavior point at GitHub release tags
+2. **Changelog page** — `content/2.whats-new/1.changelog.md`: add a section for the new minor/major version at the top, linking the GitHub release tag(s). Patch release: add a short bullet list under its minor version's section instead. The `::github-releases` block at the bottom auto-fetches full release notes from the GitHub API — no manual update needed there. Since v0.23, significant releases also get a per-version What's New page (`content/02.whats-new/01.v0-XX.md`, zero-padded prefixes so 10+ pages sort correctly); the welcome-page `::note` callout links to it
 3. **Feature docs** — if the release adds user-facing features, update the relevant guide and reference pages (`content/3.cloud/`, `content/9.reference/`, etc.)
 4. **Deploy** — push to main auto-deploys to development; production requires manual workflow dispatch via GitHub Actions
 

content/0.welcome.md

@@ -11,7 +11,7 @@ seo:
 **Basic Memory** is real memory for your AI — a knowledge base you own. Built-in AI memory is small, vendor-owned, and usually invisible. Basic Memory is large, structured, and inspectable: a knowledge graph written in plain Markdown. Open it in any editor, hand it to any AI tool, and keep it forever.
 
 ::note{icon="i-lucide-megaphone"}
-**New in Basic Memory Cloud:** review notes change by change with [Comments and Suggestions](/whats-new/comments-and-suggestions), and browse, edit, or graph your knowledge directly inside ChatGPT and Claude with the [Interactive MCP App](/whats-new/interactive-mcp-app).
+**New in v0.23:** the search release — reranking, Milvus, and a deadlock-free indexing core. See [What's New in v0.23](/whats-new/v0-23). Also new in Basic Memory Cloud: [Comments and Suggestions](/whats-new/comments-and-suggestions) and the [Interactive MCP App](/whats-new/interactive-mcp-app) for ChatGPT and Claude.
 ::
 
 ## Pick your path

content/01.start-here/3.quickstart-local.md

@@ -218,7 +218,7 @@ Restart Claude Desktop for changes to take effect. For more on projects and defa
 ## Useful CLI commands
 
 ```bash
-# Check sync status
+# Check project index status
 basic-memory status
 
 # List all projects

content/02.whats-new/01.v0-23.md

@@ -0,0 +1,74 @@
+---
+title: Basic Memory v0.23
+description: Reranked semantic search, pluggable vector indexes with Milvus, deadlock-free concurrent indexing, and a retrieval inspector.
+---
+
+**Basic Memory v0.23** shipped in August 2026 ([v0.23.0 release notes](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0)). The theme is search you can trust: semantic search matures with cross-encoder reranking and pluggable vector indexes, the indexing core stops deadlocking under concurrent writers, and a new inspector shows exactly why a search returned what it did.
+
+## Search that ranks
+
+### Opt-in cross-encoder reranking
+
+Vector and hybrid search can now rescore their leading candidates with a cross-encoder that reads the query and each candidate together:
+
+```bash
+bm config set reranker_enabled true
+```
+
+The default provider runs a local FastEmbed ONNX model — no API key, no per-query cost — and LiteLLM connects hosted rerankers from Cohere, Jina, and Voyage. On the LoCoMo long-conversation retrieval benchmark, reranking improved mean reciprocal rank from 0.616 to 0.719 — a 17% improvement in how high the right note lands in the results. Reranking is off by default and downloads its local model on the first reranked search. See [Enable reranking](/concepts/semantic-search#enable-reranking).
+
+### Pluggable vector indexes, with first-party Milvus
+
+Postgres deployments can now choose where vectors live: the new `semantic_vector_index` setting selects `pgvector` (the default) or Milvus, Milvus Lite, and Zilliz Cloud via `pip install "basic-memory[milvus]"`. A vector-index identity and readiness manifest lets search tell "no ready index" apart from "no results", and SQLite keeps sqlite-vec. After switching backends, rebuild with `bm reindex --embeddings`. See [Run Postgres with Milvus](/local/postgres-and-milvus).
+
+### Embedding and full-text correctness
+
+A batch of fixes makes search results more trustworthy across the board:
+
+- Notes edited directly on disk are vector-embedded when the file watcher picks them up — no more waiting for a reindex
+- FastEmbed embeddings are L2-normalized for non-BGE models, so semantic scores no longer silently degrade
+- SQLite full-text search covers complete note content (previously text beyond ~6,000 characters was invisible), and non-Latin queries — CJK, Cyrillic, Greek, Hebrew, Arabic, and more — relax correctly instead of silently degrading
+- `bm reindex --embeddings` exits nonzero on real failures and reports which index it wrote
+
+## Indexing that no longer deadlocks
+
+Underneath search, the indexing and persistence core is rebuilt around generation-versioned relations and observations with compare-and-swap publication. A stale indexing pass can never clobber or deadlock against a newer write, and observations and relations land with the accepted write instead of waiting for the next file re-index. The deadlock and lost-observation failures that appeared under concurrent multi-agent write loads are gone, and a one-time migration repairs historical duplicate observation rows left behind by the old behavior.
+
+## See what search sees
+
+The new retrieval inspector answers "why did search return that?" from the command line:
+
+- **`bm inspect chunks <note>`** shows a note exactly as the index sees it — its search rows, the vector chunks each row produced, and per-chunk ready/pending/stale/orphaned status — separating chunking problems from freshness problems in one command
+- **`bm inspect query "<query>"`** captures an execution trace from the same search call that returns the results: full-text and vector candidates, fusion, filtering, reranking, and the final page window, with stable JSON output and `--show-misses` for rejected candidates
+
+See [Retrieval inspection commands](/reference/cli-reference#retrieval-inspection-commands).
+
+## Team workspace push and pull for every member
+
+`bm cloud push` and `bm cloud pull` now work on Team workspaces for every member. Transfers run over the cloud's permissioned WebDAV API with per-project access checks — previously these commands required owner-only storage credentials, and every other member got a 403. Flags and semantics are unchanged: transfers stay additive (nothing is ever deleted) and `--on-conflict` still defaults to `fail`. See [Push and pull](/cloud/cloud-sync#push-and-pull-additive-git-style).
+
+## A real operator front door
+
+Day-to-day operation gets first-class commands:
+
+- **`bm config`** — `list` effective settings with environment overrides marked, `get`, `set` (validated through the config model), and `unset`. See [Configuration commands](/reference/cli-reference#configuration-commands)
+- **Rich `bm tool` output** — interactive commands render panels, tables, and trees on a TTY; piped output stays machine-readable, with `--plain` and `--json` overrides
+- **`basic_memory_diagnostics`** — a new MCP tool that reports version and system info for bug reports
+- **`bm status`** — redesigned around project index status
+- **`bm hook`** — harness lifecycle capture moves into the package: SessionStart and PreCompact handling for Claude Code and Codex, bounded envelope capture into a local inbox, and `bm hook status`, `flush`, `install`, and `remove` for standalone setups. See [Harness Capture](/integrations/harness-capture)
+
+## Cloud additions
+
+- **`bm cloud share`** — create, list, update, and revoke public share links from the CLI. See [Manage public share links](/cloud/cloud-cli#manage-public-share-links)
+- **`bm cloud prune`** — targeted cleanup that deletes cloud files matching this machine's `.bmignore`, without a full mirror sync. See [Prune newly ignored cloud files](/cloud/cloud-sync#prune-newly-ignored-cloud-files)
+- **Optional Redis read cache** — standalone MCP servers can cache reads via `pip install "basic-memory[redis]"` and `redis_url`. See [Optional Redis read cache](/reference/configuration#optional-redis-read-cache)
+
+## Upgrading
+
+Five database migrations run automatically on first start, including a one-time repair that removes duplicate observation rows and purges their stale full-text search entries. Most local setups need no manual action, but v0.23 also removes MCP tools and legacy API routes and changes several CLI, config, sync, and pagination contracts.
+
+::note{icon="i-lucide-arrow-up-circle"}
+Before upgrading an integration or automation, read [Upgrade to v0.23](/whats-new/v0-23-upgrade) for the breaking changes, required actions, and known issues.
+::
+
+For the complete list of changes, see the [Changelog](/whats-new/changelog) and the [v0.23.0 release on GitHub](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0).

content/02.whats-new/3.changelog.md → content/02.whats-new/05.changelog.md

@@ -7,6 +7,22 @@ Notable changes in each Basic Memory release, most recent first. For complete pa
 
 ---
 
+## v0.23 — Search that ranks and scales
+
+*[v0.23.0](https://github.com/basicmachines-co/basic-memory/releases/tag/v0.23.0)*
+
+Semantic search takes a major step forward in v0.23. Opt-in cross-encoder reranking can rescore vector and hybrid candidates locally with FastEmbed or through LiteLLM, while Postgres deployments can move vector storage from pgvector to Milvus, Milvus Lite, or Zilliz Cloud. File-watcher writes now receive embeddings, non-BGE FastEmbed models are normalized correctly, SQLite full-text search covers complete long notes and relaxes non-Latin queries (CJK, Cyrillic, and other scripts), and reindex failures are reported honestly.
+
+The operator surface expands with **`bm inspect`** — a [retrieval inspector](/reference/cli-reference#retrieval-inspection-commands) that shows how the index sees a note (`bm inspect chunks`) and traces a query's retrieval stages (`bm inspect query`) — plus **`bm config`** for validated settings, **`bm hook`** for harness lifecycle capture, Rich interactive output for **`bm tool`**, a diagnostics MCP tool, a usable local Postgres path, Cloud share management, and targeted **`bm cloud prune`** cleanup.
+
+Team workspaces gain working **`bm cloud push`**/**`pull`**: transfers now run over the cloud's permissioned WebDAV API with per-project access checks, so every member can sync — previously these commands required owner-only storage credentials on Team workspaces. `list_directory` learns title and updated-time sorting for one-read folder navigation.
+
+Underneath those features, the indexing and persistence core moves to generation-versioned relations and observations, compare-and-swap materialization, consistent lock ordering, and batched resolution. Observations and relations now land with accepted writes, eliminating the deadlock and stale-projection failures that appeared under concurrent agent workloads.
+
+This release also removes MCP tools and legacy API routes and changes several CLI, config, sync, edit, and pagination contracts. Read [What's New in v0.23](/whats-new/v0-23) for the highlights and [Upgrade to v0.23](/whats-new/v0-23-upgrade) before upgrading an integration or automation.
+
+---
+
 ## August 2026 — Cloud review and interactive MCP Apps
 
 *August 2026 · Basic Memory Cloud*

content/02.whats-new/06.v0-23-upgrade.md

@@ -0,0 +1,103 @@
+---
+title: Upgrade to v0.23
+description: Breaking changes, migrations, and required actions when upgrading Basic Memory from v0.22.1 to v0.23.
+---
+
+v0.23 applies database migrations automatically, but integrations and operator scripts need review. Complete the actions below before relying on existing automation.
+
+## Rebuild vectors after changing indexes
+
+If you change `semantic_vector_index` between `pgvector` and `milvus`, rebuild the configured vector store:
+
+```bash
+bm reindex --embeddings
+```
+
+The default incremental run is enough. Before it finishes, vector search returns no results and hybrid search quietly serves full-text results only. See [Run Postgres with Milvus](/local/postgres-and-milvus) for the full switch and recovery procedure.
+
+Milvus requires the `basic-memory[milvus]` extra. Standalone Redis read caching requires `basic-memory[redis]`. Reranking remains off by default and downloads its local model on the first reranked search.
+
+## Update CLI automation
+
+- `bm status` now reports project index status instead of the old sync-report tree. Scripts that parse its human output must switch to `--json` and the new shape.
+- `bm reindex --embeddings` exits nonzero when embedding fails. Treat that exit as a real failed rebuild instead of assuming success.
+- Interactive `bm tool` commands render Rich output on a TTY. Piped output remains machine-readable; pass `--json` when a script requires a stable contract.
+- The new top-level groups are `bm config` and `bm hook`. The top-level command set otherwise remains intact; `bm sync` was already absent in v0.22.1.
+
+## Update MCP clients
+
+- The `canvas`, `cloud_info`, and `release_notes` MCP tools are removed. Obsidian Canvas generation and the API resource-write endpoints behind it are no longer available.
+- The ChatGPT compatibility tools `search` and `fetch` now accept OpenAI MCP clients only. Other clients must use `search_notes` and `read_note`.
+- `list_directory` is bounded and paginated. Consumers must use `page` and `page_size` instead of assuming one exhaustive response.
+- `replace_section` is heading-level-aware. By default it replaces the selected section through the next heading of the same or higher level, including nested subsections. Set `replace_subsections=false` to preserve nested subsections.
+- Ambiguous identifiers now raise an error instead of returning a best guess, and `write_note` rejects filename-convention twins instead of creating a duplicate.
+- FastMCP moves to `4.0.0b1` with MCP SDK v2. Downstream embedders pinned to FastMCP 3.x must upgrade with Basic Memory.
+
+## Update HTTP clients
+
+Resource write endpoints and pre-v0.18.0 legacy routes are removed. Old clients that still call those routes receive `404` responses. The current v2 API remains the supported surface.
+
+## Update configuration
+
+Basic Memory automatically migrates these config-file keys and legacy environment variables:
+
+| Old | New |
+|---|---|
+| `sync_delay` | `index_delay` |
+| `sync_changes` | `index_changes` |
+
+When old and new names are both set, the new name wins.
+
+`sync_thread_pool_size` and `sync_max_concurrent_files` are removed without aliases and are silently ignored in `config.json`. Remove them. `materialization_workers` is the nearest replacement for bounding local write materialization, but it is not a one-for-one thread-pool setting.
+
+## Review behavior changes
+
+::warning
+`bm cloud sync` is a one-way mirror and now deletes a previously synced cloud file when that file becomes ignored by `.bmignore`. Preview the exact deletion set with `bm cloud sync --name <project> --dry-run`, or use the additive `bm cloud push` and `bm cloud pull` workflow.
+::
+
+- Deleting the default project now chooses a new default instead of refusing the deletion.
+- `created` and `modified` frontmatter timestamps are authoritative. Historical values can change recency ordering after the first reindex.
+- Timestamp-shaped labels and Markdown checkbox markers are no longer indexed as observation categories.
+- Note-type filters are case-canonicalized, so values such as `Person` and `person` now match the same population.
+
+## Let migrations finish
+
+Five revisions run automatically on first start:
+
+1. A durable note-file vacate record distinguishes moves from byte-identical copies.
+2. The semantic manifest gains vector-index identity and readiness state.
+3. Relation-derived search refreshes become durable, retryable work items.
+4. Relations and their search refreshes gain generation ownership.
+5. A one-time repair removes duplicate observations and orphaned observation rows from full-text search.
+
+The final repair is not reversible through a downgrade. Markdown files remain the source of truth and the index is rebuildable, but back up `memory.db` before the upgrade if you want a pre-migration database snapshot.
+
+## Known issues in v0.23.0
+
+### Asymmetric FastEmbed models need manual prefixes
+
+The FastEmbed provider does not apply query/passage prefixes automatically, so asymmetric embedding models — notably the `intfloat/multilingual-e5` family, the strongest local option for multilingual notes — run off-label and retrieval quality collapses without them ([#1264](https://github.com/basicmachines-co/basic-memory/issues/1264)). The prefix configuration below is the supported setup for these models; per-model-family automatic defaults are tracked separately in [#1284](https://github.com/basicmachines-co/basic-memory/issues/1284). Set the literal prefixes yourself:
+
+```bash
+bm config set semantic_embedding_query_prefix "query: "
+bm config set semantic_embedding_document_prefix "passage: "
+```
+
+The trailing spaces are meaningful and preserved. Both prefixes are part of the embedding provider identity, so setting or changing them re-embeds your notes — run `bm reindex --embeddings` afterwards. The symmetric default model (`bge-small-en-v1.5`) needs no prefixes.
+
+### macOS file-identity edge cases
+
+Two open issues can produce duplicate entities for a single file on macOS:
+
+- **Unicode normalization (NFC/NFD):** APFS preserves whichever byte form a filename was written with, and some cross-platform sync tools (notably Syncthing) rewrite names to the other form. File-path lookups are byte-wise, so the same file can be indexed twice, accumulating `-1`-suffixed permalinks and breaking `edit_note` on the affected notes ([#1275](https://github.com/basicmachines-co/basic-memory/issues/1275)).
+- **Case-only renames:** on a case-insensitive APFS volume, renaming `config.md` to `Config.md` via `move_note` is refused as "destination already exists"; case-only folder renames can silently not change the folder's case on disk and leave duplicate index entries behind ([#1281](https://github.com/basicmachines-co/basic-memory/issues/1281)).
+
+Workarounds: avoid case-only and normalization-only renames from MCP tools (rename through an intermediate name instead), and run `bm reindex --full -p <project>` to collapse duplicates if they appear.
+
+## Continue setup
+
+- [Semantic Search](/concepts/semantic-search) — enable and tune reranking.
+- [Run Postgres with Milvus](/local/postgres-and-milvus) — start local Postgres, configure Milvus, and switch indexes safely.
+- [Configuration](/reference/configuration) — review every new v0.23 setting.
+- [CLI Reference](/reference/cli-reference) — update commands and output contracts.