Reference

Configuration

Configuration reference for Basic Memory, including project routing, semantic search, and cloud settings.

Basic Memory reads configuration from:

Environment variables (BASIC_MEMORY_*)
Config file (~/.basic-memory/config.json by default)
Built-in defaults

Environment variables override config file values.

Config file location

Default location:

~/.basic-memory/config.json

To isolate config and default SQLite data per workspace/process, set:

export BASIC_MEMORY_CONFIG_DIR=/path/to/custom-dir

When set, Basic Memory stores config and default app DB in that directory.

Example config (v0.19+)

{
  "default_project": "main",
  "projects": {
    "main": {
      "path": "/Users/you/basic-memory",
      "mode": "local"
    },
    "research": {
      "path": "/Users/you/research-notes",
      "mode": "cloud",
      "cloud_sync_path": "/Users/you/research-notes",
      "bisync_initialized": true,
      "last_sync": "2026-02-15T18:30:00Z"
    }
  },
  "semantic_search_enabled": true,
  "semantic_min_similarity": 0.55,
  "permalinks_include_project": true,
  "cloud_mode": false
}

Project and routing settings

`projects`

Projects are now stored as structured entries, not just name -> path strings.

Each project entry supports:

path: local filesystem path
mode: local or cloud
cloud_sync_path (optional)
bisync_initialized (optional)
last_sync (optional)

`default_project`

Fallback project name used when tools/commands do not pass a project.

Type: string | null
Default: "main"

default_project_mode is deprecated/removed from active config behavior. Use default_project as fallback instead.

`BASIC_MEMORY_MCP_PROJECT`

Environment-level project constraint for MCP sessions.

Locks operations to one project for that process/session
Highest-priority project constraint

Per-project routing mode

Use CLI to manage per-project routing:

bm project set-cloud research
bm project set-local research

Cloud-routed projects use cloud credentials/API key; local-routed projects use local ASGI transport.

Semantic search settings

`semantic_search_enabled`

Enable vector/hybrid retrieval.

Type: boolean
Default: true
Env: BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED

Semantic search is enabled and included by default in all standard installs. Embeddings are generated automatically on first startup. If sqlite-vec fails to load, search gracefully falls back to text-only mode.

`semantic_embedding_provider`

Embedding provider.

Type: string
Default: "fastembed"
Common values: fastembed, openai
Env: BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER

`semantic_embedding_model`

Embedding model name.

Type: string
Default: "bge-small-en-v1.5"
Env: BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL

`semantic_embedding_dimensions`

Embedding dimensions override.

Type: integer | null
Default: null (auto)
Env: BASIC_MEMORY_SEMANTIC_EMBEDDING_DIMENSIONS

`semantic_embedding_batch_size`

Embedding batch size.

Type: integer
Default: 64
Env: BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE

`semantic_vector_k`

Vector candidate count.

Type: integer
Default: 100
Env: BASIC_MEMORY_SEMANTIC_VECTOR_K

`semantic_min_similarity`

Global minimum similarity threshold for vector results.

Type: float (0.0 to 1.0)
Default: 0.55
Env: BASIC_MEMORY_SEMANTIC_MIN_SIMILARITY

Set to 0.0 to disable threshold filtering globally.

Semantic search dependencies are included by default in all standard installs.

Permalink and file behavior

`permalinks_include_project`

When enabled, generated permalinks include project slug prefix.

Type: boolean
Default: true
Env: BASIC_MEMORY_PERMALINKS_INCLUDE_PROJECT

`ensure_frontmatter_on_sync`

Add frontmatter to files during sync if they don't already have it.

Type: boolean
Default: true
Env: BASIC_MEMORY_ENSURE_FRONTMATTER_ON_SYNC

`write_note_overwrite_default`

Default value for the overwrite parameter on write_note. When false (default), writing to an existing note path returns an error unless overwrite=True is passed explicitly. Set to true to restore the pre-v0.19 upsert behavior.

Type: boolean
Default: false
Env: BASIC_MEMORY_WRITE_NOTE_OVERWRITE_DEFAULT

`update_permalinks_on_move`

Update permalinks when files move.

Type: boolean
Default: false
Env: BASIC_MEMORY_UPDATE_PERMALINKS_ON_MOVE

`disable_permalinks`

Disable automatic permalink generation for new notes.

Type: boolean
Default: false
Env: BASIC_MEMORY_DISABLE_PERMALINKS

`kebab_filenames`

Generate kebab-case filenames for tool-created notes.

Type: boolean
Default: false
Env: BASIC_MEMORY_KEBAB_FILENAMES

Sync and watch settings

`sync_changes`

Enable filesystem-to-index synchronization.

Type: boolean
Default: true
Env: BASIC_MEMORY_SYNC_CHANGES

`sync_delay`

Debounce delay for sync in milliseconds.

Type: integer
Default: 1000
Env: BASIC_MEMORY_SYNC_DELAY

`sync_thread_pool_size`

Thread pool size for file operations.

Type: integer
Default: 4
Env: BASIC_MEMORY_SYNC_THREAD_POOL_SIZE

`sync_max_concurrent_files`

Maximum number of files to process concurrently during sync operations.

Type: integer
Default: 10
Env: BASIC_MEMORY_SYNC_MAX_CONCURRENT_FILES

`skip_initialization_sync`

Skip the initial full sync when the MCP server starts. Useful for large projects where you want the server to start faster and rely on the file watcher for incremental updates.

Type: boolean
Default: false
Env: BASIC_MEMORY_SKIP_INITIALIZATION_SYNC

`watch_project_reload_interval`

Seconds between project list reloads in watch-related services.

Type: integer
Default: 300
Env: BASIC_MEMORY_WATCH_PROJECT_RELOAD_INTERVAL

Formatter settings

`format_on_save`

Automatically format notes when they are saved via write_note or edit_note.

Type: boolean
Default: false
Env: BASIC_MEMORY_FORMAT_ON_SAVE

`formatter_command`

External command to use for formatting markdown files. When set and format_on_save is enabled, this command is called with the file path as an argument.

Type: string | null
Default: null
Env: BASIC_MEMORY_FORMATTER_COMMAND

`formatter_timeout`

Maximum time in seconds to wait for the formatter command to complete.

Type: float
Default: 5.0
Env: BASIC_MEMORY_FORMATTER_TIMEOUT

Database settings

`database_backend`

Database backend to use for the knowledge index.

Type: string
Default: "sqlite"
Values: sqlite, postgres
Env: BASIC_MEMORY_DATABASE_BACKEND

SQLite is used for local installations. Postgres is used by Basic Memory Cloud and can be configured for self-hosted deployments.

`database_url`

Connection URL for the database when using the Postgres backend.

Type: string | null
Default: null
Env: BASIC_MEMORY_DATABASE_URL

Only required when database_backend is postgres. Example: postgresql://user:pass@host:5432/dbname

Cloud settings

`cloud_mode`

Global cloud mode toggle.

Type: boolean
Default: false
Env: BASIC_MEMORY_CLOUD_MODE

`cloud_api_key`

Account-level cloud API key (bmc_...) used for cloud-routed projects.

Type: string | null
Default: null
Env: BASIC_MEMORY_CLOUD_API_KEY

Use CLI:

bm cloud api-key save bmc_...
bm cloud api-key create "my-laptop"

`cloud_promo_opt_out`

Disable CLI cloud promo messages.

Type: boolean
Default: false
Env: BASIC_MEMORY_CLOUD_PROMO_OPT_OUT

Logging and diagnostics

`log_level`

Default: INFO
Env: BASIC_MEMORY_LOG_LEVEL

Migration notes

When loading older config files, Basic Memory automatically migrates legacy keys and formats, including:

legacy string-valued projects mapping
project_modes
cloud_projects
default_project_mode

After migration, config is re-saved in current format.

Edit this pageorReport an issue

Troubleshooting

Common issues and solutions for Basic Memory.

Docker

Run Basic Memory in Docker containers for server deployments and SSE transport