Search

Search through your memories and documents with a single API call.

Use searchMode: "hybrid" for best results. It searches both memories and document chunks, returning the most relevant content.

TypeScript SDK: call client.search({ q, searchMode }) directly — searchMode ("memories", "documents", or "hybrid") picks what comes back. client.search.memories() and client.search.documents() still work but are deprecated; no migration is required, just use client.search() going forward. The Python SDK is unaffected — client.search.memories() remains the call there.

Quick Start

TypeScript
Python
cURL

import Supermemory from 'supermemory';

const client = new Supermemory();

const results = await client.search({
  q: "machine learning",
  containerTag: "user_123",
  searchMode: "hybrid",
  limit: 5
});

results.results.forEach(result => {
  console.log(result.memory || result.chunk, result.similarity);
});

from supermemory import Supermemory

client = Supermemory()

results = client.search.memories(
    q="machine learning",
    container_tag="user_123",
    search_mode="hybrid",
    limit=5
)

for result in results.results:
    print(result.memory or result.chunk, result.similarity)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "machine learning",
    "containerTag": "user_123",
    "searchMode": "hybrid",
    "limit": 5
  }'

Response:

{
  "results": [
    {
      "id": "mem_xyz",
      "memory": "User is interested in machine learning for product recommendations",
      "similarity": 0.91,
      "metadata": { "topic": "interests" },
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "version": 1
    },
    {
      "id": "chunk_abc",
      "chunk": "Machine learning enables personalized experiences at scale...",
      "similarity": 0.87,
      "metadata": { "source": "onboarding_doc" },
      "updatedAt": "2024-01-14T09:15:00.000Z",
      "version": 1
    }
  ],
  "timing": 92,
  "total": 5
}

In hybrid mode, results contain either a memory field (extracted facts) or a chunk field (document content), depending on the source.

Parameters

Parameter	Type	Default	Description
`q`	string	required	Search query
`containerTag`	string	—	Filter by user/project
`searchMode`	string	`"memories"`	`"memories"`, `"hybrid"` (recommended), or `"documents"`
`limit`	number	10	Max results
`threshold`	0-1	0.5	Similarity cutoff (higher = fewer, better results)
`rerank`	boolean	false	Re-score for better relevance (+100ms)
`rewriteQuery`	boolean	false	Generate multiple rewrites, search all of them, and merge results. No extra cost, but adds latency. Composes with filtering, hybrid search, and recency bias
`filters`	object	—	Metadata filters (`AND`/`OR` structure)
`include`	object	—	`{ documents, summaries, relatedMemories, forgottenMemories }` — opt in to extra context per result

Search Modes

hybrid (recommended) — Searches both memories and document chunks, and returns both in the response
memories — Only searches extracted memories
documents — Only searches raw document/chunk content, skipping extracted memories

// Hybrid: memories + document chunks (recommended)
await client.search({
  q: "quarterly goals",
  containerTag: "user_123",
  searchMode: "hybrid"
});

// Memories only: just extracted facts
await client.search({
  q: "user preferences",
  containerTag: "user_123",
  searchMode: "memories"
});

Filtering

Filter by containerTag to scope results to a user or project:

const results = await client.search({
  q: "project updates",
  containerTag: "user_123",
  searchMode: "hybrid"
});

Use filters for metadata-based filtering:

const results = await client.search({
  q: "meeting notes",
  containerTag: "user_123",
  filters: {
    AND: [
      { key: "type", value: "meeting" },
      { key: "year", value: "2024" }
    ]
  }
});

Filter Types

String equality: { key: "status", value: "active" }
String contains: { filterType: "string_contains", key: "title", value: "react" }
Numeric: { filterType: "numeric", key: "priority", value: "5", numericOperator: ">=" }
Array contains: { filterType: "array_contains", key: "tags", value: "important" }
Negate: { key: "status", value: "draft", negate: true }

See Organizing & Filtering for full syntax.

Query Optimization

Reranking

Re-scores results for better relevance. Adds ~100ms latency.

const results = await client.search({
  q: "complex technical question",
  containerTag: "user_123",
  rerank: true
});

Threshold

Control result quality vs quantity:

// Broad search — more results
await client.search({ q: "...", threshold: 0.3 });

// Precise search — fewer, better results
await client.search({ q: "...", threshold: 0.8 });

Including Forgotten Memories

By default, search excludes memories that have been forgotten or have passed their forgetAfter expiration. Set include.forgottenMemories to true to recover them:

await client.search({
  q: "old project notes",
  include: { forgottenMemories: true }
});

Chatbot Example

Optimal configuration for conversational AI:

async function getContext(userId: string, message: string) {
  const results = await client.search({
    q: message,
    containerTag: userId,
    searchMode: "hybrid",
    threshold: 0.6,
    limit: 5
  });

  return results.results
    .map(r => r.memory || r.chunk)
    .join('\n\n');
}

Response Schema

interface SearchResult {
  id: string;
  memory?: string;        // Present for memory results
  chunk?: string;         // Present for document chunk results
  similarity: number;     // 0-1
  metadata: object | null;
  updatedAt: string;
  version: number;
}

interface SearchResponse {
  results: SearchResult[];
  timing: number;         // ms
  total: number;
}

Next Steps

Ingesting Content — Add content to search
User Profiles — Get user context with search
Organizing & Filtering — Container tags and metadata

Getting Started

Concepts

Using supermemory

Deployment

Other resources

Migration Guides

Quick Start

Parameters

Search Modes

Filtering

Query Optimization

Reranking

Threshold

Including Forgotten Memories

Chatbot Example

Next Steps

​Quick Start

​Parameters

​Search Modes

​Filtering

​Query Optimization

​Reranking

​Threshold

​Including Forgotten Memories

​Chatbot Example

​Next Steps

Quick Start

Parameters

Search Modes

Filtering

Query Optimization

Reranking

Threshold

Including Forgotten Memories

Chatbot Example

Next Steps