supermemory Documentation

Include your key in all requests:

curl -X POST https://api.supermemory.ai/ns/user_123/search \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{"query": "hello"}'

import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: "YOUR_API_KEY" });

from supermemory import Supermemory

client = Supermemory(api_key="YOUR_API_KEY")

Connector branding Copy Chapter

When users connect external services (Google Drive, Notion, OneDrive), they see a "Log in to Supermemory" prompt by default. You can replace this with your own app name by providing your own OAuth credentials.

This works for Google Drive, Notion, and OneDrive. See the full setup in Customization.

Scoped API keys Copy Chapter

Scoped keys are restricted to one namespace (what v3/v4 called a container tag), or to a fixed list of namespaces. They can read and write content only inside those namespaces, subject to the key's read/write permission and member restrictions — use them to give a client, session, or tenant limited access without shipping your org master key.

Pairs with namespaces for multi-tenant isolation.

Allowed endpoints: /ns/{namespace}/document, /ns/{namespace}/list, /ns/{namespace}/search, /ns/{namespace}/profile, and /ns/{namespace}/memories; /namespaces and /ns/{namespace}; and the legacy /v3/documents, /v3/memories, /v4/memories, /v4/conversations, /v3/search, /v4/search, /v4/profile, /v3/container-tags/list, and /v3/session routes. Any other route returns 403.

Scoped keys cannot read billing, manage org settings, or mint further keys.

Create a scoped key Copy Section

The scoped-key endpoint still takes the namespace in a field named containerTag.

curl https://api.supermemory.ai/v3/auth/scoped-key \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "containerTag": "my-project",
    "name": "my-key-name",
    "expiresInDays": 30
  }'

Parameters Copy Section

Response Copy Section

{
  "key": "sm_orgId_...",
  "id": "key-id",
  "name": "scoped_my-project",
  "containerTag": "my-project",
  "containerTags": ["my-project"],
  "expiresAt": "2026-03-08T00:00:00.000Z",
  "allowedEndpoints": ["/v3/session", "/v3/documents", "/v3/memories", "/v4/memories", "/v4/conversations", "/ns/*/memories", "/v3/search", "/v4/search", "/v4/profile", "/v3/container-tags/list", "/ns/*/document", "/ns/*/list", "/ns/*/search", "/ns/*/profile", "/namespaces$", "/ns$", "/ns/*$"]
}

Use the returned key like a normal API key — it just will not work outside its namespace.

Disable a scoped key Copy Section

Revoke with the id from creation. Subsequent requests get 401. Memories and namespaces are not deleted.

curl https://api.supermemory.ai/v3/auth/scoped-key/KEY_ID \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_API_KEY'

{ "success": true }

Apps Docs Install (`apps/docs/install.md`) Copy Section

You are integrating Supermemory into my application. Supermemory provides user memory, semantic search, and automatic knowledge extraction for AI applications.

You can always reference the documentation by using the SearchSupermemoryDocs MCP or running a web search tool for content on supermemory.ai/docs.

STEP 1: ASK ME THESE QUESTIONS Copy Chapter

1. What are you building?

   • Personal chatbot/assistant
   • Team knowledge base
   • Customer support bot
   • Document Q&A
   • Other

2. How do you want to integrate?

   • Vercel AI SDK (@supermemory/tools)
   • OpenAI plugins
   • Direct SDK (supermemory npm/pip)
   • Direct API calls

3. Data model?

   • Individual users only → containerTag: userId
   • Organizations only → containerTag: orgId
   • Both users AND orgs → ask for strategy

4. Do you want USER PROFILES?
   User profiles are automatically-maintained facts about users (what they like, what they're working on, preferences).

   • Yes (RECOMMENDED) → Use client.profile() to get context
   • No → Just use search

5. How should I retrieve context?

   • OPTION A: One call with search included → profile({ containerTag, q: userMessage })
   • OPTION B: Separate calls → profile() for facts, search() for memories

STEP 2: INSTALL Copy Chapter

# Get API key: https://console.supermemory.ai
npm install supermemory  # or: pip install supermemory
# For Vercel AI SDK: npm install @supermemory/tools
export SUPERMEMORY_API_KEY="sm_..."

STEP 3: CONFIGURE SETTINGS (DO THIS FIRST) Copy Chapter

// PATCH https://api.supermemory.ai/v3/settings
fetch('https://api.supermemory.ai/v3/settings', {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    shouldLLMFilter: true,
    filterPrompt: `This is a [your app description]. containerTag is [userId/orgId]. We store [what data].`
  })
})

STEP 4: CONTAINER TAG STRATEGY Copy Chapter

Based on their data model answer:

USER-ONLY APP:

containerTag: userId

ORG-ONLY APP:

containerTag: orgId  // Org members share memories

BOTH (ask which):

// Option A: Unique per user-org combination
containerTag: `${userId}-${orgId}`

// Option B: Org-scoped with user metadata
containerTag: orgId, metadata: { userId }

// Option C: User-scoped with org metadata
containerTag: userId, metadata: { orgId }

STEP 5: INTEGRATION CODE Copy Chapter

Based on their integration choice:

VERCEL AI SDK Copy Section

import { streamText } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'
import { supermemoryTools } from '@supermemory/tools/ai-sdk'

// Option 1: Agent tools (recommended for agentic flows)
const result = await streamText({
  model: anthropic('claude-3-5-sonnet-20241022'),
  prompt: userMessage,
  tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY, {
    containerTags: [userId]
  })
})
// Agent gets searchMemories, addMemory, fetchMemory tools

// Option 2: Profile middleware (automatic context injection)
import { withSupermemory } from '@supermemory/tools/ai-sdk'
const modelWithMemory = withSupermemory(anthropic('claude-3-5-sonnet-20241022'), {
  containerTag: userId,
  customId: 'conversation-1',
})

const result = await generateText({
  model: modelWithMemory,
  messages: [{ role: 'user', content: userMessage }]
})
// Profile is automatically injected into context

DIRECT SDK (WITH PROFILES) Copy Section

import Supermemory from 'supermemory'

const client = new Supermemory()

// Before each LLM call:
const { profile, searchResults } = await client.profile({
  containerTag: userId,
  q: userMessage  // Include this if they chose OPTION A (one call)
                  // Omit if they chose OPTION B (separate calls)
})

// Build context
const context = `
Static facts: ${profile.static.join('\n')}
Recent context: ${profile.dynamic.join('\n')}
${searchResults ? `Memories: ${searchResults.results.map(r => r.content).join('\n')}` : ''}
`

// Send to LLM
const messages = [
  { role: 'system', content: `User context:\n${context}` },
  { role: 'user', content: userMessage }
]

// After LLM responds:
await client.memories.add({
  content: `user: ${userMessage}\nassistant: ${response}`,
  containerTag: userId
})

DIRECT SDK (NO PROFILES) Copy Section

import Supermemory from 'supermemory'

const client = new Supermemory()

// Search for relevant memories
const results = await client.search({
  q: userMessage,
  containerTag: userId,
  searchMode: 'hybrid',  // Searches memories + document chunks
  limit: 5
})

// Build context
const context = results.results.map(r => r.content).join('\n')

// Send to LLM with context
const messages = [
  { role: 'system', content: `Relevant context:\n${context}` },
  { role: 'user', content: userMessage }
]

// Store the conversation
await client.memories.add({
  content: `user: ${userMessage}\nassistant: ${response}`,
  containerTag: userId
})

PYTHON VERSION Copy Section

from supermemory import Supermemory

client = Supermemory()

# With profiles (if they want it)
profile_data = client.profile(
    container_tag=user_id,
    q=user_message  # Include if OPTION A, omit if OPTION B
)

context = f"""
Static: {chr(10).join(profile_data.profile.static)}
Dynamic: {chr(10).join(profile_data.profile.dynamic)}
"""

# Store conversation
client.add(content=f"user: {user_message}\\nassistant: {response}", container_tag=user_id)

DIRECT API Copy Section

# Add memory
curl -X POST https://api.supermemory.ai/v3/documents \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "conversation", "containerTag": "userId"}'

# Get profile
curl -X POST https://api.supermemory.ai/v4/profile \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"containerTag": "userId", "q": "search query"}'

# Search
curl -X POST https://api.supermemory.ai/v4/search \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "query", "containerTag": "userId", "searchMode": "hybrid"}'

STEP 6: FILE UPLOADS (if they need it) Copy Chapter

// Files are automatically extracted (PDFs, images with OCR, videos with transcription)
const formData = new FormData()
formData.append('file', fileBlob)
formData.append('containerTag', userId)

await fetch('https://api.supermemory.ai/v3/documents/file', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: formData
})

// Processing is async - check status before assuming searchable
// GET /v3/documents/{documentId}

STEP 7: SEARCH MODES Copy Chapter

// HYBRID (recommended) - searches memories + document chunks
searchMode: 'hybrid'

// MEMORIES ONLY - just extracted memories, no original text
searchMode: 'memories'

STEP 8: METADATA FILTERS (if they need secondary filtering) Copy Chapter

await client.search({
  q: query,
  containerTag: userId,
  filters: {
    AND: [
      { key: 'type', value: 'conversation', type: 'string_equal' },
      { key: 'timestamp', value: '2024', type: 'string_contains' }
    ]
  }
})

KEY POINTS: Copy Chapter

1. Configure settings FIRST with filterPrompt
2. User profiles = automatic facts about users (profile.static + profile.dynamic)
3. profile({ containerTag, q }) combines profile + search in ONE call
4. Search modes: 'hybrid' (recommended) or 'memories'
5. File extraction is automatic - no config needed
6. Store conversations after each interaction
7. containerTag should match what you put in filterPrompt

TESTING: Copy Chapter

# 1. Configure settings
curl -X PATCH https://api.supermemory.ai/v3/settings \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shouldLLMFilter": true, "filterPrompt": "..."}'

# 2. Add test memory
curl -X POST https://api.supermemory.ai/v3/documents \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test", "containerTag": "test_user"}'

# 3. Get profile
curl -X POST https://api.supermemory.ai/v4/profile \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"containerTag": "test_user"}'

NOW: Copy Chapter

1. Ask me the 5 questions above
2. Generate complete working code based on my answers
3. Include installation, settings config, and full integration

DOCS: https://supermemory.ai/docs

Apps Docs Invite Team Members (`apps/docs/invite-team-members.mdx`) Copy Section

title: "Invite team members" sidebarTitle: "Invite Team Members" contentType: "How-to" icon: "/icons/hugeicons/user-multiple.svg" Copy Chapter

Invite colleagues from the Supermemory console so they can access your organization’s workspace. Choose their role and access, then share an invitation link they can accept with their own account.

Before you begin Copy Chapter

Check these requirements before you invite someone:

• You’re an Owner or Admin in the organization.
• Your organization has a plan that supports team invitations. Pro and higher include this feature.
• You have an available member seat. Members and unexpired pending invitations count toward your limit.
• You know the email address your colleague uses to sign in to Supermemory.

If Invite member is disabled, hover over it to check the plan or member limit. Open Billing to upgrade if needed.

Create and share an invitation Copy Chapter

Create the invitation in the organization your colleague needs to join:

<Frame caption="Team settings lists members and pending invitations. This screenshot uses a local Acme demo organization.">
  
</Frame>

- **Member**: Use this role for workspace access without team or billing administration.
- **Admin**: Use this role for full access, including members, billing, and settings.

For a **Member**, keep **Full access** to include all containers. On Scale or Enterprise, choose **Restricted** to limit access to selected [container tags](/concepts/container-tags). Add at least one tag and select **Read** or **Write** for each tag.

<Frame caption="The Invite member dialog defaults to Member and Full access.">
  
</Frame>

The invitation expires after seven days. To cancel it, click the **×** at the end of its row.

Accept the invitation Copy Chapter

Ask your colleague to complete these steps:

