Environment variables
Derived from .env.example and server/settings.py. Every variable maps 1:1 to a settings field (SODAMEM_ prefix, pydantic-settings).
GET /v1/admin/config reports the effective configuration of a running server, with every secret shown as set / not-set and never masked-but-printed.
Auth
| variable | default | meaning |
|---|---|---|
SODAMEM_API_KEY | — | Required. Shared secret sent as Authorization: Bearer <key> or X-API-Key. The server refuses to start without it. |
SODAMEM_AUTH_DISABLED | false | Local-dev escape hatch. docker-compose.yml deliberately never sets it. |
Do not disable auth on anything reachable off your machine
There is no silently-open default, and turning auth off is meant to stay an explicit, per-deployment choice.
Storage
| variable | default | meaning |
|---|---|---|
SODAMEM_DATA_ROOT | /data under compose | Where stores live. Fixed by docker-compose.yml to match the named volume; set it only when running the image directly. |
SODAMEM_STORE_CACHE_MAX | 64 | LRU cap on concurrently-open per-user stores. Raise it above your expected concurrent distinct users. |
SODAMEM_ALLOW_PURGE | false | Allows DELETE /v1/memories/{id}?purge=true to physically erase and cascade to roles, edges and vectors. |
SODAMEM_ALLOW_PURGE is off because an ordinary DELETE already archives: the memory leaves search and context while the record and its provenance stay. Turn it on only for right-to-erasure deletes — it is irreversible and it breaks the provenance of any answer that cited the fact.
Control plane
Operational state — async job status, named API keys, the request log — lives in its own SQLite database at <data_root>/.control/sodamem_control.db, so deleting a user's memories never takes the operator's job history with it (ADR 0001).
| variable | default | meaning |
|---|---|---|
SODAMEM_REQUEST_LOG_MAX | 10000 | Rolling cap on the persisted request log, enforced in the same transaction as each insert. 0 turns the log off entirely — a real off switch, not a very small cap. |
SODAMEM_JOB_RETENTION_MAX | 5000 | Rolling cap on persisted job records. Oldest pruned first, so a job you just submitted is never the one dropped. |
There is no worker-count knob. One worker is a correctness constraint, not a tuning parameter: per-user stores are SQLite without WAL, the server takes an exclusive lock on its data root, and a second process refuses to start with data_root_locked.
LLM
Needed for ingest extraction and POST /v1/answer. Not needed by /v1/search or /v1/context — those are the zero-LLM tier and work with everything here unset.
The same four names are what the library reads (sodamem.llm.create_provider_from_env), so an embedded process and a container are configured identically.
| variable | default | meaning |
|---|---|---|
SODAMEM_LLM_PROVIDER | openai | one of openai, anthropic, deepseek, gemini |
SODAMEM_LLM_MODEL | provider default | |
SODAMEM_LLM_API_KEY | — | |
SODAMEM_LLM_BASE_URL | — | only for an OpenAI-compatible endpoint that is not api.openai.com |
Server
| variable | default | meaning |
|---|---|---|
SODAMEM_PORT | 8000 | The host port is the ports: mapping in docker-compose.yml, not this. |
SODAMEM_CORS_ORIGINS | unset | JSON array of exact origins — pydantic-settings parses list fields as JSON, not a comma list. Never "*" once auth is on. |
SODAMEM_CORS_ORIGINS=["https://your-app.example.com"]MCP
| variable | default | meaning |
|---|---|---|
SODAMEM_MCP_ALLOW_WRITE | unset (off) | Registers add_memories and delete_memory. sodamem install writes it into the client config it generates. |
SODAMEM_MCP_LOG_LEVEL | WARNING |
CLI
| variable | default | meaning |
|---|---|---|
SODAMEM_API_URL | http://127.0.0.1:8000 | Where sodamem install / daemon / hook look for the service. |
SODAMEM_API_KEY | — | Also used by the CLI as --api-key's default. |
Install extras
Not environment variables, but the same "what do I actually need" question.
| extra | what it adds |
|---|---|
| (base) | data model, storage, BM25 retrieval, ingest — four dependencies, none heavy |
chroma | vector search + the local ONNX embedder (SodaMem.open() needs this) |
llm | OpenAI-compatible providers (OpenAI / DeepSeek / Gemini wire format) |
anthropic | the Anthropic provider, which speaks its own SDK |
answer | the planner + reader answer path |
server | the HTTP service (FastAPI + uvicorn) |
mcp | the MCP server surface |
Base install pulls pydantic, numpy, rank-bm25, python-dateutil — and a CI gate fails the build if that list grows by accident.