Skip to main content
Before you write production code against AtomicMemory, it helps to understand the handful of concepts that shape every operation. This page walks through memory scope, ingestion modes, the AUDN-SC mutation engine, retrieval, providers, and the local-vs-hosted distinction. None of these require deep implementation knowledge — they are the mental model you carry into every integration.

​
Memory Scope

Every memory in AtomicMemory belongs to a scope. Scope is how the engine knows which user’s, agent’s, or application’s memories to read from and write to. Without a scope, the SDK rejects the request — there is no default global namespace. A scope is an object with up to four fields. At least one must be provided:
FieldTypeDescription
userstringThe end user this memory belongs to. Typically a user ID or username.
agentstringThe agent identity, useful when multiple agents serve the same user.
namespacestringA logical partition — e.g. an application name or tenant ID.
threadstringA specific conversation thread, for session-scoped memories.
const scope = { user: 'alice', namespace: 'my-app', agent: 'assistant' };
Use the same scope object for both ingest and search. If you ingest under { user: 'alice', namespace: 'my-app' } and search under { user: 'alice' }, you may get results from other namespaces. Keep scopes consistent across your application for predictable retrieval.
For multi-tenant applications, namespace is the right field for tenant isolation. Pair it with user to partition memories by both tenant and individual user.

​
Ingestion

Ingestion is how memories are created. You pass a conversation — a list of role/content messages — and AtomicMemory extracts structured facts, deduplicates them against what’s already known, and stores the result. There are two ingest modes with different performance and fidelity trade-offs.
Endpoint: POST /v1/memories/ingestFull ingest is the standard path. It runs the entire ingestion pipeline:
  1. Extraction — the LLM reads the conversation and extracts discrete factual claims (e.g. “Alex prefers TypeScript”, “Alex lives in Berlin”).
  2. AUDN-SC mutation — each claim is classified against the existing memory store (see the section below).
  3. Storage — claims are written, updated, versioned, or discarded according to the mutation decision.
Full ingest ensures your memory store reflects a single consistent view of what is known, even as users change their preferences or correct past statements. Use it for all normal memory capture.
Endpoint: POST /v1/memories/ingest/quickQuick ingest skips extraction and mutation. It embeds the input directly and uses embedding similarity to detect near-duplicates before writing. It is faster and cheaper per call, but it does not understand the semantic meaning of a claim or how it relates to existing memories.Use quick ingest for high-volume, low-stakes capture where speed matters more than memory coherence — for example, logging raw tool outputs or large batches of reference text.

​
AUDN-SC Mutation

When you run a full ingest, AtomicMemory’s engine evaluates every extracted claim against the existing memory store and assigns it one of six mutation labels. This is what keeps your memory store accurate over time instead of growing into a pile of stale and contradictory facts.

Add

The claim is new information not yet in the memory store. It is stored as a new memory record.

Update

The claim modifies an existing memory — for example, a user correcting a previously stated preference. The existing record is updated in place.

Delete

The claim indicates that a previously stored memory should no longer be considered true. The record is marked as removed.

No-op

The claim is already accurately represented in the memory store. No change is made.

Supersede

A newer claim replaces an older one. The original record is versioned and marked as superseded; the new claim becomes the current fact. Lineage is preserved.

Clarify

The claim adds nuance or detail to an existing memory without contradicting it. The existing record is enriched rather than replaced.
Claims that cannot pass integrity checks before mutation are assigned a SKIP sentinel and excluded from the store. This keeps the mutation pipeline fail-closed — ambiguous or malformed claims never silently corrupt your memory state.

​
Retrieval

Memory retrieval returns a ranked list of memories whose content is semantically relevant to your query. All retrieval is scoped the same way as ingestion: pass the same scope fields you used when writing memories. AtomicMemory supports two search modes: Each result includes the memory content, a relevance score, and metadata such as the memory ID and creation timestamp.

​
Providers

The SDK is backend-agnostic. You configure one or more providers at initialization time, and all memory operations route through the provider interface. This means you can swap backends — or run multiple in parallel — without changing your application logic. AtomicMemory currently ships two built-in providers:

atomicmemory

The HTTP adapter for AtomicMemory Core. This is the recommended provider for all new integrations. Supports the full feature set: full ingest, hybrid search, AUDN-SC mutation, and tiered context packaging.

mem0

An HTTP adapter for Mem0, either OSS (self-hosted) or the hosted Mem0 service. Useful if you are migrating from Mem0 or running a mixed-provider setup.
// AtomicMemory Core provider
const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: 'http://127.0.0.1:17350',
      apiKey: process.env.ATOMICMEMORY_API_KEY,
    },
  },
});

// Mem0 OSS provider
const memory = new MemoryClient({
  providers: {
    mem0: {
      apiUrl: 'http://localhost:8888',
      apiStyle: 'oss',
    },
  },
});

​
Local vs. Hosted

AtomicMemory Core can run in two deployment modes, and the SDK works identically in both.
ModeHow to runDefault portDefault API key
LocalDocker image, one command17350local-dev-key
HostedAtomicMemory hosted serviceProvided at signupProvided at signup
To switch from local development to a hosted instance, change two values in your provider config: 
// Local development
const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: 'http://127.0.0.1:17350',
      apiKey: 'local-dev-key',
    },
  },
});

// Hosted or production
const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: process.env.ATOMICMEMORY_URL,
      apiKey: process.env.ATOMICMEMORY_KEY,
    },
  },
});
There is no capability cliff between local and hosted. Every feature available locally is available on the hosted service and vice versa. You own your memory store in both cases.
The default local-dev-key is only safe when Core is bound to 127.0.0.1. Never expose a server using the default key on a public network interface.

​
Memory Tools (MCP)

The @atomicmemory/mcp-server package exposes AtomicMemory as an MCP server. Any MCP-compatible agent host — including Claude Code, Cursor, Codex, and Hermes — can connect to it and call four tools:
ToolDescription
memory_searchSearch memories by semantic query and scope
memory_ingestIngest a conversation or text into the memory store
memory_packagePackage and compress memories into a token-efficient context block
memory_listList memories with optional filters
The MCP server and the CLI share the same underlying SDK. Memories written through MCP tools are immediately available via the SDK, adapters, and HTTP API — and vice versa.