Ingesting context to supermemory

Send any raw content to Supermemory — conversations, documents, files, URLs. We extract the memories automatically. Pass id to identify content and avoid duplicates, and taskType: "superrag" if you just need it searchable, not remembered — that’s 5x cheaper per token. Every write goes to one namespace (what v3/v4 called a container tag). The namespace sits in the URL path, never in the body.

Quick start

TypeScript
Python
cURL

import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY });

// Add text content
await supermemory.add("user_123", {
  content: "Machine learning enables computers to learn from data",
  metadata: { category: "ai" },
});

// Add a URL (auto-extracted)
await supermemory.add("user_123", {
  content: "https://youtube.com/watch?v=dQw4w9WgXcQ"
});

from supermemory import Supermemory

client = Supermemory()

# Add text content
client.add(
    "user_123",
    content="Machine learning enables computers to learn from data",
    metadata={"category": "ai"},
)

# Add a URL (auto-extracted)
client.add("user_123", content="https://youtube.com/watch?v=dQw4w9WgXcQ")

curl -X POST "https://api.supermemory.ai/ns/user_123/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Machine learning enables computers to learn from data",
    "metadata": {"category": "ai"}
  }'

Response:

{ "id": "abc123", "status": "queued" }

If an irrecoverable processing error occurs, the document is automatically deleted after 2 minutes.

Updating content

Use id to update existing documents or conversations. When you send content with the same id, Supermemory intelligently processes only what’s new.

Two ways to update:

Option 1: Send only the new content

// First request
await supermemory.add("user_sarah", {
  content: "user: Hi, I'm Sarah.\nassistant: Nice to meet you!",
  id: "conv_123",
});

// Later: send only new messages
await supermemory.add("user_sarah", {
  content: "user: What's the weather?\nassistant: It's sunny today.",
  id: "conv_123", // Same ID — Supermemory links them
});

Option 2: Send the full updated content

// Supermemory detects the diff and only processes new parts
await supermemory.add("user_sarah", {
  content: "user: Hi, I'm Sarah.\nassistant: Nice to meet you!\nuser: What's the weather?\nassistant: It's sunny today.",
  id: "conv_123",
});

Both work — choose what fits your architecture.

Replace entire document

To completely replace a document’s content (not append), use documents.update():

// Replace the entire document content
await supermemory.documents.update("user_sarah", "doc_id_123", {
  content: "Completely new content replacing everything",
  metadata: { version: 2 },
});

This triggers full reprocessing of the document. If you only update metadata (no content change), the document is updated in place with no reindexing.

Formatting conversations

Format your conversations however you want. Supermemory handles any string format:

// Simple string
content: "user: Hello\nassistant: Hi there!"

// JSON stringify
content: JSON.stringify(messages)

// Template literal
content: messages.map(m => `${m.role}: ${m.content}`).join('\n')

// Any format — just make it a string
content: formatConversation(messages)

Upload files

Upload PDFs, images, and documents directly. This is a multipart request, so metadata is a JSON string here, not an object.

TypeScript
Python
cURL

import { openAsBlob } from "node:fs";

await supermemory.documents.uploadFile("user_123", {
  file: await openAsBlob("document.pdf"),
  metadata: JSON.stringify({ source: "upload" }),
});

import json

with open("document.pdf", "rb") as file:
    client.documents.upload_file(
        "user_123",
        file=file,
        metadata=json.dumps({"source": "upload"}),
    )

curl -X POST "https://api.supermemory.ai/ns/user_123/document/file" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -F "file=@document.pdf" \
  -F 'metadata={"source":"upload"}'

Supported file types

Type	Formats	Processing
Documents	PDF, DOC, DOCX, TXT, MD	Text extraction, OCR for scans
Images	JPG, PNG, GIF, WebP	OCR text extraction
Spreadsheets	CSV, Google Sheets	Structured data extraction
Videos	YouTube URLs, MP4	Auto-transcription

Limits: 50MB max file size

Scale and Enterprise include advanced document extraction for PDFs, with page-by-page OCR and descriptions of figures and diagrams. It is selected automatically from your organization’s plan; no extra upload parameter is needed. Free, Pro, and Max keep standard PDF extraction, including OCR for scans.

Parameters

