Search - Supermemory

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>

Quick Start

<Tabs> <Tab title="TypeScript"> ```typescript import Supermemory from 'supermemory';

const client = new Supermemory();

const results = await client.search.memories({
  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 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 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

{
  "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	`"hybrid"`	`"hybrid"` (recommended) or `"memories"`
`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)
`filters`	object	—	Metadata filters (`AND`/`OR` structure)

Search Modes

hybrid (recommended) — Searches both memories and document chunks, returns the most relevant
memories — Only searches extracted memories

typescript

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

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

Filtering

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

typescript

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

Use filters for metadata-based filtering:

typescript

const results = await client.search.memories({
  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 for full syntax. </Accordion>

Query Optimization

Reranking

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

typescript

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

Threshold

Control result quality vs quantity:

typescript

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

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

Chatbot Example

Optimal configuration for conversational AI:

typescript

async function getContext(userId: string, message: string) {
  const results = await client.search.memories({
    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 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](/add-memories) — Add content to search
- [User Profiles](/user-profiles) — Get user context with search
- [Organizing & Filtering](/concepts/filtering) — Container tags and metadata