Skip to main content
AtomicMemory Core is packaged as a multi-platform Docker image published to the GitHub Container Registry at ghcr.io/atomicstrata/atomicmemory-core:latest. The image bundles an embedded Postgres instance with pgvector so you get a fully self-contained memory backend — no external database required to get started. Images are built for both linux/amd64 and linux/arm64, so the same tag works on common Linux servers and Apple Silicon Macs.

​
Quick Start

1

Pull and run the image

Export your OpenAI API key, then start the container. The volume mount persists the embedded database across container restarts.
export OPENAI_API_KEY=sk-...

docker run --rm -it --pull always \
  -p 127.0.0.1:17350:17350 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest
The --pull always flag ensures you get the latest image on every run. Binding to 127.0.0.1 keeps the default local-dev-key credential off your network interfaces.
2

Verify the health endpoint

Once the container is running, confirm it is ready to accept requests:
curl -s http://127.0.0.1:17350/v1/memories/health
A successful response returns {"status":"ok"}. The server is now ready to ingest and serve memories.
3

Authenticate your first request (optional)

By default, the local image accepts local-dev-key as the bearer token. You can use it immediately without any additional setup:
curl -s http://127.0.0.1:17350/v1/memories/list \
  -H "Authorization: Bearer local-dev-key"
For production deployments, replace this with a strong random secret. See the Configuration page for how to set CORE_API_KEY.

​
Configuration Environment Variables

The following variables control the most important aspects of the container’s behaviour. See Configuration for the complete reference.
VariableDefaultDescription
OPENAI_API_KEY—Required when EMBEDDING_PROVIDER=openai or LLM_PROVIDER=openai
EMBEDDING_PROVIDERopenaiEmbedding backend: openai, transformers, ollama, voyage, openai-compatible
LLM_PROVIDERopenaiLLM backend used during full ingest extraction: openai, anthropic, ollama, groq, google-genai, openai-compatible
CORE_API_KEYlocal-dev-keyBearer token clients must pass in Authorization headers
DATABASE_URLembeddedPostgres connection string; defaults to the bundled local instance
PORT17350Port the HTTP server listens on inside the container
Data is persisted via the volume mount at /var/lib/atomicmemory/postgres. If you remove the volume, all stored memories are lost.

​
Fully Local Setup (No External API Keys)

If you want to run AtomicMemory without sending data to any external service, use the transformers embedding provider together with a local Ollama instance for LLM extraction. This configuration works entirely offline once the models are downloaded.
The transformers provider runs embedding inference locally via WASM/ONNX inside the container. Expect higher latency on the first request while the model warms up, and slightly lower throughput compared with hosted APIs. It is well-suited for development, air-gapped environments, and privacy-sensitive workloads.
docker run --rm -it --pull always \
  -p 127.0.0.1:17350:17350 \
  -e EMBEDDING_PROVIDER=transformers \
  -e LLM_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest
host.docker.internal resolves to the Docker host on macOS and Windows. On Linux, pass --add-host host.docker.internal:host-gateway or use the host’s LAN IP directly.

​
Production Deployment

For production, connect the container to an external managed Postgres instance with pgvector enabled and set a strong CORE_API_KEY. The RAW_STORAGE_DEPLOYMENT_ENV=production flag enables production-grade storage policies. 
export CORE_API_KEY=$(openssl rand -hex 32)
export STORAGE_KEY_HMAC_SECRET=$(openssl rand -hex 32)

docker run --rm -it --pull always \
  -p 17350:17350 \
  -e DATABASE_URL=postgresql://user:pass@postgres.example.com:5432/atomicmemory \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e CORE_API_KEY=$CORE_API_KEY \
  -e STORAGE_KEY_HMAC_SECRET=$STORAGE_KEY_HMAC_SECRET \
  -e EMBEDDING_DIMENSIONS=1536 \
  -e RAW_STORAGE_DEPLOYMENT_ENV=production \
  ghcr.io/atomicstrata/atomicmemory-core:latest
Never expose CORE_API_KEY in client-side code or public repositories. Rotate this secret immediately if it is ever leaked.

​
Docker Compose (Two-Container Stack)

For a local stack that manages both the application and Postgres as separate containers, use the published Compose file: 
curl -fsSLO https://raw.githubusercontent.com/atomicstrata/atomicmemory/main/packages/core/docker-compose.image.yml

cat > .env <<'EOF'
OPENAI_API_KEY=sk-...
CORE_API_KEY=replace-with-a-strong-random-secret
STORAGE_KEY_HMAC_SECRET=000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
EMBEDDING_DIMENSIONS=1536
RAW_STORAGE_DEPLOYMENT_ENV=local
EOF

docker compose -f docker-compose.image.yml up
The Compose file is the recommended approach for local development teams because it provides an isolated, reproducible Postgres instance and makes it easy to reset state by removing the named volume.