supermemory/apps/docs/search/examples/memory-search.mdx

---
title: "Memories Search (/v4/search)"
description: "Minimal-latency search optimized for chatbots and conversational AI"
---


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

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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)
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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)
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

**Sample Output:**
```json
{
  "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:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.memories({
      q: "project updates",
      containerTag: "user_123",  // Note: singular, not plural
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.memories(
        q="project updates",
        container_tag="user_123",  # Note: singular, not plural
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Threshold Control

Control result quality with similarity threshold:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.memories({
      q: "artificial intelligence research",
      threshold: 0.7,  // Higher = fewer, more similar results
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.memories(
        q="artificial intelligence research",
        threshold=0.7,  # Higher = fewer, more similar results
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Reranking

Improve result quality with secondary ranking:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.memories({
      q: "quantum computing breakthrough",
      rerank: true,  // Better relevance, slight latency increase
      limit: 5
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.memories(
        q="quantum computing breakthrough",
        rerank=True,  # Better relevance, slight latency increase
        limit=5
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Query Rewriting

Improve search accuracy with automatic query expansion:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.memories({
      q: "How do neural networks learn?",
      rewriteQuery: true,  // +400ms latency but better results
      limit: 5
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.memories(
        q="How do neural networks learn?",
        rewrite_query=True,  # +400ms latency but better results
        limit=5
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Include Related Content

Include documents, related memories, and summaries:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Metadata Filtering

Simple metadata filtering for Memories search:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.memories(
        q="research findings",
        filters={
            "AND": [
                {"key": "category", "value": "science", "negate": False},
                {"key": "status", "value": "published", "negate": False}
            ]
        },
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## Chatbot Example

Optimal configuration for conversational AI:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    // 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');
    ```
  </Tab>
  <Tab title="Python">
    ```python
    # 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])
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    # 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
      }'
    ```
  </Tab>
</Tabs>

## Complete Memories Search Example

Combining features for comprehensive results:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

## 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

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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);
      }
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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'))
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

### 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:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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);
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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'])
    ```
  </Tab>
</Tabs>

### Hybrid Search with All Features

Combining hybrid mode with other features:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    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]);
      }
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    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])
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    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
      }'
    ```
  </Tab>
</Tabs>

<Note>
  **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.
</Note>

## 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