How Supermemory Works

At it’s core, supermemory is powered by a custom learning model and a graph database that we built internally.

Learning model

Decides what and how to learn, what is important, when to forget, creating relations, etc.

Temporal Vector-graph engine

Where the learnings are actually stored, optimized for search. Fact-based temporal graph that has Vector, FTS, and graph built in.

But, you don’t have to think about the above. The interface for users is as simple as it gets.

Get started in under a minute

1. Get an API key

From the developer console — API Keys → Create API Key. console.supermemory.ai is where keys and usage live.

2. Use it

Install the SDK, drop in your key, add a memory, and search it — right below, or the full ingest → retrieve loop.

npm install supermemory

import Supermemory from "supermemory";

const client = new Supermemory({ apiKey: "sm_..." }); // from console.supermemory.ai → API Keys

await client.add({ content: "The user loves Paris.", containerTag: "user_123" });

const { results } = await client.search({
  q: "where does the user want to travel?",
  containerTag: "user_123",
});

from supermemory import Supermemory

client = Supermemory(api_key="sm_...")  # from console.supermemory.ai → API Keys

client.add(content="The user loves Paris.", container_tag="user_123")

results = client.search(
    q="where does the user want to travel?",
    container_tag="user_123",
)

curl -X POST https://api.supermemory.ai/v3/documents \
  -H "Authorization: Bearer sm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user loves Paris.",
    "containerTag": "user_123"
  }'

What you send: documents

A document is raw input — whatever you hand Supermemory:

Conversation transcripts and messages
Text, markdown, HTML
PDFs, images, audio/video, code
URLs and connector items (Drive, Notion, Gmail, …)

You do not pre-chunk or pick an embedding model. See Multi-modal ingestion for formats, and Add context for the API. Supermemory handles the ingestion and extraction for you. This also gives us a big advantage for quality - The engine extracts it in an optimized way with Contextual Chunking and other features for better quality search and memory generation.

Use a stable customId when the same conversation or file will be updated later (sessions, connector syncs). That identity also drives diff billing on re-ingest.

What the pipeline does

Stage	What happens
Queued	Accepted; waiting to run
Extracting	Text / OCR / transcription / page fetch
Chunking	Splits content for retrieval (type-aware where needed)
Embedding	Vectors for similarity search
Indexing	Makes chunks and derived structure searchable
Done	Document path is ready for search

const doc = await client.add({
  content: conversationText,
  containerTag: "user_123",
  customId: "chat_session_1",
});

// Poll until ready
const status = await client.documents.get(doc.id);
// status.status → "queued" | "extracting" | ... | "done" | "failed"

Larger PDFs and long video take longer. Short chat turns usually finish in seconds.

Dreaming (how memories enter the graph)

Document status done means chunks are indexed for search. Memories — the graph facts, updates, and derives — come from a second phase called dreaming. This is when the content is passed through the memory model and merged, arranged and organized for the future. Pass dreaming on add:

Mode	Default?	Behavior	When to use
`dynamic`	Yes	Related documents are grouped so memories form from coherent units, not one isolated write at a time. Graph quality is higher for real multi-turn / multi-doc flows. Memory extraction may continue after `status: "done"`.	Production agents, connectors, ongoing sessions
`instant`	No	This document is dreamed on its own, right away. Memories are available as soon as processing finishes for that doc. Bills one extra operation per document.	Demos, quickstarts, “I need the graph now”

// Production default — omit or set explicitly
await client.add({
  content: conversationText,
  containerTag: "user_123",
  customId: "chat_session_1",
  dreaming: "dynamic",
});

// Need memories immediately (e.g. tutorial)
await client.add({
  content: conversationText,
  containerTag: "user_123",
  customId: "chat_session_1",
  dreaming: "instant",
});

Rule of thumb: prefer dynamic for quality and cost in real apps, use instant when the next step is a memory search or profile that must reflect this document immediately (as in the quickstart). Keeping it dynamic helps it pair better with other memories and better connections, inferences to be made. How those memories connect and stay true over time is Graph memory. API detail: Processing modes.

What you get out

After the pipeline runs, the same document leads to three things -> Chunks, Memories and Profile. (in the same containerTag):

Output	Role	Go deeper
Document chunks	Grounding in the raw source (RAG / SuperRAG)	SuperRAG, Search API
Memories	Extracted facts in a living graph — updates, links, time	Graph memory
Profile	A sample of memories, static + dynamic summary for always-on context	Profiles, Profile API

Supermemory does not only store the file. It derives memories (understanding) and keeps chunks (the source) so you can personalize and ground. That distinction is the core of Memory vs RAG.

Isolation and identity

containerTag — hard isolation boundary (user, tenant, project). See Container tags.
Metadata — soft dimensions inside a tag for filtering. See Metadata filtering.
Scoped API keys — credentials that cannot cross a container. See API keys.

Next steps

Graph memory

How facts connect, update, and stay true over time.

Multi-modal ingestion

Formats, extractors, and what you can send.

Add context

API: add, customId, files, dreaming, status.

Search API

Query documents and memories after the pipeline finishes.

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Learning model

Temporal Vector-graph engine

Get started in under a minute

1. Get an API key

2. Use it

What you send: documents

What the pipeline does

Dreaming (how memories enter the graph)

What you get out

Isolation and identity

Next steps

Graph memory

Multi-modal ingestion

Add context

Search API

Learning model

Temporal Vector-graph engine

​Get started in under a minute

1. Get an API key

2. Use it

​What you send: documents

​What the pipeline does

​Dreaming (how memories enter the graph)

​What you get out

​Isolation and identity

​Next steps

Graph memory

Multi-modal ingestion

Add context

Search API

Get started in under a minute

What you send: documents

What the pipeline does

Dreaming (how memories enter the graph)

What you get out

Isolation and identity

Next steps