0
# Search Operations
1

2
Advanced search functionality for finding memories and documents with semantic understanding, filtering, and ranking capabilities across the Supermemory knowledge base.
3

4
## Capabilities
5

6
### Document Search
7

8
Search documents with advanced filtering, chunk selection, and comprehensive result formatting.
9

10
```typescript { .api }
11
/**
12
 * Search memories with advanced filtering
13
 * @param params - Search parameters with query and options
14
 * @returns Promise resolving to document search results
15
 */
16
documents(params: SearchDocumentsParams): APIPromise<SearchDocumentsResponse>;
17

18
interface SearchDocumentsParams {
19
  /** Search query string (required) */
20
  q: string;
21
  /** @deprecated Optional category filters */
22
  categoriesFilter?: Array<"technology" | "science" | "business" | "health">;
23
  /** Chunk selection sensitivity (0=more results, 1=accurate results) */
24
  chunkThreshold?: number;
25
  /** Container tags for filtering */
26
  containerTags?: string[];
27
  /** Search within specific document ID */
28
  docId?: string;
29
  /** Document selection sensitivity (0=more results, 1=accurate results) */
30
  documentThreshold?: number;
31
  /** Advanced filtering with AND/OR logic */
32
  filters?: FilterExpression | { [key: string]: unknown };
33
  /** Include full document content in response */
34
  includeFullDocs?: boolean;
35
  /** Include document summary in response */
36
  includeSummary?: boolean;
37
  /** Maximum number of results */
38
  limit?: number;
39
  /** Return only matching chunks without context */
40
  onlyMatchingChunks?: boolean;
41
  /** Rerank results based on query relevance */
42
  rerank?: boolean;
43
  /** Rewrite query for better document matching (+400ms latency) */
44
  rewriteQuery?: boolean;
45
}
46

47
interface SearchDocumentsResponse {
48
  results: DocumentResult[];
49
  timing: number;
50
  total: number;
51
}
52

53
interface DocumentResult {
54
  chunks: DocumentChunk[];
55
  createdAt: string;
56
  documentId: string;
57
  metadata: { [key: string]: unknown } | null;
58
  score: number;
59
  title: string | null;
60
  type: string | null;
61
  updatedAt: string;
62
  content?: string | null; // When includeFullDocs=true
63
  summary?: string | null; // When includeSummary=true
64
}
65

66
interface DocumentChunk {
67
  content: string;
68
  isRelevant: boolean;
69
  score: number;
70
}
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import Supermemory from "supermemory";
77

78
const client = new Supermemory({ apiKey: "your-api-key" });
79

80
// Basic document search
81
const basicSearch = await client.search.documents({
82
  q: "machine learning algorithms",
83
  limit: 10,
84
});
85

86
// Advanced search with filtering
87
const advancedSearch = await client.search.documents({
88
  q: "neural networks",
89
  containerTags: ["ai-research", "papers"],
90
  includeFullDocs: true,
91
  rerank: true,
92
  documentThreshold: 0.7,
93
  filters: {
94
    AND: [
95
      { type: "pdf" },
96
      { metadata: { category: "research" } }
97
    ]
98
  },
99
});
100

101
// Focused document search
102
const focusedSearch = await client.search.documents({
103
  q: "specific concept",
104
  docId: "document-id-123",
105
  onlyMatchingChunks: true,
106
  chunkThreshold: 0.8,
107
});
108
```
109

110
### Execute Search
111

112
Alias for document search with identical functionality and parameters.
113

114
```typescript { .api }
115
/**
116
 * Search memories with advanced filtering (alias for documents)
117
 * @param params - Search parameters identical to documents()
118
 * @returns Promise resolving to search results
119
 */
120
execute(params: SearchExecuteParams): APIPromise<SearchExecuteResponse>;
121

122
// SearchExecuteParams and SearchExecuteResponse are identical to
123
// SearchDocumentsParams and SearchDocumentsResponse respectively
124
```
125

126
### Memory Search
127

128
Low-latency search optimized for conversational interfaces, searching memory entries directly.
129

130
```typescript { .api }
131
/**
132
 * Search memory entries - Low latency for conversational
133
 * @param params - Memory search parameters
134
 * @returns Promise resolving to memory search results
135
 */
136
memories(params: SearchMemoriesParams): APIPromise<SearchMemoriesResponse>;
137

138
interface SearchMemoriesParams {
139
  /** Search query string (required) */
140
  q: string;
141
  /** Single container tag for filtering */
142
  containerTag?: string;
143
  /** Advanced filtering with AND/OR logic */
144
  filters?: FilterExpression | { [key: string]: unknown };
145
  /** Control what additional data to include */
146
  include?: MemorySearchInclude;
147
  /** Maximum number of results */
148
  limit?: number;
149
  /** Rerank results based on query relevance */
150
  rerank?: boolean;
151
  /** Rewrite query for better matching (+400ms latency) */
152
  rewriteQuery?: boolean;
153
  /** Memory selection sensitivity (0=more results, 1=accurate results) */
154
  threshold?: number;
155
}
156

157
interface MemorySearchInclude {
158
  /** Include associated documents */
159
  documents?: boolean;
160
  /** Include parent/child contextual memories */
161
  relatedMemories?: boolean;
162
  /** Include memory summaries */
163
  summaries?: boolean;
164
}
165

166
interface SearchMemoriesResponse {
167
  results: MemoryResult[];
168
  timing: number;
169
  total: number;
170
}
171

172
interface MemoryResult {
173
  id: string;
174
  memory: string;
175
  metadata: { [key: string]: unknown } | null;
176
  similarity: number;
177
  updatedAt: string;
178
  context?: MemoryContext;
179
  documents?: AssociatedDocument[];
180
  version?: number | null;
181
}
182

183
interface MemoryContext {
184
  children?: ContextualMemory[];
185
  parents?: ContextualMemory[];
186
}
187

188
interface ContextualMemory {
189
  memory: string;
190
  relation: "updates" | "extends" | "derives";
191
  updatedAt: string;
192
  metadata?: { [key: string]: unknown } | null;
193
  version?: number | null;
194
}
195

196
interface AssociatedDocument {
197
  id: string;
198
  createdAt: string;
199
  metadata: { [key: string]: unknown } | null;
200
  title: string;
201
  type: string;
202
  updatedAt: string;
203
}
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
// Basic memory search
210
const memorySearch = await client.search.memories({
211
  q: "Python programming tips",
212
  limit: 5,
213
});
214

215
// Conversational search with context
216
const contextualSearch = await client.search.memories({
217
  q: "how to optimize performance",
218
  containerTag: "user_123",
219
  include: {
220
    relatedMemories: true,
221
    documents: true,
222
  },
223
  threshold: 0.6,
224
});
225

226
// Advanced memory search
227
const advancedMemorySearch = await client.search.memories({
228
  q: "data structures",
229
  filters: {
230
    OR: [
231
      { metadata: { topic: "algorithms" } },
232
      { metadata: { topic: "computer-science" } }
233
    ]
234
  },
235
  rerank: true,
236
  rewriteQuery: true,
237
});
238
```
239

