Ingesting context to supermemory - supermemory

Send any raw content to Supermemory — conversations, documents, files, URLs. We extract the memories automatically.

Use customId to identify your content (conversation ID, document ID, etc.). This enables updates and prevents duplicates.

Quick Start

TypeScript
Python
cURL

import Supermemory from 'supermemory';

const client = new Supermemory();

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

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

from supermemory import Supermemory

client = Supermemory()

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

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

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

Response:

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

Updating Content

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

Two ways to update:

Option 1: Send only the new content

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

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

Option 2: Send the full updated content

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

Both work — choose what fits your architecture.

Replace entire document

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

// Replace the entire document content
await client.documents.update("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.

TypeScript
Python
cURL

import fs from 'fs';

await client.documents.uploadFile({
  file: fs.createReadStream('document.pdf'),
  containerTags: 'user_123'
});

with open('document.pdf', 'rb') as file:
    client.documents.upload_file(
        file=file,
        container_tags='user_123'
    )

curl -X POST "https://api.supermemory.ai/v3/documents/file" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -F "file=@document.pdf" \
  -F "containerTags=user_123"

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

Parameters

Parameter	Type	Description
`content`	string	Required. Any raw content — text, conversations, URLs, HTML
`customId`	string	Recommended. Your ID for the content (conversation ID, doc ID). Enables updates and deduplication
`containerTag`	string	Group by user/project. Required for user profiles
`metadata`	object	Key-value pairs for filtering (strings, numbers, booleans)
`filterByMetadata`	object	Filter which existing memories are used as context during ingestion. See Filtered Writes
`entityContext`	string	Context for memory extraction on this container tag. Max 1500 chars. See Customization
`dreaming`	`"dynamic" \| "instant"`	Processing mode. Default `"dynamic"`. `"instant"` processes each document on its own and bills one extra operation. See Processing Modes

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" }

Container Tags:

// By user
{ containerTag: "user_123" }

// By project
{ containerTag: "project_alpha" }

// Hierarchical
{ containerTag: "org_456_team_backend" }

Custom IDs (Recommended):

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

// Updates: same customId = same document
// Supermemory only processes new/changed content
await client.add({
  content: "Updated content...",
  customId: "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

Entity Context:

// Guide memory extraction for this container tag
{
  containerTag: "session_abc123",
  entityContext: `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 container tag
Combines with org-level filter prompts

Processing Modes

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.
"instant" — processes each document on its own right away, and bills one extra operation per document.

{
  "content": "...",
  "dreaming": "instant"
}

Filtered Writes

By default, when you add content, Supermemory uses all existing memories in the space 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 space 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 client.add({
  content: "New research findings on transformer architectures...",
  containerTag: "user_123",
  metadata: { category: "ml", source: "arxiv" },
  filterByMetadata: { category: "ml" }
});

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

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

How it works

When filterByMetadata 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

`filterByMetadata` parameter

Key	Type	Description
`filterByMetadata`	`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 client.add({
  content: "...",
  containerTag: "user_123",
  filterByMetadata: {
    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 /v3/documents/{id}:

const doc = await client.documents.get("abc123");
console.log(doc.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 client.add({
        content: doc.content,
        customId: doc.id,
        containerTag: "batch_import"
      });
      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 customId to track and deduplicate

Error Handling

Status	Error	Cause
400	BadRequestError	Missing required fields, invalid parameters
401	AuthenticationError	Invalid or missing API key
403	PermissionDeniedError	Insufficient permissions
429	RateLimitError	Too many requests or quota exceeded
500	InternalServerError	Processing failure

import { BadRequestError, RateLimitError } from 'supermemory';

try {
  await client.add({ content: "..." });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait and retry
    await new Promise(r => setTimeout(r, 60000));
  } else if (error instanceof BadRequestError) {
    // Fix request parameters
    console.error("Invalid request:", error.message);
  }
}

Delete Content

Single delete:

await client.documents.delete("doc_id_123");

Bulk delete by IDs:

await client.documents.deleteBulk({
  ids: ["doc_1", "doc_2", "doc_3"]
});

Bulk delete by container tag:

// Delete all content for a user
await client.documents.deleteBulk({
  containerTags: ["user_123"]
});

Deletes are permanent — no recovery.

Next Steps

Search Memories — Query your content
User Profiles — Get user context
Organizing & Filtering — Container tags and metadata

​Quick Start

​Updating Content

​Two ways to update:

​Replace entire document

​Formatting conversations

​Upload Files

​Supported File Types

​Parameters

​Processing Modes

​Filtered Writes

​How it works

​filterByMetadata 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

Filtered Writes

How it works

`filterByMetadata` parameter

Processing Pipeline

Next Steps