Quickstart

By the end of this page you will:

Ingest a conversation (how personal memory actually arrives)
Ingest a document (how knowledge for RAG arrives)
Retrieve three ways — document search (RAG), memory graph traversal, and user profile
Drop it into a chat harness that remembers across restarts

Same namespace for everything. One engine, three ways out. A namespace is what v3/v4 called a container tag.

Get an API key

Grab a key from the developer console — API Keys → Create API Key. console.supermemory.ai is where keys and usage live.

npm i supermemory
export SUPERMEMORY_API_KEY="sm_..."

pip install supermemory
export SUPERMEMORY_API_KEY="sm_..."

export SUPERMEMORY_API_KEY="sm_..."

1. Ingest a conversation

Real apps do not push four isolated one-liners as separate “memories.” They send conversation turns — often the full session — under a stable id so the pipeline can extract facts and link entities. We’ll use one user (user_4f8a) and one chat session. The turns never say “Sarah is my VP of Product” — that connection is what the graph should resolve later.

import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY });
const user = "user_4f8a"; // the namespace

const conversation = `
user: Just got back from Tokyo — the team offsite went great.
assistant: Glad it went well! Anything stand out?
user: Sarah presented the Q3 roadmap at the offsite.
assistant: Sounds like a big moment for her.
user: She's being promoted to VP of Product.
assistant: Congrats to Sarah — that's huge.
user: I need a gift idea for my VP of Product.
assistant: Happy to help brainstorm something personal.
`.trim();

const conv = await supermemory.add(user, {
  content: conversation,
  id: "chat_offsite_2026", // one session → one document
  metadata: { type: "conversation" },
  dreaming: "instant", // process this document now — see note below
});

console.log(conv.id, conv.status); // e.g. "queued"

from supermemory import Supermemory

client = Supermemory()
user = "user_4f8a"

conversation = """
user: Just got back from Tokyo — the team offsite went great.
assistant: Glad it went well! Anything stand out?
user: Sarah presented the Q3 roadmap at the offsite.
assistant: Sounds like a big moment for her.
user: She's being promoted to VP of Product.
assistant: Congrats to Sarah — that's huge.
user: I need a gift idea for my VP of Product.
assistant: Happy to help brainstorm something personal.
""".strip()

conv = client.add(
    user,
    content=conversation,
    id="chat_offsite_2026",  # one session → one document
    metadata={"type": "conversation"},
    dreaming="instant",  # process this document now, see note below
)
print(conv.id, conv.status)  # e.g. "queued"

curl -X POST "https://api.supermemory.ai/ns/user_4f8a/document?dreaming=instant" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "user: Just got back from Tokyo — the team offsite went great.\nassistant: Glad it went well! Anything stand out?\nuser: Sarah presented the Q3 roadmap at the offsite.\nassistant: Sounds like a big moment for her.\nuser: She is being promoted to VP of Product.\nassistant: Congrats to Sarah — that is huge.\nuser: I need a gift idea for my VP of Product.\nassistant: Happy to help brainstorm something personal.",
    "id": "chat_offsite_2026",
    "metadata": { "type": "conversation" }
  }'

add returns immediately with status: "queued". Processing is still async — wait until done before searching.

dreaming: "instant" — By default, dreaming is "dynamic": Supermemory batches related documents so memories form from coherent units, so a fresh namespace can show zero memories and an empty profile for several minutes. For this quickstart (and any path where you need memories/profiles right away), pass dreaming: "instant" so the document is processed on its own as soon as it finishes indexing. That bills one extra operation per document. See Processing Modes.

2. Ingest a document

Now add knowledge the agent should ground on — a short internal note the conversation never fully spelled out. This is the SuperRAG / document path.

const handbook = `
# Team notes — gifts & recognition

When someone is promoted to VP or above, the company recommends a thoughtful gift
in the $75–$150 range. Experiences tied to recent team milestones land better
than generic swag.

For product leadership, books on platform strategy or a dinner near the last
offsite city are common picks. Tokyo offsites often inspire travel-themed gifts.
`.trim();