240
## Advanced Filtering
241

242
```typescript { .api }
243
interface FilterExpression {
244
  AND?: unknown[];
245
  OR?: unknown[];
246
}
247

248
// Example filter structures:
249
const filters = {
250
  AND: [
251
    { type: "pdf" },
252
    { metadata: { category: "research" } },
253
    {
254
      OR: [
255
        { metadata: { priority: 1 } },
256
        { metadata: { priority: 2 } }
257
      ]
258
    }
259
  ]
260
};
261
```
262

263
**Filter Examples:**
264

265
```typescript
266
// Metadata-based filtering
267
const metadataFilter = {
268
  AND: [
269
    { metadata: { category: "documentation" } },
270
    { metadata: { language: "typescript" } }
271
  ]
272
};
273

274
// Type and status filtering
275
const typeFilter = {
276
  OR: [
277
    { type: "pdf" },
278
    { type: "webpage" },
279
    { type: "notion_doc" }
280
  ]
281
};
282

283
// Complex nested filtering
284
const complexFilter = {
285
  AND: [
286
    { type: "text" },
287
    {
288
      OR: [
289
        { metadata: { topic: "ai" } },
290
        { metadata: { topic: "ml" } }
291
      ]
292
    },
293
    { status: "done" }
294
  ]
295
};
296
```
297

298
## Search Result Processing
299

300
```typescript
301
// Process document search results
302
const documentResults = await client.search.documents({
303
  q: "API documentation",
304
  includeFullDocs: true,
305
});
306

307
documentResults.results.forEach((result) => {
308
  console.log(`Document: ${result.title} (Score: ${result.score})`);
309
  
310
  // Process chunks
311
  result.chunks.forEach((chunk) => {
312
    if (chunk.isRelevant) {
313
      console.log(`Relevant chunk: ${chunk.content.substring(0, 100)}...`);
314
    }
315
  });
316
  
317
  // Access full content if requested
318
  if (result.content) {
319
    console.log(`Full content length: ${result.content.length}`);
320
  }
321
});
322

323
// Process memory search results
324
const memoryResults = await client.search.memories({
325
  q: "JavaScript best practices",
326
  include: { relatedMemories: true },
327
});
328

329
memoryResults.results.forEach((result) => {
330
  console.log(`Memory: ${result.memory} (Similarity: ${result.similarity})`);
331
  
332
  // Process contextual memories
333
  if (result.context?.parents) {
334
    console.log("Parent memories:", result.context.parents.length);
335
  }
336
  
337
  if (result.context?.children) {
338
    console.log("Child memories:", result.context.children.length);
339
  }
340
});
341
```
342

343
## Performance Considerations
344

345
### Query Optimization
346

347
- **Basic queries**: Fast, simple text matching
348
- **Rerank enabled**: +100-200ms for better relevance
349
- **Rewrite query**: +400ms for improved document matching
350
- **Include full docs**: Larger responses, use judiciously
351
- **Context inclusion**: Memory search with relations increases response size
352

353
### Threshold Settings
354

355
- **0.0-0.3**: More results, lower precision (discovery mode)
356
- **0.4-0.6**: Balanced results (default recommended)
357
- **0.7-1.0**: Fewer results, higher precision (exact matching)
358

359
### Pagination and Limits
360

361
```typescript
362
// Efficient pagination for large result sets
363
const searchWithPagination = async (query: string, pageSize = 20) => {
364
  const results = await client.search.documents({
365
    q: query,
366
    limit: pageSize,
367
    // Note: Use cursors or timestamps for true pagination
368
    // as the API may not support traditional page offsets
369
  });
370
  
371
  return results;
372
};
373
```
374

375
## Error Handling
376

377
Search operations handle various error conditions:
378

379
```typescript
380
try {
381
  const results = await client.search.documents({
382
    q: "search query",
383
    limit: 100,
384
  });
385
} catch (error) {
386
  if (error instanceof BadRequestError) {
387
    // Invalid query parameters
388
    console.error("Invalid search parameters:", error.message);
389
  } else if (error instanceof RateLimitError) {
390
    // Too many search requests
391
    console.error("Search rate limit exceeded:", error.message);
392
  } else if (error instanceof APIConnectionTimeoutError) {
393
    // Search took too long
394
    console.error("Search timeout:", error.message);
395
  }
396
}