1. Open the invitation link you shared.
2. Log in or create an account with the email address you invited.
3. Check the organization name and role, then click ACCEPT.

If they see This invitation is not for you, ask them to click LOG IN WITH A DIFFERENT ACCOUNT. They need to sign in with the invited email address. If the invitation has expired or you canceled it, create a new invitation and share its new link.

Return to Settings → Team and confirm your colleague appears under Members. Their invitation no longer appears under Pending invitations after they accept.

Apps Docs Using Supermemory (`apps/docs/using-supermemory.mdx`) Copy Section

title: "Using Supermemory" sidebarTitle: "Overview" icon: "/icons/hugeicons/compass-01.svg" Copy Chapter

import { Journey, JourneyStep, JourneyItem } from "/snippets/journey.mdx";

Everything in this section is one of four steps. Same loop whether you're building personal memory, RAG over docs, or both on the same namespace.

Raw input automatically becomes memories (the knowledge graph) and indexed document chunks (for RAG). You don't choose one or the other; both come from the same write. Retrieval then gives you three ways to read that pool back. If you're unsure which fits, read Memory vs RAG.

Where next Copy Chapter

Apps Docs Api Reference Connections (`apps/docs/api-reference/connections.mdx`) Copy Section

title: "Connections" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

Connections pull content from Notion, Google Drive, Gmail, OneDrive, S3, GitHub, and more.

Guides: Connectors overview · provider pages under Connectors

Apps Docs Api Reference Container Tags (`apps/docs/api-reference/container-tags.mdx`) Copy Section

title: "Container tags" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

containerTag is the primary multi-tenant key (user id, workspace id, etc.). These endpoints manage settings and lifecycle for a tag.

Guide: Container tags · Filtering

Apps Docs Api Reference Documents (`apps/docs/api-reference/documents.mdx`) Copy Section

title: "Documents" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

Documents are the unit of ingestion. Adds return immediately with status: "queued"; poll until done before relying on search or profiles.

Guide: Document operations

Apps Docs Api Reference Ingest (`apps/docs/api-reference/ingest.mdx`) Copy Section

title: "Ingest" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

Send raw content into the processing pipeline. Supermemory extracts memories, chunks for RAG, and updates profiles asynchronously.

Guides: Add memories · Quickstart

Apps Docs Api Reference Memories (`apps/docs/api-reference/memories.mdx`) Copy Section

title: "Memories" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

These endpoints operate on extracted memories, not raw documents.

For document-level CRUD, use Documents. For pipeline ingest, use Ingest.

Guide: Memory operations

Apps Docs Api Reference Profiles (`apps/docs/api-reference/profiles.mdx`) Copy Section

title: "Profiles" sidebarTitle: "Profiles overview" icon: "/icons/hugeicons/id.svg" Copy Chapter

Profiles summarize what Supermemory knows about a user or entity in a containerTag.

Guides: User profiles API · Concepts · Buckets

Apps Docs Api Reference Search (`apps/docs/api-reference/search.mdx`) Copy Section

title: "Recall" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

Get context back out of Supermemory: search extracted memories / documents, or fetch a user profile.

Prefer v4 with searchMode: "hybrid" unless you only need document chunks or only extracted memories.

Guides: Search · User profiles · SuperRAG · Memory vs RAG

Apps Docs Api Reference Settings (`apps/docs/api-reference/settings.mdx`) Copy Section

title: "Settings" sidebarTitle: "Overview" icon: "/icons/hugeicons/book-open-01.svg" Copy Chapter

Org-level configuration for extraction, customization, and profile buckets.

Guide: Customization

Apps Docs Concepts Container Tags (`apps/docs/concepts/container-tags.mdx`) Copy Section

title: "Namespaces" sidebarTitle: "Namespaces" icon: "/icons/hugeicons/folder-01.svg" keywords: ["container tag", "container tags", "containerTag", "containerTags", "namespace"] Copy Chapter

A namespace is the primary way you organize and isolate memories in Supermemory. It is a string identifier you choose, and it scopes every call: add, search, list, update, and delete all happen inside one namespace.

Every memory in user_alex lives in its own isolated space, completely separate from memories in user_jordan. This is what makes Supermemory safe to use in multi-tenant applications: one user can never see another user's memories unless you explicitly query both namespaces.

How it works Copy Chapter

When you add a document to a namespace, Supermemory creates that namespace (scoped to your organization) if it does not exist yet. You don't need to provision anything ahead of time. The first write to a new namespace creates it, and later writes reuse it.

import { Supermemory } from "supermemory";

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

// First call auto-creates the "user_alex" namespace
await supermemory.add("user_alex", {
  content: "Alex prefers dark mode and concise answers",
});

// Later, retrieve only Alex's memories
const results = await supermemory.search("user_alex", {
  query: "what are the user's UI preferences?",
});

curl -X POST "https://api.supermemory.ai/ns/user_alex/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Alex prefers dark mode and concise answers" }'

curl -X POST "https://api.supermemory.ai/ns/user_alex/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what are the user'\''s UI preferences?" }'

Under the hood, each namespace is backed by a dedicated vector index. Embeddings, chunks, and memory entries for one namespace are stored and searched independently of every other namespace. There is no shared index to filter through, which is why isolation is strict rather than best-effort.

Naming rules Copy Chapter

Namespaces are validated on every request. A namespace must:

• Be 100 characters or less
• Contain only alphanumeric characters, hyphens (-), underscores (_), and colons (:)

Matching pattern: ^[a-zA-Z0-9_:-]+$

// ✅ Valid
"user_123"
"project-mobile-app"
"org:acme:user:john"
"tenant_42_workspace_7"

// ❌ Invalid — spaces, slashes, and other symbols are rejected
"user 123"
"project/mobile"
"team@acme"

The colon is intentionally allowed so you can build hierarchical namespaces (for example org:acme:user:john) that encode several levels of structure in a single identifier.

Scope lives in the URL Copy Chapter

In v5 the namespace is a path segment, not a body field. Every scoped endpoint starts with /ns/{namespace}/, and every scoped SDK call takes namespace as its first argument.

Where namespaces are used Copy Chapter

The same namespace flows through the entire lifecycle of a memory. Pass it consistently and your data stays neatly partitioned.

// Add
await supermemory.add("project_q1", { content: "Q1 planning notes" });

// Search within the same namespace
await supermemory.search("project_q1", { query: "planning" });

// List every document in the namespace
await supermemory.list("project_q1", "documents");

Access control Copy Chapter

Namespaces are also an authorization boundary, not just an organizational one. Two mechanisms can restrict which namespaces a given caller may touch:

• API key scopes — an API key can be limited to a specific set of namespaces, and a key can be read-only.
• Member restrictions — an organization member can be granted access to only certain namespaces, with read or write permission per namespace.

When a request is restricted, Supermemory validates the namespace in the URL against the caller's allowed set:

• Requesting a namespace outside the allowed set returns 403 Forbidden.
• A write (add/update/delete) to a read-only namespace returns 403 Forbidden.

This means you can hand out an API key that is physically incapable of reading or writing another tenant's data, enforced at the data layer rather than in your application code.

Managing namespaces Copy Chapter

The namespaces.* SDK methods read and change a namespace itself, as opposed to the documents inside it.

supportingContext is what v3/v4 called entityContext. The legacy "merge" operation is now a delete with moveTo, one source namespace per request.

Namespace deletion and moves require an org admin or owner with write access to the source namespace; moves also require write access to the destination. The default sm_project_default namespace cannot be permanently deleted. See deletion scope and erasure limits.

await supermemory.namespaces.update("project_research", {
  supportingContext: "This project contains research papers about machine learning.",
});

const { namespaces, pagination } = await supermemory.namespaces.list();
// namespaces: [{ id, namespace, documentCount, memoryCount, description, system }]

// Consolidate: move everything from the old namespace, then remove it
await supermemory.namespaces.delete("project_research_old", {
  moveTo: "project_research",
});
// { status: "queued", operationId, namespace, moveTo }

curl -X PATCH "https://api.supermemory.ai/ns/project_research" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "supportingContext": "This project contains research papers about machine learning." }'

curl "https://api.supermemory.ai/namespaces" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

curl -X DELETE "https://api.supermemory.ai/ns/project_research_old?moveTo=project_research" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Choosing a convention Copy Chapter

Pick a naming scheme that maps onto the isolation boundaries your application actually needs.

Next steps Copy Chapter

Apps Docs Concepts Content Types (`apps/docs/concepts/content-types.mdx`) Copy Section

title: "Supported content types" sidebarTitle: "Multi-modal ingestion" icon: "/icons/hugeicons/files-01.svg" Copy Chapter

Supermemory automatically extracts and indexes content from various formats. There are two entry points: supermemory.add() for text and URLs, supermemory.documents.uploadFile() for actual files. Both take the target namespace as the first argument. See Add Memories to learn how to ingest content via the API.

Text content Copy Chapter

Raw text, conversations, notes, or any string content.

await supermemory.add("user_123", {
  content: "User prefers dark mode and uses vim keybindings",
});

Best for: Chat messages, user preferences, notes, logs, transcripts.

URLs & Web pages Copy Chapter

Send a URL and Supermemory fetches, extracts, and indexes the content.

await supermemory.add("documentation", {
  content: "https://docs.example.com/api-reference"
});

Extracts: Article text, headings, metadata. Strips navigation, ads, boilerplate.

Documents Copy Chapter

PDF Copy Section

Files are binary, so they go through uploadFile, not add — pass a stream, not base64. The upload is multipart, so metadata is a JSON string here:

import fs from 'fs';

await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('report.pdf'),
  metadata: JSON.stringify({ title: "Q4 Financial Report" }),
});

Extracts: Text, tables, headers. OCR for scanned documents.

Advanced document extraction

Scale and Enterprise include advanced extraction for PDFs: page-by-page OCR with descriptions of figures and diagrams merged into the extracted text. This helps make the visual content in reports, research papers, and technical documents searchable alongside their text.

Free, Pro, and Max continue to support standard PDF extraction, including OCR for scanned documents. The advanced extraction tier applies to PDFs; it does not change support for other file types.

Use the same uploadFile call shown above. Supermemory selects the extraction tier automatically from your organization's plan; no additional request parameter is needed. If advanced extraction cannot process a PDF, Supermemory falls back to standard extraction, so figure and diagram descriptions are not guaranteed for every document.

See Billing & usage for plan availability.

Microsoft Office Copy Section

Word, Excel, and PowerPoint files upload the same way — Supermemory detects the type from the file itself:

await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('roadmap.docx'),
  metadata: JSON.stringify({ title: "Product Roadmap" }),
});

Google Workspace Copy Section

Automatically handled via Google Drive connector:

• Google Docs
• Google Sheets
• Google Slides

Code & markdown Copy Chapter

Both are plain text, so they go through add like any other string content — no file upload needed:

// Markdown
await supermemory.add("user_123", {
  content: markdownContent,
  metadata: { title: "README.md" },
});

// Code (language auto-detected)
await supermemory.add("user_123", {
  content: codeContent,
  metadata: { language: "typescript" },
});

Extracts: Structure, headings, code blocks with syntax awareness.

See Super RAG for how Supermemory optimizes chunking for each content type.

Images Copy Chapter

Set fileType: "image" and mimeType so Supermemory knows exactly how to process it. Both are multipart form fields, sent in the same object as file and metadata:

await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('diagram.png'),
  metadata: JSON.stringify({ title: "Architecture Diagram" }),
  fileType: "image",
  mimeType: "image/png",
});

Extracts: OCR text, visual descriptions, diagram interpretations.

Supported: PNG, JPG, JPEG, WebP, GIF

Audio & video Copy Chapter

Video and audio each have a dedicated fileType ("video", "audio"); set it with mimeType when inference is not enough:

// Video
await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('demo.mp4'),
  metadata: JSON.stringify({ title: "Product Demo" }),
  fileType: "video",
  mimeType: "video/mp4",
});

