Memories Search (/v4/search)

Memories search (POST /v4/search) provides minimal-latency search optimized for real-time interactions. This endpoint prioritizes speed over extensive control, making it perfect for chatbots, Q&A systems, and any application where users expect immediate responses.

Basic Search

TypeScript
Python
cURL

import Supermemory from 'supermemory';

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

const results = await client.search.memories({
  q: "machine learning applications",
  limit: 5
});

console.log(results)

from supermemory import Supermemory
import os

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

results = client.search.memories(
    q="machine learning applications",
    limit=5
)

console.log(results)

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

Sample Output:

{
  "results": [
    {
      "id": "mem_ml_apps_2024",
      "memory": "Machine learning applications span numerous industries including healthcare (diagnostic imaging, drug discovery), finance (fraud detection, algorithmic trading), autonomous vehicles (computer vision, path planning), and natural language processing (chatbots, translation services).",
      "similarity": 0.92,
      "title": "Machine Learning Industry Applications",
      "type": "text",
      "metadata": {
        "topic": "machine-learning",
        "industry": "technology",
        "created": "2024-01-10"
      }
    },
    {
      "id": "mem_ml_healthcare",
      "memory": "In healthcare, machine learning enables early disease detection through medical imaging analysis, personalized treatment recommendations, and drug discovery acceleration by predicting molecular behavior.",
      "similarity": 0.89,
      "title": "ML in Healthcare",
      "type": "text"
    }
  ],
  "total": 8,
  "timing": 87
}

Container Tag Filtering

Filter by user, project, or organization:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "project updates",
  containerTag: "user_123",  // Note: singular, not plural
  limit: 10
});

results = client.search.memories(
    q="project updates",
    container_tag="user_123",  # Note: singular, not plural
    limit=10
)

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

Threshold Control

Control result quality with similarity threshold:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "artificial intelligence research",
  threshold: 0.7,  // Higher = fewer, more similar results
  limit: 10
});

results = client.search.memories(
    q="artificial intelligence research",
    threshold=0.7,  # Higher = fewer, more similar results
    limit=10
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "artificial intelligence research",
    "threshold": 0.7,
    "limit": 10
  }'

Reranking

Improve result quality with secondary ranking:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "quantum computing breakthrough",
  rerank: true,  // Better relevance, slight latency increase
  limit: 5
});

results = client.search.memories(
    q="quantum computing breakthrough",
    rerank=True,  # Better relevance, slight latency increase
    limit=5
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "quantum computing breakthrough",
    "rerank": true,
    "limit": 5
  }'

Query Rewriting

Improve search accuracy with automatic query expansion:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "How do neural networks learn?",
  rewriteQuery: true,  // +400ms latency but better results
  limit: 5
});

results = client.search.memories(
    q="How do neural networks learn?",
    rewrite_query=True,  # +400ms latency but better results
    limit=5
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "How do neural networks learn?",
    "rewriteQuery": true,
    "limit": 5
  }'

Include documents, related memories, and summaries:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "machine learning trends",
  include: {
    documents: true,        // Include source documents
    relatedMemories: true,  // Include related memory entries
    summaries: true         // Include memory summaries
  },
  limit: 5
});

results = client.search.memories(
    q="machine learning trends",
    include={
        "documents": True,        # Include source documents
        "relatedMemories": True,  # Include related memory entries
        "summaries": True         # Include memory summaries
    },
    limit=5
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "machine learning trends",
    "include": {
      "documents": true,
      "relatedMemories": true,
      "summaries": true
    },
    "limit": 5
  }'

Metadata Filtering

Simple metadata filtering for Memories search:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "research findings",
  filters: {
    AND: [
      { key: "category", value: "science", negate: false },
      { key: "status", value: "published", negate: false }
    ]
  },
  limit: 10
});

results = client.search.memories(
    q="research findings",
    filters={
        "AND": [
            {"key": "category", "value": "science", "negate": False},
            {"key": "status", "value": "published", "negate": False}
        ]
    },
    limit=10
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "research findings",
    "filters": {
      "AND": [
        {"key": "category", "value": "science", "negate": false},
        {"key": "status", "value": "published", "negate": false}
      ]
    },
    "limit": 10
  }'

Chatbot Example

Optimal configuration for conversational AI:

TypeScript
Python
cURL

