Atomicmemory Core

Open-source memory engine for AI applications and agents.

Docker-deployable memory backend with durable context, semantic retrieval, and memory mutation (AUDN: Add, Update, Delete, No-op).

Docs: docs.atomicstrata.ai

Features

• Semantic ingest — extract structured facts from conversations with contradiction detection
• Hybrid retrieval — vector similarity + BM25/FTS with RRF fusion
• AUDN mutation — Add, Update, Delete, No-op decisions with fail-closed integrity
• Claim versioning — temporal lineage tracking with supersession and invalidation
• Tiered context packaging — L0/L1/L2 compression for token-efficient retrieval
• Entity graph — spreading activation over extracted entities
• Pluggable embeddings — openai, openai-compatible, ollama, transformers (local WASM)
• Docker-deployable — one-command deployment with Postgres + pgvector

Headline Results

AtomicMemory v66 is cost-Pareto SOTA on BEAM-100K, BEAM-1M, and LoCoMo10 under matched methodology against published competitors. On BEAM-10M it matches the strongest published Mem0-new result while leaving Hindsight-scale temporal retrieval as the known open frontier.

Benchmark	AtomicMemory v66	Position	Cost/Q	Sample
BEAM-100K lenient	0.7375	Parity with Hindsight at 0.75	$1.26	n=80
BEAM-1M lenient	0.6625	Cost-Pareto SOTA; +0.022 vs Mem0 paper	$0.083	n=80
BEAM-10M lenient	0.4875	Parity with Mem0-new at 0.486	$0.081	n=80
LoCoMo10 GPT-4o-mini binary	0.8396	Cost-Pareto SOTA; +0.171 vs Mem0 paper	$0.066	n=1540

These results put AtomicMemory at or near the published ceiling in each reported category while preserving the lower-cost operating profile that matters for real applications. Reproducibility artifacts and harness details will be published with the benchmark materials.

What This Is Not

• Not a benchmark suite — eval harnesses live in a separate research repo
• Not an SDK or client library — this is the server/backend. For a TypeScript client, see atomicmemory-sdk

Quick Start

For the full walkthrough, see the Core Quickstart.

Docker image (recommended)

After the first tagged release, you can run Core from the published GHCR image without cloning the repository. By default, the image starts an embedded Postgres/pgvector database and persists it to the mounted host directory:

export OPENAI_API_KEY=sk-...

docker run --rm -it --pull always \
  -p 127.0.0.1:3050:3050 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest

The image is published as ghcr.io/atomicstrata/atomicmemory-core with latest, semver, and commit-SHA tags.

Local Docker defaults use Authorization: Bearer local-dev-key, OpenAI embeddings at 1536 dimensions, and RAW_STORAGE_DEPLOYMENT_ENV=local. The quickstart binds to 127.0.0.1 so that default key is only exposed locally.

For production deployments, set real secrets and DATABASE_URL to your managed Postgres/pgvector connection string. When DATABASE_URL is unset or set to embedded, the container starts the bundled local Postgres instance.

export CORE_API_KEY=$(openssl rand -hex 32)
export STORAGE_KEY_HMAC_SECRET=$(openssl rand -hex 32)

docker run --rm -it --pull always \
  -p 3050:3050 \
  -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

If you prefer a two-container local stack, you can also run the app image with the bundled compose file:

curl -fsSLO https://raw.githubusercontent.com/atomicstrata/atomicmemory-core/main/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

Docker from source

git clone https://github.com/atomicstrata/atomicmemory-core.git
cd atomicmemory-core
cp .env.example .env
# Edit .env with your OPENAI_API_KEY and DATABASE_URL
docker compose up --build

Local development

npm install
cp .env.example .env
# Edit .env — requires a running Postgres instance with pgvector
npm run migrate
npm run dev

Health check: curl http://localhost:3050/v1/memories/health

npm CLI

The npm package also ships a thin CLI for environments where you already have a Postgres database with pgvector:

export DATABASE_URL=postgresql://user:pass@localhost:5432/atomicmemory

npx -y @atomicmemory/core migrate --profile local
npx -y @atomicmemory/core start --profile local

The local profile fills local-only defaults for the port, bearer key, storage policy, local transformers embeddings, and Claude Code as the LLM provider. It does not create or manage Postgres; use the Docker image above when you want the database bundled with Core.

API Overview

Core endpoints

Method	Path	Description
GET	/health	Health check
POST	/v1/memories/ingest	Full ingest with extraction and AUDN
POST	/v1/memories/ingest/quick	Fast ingest (embedding dedup only)
POST	/v1/memories/search	Semantic search with hybrid retrieval
POST	/v1/memories/search/fast	Fast vector-only search
GET	/v1/memories/list	List memories with optional filters
GET	/v1/memories/:id	Get a single memory
DELETE	/v1/memories/:id	Soft-delete a memory
POST	/v1/memories/consolidate	Consolidate and compress memories