// Audio
await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('call-recording.mp3'),
  metadata: JSON.stringify({ title: "Customer Call Recording" }),
  fileType: "audio",
  mimeType: "audio/mpeg",
});

Extracts: Transcription, speaker detection, topic segmentation.

Supported: MP3, WAV, M4A, MP4, WebM

Structured data Copy Chapter

JSON and CSV are text — stringify and send them through add(), no file upload needed.

JSON Copy Section

await supermemory.add("user_123", {
  content: JSON.stringify(userData),
  metadata: { title: "User Profile Data", format: "json" },
});

CSV Copy Section

await supermemory.add("user_123", {
  content: csvContent,
  metadata: { title: "Sales Data Q4", format: "csv" },
});

File upload Copy Chapter

For any binary file, use uploadFile — it accepts a stream, not base64:

import fs from 'fs';

await supermemory.documents.uploadFile("user_123", {
  file: fs.createReadStream('./document.pdf'),
  metadata: JSON.stringify({ title: "document.pdf" }),
});

No Node fs access? uploadFile also accepts a web File or Blob:

await supermemory.documents.uploadFile("user_123", {
  file: new File(['my bytes'], 'file.txt'),
});

await supermemory.documents.uploadFile("user_123", {
  file: await fetch('https://somesite/file').then((r) => r.blob())
});

Auto-Detection Copy Chapter

add() tells URLs and plain text apart on its own — no extra flag needed:

// URL detected automatically
await supermemory.add("user_123", { content: "https://example.com/page" });

// Plain text detected automatically
await supermemory.add("user_123", { content: "User said they prefer email contact" });

For files, uploadFile detects type from the file itself in most cases. fileType and mimeType only exist to force specific processing when inference is not enough — set them for images, video, and audio.

Content limits Copy Chapter

Typical processing time: text is near-instant; PDFs take 1-5s; images 2-10s; video 10s+; webpages 1-3s. Text content is split on sentence boundaries, with about 200 characters of overlap carried between chunks.

Next steps Copy Chapter

Apps Docs Concepts Customization (`apps/docs/concepts/customization.mdx`) Copy Section

title: "Customizing for your use case" sidebarTitle: "Customizing" icon: "/icons/hugeicons/settings-02.svg" Copy Chapter

Configure how Supermemory processes and retrieves content for your specific use case.

Organizational Context Copy Chapter

Tell Supermemory what your organization does and what content matters during ingestion. This steers what gets extracted into memories across every namespace. In v3/v4 this field was called filterPrompt.

// Example: Brand guidelines assistant
await supermemory.organization.update({
  organizationalContext: `You are ingesting content for Brand.ai's brand guidelines system.

    Index:
    - Official brand values and mission statements
    - Approved tone of voice guidelines
    - Logo usage and visual identity docs
    - Approved messaging and taglines

    Skip:
    - Draft documents and work-in-progress
    - Outdated brand materials (pre-2024)
    - Internal discussions about brand changes
    - Competitor analysis docs`,
});

The value replaces the existing context in full. Send null to clear it. The legacy shouldLLMFilter, categories, includeItems, and excludeItems settings are not part of the v5 organization resource.

Supporting Context Copy Chapter

Guide memory extraction for a specific namespace. Organizational context is org-wide; supporting context is per namespace. In v3/v4 this field was called entityContext.

await supermemory.add("session_abc123", {
  content: "User asked about logo variations for dark backgrounds...",
  supportingContext: `Design exploration conversation between [email protected] and Brand.ai assistant.
    Focus on John's design preferences and brand requirements.`,
});

await supermemory.namespaces.update("session_abc123", {
  supportingContext: `Design exploration conversation between [email protected] and Brand.ai assistant.
    Focus on John's design preferences and brand requirements.`,
});

Chunk size Copy Chapter

Control how documents are split into searchable pieces. Smaller chunks = more precise retrieval but less context per result.

await client.settings.update({
  chunkSize: 512  // -1 for default
});

Connector branding Copy Chapter

Show "Log in to YourApp" instead of "Log in to Supermemory" when users connect external services. See Connectors Overview for the full list of supported integrations.

```typescript
await client.settings.update({
  googleDriveCustomKeyEnabled: true,
  googleDriveClientId: "your-client-id.apps.googleusercontent.com",
  googleDriveClientSecret: "your-client-secret"
});
```

```typescript
await client.settings.update({
  notionCustomKeyEnabled: true,
  notionClientId: "your-notion-client-id",
  notionClientSecret: "your-notion-client-secret"
});
```

```typescript
await client.settings.update({
  onedriveCustomKeyEnabled: true,
  onedriveClientId: "your-azure-app-id",
  onedriveClientSecret: "your-azure-client-secret"
});
```

API reference Copy Chapter

// Read organization settings
const { organizationalContext, namespaceCount } = await supermemory.organization.get();

// Update organization context
await supermemory.organization.update({ organizationalContext: "..." });

// Read and update one namespace
const ns = await supermemory.namespaces.get("session_abc123");
await supermemory.namespaces.update("session_abc123", {
  supportingContext: "...",
});

Next steps Copy Chapter

Apps Docs Concepts Filtering (`apps/docs/concepts/filtering.mdx`) Copy Section

title: "Organizing & filtering memories" sidebarTitle: "Metadata filtering" icon: "/icons/hugeicons/filter.svg" Copy Chapter

Supermemory provides two ways to organize your memories:

Both can be used independently or together for precise filtering.

Namespaces Copy Chapter

Namespaces create isolated memory spaces. Use them to separate memories by user, project, or any logical boundary. The namespace is part of the URL (/ns/{namespace}/...), so namespace-scoped SDK calls take it as the first argument.

Adding Memories to a Namespace Copy Section

await supermemory.add("user_123", {
  content: "Meeting notes from Q1 planning",
});

Searching a Namespace Copy Section

const results = await supermemory.search("user_123", {
  query: "planning notes",
  searchMode: "chunks",
});

Recommended patterns Copy Section

// Search only within that user's org context
const results = await supermemory.search("org_acme_user_john", {
  query: "vacation policy",
  searchMode: "chunks",
});

// Project-based isolation
await supermemory.add("project_mobile_app", {
  content: "Sprint 5 retrospective notes",
});

// Time-based segmentation
await supermemory.add("user_cfo_2024_q1", {
  content: "Q1 2024 financial report",
});
```

The namespace is a path parameter on every v5 call (`add`, `search`, `list`, `profile`, `documents.*`). There is no array form; one request touches one namespace.

Metadata Copy Chapter

Metadata lets you attach custom properties to memories and filter by them later.

Adding memories with metadata Copy Section

await supermemory.add("user_123", {
  content: "Technical design document for auth system",
  metadata: {
    category: "engineering",
    priority: "high",
    year: 2024,
  },
});

Searching with a Filter Copy Section

A filter is a typed expression. One condition is an object with field, operator, and value. Several conditions are combined with an and or or node that lists them in operands:

const results = await supermemory.search("user_123", {
  query: "design document",
  filter: {
    operator: "and",
    operands: [
      { field: "category", operator: "eq", value: "engineering" },
      { field: "priority", operator: "eq", value: "high" },
    ],
  },
  searchMode: "chunks",
});

A single condition needs no wrapper:

filter: { field: "status", operator: "eq", value: "published" }

Operators Copy Section

String conditions accept an optional caseSensitive boolean. Numeric values are JSON numbers, not numeric strings.

Combining filters Copy Section

Nest and and or nodes for complex queries:

const results = await supermemory.search("user_123", {
  query: "meeting notes",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "meeting" },
      {
        operator: "or",
        operands: [
          { field: "team", operator: "eq", value: "engineering" },
          { field: "team", operator: "eq", value: "product" },
        ],
      },
    ],
  },
  searchMode: "chunks",
});

Excluding results Copy Section

Use the negative operators (neq, notContains, arrayNotContains) to exclude matches:

const results = await supermemory.search("user_123", {
  query: "documentation",
  filter: { field: "status", operator: "neq", value: "draft" },
  searchMode: "chunks",
});

**Numeric comparisons:**
```typescript
// Find high-priority items created after a specific date
const results = await supermemory.search("user_123", {
  query: "tasks",
  filter: {
    operator: "and",
    operands: [
      { field: "priority", operator: "gte", value: 7 },
      { field: "created_timestamp", operator: "gte", value: 1704067200 }, // Unix timestamp
    ],
  },
  searchMode: "chunks",
});
```

**Array membership:**
```typescript
// Find documents where a specific user is a participant
const results = await supermemory.search("user_123", {
  query: "meeting notes",
  filter: { field: "participants", operator: "arrayContains", value: "[email protected]" },
  searchMode: "chunks",
});
```

**Complex nested filters:**
```typescript
// (category = "tech" OR category = "science") AND status != "archived"
const results = await supermemory.search("user_123", {
  query: "research papers",
  filter: {
    operator: "and",
    operands: [
      {
        operator: "or",
        operands: [
          { field: "category", operator: "eq", value: "tech" },
          { field: "category", operator: "eq", value: "science" },
        ],
      },
      { field: "status", operator: "neq", value: "archived" },
    ],
  },
  searchMode: "chunks",
});
```

**Team meeting notes with specific participants:**
```typescript
const results = await supermemory.search("project_alpha", {
  query: "sprint planning",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "meeting" },
      {
        operator: "or",
        operands: [
          { field: "participants", operator: "arrayContains", value: "alice" },
          { field: "participants", operator: "arrayContains", value: "bob" },
        ],
      },
    ],
  },
  searchMode: "chunks",
});
```

**Exclude drafts and deprecated content:**
```typescript
const results = await supermemory.search("user_123", {
  query: "documentation",
  filter: {
    operator: "and",
    operands: [
      { field: "status", operator: "neq", value: "draft" },
      { field: "content", operator: "notContains", value: "deprecated" },
      { field: "tags", operator: "arrayNotContains", value: "archived" },
    ],
  },
  searchMode: "chunks",
});
```

Filters Beyond Search Copy Section

The same filter expression works on list and profile calls:

// Page through matching documents
const { documents, pagination } = await supermemory.list("user_123", "documents", {
  filter: { field: "category", operator: "eq", value: "engineering" },
});

// Build the profile only from matching memories
const { profile } = await supermemory.profile("user_123", {
  filter: { field: "source", operator: "eq", value: "onboarding" },
});

Quick reference Copy Chapter

When adding memories Copy Section

await supermemory.add("user_123", { // Isolation
  content: "Your content here",
  metadata: { key: "value" },         // Custom properties
});

When searching Copy Section

const results = await supermemory.search("user_123", { // Scopes results to this namespace
  query: "search query",
  filter: { field: "status", operator: "eq", value: "published" }, // Optional
  searchMode: "chunks",
});

Metadata key rules Copy Section

• Allowed characters: a-z, A-Z, 0-9, _, -, .
• No spaces or special characters
• Keys are literal: customer.plan is one key named customer.plan, not a nested path

Query complexity limits Copy Section

• Maximum 5 levels of nested and/or expressions
• Maximum 200 operands per logical group

Reading One Document's Chunks Copy Section

Scoping a search to a single document (docId) is not part of v5. To work with the chunks of one long document, fetch the document with its chunks attached:

const doc = await supermemory.documents.get("user_123", "doc_123", {
  include: ["chunks"],
});

Next steps Copy Chapter

Apps Docs Concepts Graph Memory (`apps/docs/concepts/graph-memory.mdx`) Copy Section

title: "Graph memory" sidebarTitle: "Graph memory" icon: "/icons/hugeicons/share-08.svg" Copy Chapter

How understanding is stored and stays true over time.

Supermemory builds a living knowledge graph of facts on top of other facts — not a static folder of embeddings, and not classic entity–relation–entity triples you maintain by hand.

The pipeline that turns a chat or file into memories is How it works.

This page is the model: what a memory is, how edges form, and why agents utilize supermemory's graph

Try it Copy Chapter

Get a key from the developer console — API Keys → Create API Key — then add a memory and pull it back with related edges:

import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: "sm_..." }); // from console.supermemory.ai → API Keys

await supermemory.add("user_123", {
  content: "Alex mentioned he just started at Stripe",
  dreaming: "instant", // memories land in the graph right away
});

const { results } = await supermemory.search("user_123", {
  query: "where does Alex work?",
  include: { related: true },
  searchMode: "memories",
});

Full walkthrough with a live example: Quickstart.

Documents vs memories Copy Chapter

Think of documents as books you hand the system. Memories are the insights it keeps — connected to each other as new content arrives.

Properties and rules of memories Copy Chapter

1. Memories are atomic - Each memory has enough information and context about one particular topic
2. They always build on top of each other - with updates, the model knows the history, a memory extends from other memories, and new facts are derived (derives relation) from existing knowledge.

Memory relationships Copy Chapter

When content is processed, new facts connect to existing ones through three relationship types.

Updates — information changes Copy Section

New fact replaces what was true before for search purposes; history can remain for audit.

Memory 1: "Alex works at Google as a software engineer"
Memory 2: "Alex just started at Stripe as a PM"
         → Memory 2 UPDATES Memory 1

isLatest (and related graph fields) keep retrieval on the current fact without erasing the past.

Extends — information enriches Copy Section

New fact adds detail without invalidating the old one.

Memory 1: "Alex works at Stripe as a PM"
Memory 2: "Alex focuses on payments and leads a team of 5"
         → Memory 2 EXTENDS Memory 1

Both stay valid; context gets richer.

Derives — information infers Copy Section

Supermemory infers a fact you never stated in one place, from patterns across memories.

Memory 1: "Alex is a PM at Stripe"
Memory 2: "Alex frequently discusses payment APIs and fraud detection"
         → Derived: "Alex likely works on Stripe's core payments product"

That is the same class of “entity chain” you see in the quickstart (gift → VP of Product → Sarah → Tokyo offsite). Search can expose edges via include: { related: true }; they come back under included.related — see Search API.

Automatic extraction (one input → many facts) Copy Chapter

Input:

Had a great call with Alex. He's enjoying the new PM role at Stripe, though the payments work is intense. He moved to Seattle for the job—Capitol Hill. Wants dinner next time I'm in town.

Example extracted memories:

• Alex works at Stripe as a PM
• Alex works on payments infrastructure (extends role)
• Alex lives in Seattle, Capitol Hill
• Alex wants to meet for dinner (episodic)

You do not define schema or draw edges. You add content; the graph updates.

Dreaming keeps the graph alive Copy Chapter

Ingest is not a one-shot snapshot. After (and alongside) indexing, dreaming continues building the graph: extracting facts, linking related memories, resolving updates, and producing derives you never stated in one place.

By default Supermemory uses dreaming: "dynamic" — related documents are grouped so memories form from coherent units (e.g. a real multi-turn session), not each isolated write in isolation. That is why production quality is higher when you keep a stable id on conversations and let dynamic dreaming do its job.

Use dreaming: "instant" when this document must hit the graph immediately (demos, “search right after add”). That path processes the document alone and costs an extra operation.

How to set the flag, statuses, and when done means what: How it works → Dreaming and Processing modes.

Memory types Copy Chapter

Automatic forgetting Copy Chapter

• Time-based — temporary facts drop after they expire (“exam tomorrow”, “meeting at 3pm today”).
• Contradiction — updates win for “what’s true now.”
• Noise filtering — casual, non-meaningful chatter is less likely to become durable memory.

For explicit product controls (forget, review low-confidence derives), see Forget & update and Memory review.

What you don’t do Copy Chapter

You do not hand-maintain the graph. You:

1. Ingest under a namespace
2. Wait for the pipeline when needed
3. Search or load a profile

await supermemory.add("user_123", {
  content: "Alex mentioned he just started at Stripe",
});

const { results } = await supermemory.search("user_123", {
  query: "where does Alex work?",
  include: { related: true },
  searchMode: "memories",
});
// Prefer latest work fact (Stripe); history remains in the graph.
// Related edges come back under results[i].included.related

Related in the docs Copy Chapter

Apps Docs Concepts How It Works (`apps/docs/concepts/how-it-works.mdx`) Copy Section

title: "How Supermemory works" sidebarTitle: "How it works" icon: "/icons/hugeicons/cpu.svg" Copy Chapter

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

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 Copy Chapter

```python Python
# pip install supermemory
from supermemory import Supermemory

