|
| 1 | +--- |
| 2 | +title: v0.19.0 |
| 3 | +description: Schema system, semantic search, per-project routing, and more in Basic Memory v0.19.0. |
| 4 | +--- |
| 5 | + |
| 6 | +v0.19.0 is a major release that introduces schema-driven note workflows, production-ready semantic search, and per-project cloud routing. These features work together to make your knowledge base more structured, more discoverable, and more flexible in how it connects to cloud and local storage. |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Schema System |
| 11 | + |
| 12 | +Knowledge bases grow organically, and over time note structure drifts — some `person` notes have a `[name]` observation, others use `[full_name]`, and relation types vary between `works_at` and `employed_by`. The new schema system gives you a way to define what "consistent" means for each note type, check your notes against that definition, and track how patterns evolve. |
| 13 | + |
| 14 | +The workflow is conversational — just ask your AI assistant: |
| 15 | + |
| 16 | +``` |
| 17 | +You: "I've been writing a lot of person notes. Can you figure out |
| 18 | + what they have in common and create a schema?" |
| 19 | +
|
| 20 | +Claude: [Analyzes your person notes, creates a schema note] |
| 21 | +
|
| 22 | +Done! I created a Person schema based on your 45 person notes. |
| 23 | +"name" is required, "role" and "works_at" are optional. |
| 24 | +
|
| 25 | +You: "How do my existing notes look against that?" |
| 26 | +
|
| 27 | +Claude: [Validates all person notes] |
| 28 | +
|
| 29 | +42 of 45 pass. Three are missing the [name] observation. |
| 30 | +Want me to fix those? |
| 31 | +``` |
| 32 | + |
| 33 | +The schema itself is just a regular note with `type: schema`: |
| 34 | + |
| 35 | +```yaml |
| 36 | +--- |
| 37 | +title: Person |
| 38 | +type: schema |
| 39 | +entity: person |
| 40 | +version: 1 |
| 41 | +schema: |
| 42 | + name: string, full name |
| 43 | + role?: string, job title |
| 44 | + works_at?: Organization, employer |
| 45 | + expertise?(array): string, areas of knowledge |
| 46 | +settings: |
| 47 | + validation: warn |
| 48 | +--- |
| 49 | +``` |
| 50 | + |
| 51 | +Schemas don't stop notes from being written — they give the AI an extra capability to check its own work and follow your preferred patterns. When a schema exists for a note type, the AI uses it as a creation guide automatically. |
| 52 | + |
| 53 | +See the full [Schema System](/concepts/schema-system) guide for syntax, resolution rules, and workflows. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Semantic Search |
| 58 | + |
| 59 | +When semantic dependencies are installed, Basic Memory automatically uses hybrid search — combining keyword matching with meaning-based retrieval. Search for "login security improvements" and find notes about "authentication hardening" even though the exact words don't match. |
| 60 | + |
| 61 | +Three search modes are available: |
| 62 | + |
| 63 | +- **`hybrid`** (default when semantic deps installed) — Combines keyword and semantic search with rank fusion |
| 64 | +- **`text`** — Keyword-only search (the fallback without semantic deps) |
| 65 | +- **`vector`** — Pure semantic similarity search |
| 66 | + |
| 67 | +```python |
| 68 | +# Hybrid is the default — just search normally |
| 69 | +search_notes(query="authentication security") |
| 70 | + |
| 71 | +# Pure meaning-based search |
| 72 | +search_notes(query="how to speed up the app", search_type="vector") |
| 73 | + |
| 74 | +# Per-query similarity threshold |
| 75 | +search_notes(query="error handling", search_type="hybrid", min_similarity=0.7) |
| 76 | +``` |
| 77 | + |
| 78 | +Semantic dependencies are included in Homebrew installs. For uv, install with extras: |
| 79 | + |
| 80 | +```bash |
| 81 | +uv tool install 'basic-memory[semantic]' |
| 82 | +bm reindex --embeddings |
| 83 | +``` |
| 84 | + |
| 85 | +Vector and hybrid search return observation-level results — individual facts and relations, not just whole notes — so you find the specific piece of information you need. |
| 86 | + |
| 87 | +See the full [Semantic Search](/concepts/semantic-search) guide for configuration, embedding providers, and how it works under the hood. |
| 88 | + |
| 89 | +--- |
| 90 | + |
| 91 | +## Per-Project Local/Cloud Routing |
| 92 | + |
| 93 | +You can now route individual projects through cloud while keeping others local. The stdio MCP server only calls local projects, while cloud projects are available via CLI commands. |
| 94 | + |
| 95 | +```bash |
| 96 | +# Save or create a cloud API key |
| 97 | +bm cloud set-key bmc_... |
| 98 | +bm cloud create-key "my-laptop" |
| 99 | + |
| 100 | +# Route a specific project through cloud |
| 101 | +bm project set-cloud research |
| 102 | + |
| 103 | +# Revert to local routing |
| 104 | +bm project set-local research |
| 105 | +``` |
| 106 | + |
| 107 | +The routing model has three levels: |
| 108 | +1. **Global** — `bm cloud login` sends all commands to cloud by default |
| 109 | +2. **Per-project** — `bm project set-cloud/set-local` overrides for specific projects |
| 110 | +3. **Per-command** — `--local` / `--cloud` flags provide one-off overrides |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## Project-Prefixed Permalinks |
| 115 | + |
| 116 | +Memory URLs now support project scoping for multi-project disambiguation. When `permalinks_include_project` is enabled (the default), generated permalinks include the project slug: |
| 117 | + |
| 118 | +```text |
| 119 | +memory://main/docs/authentication |
| 120 | +memory://research/specs/search-ranking |
| 121 | +``` |
| 122 | + |
| 123 | +This makes cross-project references unambiguous. Within notes, the `project::note-path` syntax is normalized to `project/note-path` for consistent resolution. |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## Output Format Improvements |
| 128 | + |
| 129 | +`search_notes` and `read_note` now support an `output_format` parameter: |
| 130 | + |
| 131 | +- **`default`** — Structured data (for programmatic use) |
| 132 | +- **`ascii`** — Plain text table (for terminal display) |
| 133 | +- **`ansi`** — Colorized terminal output |
| 134 | + |
| 135 | +--- |
| 136 | + |
| 137 | +## `write_note` Metadata |
| 138 | + |
| 139 | +`write_note` now accepts `note_type` and `metadata` parameters for richer frontmatter control: |
| 140 | + |
| 141 | +```python |
| 142 | +await write_note( |
| 143 | + title="Sprint Planning 2026-02-15", |
| 144 | + content="...", |
| 145 | + directory="meetings", |
| 146 | + note_type="meeting", |
| 147 | + metadata={"sprint": 12, "team": "backend", "status": "completed"}, |
| 148 | + project="main" |
| 149 | +) |
| 150 | +``` |
| 151 | + |
| 152 | +The `note_type` sets the `type` frontmatter field (used for schema resolution and filtering). The `metadata` parameter accepts any key-value pairs that get merged into the note's YAML header. |
| 153 | + |
| 154 | +--- |
| 155 | + |
| 156 | +## `bm watch` Command |
| 157 | + |
| 158 | +A new standalone watch command runs the file watcher as a dedicated long-running process: |
| 159 | + |
| 160 | +```bash |
| 161 | +bm watch |
| 162 | +bm watch --project main |
| 163 | +``` |
| 164 | + |
| 165 | +Use this when you're editing notes in an external editor (Obsidian, VS Code, etc.) and want the database index updated in real-time without running the full MCP server. |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## Upgrade Notes |
| 170 | + |
| 171 | +### Project config migration |
| 172 | + |
| 173 | +Project configuration now uses structured entries with `path`, `mode`, and sync metadata. Legacy config formats (string-valued `projects`, `project_modes`, `cloud_projects`) are migrated automatically when Basic Memory loads your config. The migrated config is re-saved in the new format. |
| 174 | + |
| 175 | +### `default_project_mode` removal |
| 176 | + |
| 177 | +The `default_project_mode` setting is no longer used. `default_project` is the fallback when no project is explicitly passed to a tool or command. |
| 178 | + |
| 179 | +### Semantic extras |
| 180 | + |
| 181 | +Semantic search dependencies are optional extras. Install them explicitly if you want vector or hybrid search: |
| 182 | + |
| 183 | +```bash |
| 184 | +uv tool install 'basic-memory[semantic]' |
| 185 | +``` |
| 186 | + |
| 187 | +### Config cleanup |
| 188 | + |
| 189 | +Legacy configuration keys (`project_modes`, `cloud_projects`, `default_project_mode`) are migrated automatically and can be safely removed from your config file. |
| 190 | + |
| 191 | +--- |
| 192 | + |
| 193 | +## Documentation |
| 194 | + |
| 195 | +- New: [Schema System](/concepts/schema-system) — Complete guide to defining, validating, and evolving schemas |
| 196 | +- New: [Semantic Search](/concepts/semantic-search) — Search modes, configuration, and how it works |
| 197 | +- Updated: [MCP Tools Reference](/reference/mcp-tools-reference) — Full parameter tables for all tools |
| 198 | +- Updated: [CLI Reference](/reference/cli-reference) — Expanded schema, watch, and reindex commands |
| 199 | +- Updated: [Configuration](/reference/configuration) — New settings for formatter, database, and sync |
| 200 | +- Updated: [AI Assistant Guide](/reference/ai-assistant-guide) — Schema-guided workflows and semantic search |
| 201 | + |
| 202 | +For commit-level release history, see [Changelog](/whats-new/changelog). |
0 commit comments