Skip to main content

SDK Quickstart

Install, initialize, and make your first ingest and search — with AtomicMemorySDK wired to a running atomicmemory-core.

Prerequisites​

  • Node.js ≥ 18 (the SDK is ESM + CJS)
  • A running atomicmemory-core — follow the Core Quickstart if you have not yet brought one up; we assume http://localhost:3050 below

Step 1 — Install​

npm install @atomicmemory/atomicmemory-sdk

Step 2 — Initialize​

AtomicMemorySDK requires a userAccounts configuration (identity and preferences) and a context.providers configuration (which memory backend to use and how to reach it).

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

const sdk = new AtomicMemorySDK({
  userAccounts: {
    identity: {
      providerType: 'web2',
      apiBaseUrl: 'http://localhost:8787',
      testMode: true,
    },
    preferences: {
      providerType: 'web2',
      apiBaseUrl: 'http://localhost:8787',
      testMode: true,
      encryption: { keySource: 'provided', key: new Uint8Array(32) },
    },
  },
  context: {
    providers: {
      default: 'atomicmemory',
      atomicmemory: { apiUrl: 'http://localhost:3050' },
    },
  },
});

await sdk.initialize();

The testMode: true flag on both user-account services installs the hardcoded test provider — a permissive default that does not require a running identity service. For production configuration see Scopes and identity.

Step 3 — Ingest a memory​

await sdk.ingest(
  {
    mode: 'text',
    content: 'JavaScript closures capture variables from their lexical scope.',
    scope: { user: 'demo-user' },
    provenance: { source: 'manual' },
  },
  'chatgpt.com',
);

The second argument, 'chatgpt.com', is the platform the capture originated from. AtomicMemorySDK runs this through its capture gate before delegating to the provider — see Consent and gating.

Step 4 — Search​

const page = await sdk.search(
  {
    query: 'How do closures work?',
    scope: { user: 'demo-user' },
    limit: 5,
  },
  'chatgpt.com',
);

for (const { memory, score } of page.results) {
  console.log(score.toFixed(3), memory.content);
}

sdk.search(request, site) gates the result against the user's injection rules for site. If the site is blocked, the response is a SearchResultPage with { results: [] }, not an exception — design your UI accordingly.

This is the whole round trip​

initialize → ingest → search. Every other method (get, delete, list, package, capabilities, loadKnowledgeBase, provider introspection) is reachable on the same sdk object. For the full surface, see the API Reference overview.

What next​