mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-09-08 22:21:07 +00:00
Update apps/docs/search/parameters.mdx
Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
This commit is contained in:
mintlify[bot]
GitHub
parent
9816215d5a
commit
d572935e9f
1 changed files with 279 additions and 233 deletions
|
|
@ -1,242 +1,288 @@
|
|||
---
|
||||
title: "Search Parameters"
|
||||
description: "Complete reference for all search parameters and their effects"
|
||||
title: Search parameters
|
||||
description: Complete reference for all search API parameters
|
||||
---
|
||||
|
||||
## Required parameters
|
||||
|
||||
Complete parameter reference for all three search endpoints: document search, memory search, and execute search.
|
||||
|
||||
## Common Parameters
|
||||
|
||||
These parameters work across all search endpoints:
|
||||
### q
|
||||
|
||||
<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](/search/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="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
|
||||
The search query string. This is the text you want to search for in your memories and documents.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "What are John's machine learning preferences?"
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Search mode
|
||||
|
||||
### searchMode
|
||||
|
||||
<ParamField query="searchMode" type="enum" default="memories">
|
||||
Controls the search behavior. Available options:
|
||||
|
||||
- `memories` (default): Searches only through memory entries
|
||||
- `hybrid`: Searches memories first, then falls back to document chunks
|
||||
|
||||
**Hybrid mode behavior:**
|
||||
- Searches memories and document chunks in parallel
|
||||
- Merges results by similarity score
|
||||
- Automatically deduplicates chunks already associated with memories
|
||||
- Returns the most relevant results from both sources
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "machine learning",
|
||||
"searchMode": "hybrid"
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Result control
|
||||
|
||||
### limit
|
||||
|
||||
<ParamField query="limit" type="number" default={10}>
|
||||
Maximum number of results to return. Must be between 1 and 100.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### threshold
|
||||
|
||||
<ParamField query="threshold" type="number" default={0.7}>
|
||||
Minimum similarity score for results (0-1). Higher values return only more relevant results.
|
||||
|
||||
- `0.9-1.0`: Very high similarity (exact matches)
|
||||
- `0.7-0.9`: High similarity (recommended)
|
||||
- `0.5-0.7`: Moderate similarity
|
||||
- `0.0-0.5`: Low similarity (may include irrelevant results)
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"threshold": 0.8
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Query optimization
|
||||
|
||||
### rerank
|
||||
|
||||
<ParamField query="rerank" type="boolean" default={false}>
|
||||
Rerank results using a more sophisticated model for improved relevance. Adds ~200ms latency.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"rerank": true
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### rewriteQuery
|
||||
|
||||
<ParamField query="rewriteQuery" type="boolean" default={false}>
|
||||
Rewrites the query to improve search results. Adds ~400ms latency.
|
||||
|
||||
Useful for:
|
||||
- Ambiguous queries
|
||||
- Queries with typos
|
||||
- Queries that need clarification
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "ml prefs",
|
||||
"rewriteQuery": true
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Filtering
|
||||
|
||||
### filters
|
||||
|
||||
<ParamField query="filters" type="object">
|
||||
Filter results by metadata conditions. Supports complex boolean logic.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"filters": {
|
||||
"and": [
|
||||
{
|
||||
"key": "category",
|
||||
"operator": "equals",
|
||||
"value": "user_preferences"
|
||||
},
|
||||
{
|
||||
"key": "priority",
|
||||
"operator": "greater_than",
|
||||
"value": 5
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [Filtering](/search/filtering) for detailed documentation.
|
||||
</ParamField>
|
||||
|
||||
### containerTag
|
||||
|
||||
<ParamField query="containerTag" type="string">
|
||||
Filter results to a specific container tag. Useful for multi-tenant applications.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"containerTag": "user_123"
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Include options
|
||||
|
||||
Control what additional data is included in the response.
|
||||
|
||||
### include.relatedMemories
|
||||
|
||||
<ParamField query="include.relatedMemories" type="boolean" default={false}>
|
||||
Include memories that are related to the search results through memory relations (updates, extends, derives).
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"relatedMemories": true
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### include.forgottenMemories
|
||||
|
||||
<ParamField query="include.forgottenMemories" type="boolean" default={false}>
|
||||
Include memories that have been marked as forgotten.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"forgottenMemories": true
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### include.documents
|
||||
|
||||
<ParamField query="include.documents" type="boolean" default={false}>
|
||||
Include document metadata (title, type, metadata) associated with memory results.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"documents": true
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### include.summaries
|
||||
|
||||
<ParamField query="include.summaries" type="boolean" default={false}>
|
||||
Include document summaries. Requires `include.documents` to be true.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"documents": true,
|
||||
"summaries": true
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### include.chunks
|
||||
|
||||
<ParamField query="include.chunks" type="boolean" default={false}>
|
||||
Include the top 5 most relevant document chunks for each memory result.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"chunks": true
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
### include.temporalContext
|
||||
|
||||
<ParamField query="include.temporalContext" type="object">
|
||||
Include memories created before and/or after each result.
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "preferences",
|
||||
"include": {
|
||||
"temporalContext": {
|
||||
"before": 3,
|
||||
"after": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
</ParamField>
|
||||
|
||||
## Complete example
|
||||
|
||||
```json
|
||||
{
|
||||
"q": "What are John's machine learning preferences?",
|
||||
"searchMode": "hybrid",
|
||||
"limit": 10,
|
||||
"threshold": 0.75,
|
||||
"rerank": true,
|
||||
"rewriteQuery": false,
|
||||
"containerTag": "user_john",
|
||||
"filters": {
|
||||
"and": [
|
||||
{
|
||||
"key": "category",
|
||||
"operator": "equals",
|
||||
"value": "preferences"
|
||||
},
|
||||
{
|
||||
"key": "confidence",
|
||||
"operator": "greater_than",
|
||||
"value": 0.8
|
||||
}
|
||||
]
|
||||
},
|
||||
"include": {
|
||||
"relatedMemories": true,
|
||||
"forgottenMemories": false,
|
||||
"documents": true,
|
||||
"summaries": true,
|
||||
"chunks": true,
|
||||
"temporalContext": {
|
||||
"before": 2,
|
||||
"after": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue