Basic Memory reads configuration from:

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

Environment variables override config file values.

Manage settings from the CLI

Use bm config for scalar settings instead of editing JSON by hand:

bm config list
bm config get reranker_enabled
bm config set reranker_enabled true
bm config unset reranker_enabled

set validates the complete configuration before writing. list shows whether each effective value comes from a default, config.json, or an environment override. Secret fields are masked and credentials embedded in URLs are redacted from list and get output.

Structured project mappings still use bm project; bm config intentionally handles only scalar settings.

New v0.23 settings

All 28 new settings can be written with bm config set <key> <value> or supplied as BASIC_MEMORY_<KEY> environment variables.

Detailed constraints and operating guidance follow below.

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

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

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
• local_sync_path (optional; legacy cloud_sync_path keys are accepted and migrated on load)
• last_sync (optional)

default_project

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

• Type: string | null
• Default: unset — the first configured project is used ("main" on fresh installs, where a main project is seeded). Setting it explicitly to null disables automatic project resolution.

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_vector_index

Vector index used by Postgres deployments.

• Type: "pgvector" | "milvus"
• Default: "pgvector"
• Env: BASIC_MEMORY_SEMANTIC_VECTOR_INDEX

SQLite always uses sqlite-vec and ignores this selector. After changing the Postgres index, run bm reindex --embeddings; before it succeeds, vector search returns nothing and hybrid search serves full-text results only.

Milvus settings

Install basic-memory[milvus] before selecting Milvus. milvus_uri accepts a remote Milvus/Zilliz endpoint or a Milvus Lite path. Lite requires a .db suffix and an existing parent directory, creates a directory tree at that path, and ignores milvus_database. See Postgres and Milvus.

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: 2
• Env: BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE

LiteLLM endpoint and asymmetric-model settings

Use the prefix pair for models whose document and query roles are expressed in input text. Rebuild embeddings after changing either prefix.

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.

Reranker settings

Reranking is disabled by default and applies only to vector and hybrid search. Enable the local provider with:

bm config set reranker_enabled true

FastEmbed downloads the configured local model on first use. LiteLLM requires an explicit provider/model name and uses normal provider credentials when reranker_api_key is unset. Increase the candidate window to widen recall at a latency cost; use a positive document-character cap to bound long-note cost. FastEmbed ignores reranker_timeout because it runs locally.

See Semantic Search for provider setup, measured latency, tuning, and fail-fast 503/502 behavior.

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

Indexing and watch settings

index_changes

Index local file changes in real time.

• Type: boolean
• Default: true
• Env: BASIC_MEMORY_INDEX_CHANGES

The old sync_changes config key and BASIC_MEMORY_SYNC_CHANGES environment variable are migrated automatically. If both old and new names are present, the new name wins.

index_delay

Wait this many milliseconds after a file change before indexing it.

• Type: integer
• Default: 1000
• Env: BASIC_MEMORY_INDEX_DELAY

The old sync_delay config key and BASIC_MEMORY_SYNC_DELAY environment variable are migrated automatically. If both old and new names are present, the new name wins.

materialization_workers

Bound the number of accepted writes that materialize to local storage concurrently.

• Type: integer greater than 0
• Default: 4
• Env: BASIC_MEMORY_MATERIALIZATION_WORKERS

This controls local write materialization, not general indexing concurrency. The removed sync_thread_pool_size and sync_max_concurrent_files settings are silently ignored; use this setting only when tuning concurrent accepted writes.

skip_initialization_sync

Skip local initialization — database setup and project reconciliation/seeding — for cloud/stateless deployments where projects are managed in the database. Not a local performance knob; it does not gate the initial file scan.

• 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

Update settings

Basic Memory can check for new releases and install them automatically for CLI installs (Homebrew, uv tool, uvx). MCP server processes check silently in the background and never block. Run bm update to check and install on demand. See bm update in the CLI Reference.

auto_update

Enable automatic update checks and installs when supported. Set to false to disable background update checks.

• Type: boolean
• Default: true
• Env: BASIC_MEMORY_AUTO_UPDATE

update_check_interval

Seconds between automatic update checks.

• Type: integer
• Default: 86400 (24 hours)
• Env: BASIC_MEMORY_UPDATE_CHECK_INTERVAL

auto_update_last_checked_at

Timestamp of the last automatic update check. Managed automatically — you don't normally set this yourself.

• Type: datetime
• Default: unset

Formatter settings

format_on_save

Automatically format notes when they are saved via write_note or edit_note. With no formatter_command configured, markdown is formatted by the built-in mdformat; setting a command (or the per-extension formatters map) overrides it with an external tool.

• Type: boolean
• Default: false
• Env: BASIC_MEMORY_FORMAT_ON_SAVE

formatter_command

External command to use for formatting markdown files. The file path is substituted via a {file} placeholder — for example npx prettier --write {file}. A per-extension formatters map is also available for different tools per file type.

• 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+asyncpg://user:pass@host:5432/dbname

SQLite tuning

These settings map directly to SQLite pragmas. The defaults are suitable for most installations.

Optional Redis read cache

Standalone MCP servers can cache read results in Redis. Install the optional dependency and set a URL:

pip install "basic-memory[redis]"
bm config set redis_url redis://localhost:6379/0

The cache is optional and limited to standalone MCP read paths. An unset URL disables it. If Redis is unavailable, Basic Memory fails open to authoritative storage reads rather than failing the request.

CLI output settings

cli_output_style

Choose the default presentation for interactive bm tool commands.

• Type: "rich" | "plain"
• Default: "rich"
• Env: BASIC_MEMORY_CLI_OUTPUT_STYLE

This setting affects interactive search, read-note, build-context, and recent-activity output. Redirected output defaults to JSON. Explicit --json and --plain flags take precedence over TTY detection and this setting.

Cloud settings

cloud_mode

Cloud deployment mode (derived, not a config-file setting).

• Type: boolean (read-only property)
• Env: BASIC_MEMORY_CLOUD_MODE

Set by managed cloud deployments via the environment variable. A cloud_mode key in config.json is ignored and removed on load — don't set it for local installs.

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
• sync_changes to index_changes
• sync_delay to index_delay

The corresponding BASIC_MEMORY_SYNC_CHANGES and BASIC_MEMORY_SYNC_DELAY environment variables are also accepted as migration aliases, but the new environment names win when both are set. Removed sync_thread_pool_size and sync_max_concurrent_files keys are ignored. After file-based migration, config is re-saved in current format.

Related pages

• CLI Reference
• MCP Tools Reference
• Semantic Search
• Postgres and Milvus
• Upgrade to v0.23