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.

Variable	Default	Description
`CEREBRO_DATA_DIR`	`~/.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_MODEL`	`all-mpnet-base-v2`	The sentence-transformers model used for semantic search embeddings. Changing this requires rebuilding the FAISS index.
`CEREBRO_EMBEDDING_DIM`	`768`	Dimension of the embedding vectors. Must match the chosen model — 768 for mpnet, 384 for MiniLM.
`CEREBRO_LOG_LEVEL`	`INFO`	Logging verbosity. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.
`CEREBRO_MAX_RESULTS`	`20`	Default maximum number of results returned by search operations.
`CEREBRO_DECAY_ENABLED`	`true`	Enable or disable the memory decay system that gradually lowers the relevance of unused memories.
`CEREBRO_DEFAULT_MODEL`	`(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 default 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 (NAS)

Mount your NAS and point Cerebro at it for centralized 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

Use a smaller model for faster indexing and 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"
      }
    }
  }
}