const doc = await supermemory.add(user, {
  content: handbook,
  id: "doc_gift_policy",
  metadata: { type: "document", source: "handbook" },
  taskType: "superrag",
});

console.log(doc.id, doc.status);

handbook = """
# Team notes — gifts & recognition

When someone is promoted to VP or above, the company recommends a thoughtful gift
in the $75–$150 range. Experiences tied to recent team milestones land better
than generic swag.

For product leadership, books on platform strategy or a dinner near the last
offsite city are common picks. Tokyo offsites often inspire travel-themed gifts.
""".strip()

doc = client.add(
    user,
    content=handbook,
    id="doc_gift_policy",
    metadata={"type": "document", "source": "handbook"},
    task_type="superrag",
)
print(doc.id, doc.status)

curl -X POST "https://api.supermemory.ai/ns/user_4f8a/document?taskType=superrag" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Team notes — gifts & recognition\n\nWhen someone is promoted to VP or above, the company recommends a thoughtful gift in the $75–$150 range. Experiences tied to recent team milestones land better than generic swag.\n\nFor product leadership, books on platform strategy or a dinner near the last offsite city are common picks. Tokyo offsites often inspire travel-themed gifts.",
    "id": "doc_gift_policy",
    "metadata": { "type": "document", "source": "handbook" }
  }'

3. Wait until both are `done`

Poll document status. With dreaming: "instant", once system.status is done the document is indexed and memories for that document should be available for search and profiles (queued → extracting → … → done).

Note that the preferred way is to have dreaming: dynamic. supermemory charges one extra operation for instant dreaming. Instant is good for one off tests, setup, debugging and benchmarking.

async function waitUntilDone(id: string) {
  for (;;) {
    const d = await supermemory.documents.get(user, id);
    if (d.system.status === "done" || d.system.status === "failed") return d;
    await new Promise((r) => setTimeout(r, 1500));
  }
}

await waitUntilDone(conv.id);
await waitUntilDone(doc.id);
console.log("ready to search");

import time

def wait_until_done(doc_id: str):
    while True:
        d = client.documents.get(user, doc_id)
        if d.system.status in ("done", "failed"):
            return d
        time.sleep(1.5)

wait_until_done(conv.id)
wait_until_done(doc.id)
print("ready to search")

# replace DOC_ID with each document id from the add responses
curl "https://api.supermemory.ai/ns/user_4f8a/document/DOC_ID" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
# repeat until "system": { "status": "done" }

Short text with instant dreaming usually finishes in a few seconds. Larger PDFs take longer. If you omit dreaming (default "dynamic"), document RAG can work after done while memory extraction may still be batching — use "instant" when the next step is memory search or profiles.

4. Three ways to get context back

A. Document search (RAG)

Chunk-level retrieval over raw knowledge — use when you need what the docs say.

const rag = await supermemory.search(user, {
  query: "gift ideas for a VP promotion after a Tokyo offsite",
  searchMode: "chunks",
  limit: 3,
});

for (const hit of rag.results) {
  console.log(hit.similarity, hit.chunk);
}

rag = client.search(
    user,
    query="gift ideas for a VP promotion after a Tokyo offsite",
    search_mode="chunks",
    limit=3,
)

for hit in rag.results:
    print(hit.similarity, hit.chunk)

curl -X POST "https://api.supermemory.ai/ns/user_4f8a/search?searchMode=chunks&limit=3" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "gift ideas for a VP promotion after a Tokyo offsite" }'

You should see chunks from the handbook (budget range, Tokyo offsite angle) — document grounding, not personal facts. Omit searchMode (or set it to "hybrid", the default) to get extracted memories and document chunks together:

await supermemory.search(user, {
  query: "gift ideas for a VP promotion after a Tokyo offsite",
  searchMode: "hybrid",
  limit: 5,
});

B. Memory graph traversal

Search extracted memories with related edges. This is the entity-chain moment: gift → VP of Product → Sarah → Tokyo offsite.

const memories = await supermemory.search(user, {
  query: "What gift should I get, and why?",
  include: { related: true },
  searchMode: "memories",
  limit: 5,
});

