> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-vorflux-slack-workspace-override-consent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Supermemory Works

> From a file or chat turn to something you can search — the ingest pipeline, statuses, and outputs.

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

<CardGroup cols={2}>
  <Card title="Learning model">
    Decides what and how to learn, what is important, when to forget, creating relations, etc.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

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

<CardGroup cols={2}>
  <Card title="1. Get an API key" icon="key" href="https://console.supermemory.ai">
    From the [developer console](https://console.supermemory.ai) — **API Keys → Create API Key**. `console.supermemory.ai` is where keys and usage live.
  </Card>

  <Card title="2. Use it" icon="terminal" href="/using-supermemory">
    Install the SDK, drop in your key, add a memory, and search it — right below, or the full [ingest → retrieve loop](/using-supermemory).
  </Card>
</CardGroup>

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install supermemory
  ```

  ```typescript TypeScript theme={null}
  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",
  });
  ```

  ```python Python theme={null}
  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",
  )
  ```

  ```bash curl theme={null}
  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"
    }'
  ```
</CodeGroup>

## 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](/concepts/content-types) for formats, and [Add context](/ingestion/add-memories) 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](/overview/billing#full-discount-on-already-seen-tokens-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                      |

```typescript theme={null}
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](/ingestion/add-memories):

| 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](/overview/billing)** per document.                                           | Demos, quickstarts, “I need the graph now”      |

```typescript theme={null}
// 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](/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](/concepts/graph-memory). API detail: [Processing modes](/ingestion/add-memories#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](/concepts/super-rag), [Search API](/recall/search)             |
| **Memories**        | Extracted facts in a living graph — updates, links, time             | [Graph memory](/concepts/graph-memory)                                    |
| **Profile**         | A sample of memories, static + dynamic summary for always-on context | [Profiles](/concepts/user-profiles), [Profile API](/recall/user-profiles) |

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](/concepts/memory-vs-rag).

## Isolation and identity

* **`containerTag`** — hard isolation boundary (user, tenant, project). See [Container tags](/concepts/container-tags).
* **Metadata** — soft dimensions *inside* a tag for filtering. See [Metadata filtering](/concepts/filtering).
* **Scoped API keys** — credentials that cannot cross a container. See [API keys](/authentication#scoped-api-keys).

## Next steps

<CardGroup cols={2}>
  <Card title="Graph memory" icon="vector-square" href="/concepts/graph-memory">
    How facts connect, update, and stay true over time.
  </Card>

  <Card title="Multi-modal ingestion" icon="file-stack" href="/concepts/content-types">
    Formats, extractors, and what you can send.
  </Card>

  <Card title="Add context" icon="plus" href="/ingestion/add-memories">
    API: add, customId, files, dreaming, status.
  </Card>

  <Card title="Search API" icon="search" href="/recall/search">
    Query documents and memories after the pipeline finishes.
  </Card>
</CardGroup>