Using the atomicmemory backend

AtomicMemoryProvider is the SDK's HTTP client for atomicmemory-core. It ships with the SDK and is the default backend when you configure default: 'atomicmemory'.

Wire it up

import { AtomicMemorySDK } from '@atomicmemory/atomicmemory-sdk';

const sdk = new AtomicMemorySDK({
  userAccounts: { /* see Scopes and identity */ },
  context: {
    providers: {
      default: 'atomicmemory',
      atomicmemory: {
        apiUrl: 'https://core.example.com',
        apiKey: process.env.CORE_API_KEY,   // optional
        timeout: 30000,                      // ms; optional
        apiVersion: 'v1',                    // default 'v1'
      },
    },
  },
});

await sdk.initialize();

Health check

Before traffic flows, confirm the backend is reachable:

const health = sdk.capabilities();
// Inspect health through the Health extension:
const healthExt = sdk.getProviderStatus();
console.log(healthExt);
// { current: 'atomicmemory', available: ['atomicmemory'] }

For a deeper liveness check, hit the core /v1/memories/health endpoint directly — it returns the full config snapshot (embedding / LLM provider, thresholds).

One ingest, one search

await sdk.ingest(
  {
    mode: 'text',
    content: 'Prefer gRPC over REST for internal service-to-service calls.',
    scope: { user: 'alice' },
    provenance: { source: 'manual' },
  },
  'internal-wiki',
);

const page = await sdk.search(
  { query: 'internal service communication', scope: { user: 'alice' }, limit: 5 },
  'internal-wiki',
);

Every SDK method has a corresponding HTTP endpoint on core. Useful if you're debugging wire traffic or comparing behaviour across clients:

SDK method	HTTP endpoint	Endpoint docs
ingest	POST /v1/memories/ingest	Ingest
search	POST /v1/memories/search	Search
package	POST /v1/memories/search with packaging params	Search
list	GET /v1/memories/list	List, get, delete
get	GET /v1/memories/:id	List, get, delete
delete	DELETE /v1/memories/:id	List, get, delete

Supported extensions

AtomicMemoryProvider declares the following extensions. Apps can rely on all of them:

• package — context packaging with token budgets
• temporal — searchAsOf for point-in-time queries
• versioning — history() per memory ref
• updater — in-place updates
• health — liveness probe

Run sdk.capabilities() at init and cache the result — you'll know exactly what's available without calling around.

Production checklist

• apiKey — set a bearer token on the SDK side and a matching gate on core. Don't rely on testMode identity in production.
• timeout — the default 30s is fine for most paths. Tighten for latency-sensitive UIs; loosen for batch workloads that trigger large searches.
• apiVersion — pin to the version your core is on. Leave as 'v1' unless you've deployed a different API version.
• Network reachability — core runs on port 3050 by default. Verify from your deployment target (container? serverless? browser?) that the URL resolves.

Next

• Swapping backends — moving memories from atomicmemory to another provider
• Using the Mem0 backend — the alternate path