// Optimized for chatbot responses
const results = await client.search.memories({
  q: userMessage,
  containerTag: userId,
  threshold: 0.6,     // Balanced relevance
  rerank: false,      // Skip for speed
  rewriteQuery: false, // Skip for speed
  limit: 3            // Few, relevant results
});

// Quick response for chat
const context = results.results
  .map(r => r.memory)
  .join('\n\n');

# Optimized for chatbot responses
results = client.search.memories(
    q=user_message,
    container_tag=user_id,
    threshold=0.6,     # Balanced relevance
    rerank=False,      # Skip for speed
    rewrite_query=False, # Skip for speed
    limit=3            # Few, relevant results
)

# Quick response for chat
context = '\n\n'.join([r.memory for r in results.results])

# Optimized for chatbot responses
curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "user question here",
    "containerTag": "user_123",
    "threshold": 0.6,
    "rerank": false,
    "rewriteQuery": false,
    "limit": 3
  }'

Complete Memories Search Example

Combining features for comprehensive results:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "machine learning model performance",
  containerTag: "research_team",
  filters: {
    AND: [
      { key: "topic", value: "ai", negate: false }
    ]
  },
  threshold: 0.7,
  rerank: true,
  rewriteQuery: false, // Skip for speed
  include: {
    documents: true,
    relatedMemories: false,
    summaries: true
  },
  limit: 5
});

results = client.search.memories(
    q="machine learning model performance",
    container_tag="research_team",
    filters={
        "AND": [
            {"key": "topic", "value": "ai", "negate": False}
        ]
    },
    threshold=0.7,
    rerank=True,
    rewrite_query=False,  # Skip for speed
    include={
        "documents": True,
        "relatedMemories": False,
        "summaries": True
    },
    limit=5
)

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "machine learning model performance",
    "containerTag": "research_team",
    "filters": {
      "AND": [
        {"key": "topic", "value": "ai", "negate": false}
      ]
    },
    "threshold": 0.7,
    "rerank": true,
    "rewriteQuery": false,
    "include": {
      "documents": true,
      "relatedMemories": false,
      "summaries": true
    },
    "limit": 5
  }'

Hybrid Search Mode

Hybrid search mode allows you to search both memories and document chunks in a single request. When searchMode="hybrid", results contain objects with either a memory key (for memory results) or a chunk key (for chunk results).

Basic Hybrid Search

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "machine learning best practices",
  searchMode: "hybrid",  // Search memories + chunks
  limit: 10
});

// Handle mixed results
results.results.forEach(result => {
  if ('memory' in result) {
    console.log('Memory:', result.memory);
  } else if ('chunk' in result) {
    console.log('Chunk:', result.chunk);
    console.log('From document:', result.documents?.[0]?.title);
  }
});

results = client.search.memories(
    q="machine learning best practices",
    search_mode="hybrid",  # Search memories + chunks
    limit=10
)

# Handle mixed results
for result in results.results:
    if 'memory' in result:
        print('Memory:', result['memory'])
    elif 'chunk' in result:
        print('Chunk:', result['chunk'])
        print('From document:', result.get('documents', [{}])[0].get('title'))

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

When to Use Hybrid Mode

Use hybrid mode when:

You want comprehensive search across both memories and documents
Memories might not exist for certain queries but document content is available
You need flexibility to get either memory or document chunk results
You want a single search endpoint that covers all content types

Use memories-only mode (searchMode="memories") when:

You only need user memories and preferences
You want faster, more focused results
You’re building a personalized chatbot that relies on user context

Handling Mixed Results

When using hybrid mode, you’ll receive mixed results. Here’s how to process them:

TypeScript
Python

const results = await client.search.memories({
  q: "quantum computing applications",
  searchMode: "hybrid",
  limit: 10
});

// Separate memory and chunk results
const memoryResults = results.results.filter(r => 'memory' in r);
const chunkResults = results.results.filter(r => 'chunk' in r);

console.log(`Found ${memoryResults.length} memories and ${chunkResults.length} chunks`);

// Process memories
memoryResults.forEach(mem => {
  console.log('Memory:', mem.memory);
  console.log('Similarity:', mem.similarity);
});

// Process chunks
chunkResults.forEach(chunk => {
  console.log('Chunk:', chunk.chunk);
  console.log('Document:', chunk.documents?.[0]?.title);
  console.log('Similarity:', chunk.similarity);
});

