Skip to main content
This guide walks you through every step needed to go from zero to a working memory store: starting the Core backend, installing the SDK, initializing a client, ingesting a conversation, and retrieving memories by semantic query. All you need is Docker, Node.js, and an OpenAI API key.
1

Start AtomicMemory Core

The fastest way to run Core is the published Docker image from the GitHub Container Registry. The command below starts an embedded Postgres + pgvector database, persists data to your home directory, and binds the server to 127.0.0.1:17350.
docker run --rm -it --pull always \
  -p 127.0.0.1:17350:17350 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest
The image is published for both linux/amd64 and linux/arm64, so it works on common Linux servers and Apple Silicon Macs without any additional flags.Once you see the server listening log line, Core is ready to accept requests. You can verify it with a quick health check:
curl http://127.0.0.1:17350/v1/memories/health
The local Docker instance uses local-dev-key as the API key by default. No additional authentication setup is required for local development. The server is bound to 127.0.0.1 so that default key is never exposed over a network interface.
2

Install the SDK

Install @atomicmemory/sdk with your preferred package manager.
npm install @atomicmemory/sdk
3

Initialize a MemoryClient

Import MemoryClient and configure it to point at your running Core instance. The apiUrl and apiKey values below match the Docker defaults, so you can copy this directly into a new file.
import { MemoryClient } from '@atomicmemory/sdk';

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

await memory.initialize();
initialize() validates connectivity to the provider and prepares the client for use. Call it once at startup before making any memory operations.
In production, set ATOMICMEMORY_URL and ATOMICMEMORY_KEY as environment variables instead of using the defaults. Switching from local to hosted is a two-value config change — your application code stays exactly the same.
4

Ingest a memory

Pass a conversation to memory.ingest(). AtomicMemory extracts structured facts from the messages and stores them as memories scoped to the user you specify. The scope field is how the engine knows which user’s memories to write to and read from.
await memory.ingest({
  mode: 'messages',
  messages: [
    { role: 'user', content: 'My name is Alex and I prefer TypeScript.' },
    { role: 'assistant', content: 'Got it, I\'ll remember that.' },
  ],
  scope: { user: 'alex' },
});
The full ingest endpoint runs extraction and AUDN-SC mutation: each extracted claim is classified as an add, update, supersede, clarify, delete, or no-op against the existing memory store. This keeps memories accurate over time rather than accumulating duplicates.
5

Search memories

Retrieve memories with a natural-language query. The engine scores results by semantic similarity and returns them ranked by relevance. Scope the search to the same user to retrieve only their memories.
const results = await memory.search({
  query: 'What are my preferences?',
  scope: { user: 'alex' },
  limit: 5,
});

for (const result of results.memories) {
  console.log(result.content, result.score);
}
You should see the memory ingested in the previous step returned with a high similarity score. Each result includes the memory content and a numeric relevance score between 0 and 1.

​
What just happened

You started a self-contained memory backend, wrote a user preference to it, and retrieved it with a semantic query — without managing embeddings, a vector database, or extraction logic yourself. AtomicMemory handles all of that inside Core.

​
Next steps

MemoryClient API

Explore the full MemoryClient surface: ingest modes, search options, filtering, and error handling.

Memory Scope

Learn how to scope memories to users, agents, namespaces, and threads for multi-tenant and multi-agent applications.

LangChain Adapter

Add persistent memory to a LangChain application with the @atomicmemory/langchain adapter.

CLI Overview

Use the AtomicMemory CLI to inspect, search, and manage memories from the command line.