client = Supermemory(api_key="sm_...")  # from console.supermemory.ai → API Keys

client.add(
    "user_123",
    content="The user loves Paris.",
    dreaming="instant",  # memories available right after processing
)

results = client.search("user_123", query="where does the user want to travel?")

curl -X POST "https://api.supermemory.ai/ns/user_123/document" \
  -H "Authorization: Bearer sm_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "The user loves Paris.", "dreaming": "instant" }'

curl -X POST "https://api.supermemory.ai/ns/user_123/search" \
  -H "Authorization: Bearer sm_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "where does the user want to travel?" }'

What you send: documents Copy Chapter

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 for formats, and Add context 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 id when the same conversation or file will be updated later (sessions, connector syncs). That identity also drives diff billing on re-ingest.

What the pipeline does Copy Chapter

const doc = await supermemory.add("user_123", {
  content: conversationText,
  id: "chat_session_1",
});

// Poll until ready
const { system } = await supermemory.documents.get("user_123", doc.id);
// system.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) Copy Chapter

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 (a field in the JSON body, next to content in the SDK):

// Production default — omit or set explicitly
await supermemory.add("user_123", {
  content: conversationText,
  id: "chat_session_1",
  dreaming: "dynamic",
});

// Need memories immediately (e.g. tutorial)
await supermemory.add("user_123", {
  content: conversationText,
  id: "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.

How those memories connect and stay true over time is Graph memory. API detail: Processing modes.

What you get out Copy Chapter

After the pipeline runs, the same document leads to three things -> Chunks, Memories and Profile. (in the same namespace):

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.

Isolation and identity Copy Chapter

• namespace — hard isolation boundary (user, tenant, project), carried in the URL. See Namespaces.
• Metadata — soft dimensions inside a namespace for filtering. See Metadata filtering.
• Scoped API keys — credentials that cannot cross a namespace. See API keys.

Next steps Copy Chapter

Apps Docs Concepts Memory Vs Rag (`apps/docs/concepts/memory-vs-rag.mdx`) Copy Section

title: "Memory vs RAG: Understanding the difference" sidebarTitle: "Memory vs RAG" icon: "/icons/hugeicons/balance-scale.svg" Copy Chapter

Most developers confuse RAG (Retrieval-Augmented Generation) with agent memory. They're not the same thing, and using RAG for memory is why your agents keep forgetting important context. Let's understand the fundamental difference.

The core problem Copy Chapter

When building AI agents, developers often treat memory as just another retrieval problem. They store conversations in a vector database, embed queries, and hope semantic search will surface the right context.

This approach fails because memory isn't about finding similar text—it's about understanding relationships, temporal context, and user state over time.

Documents vs memories in Supermemory Copy Chapter

Supermemory makes a clear distinction between these two concepts:

Documents: Raw knowledge Copy Section

Documents are the raw content you send to Supermemory—PDFs, web pages, text files. They represent static knowledge that doesn't change based on who's accessing it.

Characteristics:

• Stateless: A document about Python programming is the same for everyone
• Unversioned: Content doesn't track changes over time
• Universal: Not linked to specific users or entities
• Searchable: Perfect for semantic similarity search

Use Cases:

• Company knowledge bases
• Technical documentation
• Research papers
• General reference material

Memories: Contextual understanding Copy Section

Memories are the insights, preferences, and relationships extracted from documents and conversations. They're tied to specific users or entities and evolve over time.

Characteristics:

• Stateful: "User prefers dark mode" is specific to that user
• Temporal: Tracks when facts became true or invalid
• Personal: Linked to users, sessions, or entities
• Relational: Understands connections between facts

Use Cases:

• User preferences and history
• Conversation context
• Personal facts and relationships
• Behavioral patterns

Why RAG fails as memory Copy Chapter

Let's look at a real scenario that illustrates the problem:

# Semantic search finds closest match
result = vector_search(query)
# Returns: "I love Adidas sneakers" (highest similarity)

# Agent recommends Adidas 🤦
```

**Problem**: RAG finds the most semantically similar text but misses the temporal progression and causal relationships.

# Memory retrieval considers:
# 1. Temporal validity (Adidas preference is outdated)
# 2. Causal relationships (broke → disappointment → switch)
# 3. Current state (now prefers Puma)

# Agent correctly recommends Puma ✅
```

**Solution**: Memory systems track when facts become invalid and understand causal chains.

The technical difference Copy Chapter

RAG: Semantic similarity Copy Section

Query → Embedding → Vector Search → Top-K Results → LLM

RAG excels at finding information that's semantically similar to your query. It's stateless—each query is independent.

Memory: Contextual graph Copy Section

Query → Entity Recognition → Graph Traversal → Temporal Filtering → Context Assembly → LLM

Memory systems build a knowledge graph that understands:

• Entities: Users, products, concepts
• Relationships: Preferences, ownership, causality
• Temporal Context: When facts were true
• Invalidation: When facts became outdated

When to use each Copy Chapter

Real-world examples Copy Chapter

E-commerce assistant Copy Section

```python
# Good for RAG
"What are the specs of iPhone 15?"
"Compare Nike and Adidas running shoes"
"Show me waterproof jackets"
```

```python
# Needs Memory
"What size do I usually wear?"
"Did I like my last purchase?"
"What's my budget preference?"
```

Customer support bot Copy Section

```python
# Good for RAG
"How do I reset my password?"
"What's your return policy?"
"Troubleshooting WiFi issues"
```

```python
# Needs Memory
"Is my issue from last week resolved?"
"What plan am I on?"
"You were helping me with..."
```

How Supermemory handles both Copy Chapter

Supermemory provides a unified platform that correctly handles both patterns:

1. Document storage (RAG) Copy Section

# Add a document for RAG-style retrieval
client.add(
    "product_knowledge",  # Shared namespace, not tied to a user
    content="iPhone 15 has a 48MP camera and A17 Pro chip",
    dreaming="instant"
)

2. Memory creation Copy Section

# Add a user-specific memory
client.add(
    "user_123",  # User-specific namespace
    content="User prefers Android over iOS",
    dreaming="instant",
    metadata={
        "type": "preference",
        "confidence": "high"
    }
)

3. Hybrid retrieval Copy Section

# Search is scoped to one namespace, so query each side on its own
user = client.profile("user_123")  # User's Android preference (memory)

specs = client.search(
    "product_knowledge",  # Latest Android phone specs (document chunks)
    query="What phone should I recommend?",
    search_mode="chunks",
)

# Hand both to the model: user.profile + specs.results

The bottom line Copy Chapter

Stop treating memory like a retrieval problem. Your agents need both:

• RAG for accessing knowledge
• Memory for understanding users

Supermemory provides both capabilities in a unified platform, ensuring your agents have the right context at the right time.

Next steps Copy Chapter

Apps Docs Concepts Multi Tenancy Examples (`apps/docs/concepts/multi-tenancy-examples.mdx`) Copy Section

title: "Multi-tenancy examples" sidebarTitle: "Examples" icon: "/icons/hugeicons/check-list.svg" Copy Chapter

A few common shapes multi-tenancy takes in practice, combining namespaces for isolation with metadata filters for organization within a boundary.

Personal agent Copy Chapter

A single namespace per user is enough — there's no shared data to leak, so metadata is optional.

await supermemory.add(userId, { // one namespace per user
  content: "User prefers morning workouts and vegetarian meals",
});

const results = await supermemory.search(userId, {
  query: "workout preferences",
});

Company agent (shared + personal memory) Copy Chapter

A company-wide assistant usually needs two kinds of namespaces: one shared namespace the whole org reads from, and one personal namespace per employee that nobody else can see.

// Shared org knowledge — visible to everyone at the company
await supermemory.add("org_acme_shared", {
  content: "Q3 roadmap: ship the mobile app redesign by end of August",
  metadata: { team: "product", type: "roadmap" },
});

// Personal memory — only this employee's agent should see this
await supermemory.add("org_acme_user_alex", {
  content: "Prefers async updates over meetings",
});

Inside the shared namespace, use metadata to scope queries to a team rather than creating a namespace per team:

const results = await supermemory.search("org_acme_shared", {
  query: "roadmap updates",
  filter: { field: "team", operator: "eq", value: "product" },
  searchMode: "chunks",
});

An employee's agent typically queries both namespaces — their personal one plus the shared one — and merges the results, since a request is scoped to exactly one namespace.

Email assistant Copy Chapter

One namespace per user, with metadata carrying email-specific properties like label, sender, or folder — so the assistant can answer things like "find the Spotify email tagged Promotional".

await supermemory.add(userId, {
  content: "Your Spotify Premium receipt for July — $11.99 charged",
  metadata: {
    source: "gmail",
    sender: "[email protected]",
    label: "Promotional",
  },
});

const results = await supermemory.search(userId, {
  query: "spotify",
  filter: {
    operator: "and",
    operands: [
      { field: "source", operator: "eq", value: "gmail" },
      { field: "label", operator: "eq", value: "Promotional" },
    ],
  },
  searchMode: "chunks",
});

Multi-tenant support platform Copy Chapter

Each customer gets their own namespace, and metadata tracks ticket-level fields like status and priority — so "open, high-priority tickets" is a filter, not a new namespace, and it can never accidentally include another customer's tickets.

await supermemory.add("org_customer_442", {
  content: "Customer reports checkout button unresponsive on Safari",
  metadata: { status: "open", priority: "high", channel: "chat" },
});

const results = await supermemory.search("org_customer_442", {
  query: "checkout issue",
  filter: {
    operator: "and",
    operands: [
      { field: "status", operator: "eq", value: "open" },
      { field: "priority", operator: "eq", value: "high" },
    ],
  },
  searchMode: "chunks",
});

Next steps Copy Chapter

Apps Docs Concepts Multi Tenancy (`apps/docs/concepts/multi-tenancy.mdx`) Copy Section

title: "Multi-tenancy overview" sidebarTitle: "Overview" icon: "/icons/hugeicons/user-multiple.svg" Copy Chapter

Most apps built on Supermemory serve more than one user, customer, or tenant out of a single Supermemory organization. Multi-tenancy is how you keep those memories apart — so User A's data is never visible to User B, and so you can still slice and query within a user's own data by things like category, status, or date.

Supermemory gives you two complementary tools for this:

They solve different problems, and most production apps use both together.

Why two mechanisms Copy Chapter

It's tempting to reach for one tool and make it do everything, but namespaces and metadata aren't interchangeable — they answer different questions.

A namespace decides whether a memory is reachable at all for a given request. Metadata decides which of the reachable memories match. Filtering never crosses a namespace boundary — you can't use metadata to peek into another tenant's namespace.

How they work together Copy Chapter

A typical multi-tenant write scopes the memory to a tenant with a namespace, then attaches metadata for finer-grained querying later:

await supermemory.add("org_acme", { // isolates to the "acme" tenant
  content: "Customer requested a refund for order #4821",
  metadata: {
    category: "support",
    status: "open",
    priority: "high",
  },
});

And a search combines both: the namespace restricts which tenant's data is in scope, and the filter narrows down which memories within that tenant come back:

const results = await supermemory.search("org_acme", {
  query: "refund request",
  filter: {
    operator: "and",
    operands: [
      { field: "category", operator: "eq", value: "support" },
      { field: "status", operator: "eq", value: "open" },
    ],
  },
  searchMode: "chunks",
});

Choosing your boundary Copy Chapter

The namespace is the layer that should map to your actual tenancy model — pick the level that matches what "one isolated space" means in your app:

The simplest form is one namespace per user, derived from an ID you already have:

await supermemory.add(userId, { // one namespace per user
  content: "User prefers morning workouts",
});

const results = await supermemory.search(userId, {
  query: "workout preferences",
});

Everything within that boundary — categories, statuses, dates, custom fields — is metadata, not a new namespace. Don't create a new namespace for every property you want to filter on; that's what metadata is for.

Access control Copy Chapter

Namespaces aren't just organizational — they're enforced as an authorization boundary. API keys and org members can be restricted to specific namespaces, so a request for a namespace outside the caller's allowed set is rejected with 403 Forbidden rather than silently filtered. See Namespaces → Access control for the details.

Next steps Copy Chapter

Apps Docs Concepts Rules (`apps/docs/concepts/rules.mdx`) Copy Section

title: "Rules of supermemory" sidebarTitle: "Rules of supermemory" icon: "/icons/hugeicons/justice-scale-01.svg" Copy Chapter

Supermemory provides powerful primitives and the full context stack for building AI agents. This page collects rules of thumb from building and running supermemory in production. They aren't hard constraints, just shortcuts that save you time, cost, and confusing search results.

Thinking about ingestion Copy Chapter

What to ingest, and what not to Copy Section

Send what you would send to a human for memory

Treat supermemory as a database for human-like understanding of knowledge and search. You should be feeding it unstructured data like documents, chat conversations, or even images, videos, and websites. You should not be ingesting database records or CSVs, since those are more structured.

Although supermemory does support learning from long-horizon structured data, typically the right approach is to give an agent tools to traverse the structure directly.

Agents benefit most from having a general idea of the topic alongside tools to look through the data. For example, knowing "this company uses PostHog and has three products (API, Console, and Landing Page)" helps the agent navigate the PostHog data more effectively.

A quick test for where information belongs

Two things about this table that trip people up.

"Remember" and "look up" are both supermemory, but different reads. You ingest documents; the pipeline derives memories from them and maintains a profile per namespace. supermemory.search(namespace, { query, searchMode: "memories" }) recalls the derived facts. supermemory.search(namespace, { query, searchMode: "chunks" }) recalls the source material itself. A support agent usually needs both: memories for "this customer runs self-hosted and already tried reinstalling", documents for the actual troubleshooting guide.

Supermemory is not your system of record. There's no SQL over memories, no joins, no aggregates, no querying by primary key. Keep transactional data in your database, and ingest the narrative around it ("the customer disputed invoice #4821 and churned over it") so your AI understands what the rows mean.

Ingest with SuperRag when you just need search

When you know you only want search, you can cut costs by 5x. Just set taskType when ingesting:

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

client.add(
    "test",
    content="testing",
    task_type="superrag",
)

curl -X POST "https://api.supermemory.ai/ns/test/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "testing", "taskType": "superrag" }'

Use hybrid mode when searching over SuperRag content

hybrid mode (the v5 default) makes it much easier to get complete results from supermemory when you have both memories and documents.

const { results } = await supermemory.search("test", {
  query: "test",
  searchMode: "hybrid",
});

results = client.search(
    "test",
    query="test",
    search_mode="hybrid",
)

curl -X POST "https://api.supermemory.ai/ns/test/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "test", "searchMode": "hybrid" }'

Each entry in results carries either memory or chunk:

{ results: ({ memory: string } | { chunk: string })[], searchTime: number }

Use item.memory || item.chunk when reading results.

Keep documents medium-sized

While supermemory can handle documents with 400k+ tokens, sending smaller, self-contained documents produces better-quality learnings. The internal learning agent and "dreaming" jobs reflect on memories to build relations between them. If documents are too long, fewer memories get generated and fewer relations get made.

We also recommend ingesting documents sequentially within a single namespace where possible, since that's how supermemory determines what came first (used for updates relations and temporal reasoning).

Handling single-threaded chatbots

Many agent harnesses, like openclaw, hermes, and other single-threaded custom agents, run one long conversation with compaction. Some tips for managing single-threaded (and other long-running) conversations:

1. Send an id when you can: a sessionId, conversationId, document ID, or any representation of a "session" in your application.
2. Generate one if you don't have one, e.g. the current 4-hour window: ${new Date().toISOString().slice(0,10)}-${new Date().getHours()>>2}. Adjust the window size based on traffic per namespace.
3. Send the same prefix: keep the start of the document identical across ingests under the same id so supermemory can diff cleanly. You can either resend the full growing transcript each time, or send only the new turns since your last ingest. Just don't mix the two for the same id.

Ingestion 1:
Assistant: Hey, how are you?
User: I'm fine.

Ingestion 2 (full transcript):
Assistant: Hey, how are you?
User: I'm fine.
Assistant: Anything I can help with today?

Ingestion 2 (delta only):
Assistant: Anything I can help with today?

You're only billed for the new (diff) content you send, so doing this well improves performance, cuts cost, and keeps usage simple.

Architecture and design Copy Chapter

Let supermemory handle the learning

Don't pass content through an additional LLM before sending it to supermemory. Supermemory does that learning automatically. Because the engine already knows what it knows, it can contextually summarize, update, and forget information as needed.

Configure what you want it to learn

Ground it with supportingContext (called entityContext in v3/v4) to prevent drift over time. Picture a third person watching a conversation between two people: what do they remember, and about whom? Giving supermemory context about the entity itself helps ground its learnings and prevents drift and decay over time.

const user = auth.user.name;
await supermemory.add(user, {
  content: "Hey, I'm doing great!",
  supportingContext: `User is ${user}, talking to assistant Kira`,
}); // -> supermemory learns "Dhravya is doing great"

user = auth.user.name
client.add(
    user,
    content="Hey, I'm doing great!",
    supporting_context=f"User is {user}, talking to assistant Kira",
)  # -> supermemory learns "Dhravya is doing great"

curl -X POST "https://api.supermemory.ai/ns/dhravya/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hey, I'\''m doing great!",
    "supportingContext": "User is dhravya, talking to assistant Kira"
  }'

Use namespaces, don't over-stuff a single one

Use a namespace wherever there's a hard permission boundary.

• Don't: ingest everything into one namespace and filter through it with metadata.
• Do: give each user their own namespace (namespace: userId), and still filter by metadata inside it if needed.

There's little correlation between the number of items in a namespace and its quality or latency. Supermemory is built for multi-tenant workloads and supports up to 1M documents and 10M memories per namespace.

Use metadata filtering for detailed scoping inside namespaces

You'll often want to ingest and search with filtering inside a single namespace. Say the engineering team ingests this:

await supermemory.add("org-supermemory", {
  content: "The team prefers TypeScript",
  metadata: { team: "Engineering" },
  group: { team: "Engineering" },
});

client.add(
    "org-supermemory",
    content="The team prefers TypeScript",
    metadata={"team": "Engineering"},
    group={"team": "Engineering"},
)

curl -X POST "https://api.supermemory.ai/ns/org-supermemory/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The team prefers TypeScript",
    "metadata": { "team": "Engineering" },
    "group": { "team": "Engineering" }
  }'