results = client.search.memories(
    q="quantum computing applications",
    search_mode="hybrid",
    limit=10
)

# Separate memory and chunk results
memory_results = [r for r in results.results if 'memory' in r]
chunk_results = [r for r in results.results if 'chunk' in r]

print(f"Found {len(memory_results)} memories and {len(chunk_results)} chunks")

# Process memories
for mem in memory_results:
    print('Memory:', mem['memory'])
    print('Similarity:', mem['similarity'])

# Process chunks
for chunk in chunk_results:
    print('Chunk:', chunk['chunk'])
    print('Document:', chunk.get('documents', [{}])[0].get('title'))
    print('Similarity:', chunk['similarity'])

Hybrid Search with All Features

Combining hybrid mode with other features:

TypeScript
Python
cURL

const results = await client.search.memories({
  q: "research findings on AI",
  searchMode: "hybrid",
  containerTag: "research_team",
  threshold: 0.7,
  rerank: true,
  include: {
    documents: true,
    relatedMemories: true,
    summaries: true
  },
  limit: 10
});

// Results are automatically sorted by similarity
// Memory results have 'memory' field, chunk results have 'chunk' field
results.results.forEach(result => {
  if ('memory' in result) {
    // Memory result
    console.log('Memory:', result.memory);
    console.log('Context:', result.context);
  } else {
    // Chunk result
    console.log('Chunk:', result.chunk);
    console.log('Document:', result.documents?.[0]);
  }
});

results = client.search.memories(
    q="research findings on AI",
    search_mode="hybrid",
    container_tag="research_team",
    threshold=0.7,
    rerank=True,
    include={
        "documents": True,
        "relatedMemories": True,
        "summaries": True
    },
    limit=10
)

# Results are automatically sorted by similarity
# Memory results have 'memory' field, chunk results have 'chunk' field
for result in results.results:
    if 'memory' in result:
        # Memory result
        print('Memory:', result['memory'])
        print('Context:', result.get('context'))
    else:
        # Chunk result
        print('Chunk:', result['chunk'])
        print('Document:', result.get('documents', [{}])[0])

curl -X POST "https://api.supermemory.ai/v4/search" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "research findings on AI",
    "searchMode": "hybrid",
    "containerTag": "research_team",
    "threshold": 0.7,
    "rerank": true,
    "include": {
      "documents": true,
      "relatedMemories": true,
      "summaries": true
    },
    "limit": 10
  }'

Important: In hybrid mode, results are automatically merged and sorted by similarity score. Memory results and chunk results are deduplicated - if a chunk is already associated with a memory result, it won’t appear as a separate chunk result.

Common Use Cases

Chatbots: Basic search with container tag and low threshold
Q&A Systems: Add reranking for better relevance
Knowledge Retrieval: Include documents and summaries
Real-time Search: Skip rewriting and reranking for maximum speed
Hybrid Search: Use searchMode="hybrid" when you need comprehensive search across both memories and documents

Getting Started

Memory API

User Profiles

Memory Router

Integrations with no-code tools

Migration Guides

Deployment

Basic Search

Container Tag Filtering

Threshold Control

Reranking

Query Rewriting

Metadata Filtering

Chatbot Example

Complete Memories Search Example

Hybrid Search Mode

Basic Hybrid Search

When to Use Hybrid Mode

Handling Mixed Results

Hybrid Search with All Features

Common Use Cases

Getting Started

Memory API

User Profiles

Memory Router

Integrations with no-code tools

Migration Guides

Deployment

​Basic Search

​Container Tag Filtering

​Threshold Control

​Reranking

​Query Rewriting

​Include Related Content

​Metadata Filtering

​Chatbot Example

​Complete Memories Search Example

​Hybrid Search Mode

​Basic Hybrid Search

​When to Use Hybrid Mode

​Handling Mixed Results

​Hybrid Search with All Features

​Common Use Cases

Basic Search

Container Tag Filtering

Threshold Control

Reranking

Query Rewriting

Include Related Content

Metadata Filtering

Chatbot Example

Complete Memories Search Example

Hybrid Search Mode

Basic Hybrid Search

When to Use Hybrid Mode

Handling Mixed Results

Hybrid Search with All Features

Common Use Cases