> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory-capy-add-llmstxt-summary-and.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<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="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/key-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=019314c18131271c48490539c93e2d97" href="https://console.supermemory.ai" width="24" height="24" data-path="icons/hugeicons/key-01.svg">
    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="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/command-line.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=2866f2fa82dadec9828cc73418b7a679" href="/using-supermemory" width="24" height="24" data-path="icons/hugeicons/command-line.svg">
    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>
  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  // 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",
  });
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # pip install supermemory
  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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
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](/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 document. Bills one extra [operation](/overview/billing) per document. | Demos, quickstarts, “I need the graph now” |

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// 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](/quickstart).

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

## Isolation and identity

* **`containerTag`** — hard isolation boundary (user, tenant, project). See [Container tags](/concepts/container-tags).
* **Metadata**: extra dimensions inside a tag that you can filter on. 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="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/share-08.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=f5d3315d16f25fff9e40c16cb3ffbb0f" href="/concepts/graph-memory" width="24" height="24" data-path="icons/hugeicons/share-08.svg">
    How facts connect, update, and stay true over time.
  </Card>

  <Card title="Multi-modal ingestion" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/files-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=4068c30ab93f27c80decaedcd1ee2efe" href="/concepts/content-types" width="24" height="24" data-path="icons/hugeicons/files-01.svg">
    Formats, extractors, and what you can send.
  </Card>

  <Card title="Add context" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/plus-sign.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=e61184a2a5a45db092cdb1945c0c97c0" href="/ingestion/add-memories" width="24" height="24" data-path="icons/hugeicons/plus-sign.svg">
    API: add, customId, files, dreaming, status.
  </Card>

  <Card title="Search API" icon="https://mintcdn.com/supermemory-capy-add-llmstxt-summary-and/LIMkcglt81IfjBVR/icons/hugeicons/search-01.svg?fit=max&auto=format&n=LIMkcglt81IfjBVR&q=85&s=c99db8ae4145ac800d41acbbbb254aba" href="/recall/search" width="24" height="24" data-path="icons/hugeicons/search-01.svg">
    Query documents and memories after the pipeline finishes.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.