Skip to main content
The AtomicMemory SDK uses a pluggable provider system that separates your application code from the specific memory backend it talks to. You configure the provider once in the MemoryClient constructor, and every call to memory.ingest(), memory.search(), and the rest of the API routes through that provider. Swapping backends — for example, moving from a local AtomicMemory Core instance to a hosted deployment, or evaluating Mem0 alongside Core — requires changing only the constructor configuration.

​
Available Providers

AtomicMemory Core

The recommended backend for self-hosted deployments. Connects to a running AtomicMemory Core instance over HTTP. Supports full ingest with AUDN-SC extraction, hybrid semantic search, claim versioning, and tiered context packaging.

Mem0

An HTTP adapter for Mem0, compatible with both the Mem0 OSS server and the hosted Mem0 API. Useful if you are already running Mem0 and want to evaluate or migrate to AtomicMemory tooling.

​
AtomicMemory Provider

Pass an atomicmemory key inside the providers object to connect to an AtomicMemory Core instance. The apiUrl must point to the base URL of your Core deployment, and apiKey must match the CORE_API_KEY set on the server. 
import { MemoryClient } from '@atomicmemory/sdk';

const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: 'http://127.0.0.1:17350',
      apiKey: 'local-dev-key',
    },
  },
});

await memory.initialize();
​
providers.atomicmemory.apiUrl
string
required
Base URL of the AtomicMemory Core instance, without a trailing slash. For local Docker deployments this is typically http://127.0.0.1:17350.
​
providers.atomicmemory.apiKey
string
required
Bearer token to authenticate with Core. Must match the CORE_API_KEY environment variable set on the server. For local development the default value is local-dev-key.
​
providers.atomicmemory.timeout
number
Request timeout in milliseconds. Defaults to 30000 (30 seconds). Increase this for large ingest payloads or slow LLM providers.

​
Production configuration

For production, read credentials from environment variables and never hardcode them: 
const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: process.env.ATOMICMEMORY_URL!,
      apiKey: process.env.ATOMICMEMORY_KEY!,
    },
  },
});

​
Mem0 Provider

Pass a mem0 key inside the providers object to connect to a Mem0 server. The same MemoryClient API surface works identically — no application code changes are needed when switching between atomicmemory and mem0. 
import { MemoryClient } from '@atomicmemory/sdk';

const memory = new MemoryClient({
  providers: {
    mem0: {
      apiUrl: 'https://api.mem0.ai',   // or your self-hosted Mem0 URL
      apiKey: process.env.MEM0_API_KEY!,
    },
  },
});

await memory.initialize();
​
providers.mem0.apiUrl
string
required
Base URL of the Mem0 API. Use https://api.mem0.ai for the hosted Mem0 service, or the URL of your self-hosted Mem0 instance.
​
providers.mem0.apiKey
string
required
API key for authenticating with the Mem0 service.

​
Switching Providers at Runtime

Because the provider is just a constructor argument, you can select the active backend at application startup using environment variables: 
import { MemoryClient } from '@atomicmemory/sdk';

const provider = process.env.ATOMICMEMORY_PROVIDER ?? 'atomicmemory';

const memory = new MemoryClient({
  providers:
    provider === 'mem0'
      ? {
          mem0: {
            apiUrl: process.env.MEM0_URL!,
            apiKey: process.env.MEM0_API_KEY!,
          },
        }
      : {
          atomicmemory: {
            apiUrl: process.env.ATOMICMEMORY_URL!,
            apiKey: process.env.ATOMICMEMORY_KEY!,
          },
        },
});

await memory.initialize();
This pattern is useful for running integration tests against a local AtomicMemory Core instance while pointing your staging and production environments at a managed deployment — all controlled by a single environment variable with no code changes.

​
Implementing a Custom Provider

If you need to connect to a backend that is not natively supported, you can implement the MemoryProvider interface exported from @atomicmemory/sdk/memory and pass it through the provider registry. Custom providers receive the same scope routing, error normalisation, and type safety as the built-in adapters. 
import type { MemoryProvider } from '@atomicmemory/sdk/memory';

class MyCustomProvider implements MemoryProvider {
  // Implement: ingest, search, get, delete, list, and capabilities
}
Refer to the MemoryProvider TypeScript interface in @atomicmemory/sdk/memory for the full method signatures.