console.log(JSON.stringify(memories, null, 2));

memories = client.search(
    user,
    query="What gift should I get, and why?",
    search_mode="memories",
    include={"related": True},
    limit=5,
)
print(memories.to_json())

curl -X POST "https://api.supermemory.ai/ns/user_4f8a/search?searchMode=memories&limit=5" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What gift should I get, and why?",
    "include": { "related": true }
  }'

Abbreviated shape:

{
  "results": [
    {
      "id": "mem_8c1f",
      "memory": "Sarah is being promoted to VP of Product",
      "similarity": 0.81,
      "included": {
        "related": {
          "parents": [
            { "id": "mem_2a90", "memory": "Sarah presented the Q3 roadmap at the Tokyo offsite" }
          ],
          "children": [
            { "id": "mem_b713", "memory": "User needs a gift idea for their VP of Product, Sarah" }
          ]
        }
      }
    }
  ],
  "searchTime": 287
}

You never wrote “Sarah is my VP of Product” as one sentence. The graph connected sessions of speech. Deep dive: graph memory.

C. User profile

Profiles are the always-on summary (static + recent dynamic) of an entity (or a namespace) - what you inject every turn without re-searching the world.

const { profile } = await supermemory.profile(user);

console.log("static:", profile.static.map((m) => m.memory));
console.log("dynamic:", profile.dynamic.map((m) => m.memory));

profile = client.profile(user).profile

print("static:", [m.memory for m in profile.static])
print("dynamic:", [m.memory for m in profile.dynamic])

curl -X POST "https://api.supermemory.ai/ns/user_4f8a/profile" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

The v5 profile call takes no query. When you also want query-ranked memories, run a search next to it (the harness below does exactly that).

There is a lot more to profiles - with Buckets, for example, you can make supermemory learn and categorize incoming information for learning specific things.

Path	Use when
Document search	Ground in policies, docs, handbooks
Memory + related	Personal facts, entity links, “what’s true about this user”
Profile	Cheap always-on context every LLM turn

Same namespace → same context pool. See Memory vs RAG.

5. Put it in a harness

There is no single required harness. The pattern is the same wherever you run the model: read context (profile / search / docs), generate, write the turn back under a stable id so the session stays one document. Here are two example shapes — pick whatever matches your stack.

Example: explicit profile + search + add

// npm i supermemory openai
import { Supermemory } from "supermemory";
import OpenAI from "openai";
import * as readline from "node:readline/promises";

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY });
const llm = new OpenAI();
const user = "user_4f8a";
const sessionId = "chat_live_session";
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

while (true) {
  const question = await rl.question("you: ");

  const { profile } = await supermemory.profile(user);

  const related = await supermemory.search(user, {
    query: question,
    searchMode: "memories",
    limit: 5,
  });

  // optional: also pull document chunks for grounding
  const rag = await supermemory.search(user, {
    query: question,
    searchMode: "chunks",
    limit: 3,
  });

  const context = [
    "## Profile (static)",
    ...profile.static.map((m) => m.memory),
    "## Profile (dynamic)",
    ...profile.dynamic.map((m) => m.memory),
    "## Related memories",
    ...related.results.map((r) => r.memory).filter(Boolean),
    "## Docs",
    ...rag.results.map((r) => r.chunk).filter(Boolean),
  ].join("\n");

  const res = await llm.chat.completions.create({
    model: "gpt-4o",
    messages: [
      { role: "system", content: `You help this user. Context:\n${context}` },
      { role: "user", content: question },
    ],
  });
  const answer = res.choices[0].message.content ?? "";
  console.log(`assistant: ${answer}`);

  // append this turn into the same conversation document
  await supermemory.add(user, {
    content: `user: ${question}\nassistant: ${answer}`,
    id: sessionId,
  });
}

# pip install supermemory openai
from supermemory import Supermemory
from openai import OpenAI

memory = Supermemory()
llm = OpenAI()
user = "user_4f8a"
session_id = "chat_live_session"

