Skip to main content
AtomicMemory Core is configured entirely through environment variables. There is no configuration file to manage — every knob from bearer tokens to embedding provider selection is exposed as an env var that you can set in a .env file, a Docker run command, a Compose file, or your deployment platform’s secrets manager. The sections below cover the most important variables grouped by concern.

​
API Keys

Two separate credentials control access to the Core HTTP API:
​
CORE_API_KEY
string
The bearer token that all clients must send in the Authorization: Bearer <key> header to access memory, search, and ingest endpoints. Defaults to local-dev-key for local Docker runs — replace this with a strong random secret for any internet-accessible deployment.
export CORE_API_KEY=$(openssl rand -hex 32)
Clients authenticate by passing the key as a standard HTTP Authorization header: 
curl -s http://127.0.0.1:17350/v1/memories/list \
  -H "Authorization: Bearer $CORE_API_KEY"
Never embed CORE_API_KEY in client-side JavaScript bundles, mobile apps, or public repositories. This is a server-side credential. If the key is ever leaked, generate a new one with openssl rand -hex 32 and rotate it in your deployment immediately.

​
Embedding Providers

Set EMBEDDING_PROVIDER to choose the backend that generates vector embeddings for every memory stored and every search query. The default is openai.
Runs embedding inference entirely inside the container using @huggingface/transformers (WASM/ONNX). No external API call is made, so this option works fully offline and does not require any API key.
EMBEDDING_PROVIDER=transformers
Best for: air-gapped environments, local development without API spend, and privacy-sensitive workloads. Expect higher latency on the first request while the model warms up compared with hosted APIs.
Uses the OpenAI Embeddings API with text-embedding-3-small at 1536 dimensions by default. Requires a valid OPENAI_API_KEY.
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
EMBEDDING_DIMENSIONS=1536
Best for: production workloads where retrieval quality is the priority.
Points to any API that implements the OpenAI embeddings interface. Recommended for self-hosters who run a local inference server (LM Studio, vLLM, LocalAI, etc.).
EMBEDDING_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_BASE_URL=http://localhost:8080/v1
OPENAI_COMPATIBLE_API_KEY=my-local-key
Connects to a running Ollama server. The model must already be pulled in Ollama before starting Core.
EMBEDDING_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434
Uses Voyage AI embedding models, which are designed for high retrieval quality. Requires a VOYAGE_API_KEY.
EMBEDDING_PROVIDER=voyage
VOYAGE_API_KEY=pa-...

​
LLM Providers

The LLM provider is used during full ingest (POST /v1/memories/ingest) to extract structured claims from conversation messages and apply AUDN-SC mutation decisions (Add, Update, Delete, No-op, Supersede, Clarify). Quick ingest (POST /v1/memories/ingest/quick) uses embedding deduplication only and does not call the LLM provider. Set LLM_PROVIDER to one of the following values:
ProviderLLM_PROVIDER valueRequired variable
OpenAIopenaiOPENAI_API_KEY
AnthropicanthropicANTHROPIC_API_KEY
Ollama (local)ollamaOLLAMA_BASE_URL
GroqgroqGROQ_API_KEY
Google Geminigoogle-genaiGOOGLE_GENAI_API_KEY
OpenAI-compatibleopenai-compatibleOPENAI_COMPATIBLE_BASE_URL
Claude Code (local dev)claude-codeLogged-in claude session
Codex (local dev)codexLogged-in codex session
claude-code and codex use your locally authenticated account session rather than a standalone API key. They are intended for personal development only — not for hosted or team deployments — because they consume account limits and are not designed for multi-user concurrency.

​
Port

​
PORT
number
default:"17350"
The port the Core HTTP server listens on inside the container. Map this to your host in the Docker run command with -p <host-port>:$PORT.
To run on a non-default port: 
docker run --rm -it --pull always \
  -p 127.0.0.1:8080:8080 \
  -e PORT=8080 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest

​
Storage and Database

​
DATABASE_URL
string
default:"embedded"
Postgres connection string. When unset or set to embedded, the container starts its bundled local Postgres instance and persists data to /var/lib/atomicmemory/postgres (which you should mount as a volume). For production, point this at a managed Postgres instance with the pgvector extension enabled.
DATABASE_URL=postgresql://user:pass@postgres.example.com:5432/atomicmemory
​
STORAGE_KEY_HMAC_SECRET
string
HMAC secret used to sign storage artifact keys. Required in production. Generate one with openssl rand -hex 32.
​
RAW_STORAGE_DEPLOYMENT_ENV
string
default:"local"
Set to production to enable production-grade storage policies. The local value relaxes certain constraints that are appropriate for development but not for multi-user deployments.

​
Migrations

By default the container runs database migrations automatically on startup before accepting traffic. For rolling production deployments where you need to run migrations as a separate pre-deploy job, disable the startup migration step: 
ATOMICMEMORY_RUN_MIGRATIONS_ON_STARTUP=false
You can also raise the advisory-lock timeout if multiple replicas start simultaneously: 
MIGRATION_LOCK_TIMEOUT_MS=30000