namespace, taskType, and dreaming are top-level keys on the SDK call (taskType and dreaming are query parameters on the HTTP route). Everything else goes in body.

Parameter	Type	Description
`namespace`	string	Required. Group by user/project. Goes in the URL path. Required for user profiles
`content`	string	Required. Any raw content — text, conversations, URLs, HTML
`id`	string	Recommended. Your ID for the content (conversation ID, doc ID). Enables updates and deduplication. The response `id` echoes it back
`metadata`	object	Key-value pairs for filtering (strings, numbers, booleans)
`group`	object	Filter which existing memories are used as context during ingestion. See Filtered Writes
`supportingContext`	string	Context for memory extraction on this namespace. Max 1500 chars. See Customization
`date`	string	ISO 8601 date the content was originally created. Use when backfilling. See Backfill historical data
`dreaming`	`"dynamic" \| "instant"`	Processing mode. Default `"dynamic"`. `"instant"` processes each document on its own and bills one extra operation. See Processing Modes
`taskType`	`"memory" \| "superrag"`	Pipeline to run. Default `"memory"`. `"superrag"` skips fact extraction and profile updates, doing only chunk/embed/index — at 5x cheaper per token. See SuperRAG ingestion

Parameter details & examples

Content Types:

// Any text — conversations, notes, documents
{ content: "Meeting notes from today's standup" }
{ content: JSON.stringify(messages) }

// URLs (auto-detected and extracted)
{ content: "https://example.com/article" }
{ content: "https://youtube.com/watch?v=abc123" }

// Markdown, HTML, or any format
{ content: "# Project Docs\n\n## Features\n- Real-time sync" }

Namespaces:

// By user
{ namespace: "user_123" }

// By project
{ namespace: "project_alpha" }

// Hierarchical
{ namespace: "org_456_team_backend" }

IDs (Recommended):

// Use IDs from your system
{ id: "conv_abc123" }        // Conversation ID
{ id: "doc_456" }            // Document ID
{ id: "thread_789" }         // Thread ID
{ id: "meeting_2024_01_15" } // Meeting ID

// Updates: same id = same document
// Supermemory only processes new/changed content
await supermemory.add("user_123", {
  content: "Updated content...",
  id: "doc_456", // Links to existing document
});

Metadata:

{
  metadata: {
    source: "slack",
    author: "john",
    priority: 1,
    reviewed: true
  }
}

No nested objects or arrays
Values: string, number, or boolean only

Supporting Context:

// Guide memory extraction for this namespace
await supermemory.add("session_abc123", {
  content: "...",
  supportingContext: `Design exploration conversation between john@acme.com and Brand.ai assistant.
    Focus on John's design preferences and brand requirements.`,
});

Max 1500 characters
Persists on the namespace
Combines with org-level organizational context

Processing modes

Dreaming: dynamic vs instant

The dreaming parameter controls how Supermemory turns a document into memories.

"dynamic" (default) — groups related documents together so memories form from coherent, logical units rather than one isolated entry at a time. A fresh namespace can show zero memories and an empty profile for several minutes.
"instant" — processes each document on its own right away, and bills one extra operation per document. Use it for quickstarts, tests, and any flow that reads memories or a profile right after add.

await supermemory.add("user_123", {
  content: "...",
  dreaming: "instant",
});

Memory vs SuperRAG ingestion

The taskType parameter controls whether that content also feeds the memory pipeline.

"memory" (default) — chunks/embeds for search and extracts facts, updates the user’s profile, and links into the graph.
"superrag" — chunks/embeds for search only. No fact extraction, no profile updates. Priced at 5x cheaper per token than "memory".

await supermemory.add("user_123", {
  content: "...",
  taskType: "superrag",
});

Use "superrag" for reference material you want searchable but that shouldn’t shape what Supermemory knows about a user. Full explanation: SuperRAG → Ingesting as pure SuperRAG.

Filtered writes

By default, when you add content, Supermemory uses all existing memories in the namespace as context for generating new memories. With filtered writes, you can scope this context to only memories from documents matching specific metadata. This is useful when you have many documents in a namespace but want new memories to build on top of a specific subset — for example, only memories from a particular source, category, or user.

The metadata itself is still written to the document, but the memories will only be built on top of what’s already there matching the filter.

