mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-05-17 12:20:04 +00:00
87b361c26b
Some checks failed
Publish AI SDK / publish (push) Has been cancelled
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
264 lines
8.3 KiB
Text
264 lines
8.3 KiB
Text
---
|
|
title: "Search Parameters"
|
|
description: "Complete reference for all search parameters and their effects"
|
|
---
|
|
|
|
|
|
Complete parameter reference for all three search endpoints: document search, memory search, and execute search.
|
|
|
|
## Common Parameters
|
|
|
|
These parameters work across all search endpoints:
|
|
|
|
<ParamField query="q" type="string" required>
|
|
**Search query string**
|
|
|
|
The text you want to search for. Can be natural language, keywords, or questions.
|
|
|
|
```typescript
|
|
q: "machine learning neural networks"
|
|
q: "What are the applications of quantum computing?"
|
|
q: "python tutorial beginner"
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="limit" type="number" default="10">
|
|
**Maximum number of results to return**
|
|
|
|
Controls how many results you get back. Higher limits increase response time and size.
|
|
|
|
```typescript
|
|
limit: 5 // Fast, focused results
|
|
limit: 20 // Comprehensive results
|
|
limit: 100 // Maximum recommended
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="containerTags" type="Array<string>">
|
|
**Filter by container tags**
|
|
|
|
Organizational tags for filtering results. Uses **exact array matching** - must match all tags in the same order.
|
|
|
|
```typescript
|
|
containerTags: ["user_123"] // Single tag
|
|
containerTags: ["user_123", "project_ai"] // Multiple tags (exact match)
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="filters" type="string">
|
|
**Metadata filtering with SQL-like structure**
|
|
|
|
JSON string containing AND/OR logic for filtering by metadata fields. Uses the same structure as memory listing filters.
|
|
|
|
```typescript
|
|
filters: JSON.stringify({
|
|
AND: [
|
|
{ key: "category", value: "tutorial", negate: false },
|
|
{ key: "difficulty", value: "beginner", negate: false }
|
|
]
|
|
})
|
|
```
|
|
|
|
<Note>
|
|
See [Metadata Filtering Guide](/concepts/filtering) for complete syntax and examples.
|
|
</Note>
|
|
</ParamField>
|
|
|
|
<ParamField query="rerank" type="boolean" default="false">
|
|
**Re-score results for better relevance**
|
|
|
|
Applies a secondary ranking algorithm to improve result quality. Adds ~100-200ms latency but increases accuracy.
|
|
|
|
```typescript
|
|
rerank: true // Better accuracy, slower
|
|
rerank: false // Faster, standard accuracy
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="rewriteQuery" type="boolean" default="false">
|
|
**Expand and improve the query**
|
|
|
|
Rewrites your query to find more relevant results. Particularly useful for abbreviations and domain-specific terms. **Adds ~400ms latency**.
|
|
|
|
```typescript
|
|
// Query rewriting examples:
|
|
"ML" → "machine learning artificial intelligence"
|
|
"JS" → "JavaScript programming language"
|
|
"API" → "application programming interface REST"
|
|
```
|
|
|
|
<Warning>
|
|
Query rewriting significantly increases latency. Only use when search quality is more important than speed.
|
|
</Warning>
|
|
</ParamField>
|
|
|
|
## Document Search Parameters (POST `/v3/search`)
|
|
|
|
These parameters are specific to `client.search.documents()`:
|
|
|
|
<ParamField query="chunkThreshold" type="number" range="0-1" default="0.5">
|
|
**Sensitivity for chunk selection**
|
|
|
|
Controls which text chunks are included in results:
|
|
- **0.0** = Least sensitive (more chunks, more results)
|
|
- **1.0** = Most sensitive (fewer chunks, higher quality)
|
|
|
|
```typescript
|
|
chunkThreshold: 0.2 // Broad search, many chunks
|
|
chunkThreshold: 0.8 // Precise search, only relevant chunks
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="documentThreshold" type="number" range="0-1" default="0.5">
|
|
**Sensitivity for document selection**
|
|
|
|
Controls which documents are considered for search:
|
|
- **0.0** = Search more documents (comprehensive)
|
|
- **1.0** = Search only highly relevant documents (focused)
|
|
|
|
```typescript
|
|
documentThreshold: 0.1 // Cast wide net
|
|
documentThreshold: 0.9 // Only very relevant documents
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="docId" type="string">
|
|
**Search within a specific document**
|
|
|
|
Limit search to chunks within a single document. Useful for finding content in large documents.
|
|
|
|
```typescript
|
|
docId: "doc_abc123" // Only search this document
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="onlyMatchingChunks" type="boolean" default="false">
|
|
**Return only exact matching chunks**
|
|
|
|
By default, Supermemory includes surrounding chunks for context. Set to `true` to get only the exact matching text.
|
|
|
|
```typescript
|
|
onlyMatchingChunks: false // Include context chunks (default)
|
|
onlyMatchingChunks: true // Only matching chunks
|
|
```
|
|
|
|
<Note>
|
|
Context chunks help LLMs understand the full meaning. Only disable if you need precise text extraction.
|
|
</Note>
|
|
</ParamField>
|
|
|
|
<ParamField query="includeFullDocs" type="boolean" default="false">
|
|
**Include complete document content**
|
|
|
|
Adds the full document text to each result. Useful for chatbots that need complete context.
|
|
|
|
```typescript
|
|
includeFullDocs: true // Full document in response
|
|
includeFullDocs: false // Only chunks and metadata
|
|
```
|
|
|
|
<Warning>
|
|
Including full documents can make responses very large. Use sparingly and with appropriate limits.
|
|
</Warning>
|
|
</ParamField>
|
|
|
|
<ParamField query="includeSummary" type="boolean" default="false">
|
|
**Include document summaries**
|
|
|
|
Adds AI-generated document summaries to results. Good middle-ground between chunks and full documents.
|
|
|
|
```typescript
|
|
includeSummary: true // Include document summaries
|
|
includeSummary: false // No summaries
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="filters" type="string">
|
|
**Filter by metadata using SQL queries**
|
|
|
|
```typescript
|
|
|
|
// Use this instead:
|
|
filters: JSON.stringify({
|
|
OR: [
|
|
{ key: "category", value: "technology", negate: false },
|
|
{ key: "category", value: "science", negate: false }
|
|
]
|
|
})
|
|
```
|
|
</ParamField>
|
|
|
|
## Memory Search Parameters (POST `/v4/search`)
|
|
|
|
These parameters are specific to `client.search.memories()`:
|
|
|
|
<ParamField query="threshold" type="number" range="0-1" default="0.5">
|
|
**Sensitivity for memory selection**
|
|
|
|
Controls which memories are returned based on similarity:
|
|
- **0.0** = Return more memories (broad search)
|
|
- **1.0** = Return only highly similar memories (precise search)
|
|
|
|
```typescript
|
|
threshold: 0.3 // Broader memory search
|
|
threshold: 0.8 // Only very similar memories
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="searchMode" type="string" default="memories">
|
|
**Search mode - memories only or hybrid search**
|
|
|
|
Controls whether to search only memories or also include document chunks:
|
|
- **`"memories"`** (default): Searches only memory entries. Returns results with `memory` field.
|
|
- **`"hybrid"`**: Searches memories first, then falls back to document chunks if needed. Returns mixed results with either `memory` field (for memory results) or `chunk` field (for chunk results).
|
|
|
|
<Note>
|
|
In hybrid mode, results are automatically merged and deduplicated. Results contain objects with either a `memory` key (for memory results) or a `chunk` key (for chunk results from document search).
|
|
</Note>
|
|
|
|
```typescript
|
|
searchMode: "memories" // Only search memories (default)
|
|
searchMode: "hybrid" // Search memories + fallback to chunks
|
|
```
|
|
|
|
**When to use hybrid mode:**
|
|
- When you want comprehensive search across both memories and documents
|
|
- When memories might not exist for certain queries but document content is available
|
|
- When you need the flexibility to get either memory or document chunk results
|
|
</ParamField>
|
|
|
|
<ParamField query="containerTag" type="string">
|
|
**Filter by single container tag**
|
|
|
|
Note: Memory search uses `containerTag` (singular) while document search uses `containerTags` (plural array).
|
|
|
|
```typescript
|
|
containerTag: "user_123" // Single tag for memory search
|
|
```
|
|
</ParamField>
|
|
|
|
<ParamField query="include" type="object">
|
|
**Control what additional data to include**
|
|
|
|
Object specifying what contextual information to include with memory results.
|
|
|
|
<ParamField query="include.documents" type="boolean" default="false">
|
|
Include associated documents for each memory
|
|
</ParamField>
|
|
|
|
<ParamField query="include.relatedMemories" type="boolean" default="false">
|
|
Include parent and child memories (contextual relationships)
|
|
</ParamField>
|
|
|
|
<ParamField query="include.summaries" type="boolean" default="false">
|
|
Include memory summaries
|
|
</ParamField>
|
|
|
|
```typescript
|
|
include: {
|
|
documents: true, // Show related documents
|
|
relatedMemories: true, // Show parent/child memories
|
|
summaries: true // Include summaries
|
|
}
|
|
```
|
|
</ParamField>
|