From e1df23d7939bbf72e5d10c924f08cd447ed88913 Mon Sep 17 00:00:00 2001 From: phernandez Date: Tue, 24 Feb 2026 20:20:23 -0600 Subject: [PATCH] docs: add v0.19.0 release notes Covers all 66 commits since v0.18.0: semantic vector search, schema system, project-prefixed permalinks, per-project cloud routing, FastMCP 3.0 upgrade, and 16 bug fixes. Co-Authored-By: Claude Opus 4.6 Signed-off-by: phernandez --- docs/releases/v0.19.0.md | 252 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/releases/v0.19.0.md diff --git a/docs/releases/v0.19.0.md b/docs/releases/v0.19.0.md new file mode 100644 index 00000000..4a146263 --- /dev/null +++ b/docs/releases/v0.19.0.md @@ -0,0 +1,252 @@ +# v0.19.0 Release Notes + +## Overview + +v0.19.0 is a major release that introduces semantic vector search, a schema validation system, +project-prefixed permalinks, per-project cloud routing, and a significant upgrade to FastMCP 3.0. +It includes 66 commits since v0.18.0 spanning new features, architectural improvements, and +stability fixes across both SQLite and Postgres backends. + +--- + +## Major Features + +### Semantic Vector Search + +Full vector and hybrid search for SQLite (via sqlite-vec) and Postgres (via pgvector). + +- **Hybrid search mode** combines full-text search (FTS) with vector similarity for best results +- **Default search mode** is now `hybrid` when semantic search is enabled, `text` when disabled +- Embedding providers: FastEmbed (local, default) or OpenAI API +- Configurable similarity threshold via `semantic_min_similarity` (default 0.55) +- Per-query `min_similarity` override on `search_notes` tool +- Auto-backfill: existing entities get embeddings generated on first startup +- Backend-specific distance-to-similarity conversion (cosine for SQLite, inner product for Postgres) +- FTS fallback: if semantic dependencies are missing, search gracefully degrades to text-only + +**Configuration:** +```json +{ + "semantic_search_enabled": true, + "semantic_embedding_provider": "fastembed", + "semantic_embedding_model": "bge-small-en-v1.5", + "semantic_min_similarity": 0.55 +} +``` + +**Usage:** +``` +search_notes("machine learning concepts", search_type="hybrid") +search_notes("similar to my notes on coffee", search_type="vector") +search_notes("exact phrase match", search_type="text") +search_notes("broad search", min_similarity=0.3) # lower threshold for more results +``` + +### Schema System + +Validate note structure against user-defined schemas with frontmatter-based rules. + +- Define schemas as YAML in note frontmatter with field types, required fields, and constraints +- Frontmatter validation during sync — malformed notes get clear error messages +- Schema inference from existing notes to bootstrap schemas from your content +- Schema diff to compare two schemas and see changes +- Available via MCP tools and CLI + +### Project-Prefixed Permalinks + +Permalinks now include the project name for unambiguous cross-project references. + +- Memory URLs like `memory://project-name/folder/note` route to the correct project +- Existing non-prefixed permalinks continue to work (backwards compatible) +- Controlled by `permalinks_include_project` config (default: true) +- `build_context` and `search_notes` auto-detect project from URL prefix + +### Per-Project Cloud Routing + +Individual projects can be routed through the cloud while others stay local. + +- Set a project to cloud mode: `bm project set-cloud research` +- Revert to local: `bm project set-local research` +- Uses API key authentication: `bm cloud set-key bmc_abc123...` +- MCP tools automatically route based on each project's mode +- Local MCP server (`bm mcp`) still uses local routing for all projects by default +- `--local` and `--cloud` CLI flags override per-command + +### Workspace Selection + +Cloud projects can target specific workspaces for multi-tenant environments. + +- `workspace` parameter on MCP tools for explicit workspace targeting +- CLI workspace-aware project listing with `bm project list` +- Spinner feedback while fetching cloud projects + +--- + +## New Tools and Capabilities + +### JSON Output Mode + +All MCP tools now support `output_format="json"` for machine-readable responses. + +- Default remains `"text"` for human-readable output (no breaking changes) +- `build_context` defaults to `"json"` with slimmed payloads (redundant fields stripped) +- CLI tool commands support `--format json` flag + +### `bm watch` Command + +New CLI command for real-time file watching and sync. + +```bash +bm watch # Watch default project +bm watch --project research # Watch specific project +``` + +### Structured Metadata Search + +New `search_by_metadata` tool for searching by frontmatter fields. + +``` +search_by_metadata({"status": "in-progress"}) +search_by_metadata({"tags": ["security", "oauth"]}) +search_by_metadata({"priority": {"$in": ["high", "critical"]}}) +search_by_metadata({"schema.confidence": {"$gt": 0.7}}) +``` + +### `tag:` Search Shorthand + +Search by tag using convenient shorthand syntax. + +``` +search_notes("tag:security") +search_notes("tag:coffee AND tag:brewing") +``` + +### Entity User Tracking + +Entities now track `created_by` and `last_updated_by` fields for attribution. + +### Matched Chunk Text in Search + +Search results now include `matched_chunk` field showing the specific text that matched. + +--- + +## Architecture Changes + +### FastMCP 3.0 Upgrade + +Upgraded from FastMCP 2.12.3 to 3.0.1. + +- Tool annotations (`readOnlyHint`, `openWorldHint`) for better client integration +- Improved MCP protocol compliance +- Better error handling and context management + +### Prompts Call MCP Tools Directly + +MCP prompts (`search`, `continue_conversation`) now call MCP tools directly instead of +going through API endpoints. This fixes empty results in discovery mode and ensures prompts +use the same resolution logic as tools (including LinkResolver fallback). + +### build_context LinkResolver Fallback + +`build_context` now falls back to LinkResolver when an exact permalink lookup returns empty. +This uses the same 7-strategy resolution pipeline as `read_note`, so callers no longer get +empty results for valid note identifiers that don't match exact permalinks. + +### Sync Handles Semantic Dependency Errors Gracefully + +When sqlite-vec or another embedding provider is unavailable, `sync_file` now catches +`SemanticDependenciesMissingError` separately. The entity is created and FTS-indexed +successfully — only vector embeddings are skipped, with a clear warning: + +``` +WARNING: Semantic search dependencies missing — vector embeddings skipped for path=note.md. +Run 'bm reindex --embeddings' after resolving the dependency issue. +``` + +### Unified Project Path + +Cloud projects with bisync now store the local filesystem path in `path` (not the Docker +container path). Config migration automatically promotes `local_sync_path` → `path` for +existing configs. + +--- + +## CLI Improvements + +### Status and Doctor Default to Local Routing + +`bm status` and `bm doctor` now default to local routing since they scan the local filesystem. +Previously, cloud-mode projects would route these commands to the cloud API, which returned +Docker-internal paths that don't exist locally. + +### `--format json` for CLI Tool Commands + +All `bm tool` subcommands support `--format json` for machine-readable output, enabling +integration with scripts and plugins. + +### Cloud Promo and Analytics + +- Cloud promo panel shown on first run or version bump with OSS discount code +- Anonymous usage telemetry via Umami Cloud (promo/login funnel events only) +- Opt out with `BASIC_MEMORY_NO_PROMOS=1` +- No PII, no file contents, no per-command tracking +- See [Telemetry](https://github.com/basicmachines-co/basic-memory#telemetry) in README + +--- + +## Bug Fixes + +- **#582**: build_context returns empty results on valid note identifiers +- **#575**: Remove hardcoded "main" default from default_project +- **#595**: recent_activity dedup and pagination across MCP tools +- **#593**: Backend-specific distance-to-similarity conversion +- **#592**: Strip NUL bytes from content before PostgreSQL search indexing +- **#562**: Use VIRTUAL instead of STORED columns in SQLite migration +- **#558**: Add X-Tigris-Consistent headers to all rclone commands +- **#541**: Handle EntityCreationError as conflict +- **#536**: Stabilize metadata filters on Postgres +- **#533**: Fix recent_activity prompt defaults +- **#530**: Prevent spurious `metadata: {}` in frontmatter output +- **#601**: Return matched chunk text in search results +- Parameterize SQL queries in search repository type filters +- Double-default display in project list +- `ensure_frontmatter_on_sync` default changed to `True` +- Status/doctor commands fail with cloud-mode projects (Docker path error) +- Prompts return "0 projects" in discovery mode + +--- + +## Internal / Developer + +- **#598**: Upgrade FastMCP 2.12.3 → 3.0.1 with tool annotations +- **#594**: Add `ty` as supplemental type checker +- **#538**: Add fast feedback loop tooling (`just fast-check`, `just doctor`, `just testmon`) +- **#600**: Rename `entity_type` to `note_type` for consistency +- **#596**: Fix CLI runtime defects and audit regressions +- CLI refactoring and workspace-aware cloud project listing +- Split and speed up PR test matrix in CI + +--- + +## Configuration Changes + +| Setting | Old Default | New Default | Notes | +|---------|-------------|-------------|-------| +| `semantic_search_enabled` | `false` | `true` | Semantic search on by default | +| `ensure_frontmatter_on_sync` | `false` | `true` | Frontmatter added during sync | +| `permalinks_include_project` | `false` | `true` | Project prefix in permalinks | + +--- + +## Upgrade Notes + +- **Semantic search dependencies** are now included by default. If sqlite-vec fails to load, + search gracefully falls back to FTS. Run `bm reindex --embeddings` to generate embeddings + for existing content. +- **Project-prefixed permalinks** are enabled by default. Existing notes keep their current + permalinks until modified. Set `permalinks_include_project: false` to disable. +- **Frontmatter on sync** is now enabled by default. Files without frontmatter will have it + added on next sync. Set `ensure_frontmatter_on_sync: false` to preserve old behavior. +- **Config migration** runs automatically for cloud projects with bisync — `local_sync_path` + is promoted to `path` so filesystem operations work correctly.