> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Semantic search across your memories and documents

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

<Tip>
  **Use `searchMode: "hybrid"`** for best results. It searches both memories and document chunks, returning the most relevant content.
</Tip>

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

## Quick Start

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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
      }'
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "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
}
```

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

***

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

```typescript theme={null}
// 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:

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

Use `filters` for metadata-based filtering:

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

<Accordion title="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](/docs/concepts/filtering) for full syntax.
</Accordion>

***

## Query Optimization

### Reranking

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

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

### Threshold

Control result quality vs quantity:

```typescript theme={null}
// 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:

```typescript theme={null}
await client.search({
  q: "old project notes",
  include: { forgottenMemories: true }
});
```

***

## Chatbot Example

Optimal configuration for conversational AI:

```typescript theme={null}
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');
}
```

<Accordion title="Response Schema">
  ```typescript theme={null}
  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;
  }
  ```
</Accordion>

***

## Next Steps

* [Ingesting Content](/docs/ingestion/add-memories) — Add content to search
* [User Profiles](/docs/recall/user-profiles) — Get user context with search
* [Organizing & Filtering](/docs/concepts/filtering) — Container tags and metadata