Tip: group (called filterByMetadata in v3/v4) ensures a fact like "the team prefers TypeScript" is only built on top of the engineering team's knowledge.

Later, the research team ingests this into the same namespace (POST /ns/org-supermemory/document) but with different metadata:

{
  "content": "The team prefers Python",
  "metadata": { "team": "Research" },
  "group": { "team": "Research" }
}

This keeps research's and engineering's memories from mixing, even though they share a namespace. When searching:

const results = await supermemory.search("org-supermemory", {
  query: "preferred language",
  filter: { field: "team", operator: "eq", value: "Research" },
  searchMode: "chunks",
}); // -> "python"

results = client.search(
    "org-supermemory",
    query="preferred language",
    search_mode="chunks",
    filter={"field": "team", "operator": "eq", "value": "Research"},
)  # -> "python"

curl -X POST "https://api.supermemory.ai/ns/org-supermemory/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "preferred language",
    "searchMode": "chunks",
    "filter": { "field": "team", "operator": "eq", "value": "Research" }
  }'

Thinking about harness Copy Chapter

Think about how to bring memory back into the harness itself.

Embrace a little noise

You might want to hyper-optimize everything that goes into the model's prompt, but counterintuitively, you sometimes want to embrace noise, since true personalization comes from distinctive information.

