Configuration

Basic Memory can be configured through ~/.basic-memory/config.json or environment variables. Environment variables take precedence over config file settings.

Configuration File

Location: ~/.basic-memory/config.json

Example configuration:

{
  "default_project": "main",
  "default_project_mode": true,
  "log_level": "INFO",
  "sync_delay": 1000,
  "kebab_filenames": false,
  "disable_permalinks": false,
  "sync_changes": true
}

Project Settings

projects

Mapping of project names to filesystem paths.

default_project

Name of the default project used when no project is specified.

default_project_mode

Automatic project selection for single-project users. When enabled, AI assistants automatically use the default project without asking.

Behavior:

• When true, tools automatically use your default project
• You can still override by explicitly passing a different project
• Best for users who primarily work in one project

project_root

Constrain all projects under a root directory.

When set, all project paths must be within this directory.

Sync Settings

sync_changes

Enable or disable real-time synchronization.

When false, changes are not automatically synced to the database.

sync_delay

Milliseconds to wait after changes before syncing. Prevents excessive sync operations during rapid edits.

sync_thread_pool_size

Thread pool size for file I/O operations. Higher values may improve performance with many files.

skip_initialization_sync

Skip expensive initialization sync. Useful for cloud/stateless deployments.

watch_project_reload_interval

Seconds between reloading project list. Used in watch service to detect new projects.

File Management

kebab_filenames

Filename format for generated files.

• false: Preserves spaces and special characters (e.g., My Important Note.md)
• true: Converts to kebab-case (e.g., my-important-note.md)

update_permalinks_on_move

Update permalinks when files are moved.

When true, permalinks are updated to reflect new file location. When false, permalinks remain stable identifiers.

disable_permalinks

Disable automatic permalink generation.

When true, new notes won't have permalinks added. Existing permalinks still work for reading.

Logging

log_level

Logging verbosity level.

Console Logging

Enable logging to console (environment variable only).

Log file location: ~/.basic-memory/basic-memory-{process}.log

Environment Variables

All configuration can be overridden with environment variables using the BASIC_MEMORY_ prefix:

# Set default project mode
export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true

# Change log level
export BASIC_MEMORY_LOG_LEVEL=DEBUG

# Enable console logging
export BASIC_MEMORY_CONSOLE_LOGGING=true

# Set custom sync delay
export BASIC_MEMORY_SYNC_DELAY=2000

Special Environment Variables

Configuration Priority

Settings are applied in this order (highest to lowest priority):

Example:

# Config file has: "log_level": "INFO"
# Environment has: BASIC_MEMORY_LOG_LEVEL=DEBUG
# Result: DEBUG is used (environment wins)

Cloud Configuration

When using Basic Memory Cloud, additional configuration is stored in ~/.basic-memory/basic-memory-cloud.json:

{
  "access_token": "...",
  "refresh_token": "...",
  "tenant_id": "...",
  "expires_at": "..."
}

This file is managed automatically by bm cloud login and bm cloud logout.

Cloud-Specific Settings

Editing Configuration

Via Config File

# Edit configuration
vim ~/.basic-memory/config.json

# Restart MCP server for changes to take effect
# (Claude Desktop, VS Code, etc.)

Via CLI

# Set default project
basic-memory project default work

# View all projects
basic-memory project list

# Check current configuration
cat ~/.basic-memory/config.json

Via Environment

# Temporary (current session)
export BASIC_MEMORY_LOG_LEVEL=DEBUG
basic-memory status

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true' >> ~/.bashrc

Ignore Patterns

Basic Memory respects ignore patterns to skip sensitive files during indexing.

Pattern Sources

1. Global patterns: ~/.basic-memory/.bmignore (applied to all projects)
2. Project patterns: {project}/.gitignore (applied to specific project)

Example .bmignore

# Sensitive files
.env
.env.*
*.key
credentials.json

# Build artifacts
node_modules/
__pycache__/
dist/
build/

# OS files
.DS_Store
Thumbs.db

# Database files
*.db
*.db-wal
*.db-shm

Benefits

• Security: Prevents indexing sensitive files like .env or API keys
• Performance: Skips unnecessary files like node_modules/ or build outputs
• Cleaner knowledge base: Ignores OS and editor files

Files matching these patterns are automatically skipped during index sync and never indexed in your knowledge base.

Complete Settings Reference

Next Steps