See the HTTP API reference for full endpoint documentation.

Per-request config override

Search and ingest routes accept an optional config_override body field that overlays the startup RuntimeConfig for that single request. Useful for A/B tests, experiments, or dial-turning without restarting the server.

curl -X POST http://localhost:3050/v1/memories/search \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "alice",
    "query": "what stack does alice use?",
    "config_override": { "hybridSearchEnabled": true, "maxSearchResults": 20 }
  }'

Responses from requests carrying an override emit four observability headers:

Header	Emitted when	Value
X-Atomicmem-Config-Override-Applied	Override present	true
X-Atomicmem-Effective-Config-Hash	Override present	sha256:<hex> of the merged config
X-Atomicmem-Config-Override-Keys	Override present	Comma-joined sorted override keys
X-Atomicmem-Unknown-Override-Keys	One or more keys don't match a current RuntimeConfig field	Comma-joined sorted unknown keys

The schema is permissive — unknown keys don't 400. They ride through on the effective config and surface via the fourth header plus a server-side warning log, so callers catch typos without gating new runtime fields behind a schema release.

Environment Variables

Required

Variable	Description
DATABASE_URL	Postgres connection string (must have pgvector extension)
OPENAI_API_KEY	OpenAI API key (when using openai embedding/LLM provider)
PORT	Server port (default: 3050)

Embedding Provider

Set EMBEDDING_PROVIDER to choose your embedding backend:

Value	Description
openai	OpenAI Embeddings API (default)
openai-compatible	Any OpenAI-compatible API (recommended for self-hosters)
ollama	Local Ollama instance
transformers	Local WASM/ONNX inference via @huggingface/transformers
voyage	Voyage AI embeddings with separate document/query models

For self-hosted deployments, openai-compatible is recommended as it works with any OpenAI-compatible embedding service.

LLM Provider

Set LLM_PROVIDER to choose the extraction backend:

Value	Description
openai	OpenAI Chat Completions API (default)
openai-compatible	Any OpenAI-compatible chat API
ollama	Local Ollama instance
groq	Groq OpenAI-compatible API
anthropic	Anthropic Messages API
google-genai	Google Gemini OpenAI-compatible endpoint
claude-code	Local Claude Code Agent SDK session for personal development

For personal local use, LLM_PROVIDER=claude-code uses the logged-in claude CLI session instead of requiring ANTHROPIC_API_KEY. It still consumes the user's Claude Code / Claude subscription limits and is not intended for hosted or team deployments. Pair it with a non-OpenAI embedding provider, such as EMBEDDING_PROVIDER=transformers, if you want to run without an OpenAI API key as well.

In-process benchmark harnesses can avoid editing env files by passing a composition-time config to the runtime:

import { config, createCoreRuntime } from '@atomicmemory/core';

const runtime = createCoreRuntime({
  pool,
  config: {
    ...config,
    embeddingProvider: 'voyage',
    embeddingDimensions: 1024,
    voyageApiKey,
    voyageDocumentModel: 'voyage-4-large',
    voyageQueryModel: 'voyage-4-lite',
  },
});

Provider/model fields are still startup-only for a given runtime. Use a new isolated runtime or process for each embedding configuration.

See .env.example for the full list of configuration options.

Deployment

Platform-specific deployment

See deploy/ for platform-specific configs (Railway, etc.). Copy the relevant config to your project root before deploying.

Docker

docker compose up --build

The compose file includes Postgres with pgvector. The app container runs migrations on startup, then starts the server.

Architecture

src/
  routes/       # Express route handlers
  services/     # Business logic (extraction, retrieval, packaging)
  db/           # Repository layer, schema, migrations
  adapters/     # Type contracts for external integrations
  config.ts     # Environment-driven configuration
  server.ts     # Express app bootstrap

Storage: Postgres + pgvector. Retrieval: hybrid (vector + BM25/FTS). Mutation: contradiction-safe AUDN with claim versioning.

Development

npm test                    # Run unit tests
npm run test:deployment     # Deployment config tests
npm run test:docker-smoke   # Docker smoke test
npm run test:schema         # Schema regression fuzzing (Schemathesis)
npm run migrate:test        # Run migrations against test DB

Schema regression tests

Property-based fuzzing of openapi.yaml via Schemathesis runs on every PR (schema-fuzz job in .github/workflows/ci.yml). Catches wire-shape regressions where a route's response drifts from its declared schema. See tests/schema/ for how to run locally and how to read the report.

Contributing

See CONTRIBUTING.md for setup, workflow, and code style expectations.

License

Apache-2.0