Getting StartedWorking with CerebroMCP ToolsSetup GuideConfigurationTroubleshooting
Documentation

Configuration

Customize storage, embeddings, and runtime settings for your Cerebro deployment.

You don't need any of this to get started. The Cerebro Desktop installer picks sane defaults, creates your data directory, and wires up the MCP server automatically. The variables below are for advanced users and self-hosted deployments who want to relocate storage, swap the embedding model, or run across multiple machines.

Environment variables

Set these in your shell profile, a .env file in your data directory, or the launch environment of the app.

CEREBRO_DATA_DIRdefault ~/.cerebro/data
Base directory for all Cerebro data — the SQLite memory store, the FAISS index, and runtime state. AI_MEMORY_PATH is accepted as an alias.
CEREBRO_EMBEDDING_MODELdefault all-mpnet-base-v2
The sentence-transformers model used for semantic search embeddings. Changing this requires rebuilding the FAISS index.
CEREBRO_EMBEDDING_DIMdefault 768
Dimension of the embedding vectors. Must match the chosen model — 768 for mpnet, 384 for MiniLM.
CEREBRO_LOG_LEVELdefault INFO
Logging verbosity. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.
CEREBRO_MAX_RESULTSdefault 20
Default maximum number of results returned by search operations.
CEREBRO_DECAY_ENABLEDdefault true
Enable or disable the memory decay system that gradually lowers the relevance of unused memories.
CEREBRO_DEFAULT_MODELdefault (Claude Code default)
Override which Claude model Cerebro's chat and agents use. Leave unset to follow your Claude Code subscription.

Storage options

Cerebro stores all data locally. Use the default location, a custom directory, or a network-attached storage (NAS) path shared across machines.

Local filesystem (default) — the data directory is ~/.cerebro/data. Everything stays on your machine.

.env
CEREBRO_DATA_DIR=~/.cerebro/data

Custom directory — point to any directory with sufficient storage.

.env
CEREBRO_DATA_DIR=/data/cerebro

Network-attached storage — mount your NAS and point Cerebro at it for one memory shared by every machine on your network.

.env (macOS / Linux)
# Mount your NAS first
sudo mount -t nfs nas-ip:/share /mnt/nas

# Point Cerebro to the NAS path
CEREBRO_DATA_DIR=/mnt/nas/cerebro
.env (Windows)
# Map a network drive first
net use Z: \\NAS-IP\share

# Point Cerebro to the mapped drive
CEREBRO_DATA_DIR=Z:\cerebro

Embedding configuration

Cerebro uses sentence-transformers for semantic search. The default model gives strong accuracy out of the box.

Default model (recommended) — high-accuracy 768-dimension embeddings, what Cerebro ships with.

.env
CEREBRO_EMBEDDING_MODEL=all-mpnet-base-v2
CEREBRO_EMBEDDING_DIM=768

Lighter / faster model — smaller, quicker to index, lower memory use at a modest accuracy cost. Handy on low-resource machines.

.env
CEREBRO_EMBEDDING_MODEL=all-MiniLM-L6-v2
CEREBRO_EMBEDDING_DIM=384
Heads up: changing the embedding model requires rebuilding the FAISS index. After updating the model, open Settings → Run Diagnostics in Cerebro Desktop and trigger a vector-index rebuild.

Advanced: self-hosted MCP wiring

The desktop app registers the Cerebro MCP server for you. If you're running the memory server standalone and wiring it into another MCP client by hand, this is the shape of the config:

mcp config (advanced)
{
  "mcpServers": {
    "cerebro": {
      "command": "cerebro",
      "args": ["serve"],
      "env": {
        "CEREBRO_DATA_DIR": "/path/to/data",
        "CEREBRO_EMBEDDING_MODEL": "all-mpnet-base-v2",
        "CEREBRO_EMBEDDING_DIM": "768",
        "CEREBRO_LOG_LEVEL": "INFO",
        "CEREBRO_MAX_RESULTS": "20",
        "CEREBRO_DECAY_ENABLED": "true"
      }
    }
  }
}

Your operations platform is waiting.

An AI that remembers everything and runs your work — no API keys, no cloud, no per-token meter.

Get Cerebro