Example: a user says "hi" and the LLM responds "Hey Dhravya! How's it going? How's the new office coming along?" instead of something generic.

Supermemory is designed for this: it returns an average of 10 tokens per fact, so even 50 facts is just 500 tokens of context, cheap enough to stay generous.

Tools, hooks, and making the choice

Think about how supermemory fits into your harness. Example, a personal agent:

• Session start hook → load profile
• On-message hook → enrich the prompt with search
• On-stop hook → save the conversation

Play around with these options in our playground, and read more in this post on memory at the harness level.

Apps Docs Concepts Super Rag (`apps/docs/concepts/super-rag.mdx`) Copy Section

title: "SuperRAG (managed RAG as a service)" sidebarTitle: "SuperRAG" icon: "/icons/hugeicons/flash.svg" Copy Chapter

Supermemory doesn't just store your content—it transforms it into optimized, searchable knowledge. Every upload goes through an intelligent pipeline that extracts, chunks, and indexes content in the ideal way for its type.

Automatic content intelligence Copy Chapter

When you add content, Supermemory:

1. Detects the content type — PDF, code, markdown, images, video, etc.
2. Extracts content optimally — Uses type-specific extraction (OCR for images, transcription for audio)
3. Chunks intelligently — Applies the right chunking strategy for the content type
4. Generates embeddings — Creates vector representations for semantic search
5. Builds relationships — Connects new knowledge to existing memories

// Just upload — Supermemory handles the rest
await supermemory.documents.uploadFile("docs_kb", {
  file: fs.createReadStream('technical-documentation.pdf'),
  metadata: JSON.stringify({ title: "Technical Documentation" }),
});

No chunking strategies to configure. No embedding models to choose. It just works.

Ingesting as pure SuperRAG (`taskType: "superrag"`) Copy Chapter

By default, every supermemory.add() call runs on the memory path (taskType: "memory"): Supermemory chunks and embeds the content for retrieval, and runs it through the memory pipeline — extracting facts, updating the profile, and linking it into the knowledge graph.

If you're ingesting content that's purely reference material — documentation, a large PDF, a knowledge base article — and you don't need Supermemory to derive personal facts or update a profile from it, set taskType: "superrag" in the request body. It skips the memory pipeline entirely and only does the chunk → embed → index work needed to make the content searchable.

await supermemory.add("docs_kb", { // e.g. a long internal wiki page
  content: "...",
  taskType: "superrag",
});

client.add(
    "docs_kb",
    content="...",  # e.g. a long internal wiki page
    task_type="superrag",
)

curl -X POST "https://api.supermemory.ai/ns/docs_kb/document" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "...", "taskType": "superrag" }'

When you're searching over a mix of both, searchMode: "hybrid" (below) is what pulls memory-path facts and superrag-path document chunks into one result set. More ingestion guidance: Rules of supermemory → Ingest with SuperRag when you just need search.

Smart chunking by content type Copy Chapter

Different content types need different chunking strategies. Supermemory applies the optimal approach automatically:

Documents (PDF, DOCX) Copy Section

PDFs and documents are chunked by semantic sections — headers, paragraphs, and logical boundaries. This preserves context better than arbitrary character splits.

├── Executive Summary (chunk 1)
├── Introduction (chunk 2)
├── Section 1: Architecture
│   ├── Overview (chunk 3)
│   └── Components (chunk 4)
└── Conclusion (chunk 5)

Code Copy Section

When content is recognized as Markdown, fenced code blocks are kept whole when they fit in a chunk. Larger blocks are split and re-wrapped in the original fence, including its language tag. Overlap can contain part of a previous line, so chunks are not guaranteed to be independently valid code.

Raw source files and content not recognized as Markdown use plain-text chunking. A lone fenced block may not be enough for automatic Markdown detection.

Web pages Copy Section

URLs are fetched, cleaned of navigation/ads, and chunked by article structure — headings, paragraphs, lists.

Markdown Copy Section

Chunked by heading hierarchy, preserving the document structure.

See Content Types for the full list of supported formats.

Hybrid memory + RAG Copy Chapter

Supermemory combines the best of both approaches in every search:

With searchMode: "hybrid" (the default), you get both:

const results = await supermemory.search("user_123", {
  query: "how do I deploy the app?",
  searchMode: "hybrid",
});

// Returns:
// - Deployment docs from your knowledge base (RAG)
// - User's previous deployment preferences (Memory)
// - Their specific environment configs (Memory)

Search optimization Copy Chapter

Two flags give you fine-grained control over result quality:

Reranking Copy Section

Re-scores results using a cross-encoder model for better relevance. rerank takes "none" (default), "order", or "aggregate":

const results = await supermemory.search("user_123", {
  query: "complex technical question",
  rerank: "order", // +~100ms, significantly better ranking
});

When to use: Complex queries, technical documentation, when precision matters more than speed.

Query rewriting Copy Section

Expands your query to capture more relevant results:

const results = await supermemory.search("user_123", {
  query: "how to auth",
  rewriteQuery: true, // Expands to "authentication login oauth jwt..."
});

When to use: Short queries, user-facing search, when recall matters.

Why it's "Super" Copy Chapter

You focus on building your product. Supermemory handles the RAG complexity.

Next steps Copy Chapter

Apps Docs Concepts User Profiles (`apps/docs/concepts/user-profiles.mdx`) Copy Section

title: "User profiles" sidebarTitle: "Profiles" icon: "/icons/hugeicons/user-circle.svg" Copy Chapter

User profiles are automatically maintained collections of facts about your users that Supermemory builds from all their interactions. Think of it as a persistent "about me" document that's always up-to-date.

Each namespace gets its own profile.

Note: It's called "user" profile, but in reality it can be anything - an agent, organization, etc.

Why Profiles? Copy Chapter

Traditional memory systems rely entirely on search:

Search is too narrow: When you search for "project updates", you miss that the user prefers bullet points, works in PST, and uses specific terminology.

Profiles provide the foundation: Instead of searching for basic context, profiles give your LLM a complete picture of who the user is.

A pure search architecture means every turn pays a search(prompt) round trip before the agent can respond. A profile is attached once and sits alongside every user prompt and agent output — no extra call, no latency, and no risk of the query missing something important.

Non-literal-matching use cases Copy Chapter

Semantic search retrieves content that's similar to the query — it's built for questions like "what did we discuss about the migration?" It's a poor fit for facts that should be known regardless of what's being asked, because there's rarely a query that's semantically close to them.

The clearest example is the user's own name. If someone tells your agent "call me Dhravya, not my full name" once during onboarding, that fact has almost nothing in common — vector-wise — with "help me plan a trip to Japan" or "review this PR." A search for either of those queries will not surface the name preference, because search only returns what's relevant to the query, and a name preference isn't relevant to trip planning or code review — it should just always be there.

// Weeks earlier, during onboarding
await supermemory.add("user_123", {
  content: "Call me Dhravya, not my full first name",
});

// Later — an unrelated query
const { results } = await supermemory.search("user_123", {
  query: "help me plan a trip to Japan",
});
// The name preference won't be in `results` — it's not semantically
// related to trip planning, so search correctly leaves it out.

// But it's always in the profile, independent of the query:
const { profile } = await supermemory.profile("user_123");
console.log(profile.static.map((m) => m.memory)); // ["User goes by Dhravya, not their full name", ...]

This is the general pattern: names, pronouns, timezone, tone/format preferences, role, and other facts that should color every response — not just responses to a matching query — belong in the profile, not left to be caught by search. If your agent needs to "just know" something at all times, that's a strong signal it belongs in the profile rather than relying on a lucky semantic match.

Static vs dynamic Copy Chapter

Profiles separate two types of information:

Static profile Copy Section

Long-term, stable facts:

• "Sarah is a senior software engineer at TechCorp"
• "Sarah specializes in distributed systems"
• "Sarah prefers technical docs over video tutorials"

Dynamic profile Copy Section

Recent context and temporary states:

• "Sarah is migrating the payment service to microservices"
• "Sarah is preparing for a conference talk next month"
• "Sarah is debugging a memory leak in auth service"

Buckets Copy Chapter

Static and dynamic split facts by how long-lived they are. Buckets split them by topic — a third, independent axis you define, like preferences, goals, or work. As content is ingested, a classifier sorts each fact into the buckets it matches.

Every org starts with a default preferences bucket, which is always present — custom buckets are added alongside it, never in place of it. Add your own in console settings at the organization level, or per namespace with supermemory.profiles.setBuckets() — namespace buckets are add-only, so a namespace always keeps every org-level bucket.

// Define a namespace-level bucket (name → description)
await supermemory.profiles.setBuckets("user_123", {
  buckets: { goals: "Goals and targets the user is actively working toward" },
});

const { profile } = await supermemory.profile("user_123", { // optional — omit for all configured buckets
  buckets: ["preferences", "goals"],
});

console.log(profile.buckets.preferences); // [{ id, memory }, ...]
console.log(profile.buckets.goals);

Bucket descriptions steer the classifier, so a precise description ("explicit first-person preferences only, exclude inferred traits") produces cleaner buckets than a vague one. Buckets are separate from organizationalContext (called filterPrompt in v3/v4), which steers what gets extracted at all — buckets only organize facts that already made it into the profile.

How it works Copy Chapter

Profiles are built automatically through ingestion:

1. Ingest content — Users add documents, chat, or any content
2. Extract facts — AI analyzes content for facts about the user
3. Update profile — System adds, updates, or removes facts
4. Always current — Profiles reflect the latest information

Profiles + search Copy Chapter

Profiles don't replace search — they complement it:

• Profile = broad foundation (who the user is, preferences, background)
• Search = specific details (exact memories matching a query)

Example Copy Section

User asks: "Can you help me debug this?"

Without profiles: LLM has no context about expertise, projects, or preferences.

With profiles: LLM knows:

• Senior engineer (adjust technical level)
• Working on payment service (likely context)
• Prefers CLI tools (tool suggestions)
• Recent memory leak issues (possible connection)

Filtering profiles Copy Chapter

Not many people realize this, but profiles support the same metadata filtering as memory and document search. A profile is synthesized from the underlying memories in a namespace, so any filter expression you'd pass to search also narrows which memories are eligible to contribute to static, dynamic, and buckets.

// Only build the profile from memories tagged as onboarding data
const { profile } = await supermemory.profile("user_123", {
  filter: { field: "source", operator: "eq", value: "onboarding" },
});

This is useful when a namespace mixes memories from several sources or contexts and you only want one of them reflected in the profile — for example, a support agent that should only see profile facts derived from support tickets, not from an internal wiki synced into the same namespace:

const { profile } = await supermemory.profile("org_customer_442", {
  filter: { field: "channel", operator: "eq", value: "support_ticket" },
});

A v5 profile call takes no search query. If you also need query-ranked memories, make a separate supermemory.search() call with the same filter. See Filtering Profiles for the full parameter reference.

Use cases Copy Chapter

Personalized AI assistants Copy Section

Profiles provide: expertise level, communication preferences, tools used, current projects.

const systemPrompt = `You are assisting ${userName}.

Background: ${profile.static.map((m) => m.memory).join('\n')}
Current focus: ${profile.dynamic.map((m) => m.memory).join('\n')}

Adjust responses to their expertise and preferences.`;

Customer support Copy Section

Profiles provide: product usage, previous issues, tech proficiency.

