How Supermemory works

How a file or chat turn becomes something you can search: the ingest pipeline, statuses and outputs.

At its 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.

TypeScript

// 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",
});

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)

A document with status done has its chunks indexed for search. Memories (the graph’s facts, updates and derived facts) 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 document. 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: use dynamic in real apps for better quality and cost, because batching lets new memories connect to related ones. Use instant when the very next step is a memory search or profile that must already reflect this document, as in the quickstart.

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 more than store the file. It derives memories (what it understood) and keeps chunks (the source), so you can both personalize and ground answers. That distinction is the core of Memory vs RAG.

Isolation and identity

• containerTag — hard isolation boundary (user, tenant, project). See Container tags.
• Metadata: extra dimensions inside a tag that you can filter on. 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.