v0.19.0 Migration Guide

This guide covers configuration and behavior changes when upgrading from v0.18 to v0.19. For a user-friendly overview of new features, see What's New in v0.19.0.

write_note is non-destructive by default

write_note no longer silently overwrites existing notes. If a note already exists at the target path, the tool returns an error instead of replacing it.

This prevents accidental data loss when an AI assistant writes a note without realizing one already exists.

Restore old behavior: Set write_note_overwrite_default: true in ~/.basic-memory/config.json.

Semantic search enabled by default

Semantic search is now on out of the box. Embeddings are generated automatically on first startup — no opt-in or manual setup required. If sqlite-vec fails to load, search gracefully falls back to text-only mode.

Restore old behavior: Set semantic_search_enabled: false in config, or set BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=false.

Frontmatter added on sync

Files without YAML frontmatter (the metadata block at the top of a note) now get it added automatically during sync. This ensures all notes have proper metadata for search, permalinks, and schema resolution.

Restore old behavior: Set ensure_frontmatter_on_sync: false in config.

Project-prefixed permalinks

Generated permalinks (permanent links to notes) now include the project slug by default, making cross-project references unambiguous.

Existing permalinks without a project prefix still resolve correctly — resolution tries project-prefixed first, then falls back to bare path.

Restore old behavior: Set permalinks_include_project: false in config.

build_context defaults to JSON output

build_context now returns JSON by default instead of text. The JSON response strips redundant fields for smaller, faster responses. All other tools still default to "text".

Get text output: Pass output_format="text" explicitly.

default_project_mode removed

The default_project_mode setting is no longer used. Use default_project as the fallback when no project is explicitly passed to a tool or command. Per-project routing (set-cloud / set-local) replaces the global mode toggle.

Project config format changed

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 and re-saved in the new format.

// Before (v0.18)
{
  "projects": {
    "main": "/Users/you/basic-memory"
  }
}

// After (v0.19)
{
  "projects": {
    "main": {
      "path": "/Users/you/basic-memory",
      "mode": "local"
    }
  }
}

Legacy configuration keys (project_modes, cloud_projects, default_project_mode) can be safely removed from your config file after migration.