AtomicMemory FAQ: Architecture, Providers, and Integrations

AtomicMemory brings together several components — a backend service, a TypeScript SDK, a CLI, an MCP server, framework adapters, and host plugins — and the relationship between them is not always obvious from the outside. These answers address the questions that come up most often when evaluating or building with AtomicMemory.

What's the difference between AtomicMemory Core and the SDK?

Core and the SDK are two distinct layers that work together.AtomicMemory Core (@atomicmemory/core) is the backend service. It runs as a Docker container, manages the PostgreSQL database with pgvector, handles semantic ingest, AUDN-SC mutation, hybrid retrieval, and exposes the HTTP API on port 17350. Core is the engine — it does the actual memory work.The SDK (@atomicmemory/sdk) is the TypeScript client library you use in your application code. It talks to Core over HTTP and provides a typed interface for ingest, search, storage helpers, and local embedding utilities. The SDK does not store anything by itself — it needs Core running to do anything meaningful.You always need Core running. The SDK is how your application code talks to it.

import { MemoryClient } from '@atomicmemory/sdk';

// SDK connects to Core at this URL
const memory = new MemoryClient({
  providers: {
    atomicmemory: { apiUrl: 'http://localhost:17350' },
  },
});

Can I use AtomicMemory without OpenAI?

Yes. AtomicMemory supports fully local operation with no external API keys required.Set EMBEDDING_PROVIDER=transformers to use local WASM-based embeddings (via @huggingface/transformers) and LLM_PROVIDER=ollama to run extraction through a local Ollama instance:

EMBEDDING_PROVIDER=transformers
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434

For personal development on a machine with Claude Code or Codex installed, you can also use LLM_PROVIDER=claude-code or LLM_PROVIDER=codex — these route through your logged-in account session without requiring a separate API key. These options consume your account limits and are not intended for hosted or team deployments.The transformers provider downloads the embedding model on first use and caches it locally. After the initial download, all embedding inference runs on your machine.

What is the difference between `ingest` and `ingest/quick`?

The two ingest endpoints trade accuracy for speed.Full ingest (POST /v1/memories/ingest) runs LLM-based extraction and AUDN-SC mutation. It extracts discrete claims from your input, evaluates each claim against existing memories, and decides whether to Add, Update, Delete, leave as No-op, Supersede, or Clarify an existing record. This process prevents duplicate and contradictory memories from accumulating over time, and it produces versioned lineage for every mutation.Quick ingest (POST /v1/memories/ingest/quick) skips LLM extraction and uses embedding-based deduplication only. It is substantially faster and cheaper per call, but it does not perform contradiction detection or AUDN-SC mutation decisions.

	Full ingest	Quick ingest
LLM extraction	✓	✗
AUDN-SC mutation	✓	✗
Contradiction detection	✓	✗
Embedding deduplication	✓	✓
Speed	Slower	Faster
Best for	Accuracy-critical memories	High-throughput or ephemeral notes

Use full ingest when what your agent believes matters. Use quick ingest for high-throughput logging, ephemeral session notes, or cases where deduplication is sufficient.

How do I ensure memories from different users don't mix?

Always provide a unique user scope field per user, drawn from your own authentication system.AtomicMemory rejects scopeless requests at the SDK level — this prevents accidental writes without a scope. But it is your responsibility to map your application’s user identities to scope fields consistently.

// Each user gets their own isolated scope
await memory.ingest({
  mode: 'messages',
  messages: [{ role: 'user', content: 'I live in Berlin.' }],
  scope: { user: session.userId },  // from your auth system
});

A few rules to follow:

Use stable, unique user IDs — not display names or email addresses that can change
Never share a user ID across tenants, even in test environments
If you operate multiple isolated tenants, combine user with namespace to add a second isolation boundary: scope: { user: userId, namespace: tenantId }

Can I run AtomicMemory in production without Docker?

The recommended and fully supported deployment path is Docker. The published GHCR image (ghcr.io/atomicstrata/atomicmemory-core:latest) is tested for both linux/amd64 and linux/arm64 and includes an embedded PostgreSQL/pgvector instance for simpler deployments.For custom deployments, you can run Core directly with Node.js by installing @atomicmemory/core from npm and using the thin CLI. The CLI requires Node.js 20 or later; the TypeScript SDK (@atomicmemory/sdk) requires Node.js 22 or later.

