First run

bee keeps exactly one thing on your machine: how to reach the config store. Everything else — provider keys, endpoints, rules, memories — lives in MongoDB, shared by every machine and every agent that points at the same store.

1 · Point bee at a store

bee init

The wizard asks for one Mongo connection string, tests it live, and only then writes ~/.bee/config.json with 0600 permissions. A connection that does not answer is never saved.

Scripted, non-interactive:

bee init --mongo "mongodb://localhost:27017" --database bee --collection config

Any MongoDB will do

A local container is enough to try it:

docker run -d --name bee-mongo -p 27017:27017 mongo:8
bee init --mongo "mongodb://localhost:27017" --database bee --collection config

Connecting to a replica set from the host

A replica set member advertises itself under the name it knows — often a container hostname your machine cannot resolve. The driver then tries to reach that name and hangs on discovery. Connect directly instead:

bee init --mongo "mongodb://localhost:27018/?directConnection=true" \
         --database bee --collection config

Keeping a store separate

BEE_HOME replaces your home directory for bee, and bee still appends .bee to it. Point it at a directory and you get <that directory>/.bee/config.json:

export BEE_HOME=/path/to/project
bee init --mongo "mongodb://localhost:27017" --database bee_test --collection config
# → /path/to/project/.bee/config.json

Useful for a throwaway test store that must not touch the one your real work uses.

2 · Give it a brain (optional)

Only needed for bee ask. Memory, rules and lint work without it.

bee config set ask.provider deepseek
bee config set deepseek.apiKey sk-... --secret
bee config show          # secrets masked

DeepSeek, OpenAI and Anthropic are supported.

3 · Make the first memory

bee remember "Redis caches session tokens, not user data" \
  --type decision --reason "user data has a different TTL"

bee remember search "redis"

4 · Wire it into your agent

bee hook install --harness claude --scope project

See Hooks for what each runtime does and does not support.

Where things live

what	where
Mongo bootstrap connection	~/.bee/config.json (0600) — the only local file
Embedding model	~/.bee/models/ — downloaded on first semantic search
Everything else	your MongoDB config store