TypeScript
Python
cURL

await supermemory.add("user_123", {
  content: "New research findings on transformer architectures...",
  metadata: { category: "ml", source: "arxiv" },
  group: { category: "ml" },
});

client.add(
    "user_123",
    content="New research findings on transformer architectures...",
    metadata={"category": "ml", "source": "arxiv"},
    group={"category": "ml"},
)

curl -X POST "https://api.supermemory.ai/ns/user_123/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New research findings on transformer architectures...",
    "metadata": {"category": "ml", "source": "arxiv"},
    "group": {"category": "ml"}
  }'

How it works

When group is provided:

Profile memories (static context) are filtered to only those from documents matching the metadata
Similar memories used as context during ingestion are filtered the same way
The new document’s own metadata is written normally — the filter only affects which existing memories are used as context

`group` parameter

Key	Type	Description
`group`	`Record<string, string \| number \| boolean \| string[]>`	Key-value pairs to filter existing memories by their source document metadata

Scalar values (string, number, boolean) match exactly
Array values match if any value in the array matches (OR logic)
Multiple keys are combined with AND logic

// Match documents where category is "ml" AND source is either "arxiv" or "pubmed"
await supermemory.add("user_123", {
  content: "...",
  group: {
    category: "ml",
    source: ["arxiv", "pubmed"],
  },
});

Processing pipeline

When you add content, Supermemory:

Validates your request
Stores the document and queues for processing
Extracts content (OCR, transcription, web scraping)
Chunks into searchable memories
Embeds for vector search
Indexes for retrieval

Track progress with GET /ns/{namespace}/document/{id}:

const doc = await supermemory.documents.get("user_123", "abc123");
console.log(doc.system.status); // "queued" | "processing" | "done"

Batch upload

Process multiple documents with rate limiting:

async function batchUpload(documents: Array<{id: string, content: string}>) {
  const results = [];

  for (const doc of documents) {
    try {
      const result = await supermemory.add("batch_import", {
        content: doc.content,
        id: doc.id,
      });
      results.push({ id: doc.id, success: true, docId: result.id });
    } catch (error) {
      results.push({ id: doc.id, success: false, error });
    }

    // Rate limit: 1 second between requests
    await new Promise(r => setTimeout(r, 1000));
  }

  return results;
}

Tips:

Batch size: 3-5 documents at once
Delay: 1-2 seconds between requests
Use id to track and deduplicate
For large backfills use documents.batchAdd instead. See Backfill historical data

Error handling

Status	Error	Cause
400	Bad request	Missing required fields, invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
429	Rate limited	Too many requests or quota exceeded
500	Internal error	Processing failure

try {
  await supermemory.add("user_123", { content: "..." });
} catch (error) {
  // Back off on 429, fix the request on 400, retry later on 5xx
  console.error("add failed:", error);
}

Delete Content

Delete by IDs (one or many, Supermemory or your own ids):

const { count, errors } = await supermemory.documents.delete("user_123", {
  ids: ["doc_1", "doc_2", "doc_3"],
});

Delete everything in a namespace:

// Delete all content for a user
await supermemory.namespaces.delete("user_123");

Deletes are permanent — no recovery.

Next steps

How to backfill historical data — Import dated content with the batch API
Search Memories — Query your content
User Profiles — Get user context
Organizing & Filtering — Namespaces and metadata

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Quick start

Updating content

Two ways to update:

Replace entire document

Formatting conversations

Upload files

Supported file types

Parameters

Processing modes

Dreaming: dynamic vs instant

Memory vs SuperRAG ingestion

Filtered writes

How it works

`group` parameter

Processing pipeline

Next steps

​Quick start

​Updating content

​Two ways to update:

​Replace entire document

​Formatting conversations

​Upload files

​Supported file types

​Parameters

​Processing modes

​Dreaming: dynamic vs instant

​Memory vs SuperRAG ingestion

​Filtered writes

​How it works

​group parameter

​Processing pipeline

​Next steps

Quick start

Updating content

Two ways to update:

Replace entire document

Formatting conversations

Upload files

Supported file types

Parameters

Processing modes

Dreaming: dynamic vs instant

Memory vs SuperRAG ingestion

Filtered writes

How it works

`group` parameter

Processing pipeline

Next steps