• No more "let me look up your account"
• Agents immediately understand context
• AI support references past interactions naturally

Educational platforms Copy Section

Profiles provide: learning style, completed courses, strengths/weaknesses.

Development tools Copy Section

Profiles provide: preferred languages, coding style, current project context.

Next steps Copy Chapter

Apps Docs Connectors Github (`apps/docs/connectors/github.mdx`) Copy Section

title: "GitHub connector" sidebarTitle: "GitHub" icon: "/images/github-icon.svg" Copy Chapter

Connect GitHub repositories to sync documentation files into your Supermemory knowledge base with OAuth authentication, webhook support, and automatic incremental syncing.

Quick setup Copy Chapter

1. Create GitHub Connector Copy Section

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

const connector = await supermemory.connectors.create("user-123", {
  provider: "github",
  redirectUrl: "https://yourapp.com/auth/github/callback",
  documentLimit: 5000,
})

// Send the user to GitHub to authorize
if (connector.authorization) window.location.href = connector.authorization.url
console.log("Auth URL expires at:", connector.authorization?.expiresAt)
```

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "github",
        "redirect_url": "https://yourapp.com/auth/github/callback",
        "document_limit": 5000,
    },
)

# Send the user to GitHub to authorize
print(f"Redirect to: {connector.authorization.url}")
print(f"Auth URL expires at: {connector.authorization.expires_at}")
```

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }
```

2. Handle OAuth callback Copy Section

Send the user to authorization.url before authorization.expiresAt. After the user grants permissions, Supermemory sends them to a hosted repository picker; once they choose repositories, they return to your redirectUrl. A pending OAuth connector is not returned by list until the user finishes authorization; get returns it with system.status: "pending_authorization".

3. Select Repositories Copy Section

Unlike most connectors, GitHub requires repository selection before syncing begins. There are two ways to set it:

• Hosted picker: read the connector with include: "picker" and send the user to picker.url. The link works once and expires at picker.expiresAt.
• Direct selection: if you already know the repository ids, pass them in selection.repos with connectors.update. A new selection replaces the old one and starts a sync.

if (withPicker.picker) window.location.href = withPicker.picker.url

// Option B: set the repositories directly by id
await supermemory.connectors.update("user-123", connectorId, {
  selection: {
    repos: ["123456789", "987654321"],
  },
})

console.log("Repository sync initiated")
```

if with_picker.picker:
    print(f"Redirect to: {with_picker.picker.url}")

# Option B: set the repositories directly by id
client.connectors.update(
    "user-123",
    connector_id,
    selection={"repos": ["123456789", "987654321"]},
)

print("Repository sync initiated")
```

# Response includes: "picker": { "url": "https://...", "expiresAt": "2024-01-15T11:30:00.000Z" }

# Option B: set the repositories directly by id
curl -X PATCH "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "repos": ["123456789", "987654321"]
    }
  }'
```

Supported document types Copy Chapter

The GitHub connector syncs documentation and text files with the following extensions:

• Markdown files: .md, .mdx, .markdown
• Text files: .txt
• reStructuredText: .rst
• AsciiDoc: .adoc
• Org-mode: .org

Files are indexed as github_markdown document type in Supermemory.

Incremental sync with webhooks Copy Chapter

The GitHub connector automatically sets up webhooks for real-time incremental syncing. When files are pushed or deleted in configured repositories, Supermemory is notified immediately.

How it works Copy Section

1. Webhook Setup: When you set the selection, a webhook is automatically installed in each repository
2. Push Events: When commits are pushed to the default branch, changed documentation files are synced
3. Delete Events: When documentation files are deleted, they're removed from your Supermemory knowledge base
4. Incremental Updates: Only changed files are processed, keeping sync fast and efficient

Webhook security Copy Section

Webhooks are secured using HMAC-SHA256 signature validation with constant-time comparison. Supermemory automatically validates that webhook events come from GitHub before processing them. Each repository gets a unique webhook secret for maximum security.

console.log("Webhooks:", connector.capabilities.webhooks)
console.log("Last synced:", connector.system.lastSuccessfulSyncAt)
console.log("Last sync:", connector.latestRun?.system.status, connector.latestRun?.error)
console.log("Repositories:", connector.selection?.repos)
console.log("Recent runs:", connector.syncs)
```

print(f"Webhooks: {connector.capabilities.webhooks}")
print(f"Last synced: {connector.system.last_successful_sync_at}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")
if connector.latest_run and connector.latest_run.error:
    print(connector.latest_run.error)
repos = (connector.selection or {}).get("repos") or []
print(f"Repositories: {[r.name for r in repos]}")
print(f"Recent runs: {connector.syncs}")
```

Connector Management Copy Chapter

List All Connectors Copy Section

connectors
  .filter(connector => connector.provider === "github")
  .forEach(connector => {
    console.log(`Provider: ${connector.provider}`)
    console.log(`ID: ${connector.id}`)
    console.log(`Account: ${connector.account}`)
    console.log(`Created: ${connector.system.createdAt}`)
    console.log(`Document limit: ${connector.documentLimit}`)
    console.log(`Repositories: ${connector.selection?.repos?.length ?? 0}`)
    console.log("---")
  })
```

for connector in connectors:
    print(f"Provider: {connector.provider}")
    print(f"ID: {connector.id}")
    print(f"Account: {connector.account}")
    print(f"Created: {connector.system.created_at}")
    print(f"Document limit: {connector.document_limit}")
    repos = (connector.selection or {}).get("repos") or []
    print(f"Repositories: {len(repos)}")
    print("---")
```

Update Repository Selection Copy Section

You can update which repositories are synced at any time. The new selection replaces the old one and starts a sync.

console.log("Repository selection updated")
```

print("Repository selection updated")
```

Delete Connector Copy Section

// Delete the connector but keep the imported documents
await supermemory.connectors.delete("user-123", connectorId, {
  deleteDocuments: false,
})
```

# Delete the connector but keep the imported documents
client.connectors.delete("user-123", connector_id, delete_documents=False)
```

# Delete the connector but keep the imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

Manual sync Copy Section

Trigger a manual synchronization for all selected repositories. The call returns 409 while a sync for that connector is already running.

console.log(run.status)
// Output: queued
```

print(run.status)
# Output: queued
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
```

Advanced configuration Copy Chapter

Custom OAuth application Copy Section

For white-label deployments or custom branding you can connect with your own GitHub OAuth app. Custom OAuth credentials are an organization setting and are not part of the v5 connector routes. See Custom OAuth Applications.

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

const connector = await supermemory.connectors.create("user-123", {
  provider: "gmail",
  redirectUrl: "https://yourapp.com/auth/gmail/callback",
  documentLimit: 5000,
})

// Send the user to Google to authorize
if (connector.authorization) window.location.href = connector.authorization.url
console.log("Auth URL expires at:", connector.authorization?.expiresAt)
```

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "gmail",
        "redirect_url": "https://yourapp.com/auth/gmail/callback",
        "document_limit": 5000,
    },
)

# Send the user to Google to authorize
print(f"Redirect to: {connector.authorization.url}")
print(f"Auth URL expires at: {connector.authorization.expires_at}")
```

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }
```

console.log("Connected email:", connector.account)
console.log("Last sync:", connector.latestRun?.system.status)
console.log("Threads synced:", connector.documentCount)

// List synced email threads in the namespace
const docs = await supermemory.list("user-123", "documents")

console.log(`Synced ${docs.pagination.totalItems} email threads`)
```

print(f"Connected email: {connector.account}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")
print(f"Threads synced: {connector.document_count}")

# List synced email threads in the namespace
docs = client.list("user-123", "documents")

print(f"Synced {docs.pagination.total_items} email threads")
```

# List synced email threads in the namespace
curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

const results = await supermemory.search("user-123", {
  query: "project update",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "gmail_thread" },
      { field: "from", operator: "contains", value: "[email protected]" },
    ],
  },
  searchMode: "chunks",
})

connectors.forEach(connector => {
  console.log(`Provider: ${connector.provider}`)
  console.log(`ID: ${connector.id}`)
  console.log(`Account: ${connector.account}`)
  console.log(`Created: ${connector.system.createdAt}`)
  console.log(`Document limit: ${connector.documentLimit}`)
  console.log("---")
})
```

for connector in connectors:
    print(f"Provider: {connector.provider}")
    print(f"ID: {connector.id}")
    print(f"Account: {connector.account}")
    print(f"Created: {connector.system.created_at}")
    print(f"Document limit: {connector.document_limit}")
    print("---")
```

// Delete the connector but keep the imported documents
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})
```

# Delete the connector but keep the imported documents
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", delete_documents=False)
```

# Delete the connector but keep the imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

console.log(run.status)
// Output: queued
```

print(run.status)
# Output: queued
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
```

// Re-create the connector to get fresh tokens
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})

const next = await supermemory.connectors.create("user-123", {
  provider: "gmail",
  redirectUrl: "https://yourapp.com/auth/gmail/callback"
})

// User must re-authenticate
if (next.authorization) window.location.href = next.authorization.url

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

const connector = await supermemory.connectors.create("user-123", {
  provider: "google-drive",
  redirectUrl: "https://yourapp.com/auth/google-drive/callback",
  documentLimit: 3000,
  config: { syncScope: "selected" },
})

// Send the user to Google to authorize
if (connector.authorization) window.location.href = connector.authorization.url
console.log("Auth URL expires at:", connector.authorization?.expiresAt)
```

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "google-drive",
        "redirect_url": "https://yourapp.com/auth/google-drive/callback",
        "document_limit": 3000,
        "config": {"sync_scope": "selected"},
    },
)

# Send the user to Google to authorize
print(f"Redirect to: {connector.authorization.url}")
print(f"Auth URL expires at: {connector.authorization.expires_at}")
```

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }
```

if (connector.picker) window.location.href = connector.picker.url
```

# Response includes: "picker": { "url": "https://...", "expiresAt": "2024-01-15T11:30:00.000Z" }
```

console.log("Account:", connector.account)
console.log("Selection:", connector.selection)
console.log("Last sync:", connector.latestRun?.system.status)

// List synced documents in the namespace
const { documents } = await supermemory.list("user-123", "documents")
```

print(f"Account: {connector.account}")
print(f"Selection: {connector.selection}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")

# List synced documents in the namespace
documents = client.list("user-123", "documents").documents
```

# List synced documents in the namespace
curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

connectors.forEach(connector => {
  console.log(`Provider: ${connector.provider}`)
  console.log(`ID: ${connector.id}`)
  console.log(`Account: ${connector.account}`)
  console.log(`Created: ${connector.system.createdAt}`)
  console.log(`Document limit: ${connector.documentLimit}`)
  console.log("---")
})
```

for connector in connectors:
    print(f"Provider: {connector.provider}")
    print(f"ID: {connector.id}")
    print(f"Account: {connector.account}")
    print(f"Created: {connector.system.created_at}")
    print(f"Document limit: {connector.document_limit}")
    print("---")
```

# Response example:
# {
#   "connectors": [
#     {
#       "id": "PTzGiUYei7pgzg5buzZHgA",
#       "provider": "google-drive",
#       "namespace": "user-123",
#       "account": "[email protected]",
#       "documentLimit": 3000,
#       "documentCount": 120,
#       "latestRun": { "system": { "status": "completed", ... }, "error": null },
#       "system": { "status": "active", "createdAt": "2024-01-15T10:30:00.000Z", "lastSuccessfulSyncAt": "..." }
#     }
#   ],
#   "pagination": { "currentPage": 1, "limit": 10, "totalItems": 1, "totalPages": 1 }
# }
```

// Delete the connector but keep the imported documents
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})
```

# Delete the connector but keep the imported documents
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", delete_documents=False)
```

# Delete the connector but keep the imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

console.log(run.status)
// Output: queued
```

