Search

Search through your memories and documents with a single API call. Each search runs inside one namespace (what v3/v4 called a container tag).

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

SDKs: one call, supermemory.search(namespace, { query, searchMode }) in TypeScript or client.search(namespace, query=..., search_mode=...) in Python. searchMode ("memories", "chunks", or "hybrid") picks what comes back.

Quick start

TypeScript
Python
cURL

import { Supermemory } from "supermemory";

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

const results = await supermemory.search("user_123", {
  query: "machine learning",
  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(
    "user_123",
    query="machine learning",
    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/ns/user_123/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "machine learning", "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" },
      "isLatest": true,
      "isInference": false,
      "system": { "createdAt": "2024-01-15T10:30:00.000Z", "updatedAt": "2024-01-15T10:30:00.000Z" }
    },
    {
      "id": "chunk_abc",
      "chunk": "Machine learning enables personalized experiences at scale...",
      "similarity": 0.87,
      "metadata": { "source": "onboarding_doc" },
      "isLatest": true,
      "isInference": false,
      "system": { "createdAt": "2024-01-14T09:15:00.000Z", "updatedAt": "2024-01-14T09:15:00.000Z" }
    }
  ],
  "searchTime": 92
}

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

Parameters

namespace is the URL path. Every other option goes in the JSON body: the second argument in TypeScript, or keyword arguments in Python. Search takes no query-string parameters; sending any returns 400.

Parameter	Type	Default	Description
`namespace`	string	required	Namespace to search (URL path)
`query`	string	required	Search query
`searchMode`	string	`"hybrid"`	`"hybrid"` (recommended), `"memories"`, or `"chunks"`
`limit`	number	10	Max results (max 100)
`threshold`	0-1	0.3	Similarity cutoff (higher = fewer, better results)
`rerank`	string	`"none"`	`"none"`, `"order"` (re-score for relevance, +100ms), or `"aggregate"`. Successful reranking or aggregation can bill one extra operation; setting the option alone does not guarantee it runs
`rewriteQuery`	boolean	false	Generate multiple rewrites, search all of them, and merge results. Adds latency and can bill one extra operation when rewriting runs successfully
`filter`	object	—	Metadata filter expression. See Filtering
`include`	object	all `false`	`{ documents, related, forgotten }` — opt in to extra context per result

Defaults changed from v4: searchMode was memories and is now hybrid; threshold was 0.6 and is now 0.3. Set both explicitly if you are comparing against v4 results.

Search modes

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

// Hybrid: memories + document chunks (default)
await supermemory.search("user_123", {
  query: "quarterly goals",
});

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

// Chunks only: RAG over documents
await supermemory.search("user_123", {
  query: "refund policy",
  searchMode: "chunks",
});

Filtering

The namespace scopes results to a user or project. Use filter for metadata-based filtering inside that namespace:

const results = await supermemory.search("user_123", {
  query: "meeting notes",
  filter: {
    operator: "and",
    operands: [
      { field: "type", operator: "eq", value: "meeting" },
      { field: "year", operator: "eq", value: 2024 },
    ],
  },
});

Filter Types

Equality: { field: "status", operator: "eq", value: "active" } (also neq; strings, numbers, booleans)
String contains: { field: "title", operator: "contains", value: "react" } (also notContains; optional caseSensitive)
Numeric: { field: "priority", operator: "gte", value: 5 } (gt, gte, lt, lte)
Array contains: { field: "tags", operator: "arrayContains", value: "important" } (also arrayNotContains)
Logic: { operator: "and" | "or", operands: [...] }, nested up to 5 levels

Keys are literal: customer.plan is one field name, not a nested path. See Organizing & Filtering for full syntax.

Query optimization

Reranking

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

const results = await supermemory.search("user_123", {
  query: "complex technical question",
  rerank: "order",
});

Threshold

Control result quality vs quantity:

// Broad search — more results
await supermemory.search("user_123", { query: "...", threshold: 0.3 });

// Precise search — fewer, better results
await supermemory.search("user_123", { query: "...", threshold: 0.8 });

Attachments

include.documents adds the most recently updated source document to each result when one is available.
include.related adds parent, child, and sibling memories (see graph memory).
include.forgotten lets forgotten and expired memories appear in results. By default, search excludes memories that have been forgotten or have passed their forgetAfter expiration.

await supermemory.search("user_123", {
  query: "old project notes",
  include: { related: true, forgotten: true },
  searchMode: "memories",
});

Attached context arrives under result.included (included.document, included.related.{parents,children,siblings}).

Chatbot example

Optimal configuration for conversational AI:

async function getContext(userId: string, message: string) {
  const results = await supermemory.search(userId, {
    query: message,
    threshold: 0.6,
    searchMode: "hybrid",
    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: Record<string, unknown>; // {} when none
  isLatest: boolean;
  isInference: boolean;   // false for chunks
  system: { createdAt?: string; updatedAt: string };
  included?: {            // Only when you pass include
    document?: object;
    related?: { parents: object[]; children: object[]; siblings: object[] };
  };
}

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

Next steps

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

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Quick start

Parameters

Search modes

Filtering

Query optimization

Reranking

Threshold

Attachments

Chatbot example

Next steps

​Quick start

​Parameters

​Search modes

​Filtering

​Query optimization

​Reranking

​Threshold

​Attachments

​Chatbot example

​Next steps

Quick start

Parameters

Search modes

Filtering

Query optimization

Reranking

Threshold

Attachments

Chatbot example

Next steps