while True:
    question = input("you: ")

    profile = memory.profile(user).profile

    related = memory.search(user, query=question, search_mode="memories", limit=5)

    # optional: also pull document chunks for grounding
    rag = memory.search(user, query=question, search_mode="chunks", limit=3)

    context = "\n".join(
        [
            "## Profile (static)",
            *[m.memory for m in profile.static],
            "## Profile (dynamic)",
            *[m.memory for m in profile.dynamic],
            "## Related memories",
            *[r.memory for r in related.results if r.memory],
            "## Docs",
            *[r.chunk for r in rag.results if r.chunk],
        ]
    )

    res = llm.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"You help this user. Context:\n{context}"},
            {"role": "user", "content": question},
        ],
    )
    answer = res.choices[0].message.content or ""
    print(f"assistant: {answer}")

    # append this turn into the same conversation document
    memory.add(
        user,
        content=f"user: {question}\nassistant: {answer}",
        id=session_id,
    )

Example: Vercel AI SDK

Same pattern, wrapped: withSupermemory injects context and can save the conversation for you. Details: AI SDK integration.

// npm install ai @ai-sdk/openai @supermemory/tools
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { withSupermemory } from "@supermemory/tools/ai-sdk";
import * as readline from "node:readline/promises";

const model = withSupermemory(openai("gpt-4o"), {
  namespace: "user_4f8a",
  id: "chat_live_session", // keep stable for the whole session
  mode: "full", // profile + query search
});

const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

while (true) {
  const prompt = await rl.question("you: ");
  const { text } = await generateText({ model, prompt });
  console.log(`assistant: ${text}`);
}

Try:

you: What gift should I get for the person being promoted?
assistant: You're looking for something for Sarah — she's being promoted to VP of
Product after presenting the Q3 roadmap in Tokyo. Your handbook suggests $75–$150
and something tied to the offsite; a Tokyo-inspired experience or platform-strategy
book would fit…

Kill it, restart it

Ctrl+C the process, start again with the same namespace (and optional same id for the live session). Ask:

you: who's getting promoted?
assistant: Sarah — she's being promoted to VP of Product.

Nothing was reloaded from your process. Memory and docs live in supermemory.

Mental model

  INGEST                         WAIT                         RETRIEVE
  ──────                         ────                         ────────
  Conversation (id)         →    system.status === done  →    Memory graph (+ related)
  Document (id)             →    system.status === done  →    Document search (RAG)
                                                          →    Profile (static + dynamic)
                                                                   │
                                                                   ▼
                                                              Chat harness

Where next

Add context

Conversations, files, URLs, id updates, and status.

Search

Hybrid vs memories, filters, thresholds, rerank.

Graph memory

How relations and entity chains are produced.

User profiles

Static vs dynamic, and when to inject a profile every turn.

AI SDK

withSupermemory modes, id, addMemory.

Namespaces

Isolation for multi-tenant products.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Get an API key

1. Ingest a conversation

2. Ingest a document

3. Wait until both are `done`

4. Three ways to get context back

A. Document search (RAG)

B. Memory graph traversal

C. User profile

5. Put it in a harness

Example: explicit profile + search + add

Example: Vercel AI SDK

Kill it, restart it

Mental model

Where next

Add context

Search

Graph memory

User profiles

AI SDK

Namespaces

​Get an API key

​1. Ingest a conversation

​2. Ingest a document

​3. Wait until both are done

​4. Three ways to get context back

​A. Document search (RAG)

​B. Memory graph traversal

​C. User profile

​5. Put it in a harness

​Example: explicit profile + search + add

​Example: Vercel AI SDK

​Kill it, restart it

​Mental model

​Where next

Add context

Search

Graph memory

User profiles

AI SDK

Namespaces

Get an API key

1. Ingest a conversation

2. Ingest a document

3. Wait until both are `done`

4. Three ways to get context back

A. Document search (RAG)

B. Memory graph traversal

C. User profile

5. Put it in a harness

Example: explicit profile + search + add

Example: Vercel AI SDK

Kill it, restart it

Mental model

Where next