print(run.status)
# Output: queued
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
```

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

const connector = await supermemory.connectors.create("org-123", {
  provider: "granola",
  config: {
    apiKey: process.env.GRANOLA_API_KEY!,
  },
  documentLimit: 1000,
})

// Granola doesn't require OAuth; authorization is null and the first sync starts now
console.log("Granola connector:", connector.id)
```

client = Supermemory(api_key=os.environ["SUPERMEMORY_API_KEY"])

connector = client.connectors.create(
    "org-123",
    request={
        "provider": "granola",
        "config": {
            "api_key": os.environ["GRANOLA_API_KEY"],
        },
        "document_limit": 1000,
    },
)

# Granola doesn't require OAuth; authorization is None and the first sync starts now
print(f"Granola connector: {connector.id}")
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "authorization": null}
```

const results = await supermemory.search("org-123", {
  query: "customer onboarding discussion",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "granola" },
      { field: "attendees", operator: "arrayContains", value: "[email protected]" },
    ],
  },
  searchMode: "chunks",
})

console.log("Last sync:", connector.latestRun?.system.status, connector.latestRun?.error)
console.log("Notes synced:", connector.documentCount)
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
```

```python Python
from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.get(
    "user-123",
    connector_id,
    include=["picker"],
    return_url="https://yourapp.com/settings/integrations",
)

print(f"Picker URL: {connector.picker.url if connector.picker else None}")
print(f"Expires at: {connector.picker.expires_at if connector.picker else None}")
print(f"Selectable: {connector.capabilities.selectable}")

curl "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}?include=picker&returnUrl=https%3A%2F%2Fyourapp.com%2Fsettings%2Fintegrations" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

{
  "id": "PTzGiUYei7pgzg5buzZHgA",
  "provider": "github",
  "namespace": "user-123",
  "capabilities": { "selectable": true, "webhooks": true },
  "selection": {
    "repos": [
      { "id": "123456789", "name": "your-org/documentation" }
    ]
  },
  "picker": {
    "url": "https://...",
    "expiresAt": "2024-01-15T11:30:00.000Z"
  }
}

```python Python
from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.update(
    "user-123",
    connector_id,
    selection={"repos": ["123456789", "987654321"]},
)

print(f"Selection: {connector.selection}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")

curl -X PATCH "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "repos": ["123456789", "987654321"]
    }
  }'

{
  "selection": {
    "repos": ["123456789"]
  }
}

{
  "id": "PTzGiUYei7pgzg5buzZHgA",
  "provider": "github",
  "selection": {
    "repos": [
      { "id": "123456789", "name": "your-org/documentation" },
      { "id": "987654321", "name": "your-org/api-docs" }
    ]
  },
  "latestRun": { "errorCode": null, "error": null, "system": { "status": "running", "startedAt": "...", "completedAt": null } }
}

```python Python
# 1. Create the connector
created = client.connectors.create(
    "user-123",
    request={
        "provider": "github",
        "redirect_url": "https://yourapp.com/callback",
    },
)

# 2. Send the user to GitHub. After they authorize, Supermemory shows the hosted
#    repository picker, then returns them to redirect_url
print(f"Redirect to: {created.authorization.url}")

# 3. To change repositories later, open the hosted picker again
connector = client.connectors.get(
    "user-123",
    created.id,
    include=["picker"],
    return_url="https://yourapp.com/settings/integrations",
)
if connector.picker:
    print(f"Redirect to: {connector.picker.url}")

# 4. Or, if you already know the repository ids, set them directly
client.connectors.update(
    "user-123",
    created.id,
    selection={"repos": selected_repository_ids},
)

# 1. Create the connector
curl -X POST "https://api.supermemory.ai/ns/user-123/connectors" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "github", "redirectUrl": "https://yourapp.com/callback"}'

# 2. ... (user authorizes at authorization.url and picks repositories in the hosted picker) ...

# 3. To change repositories later, get a one-time hosted picker URL
curl "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}?include=picker" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# 4. Or set the repositories directly
curl -X PATCH "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "repos": ["123456789"]
    }
  }'

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

const connector = await supermemory.connectors.create("user-123", {
  provider: "notion",
  redirectUrl: "https://yourapp.com/auth/notion/callback",
  documentLimit: 2000,
})

// Send the user to Notion to authorize
if (connector.authorization) window.location.href = connector.authorization.url
```

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "notion",
        "redirect_url": "https://yourapp.com/auth/notion/callback",
        "document_limit": 2000,
    },
)

# Send the user to Notion to authorize
print(f"Redirect to: {connector.authorization.url}")
```

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }
```

console.log("Connected workspace:", connector.account)
console.log("Last sync:", connector.latestRun?.system.status)
console.log("Documents synced:", connector.documentCount)

// List synced pages and databases
const { documents } = await supermemory.list("user-123", "documents")
```

print(f"Connected workspace: {connector.account}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")
print(f"Documents synced: {connector.document_count}")

# List synced pages and databases
documents = client.list("user-123", "documents").documents
```

# Response includes connector details:
# {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "provider": "notion",
#   "namespace": "user-123",
#   "account": "[email protected]",
#   "documentLimit": 2000,
#   "documentCount": 120,
#   "latestRun": { "system": { "status": "completed", ... }, "error": null },
#   "system": { "status": "active", "createdAt": "2024-01-15T10:00:00Z", "lastSuccessfulSyncAt": "2024-01-15T10:30:00Z" },
#   "syncs": [...]
# }

# List synced documents in the namespace
curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Response: {"documents": [{"title": "Product Roadmap", "system": {"status": "done", ...}, ...}], "pagination": {...}}
```

console.log(run.status)
// Output: queued
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
# 409 if a sync is already running
```

// Delete the connector but keep the imported documents
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})
```

# Delete the connector but keep the imported documents
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", delete_documents=False)
```

# Delete the connector but keep the imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"
```

// List documents in the namespace (there is no per-connector document list in v5)
const { documents } = await supermemory.list("user-123", "documents")

// Find database entries by a property value
const projectEntries = documents.filter(doc =>
  doc.metadata?.notion_prop_status === "In Progress"
)

// Database properties become searchable metadata
const projectWithStatus = await supermemory.search("user-123", {
  query: "machine learning project",
  filter: {
    operator: "and",
    operands: [
      { field: "notion_prop_status", operator: "eq", value: "In Progress" },
      { field: "notion_prop_priority", operator: "eq", value: "High" },
    ],
  },
  searchMode: "chunks",
})

import { Supermemory } from "supermemory"

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

const connector = await supermemory.connectors.create("user-123", {
  provider: "onedrive",
  redirectUrl: "https://yourapp.com/auth/onedrive/callback",
  documentLimit: 1500,
})

// Send the user to Microsoft to authorize
if (connector.authorization) window.location.href = connector.authorization.url
// Output: Redirects to https://api.supermemory.ai/v3/connections/auth/redirect?state=...

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "onedrive",
        "redirect_url": "https://yourapp.com/auth/onedrive/callback",
        "document_limit": 1500,
    },
)

# Send the user to Microsoft to authorize
print(f"Redirect to: {connector.authorization.url}")
# Output: Redirect to: https://api.supermemory.ai/v3/connections/auth/redirect?state=...

curl -X POST "https://api.supermemory.ai/ns/user-123/connectors" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "onedrive",
    "redirectUrl": "https://yourapp.com/auth/onedrive/callback",
    "documentLimit": 1500
  }'

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }

console.log("Account:", connector.account)
console.log("Last sync:", connector.latestRun?.system.status)
console.log("Documents synced:", connector.documentCount)

// List synced Office documents in the namespace
const { documents } = await supermemory.list("user-123", "documents")
```

# Check connector details with recent sync runs
  connector = client.connectors.get("user-123", "PTzGiUYei7pgzg5buzZHgA", include=["syncs"])

  print(f"Account: {connector.account}")
  print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")
  print(f"Documents synced: {connector.document_count}")

  # List synced Office documents in the namespace
  documents = client.list("user-123", "documents").documents
  ```
```bash cURL
  # Get connector details with recent sync runs
  curl "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?include=syncs" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

  # List synced Office documents in the namespace
  curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

<Note>
There is no per-connector document list in v5. `supermemory.list(namespace, "documents")` returns every document in the namespace.
</Note>

## Supported document types

### Microsoft Word documents
- **Rich text formatting** converted to markdown
- **Headers and styles** preserved as markdown hierarchy
- **Images and charts** extracted and referenced
- **Tables** converted to markdown tables

### Excel spreadsheets
- **Worksheet data** converted to structured markdown
- **Multiple sheets** processed separately
- **Charts and graphs** extracted as images
- **Formulas** converted to calculated values
- **Cell formatting** simplified in markdown

### PowerPoint presentations
- **Slide content** converted to structured markdown
- **Speaker notes** included when present
- **Images and media** extracted and referenced
- **Embedded objects** processed when possible

## Sync mechanism

Webhooks lead to real-time syncing of changes in documents. You may also manually trigger a sync.

### Manual sync trigger

The call returns `409` while a sync for that connector is already running.

<CodeGroup>
```typescript Typescript
  const run = await supermemory.connectors.sync("user-123", "PTzGiUYei7pgzg5buzZHgA")

  console.log(run.status)
  // Output: queued
  ```
```python Python
  run = client.connectors.sync("user-123", "PTzGiUYei7pgzg5buzZHgA")

  print(run.status)
  # Output: queued
  ```
```bash cURL
  curl -X POST "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA/sync" \
    -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

  # Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
  ```
</CodeGroup>

## Delete Connector

Remove a OneDrive connector when no longer needed:

<CodeGroup>

```typescript Typescript
// Delete the connector and its imported documents (default)
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA")

// Delete the connector but keep the imported documents
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
deleteDocuments: false,
})

# Delete the connector and its imported documents (default)
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA")

# Delete the connector but keep the imported documents
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", delete_documents=False)

# Delete the connector and its imported documents (default)
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Delete the connector but keep the imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

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

const connector = await supermemory.connectors.create("org-123", {
  provider: "s3",
  config: {
    bucket: "my-documents-bucket",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
})

// S3 doesn't require OAuth; authorization is null and the first sync starts now
console.log("Connector ID:", connector.id)
```

client = Supermemory(api_key=os.environ["SUPERMEMORY_API_KEY"])

connector = client.connectors.create(
    "org-123",
    request={
        "provider": "s3",
        "config": {
            "bucket": "my-documents-bucket",
            "region": "us-east-1",
            "access_key_id": os.environ["AWS_ACCESS_KEY_ID"],
            "secret_access_key": os.environ["AWS_SECRET_ACCESS_KEY"],
        },
    },
)

# S3 doesn't require OAuth; authorization is None and the first sync starts now
print(f"Connector ID: {connector.id}")
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "authorization": null}
```

// MinIO
const connector = await supermemory.connectors.create("minio-sync", {
  provider: "s3",
  config: {
    bucket: "my-bucket",
    region: "auto",
    accessKeyId: "minio-key",
    secretAccessKey: "minio-secret",
    endpoint: "https://minio.example.com",
  },
})

const connector = await supermemory.connectors.create("r2-sync", {
  provider: "s3",
  config: {
    bucket: "my-bucket",
    region: "auto",
    accessKeyId: process.env.R2_ACCESS_KEY_ID!,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
    endpoint: "https://<account-id>.r2.cloudflarestorage.com",
  },
})

const connector = await supermemory.connectors.create("engineering-docs", {
  provider: "s3",
  config: {
    bucket: "company-data",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    prefix: "documents/engineering/", // Only syncs files under this path
  },
})

await supermemory.connectors.create("user-123", {
  provider: "s3",
  config: {
    bucket: "user-files",
    region: "us-east-1",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    prefix: "users/user-123/",
  },
})

console.log("Bucket:", connector.config?.bucket)
console.log("Last sync:", connector.latestRun?.system.status, connector.latestRun?.error)
console.log("Files synced:", connector.documentCount)
```

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}
```