export DATABASE_URL=postgresql://user:pass@localhost:5432/atomicmemory
npx -y @atomicmemory/core migrate --profile local
npx -y @atomicmemory/core start --profile local

This path requires you to provision and manage PostgreSQL with the pgvector extension yourself. Docker is preferred because it handles the database bundling, the migration on startup, and the platform compatibility concerns for you.

What frameworks does AtomicMemory integrate with?

AtomicMemory publishes official adapters for the most widely-used TypeScript AI frameworks:

Framework	Package
Vercel AI SDK	`@atomicmemory/vercel-ai`
OpenAI Agents SDK	`@atomicmemory/openai-agents`
LangChain JS	`@atomicmemory/langchain`
LangGraph JS	`@atomicmemory/langgraph`
Mastra	`@atomicmemory/mastra`

All adapters are built on top of @atomicmemory/sdk. They are conveniences, not gatekeepers — you can always drop down to the SDK directly within a framework context and get the same memory store, indexes, and retrieval behavior.For frameworks not listed, use the SDK directly or configure the MCP server. Any agent framework that supports MCP tool calling can use AtomicMemory through the MCP server without a custom adapter.

How does the MCP server work with Claude Code?

The Claude Code plugin (@atomicmemory/claude-code-plugin) does more than add the MCP server as a tool source — it installs lifecycle hooks that automate memory capture throughout a session.The hooks fire at four points:

Session start — captures initial context and loads relevant memories into the session
Each user prompt — captures the prompt and retrieves relevant memories to ground the response
Before context compaction — saves key context before Claude Code compresses the conversation window
After context compaction — restores important memories into the compacted context

This means memory capture is automatic once the plugin is installed. You do not need to manually call ingest on every message — the hooks handle it. Install the plugin with:

atomicmemory hooks install --host claude-code --runtime node

Where are memories stored?

AtomicMemory Core uses PostgreSQL with the pgvector extension for all storage. Memories, embeddings, entity graphs, version lineage, and audit records all live in Postgres.When running via Docker with the default configuration, data is persisted in the directory you mount at /var/lib/atomicmemory/postgres on the container:

docker run --rm -it \
  -p 127.0.0.1:17350:17350 \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest

For production deployments, set DATABASE_URL to your managed PostgreSQL connection string and the embedded database will not be used:

-e DATABASE_URL=postgresql://user:pass@postgres.example.com:5432/atomicmemory

You own your memory store. The data never leaves your infrastructure unless you point DATABASE_URL at a hosted database that you control.

Can I import an existing knowledge base?

Yes. The @atomicmemory/llmwiki package provides a one-way bridge from llmwiki JSON exports into AtomicMemory.Each wiki page in the export becomes one verbatim memory record, with all advisory metadata preserved under memory.metadata.llmwiki.* — including kind, citations, confidence, provenance state, contradictions, aliases, and freshness indicators.Import from the CLI:

atomicmemory import --source llmwiki --file export.json

Or use the bridge package programmatically in your own ingest pipeline. See the @atomicmemory/llmwiki documentation for the full workflow.

@atomicmemory/llmwiki is currently in the implemented, publish pending state — the code works locally in the monorepo but the first npm release has not been cut yet. Check the package matrix for the current status before adding it to an install command.

What is AUDN-SC mutation?

AUDN-SC is the decision engine that runs during full ingest. When you ingest a conversation or a set of claims, the engine does not simply append new records — it evaluates each extracted claim against what is already stored and chooses one of six mutation actions:

Decision	Meaning
Add	This claim is new — create a new memory record
Update	This claim updates an existing memory with new information
Delete	This claim signals that a prior belief is no longer valid
No-op	This claim is already accurately represented — no change needed
Supersede	This claim replaces an existing memory entirely; the old version is versioned and retained in lineage
Clarify	This claim adds nuance to an existing memory without replacing it

Pre-AUDN rejections — cases where the input is filtered before extraction runs — use a separate SKIP sentinel in the ingest trace.AUDN-SC is what prevents your agent’s memory from accumulating contradictions and duplicates over time. Without it, every conversation would add new records regardless of whether the information was already known, updated, or retracted.