mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-05-17 12:20:04 +00:00
354 lines
11 KiB
Text
354 lines
11 KiB
Text
---
|
|
title: "Response Schema"
|
|
description: "Complete response structure for all search endpoints with scoring details"
|
|
---
|
|
|
|
|
|
## Document Search Response (POST `/v3/search`)
|
|
|
|
Response from `client.search.documents()` and `client.search.execute()`:
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"documentId": "doc_abc123",
|
|
"title": "Machine Learning Fundamentals",
|
|
"type": "pdf",
|
|
"score": 0.89,
|
|
"chunks": [
|
|
{
|
|
"content": "Machine learning is a subset of artificial intelligence...",
|
|
"score": 0.95,
|
|
"isRelevant": true
|
|
}
|
|
],
|
|
"metadata": {
|
|
"category": "education",
|
|
"author": "Dr. Smith",
|
|
"difficulty": "beginner"
|
|
},
|
|
"createdAt": "2024-01-15T10:30:00Z",
|
|
"updatedAt": "2024-01-20T14:45:00Z"
|
|
}
|
|
],
|
|
"timing": 187,
|
|
"total": 1
|
|
}
|
|
```
|
|
|
|
### Document Result Fields
|
|
|
|
<ResponseField name="documentId" type="string">
|
|
Unique identifier for the document containing the matching chunks.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="title" type="string | null">
|
|
Document title if available. May be null for documents without titles.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="type" type="string | null">
|
|
Document type (e.g., "pdf", "text", "webpage", "notion_doc"). May be null if not specified.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="score" type="number" range="0-1">
|
|
**Overall document relevance score**. Combines semantic similarity, keyword matching, and metadata relevance.
|
|
|
|
- **0.9-1.0**: Extremely relevant
|
|
- **0.7-0.9**: Highly relevant
|
|
- **0.5-0.7**: Moderately relevant
|
|
- **0.3-0.5**: Somewhat relevant
|
|
- **0.0-0.3**: Marginally relevant
|
|
</ResponseField>
|
|
|
|
<ResponseField name="chunks" type="Array<Chunk>">
|
|
Array of matching text chunks from the document. Each chunk represents a portion of the document that matched your query.
|
|
|
|
<ResponseField name="chunks[].content" type="string">
|
|
The actual text content of the matching chunk. May include context from surrounding chunks unless `onlyMatchingChunks=true`.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="chunks[].score" type="number" range="0-1">
|
|
**Chunk-specific similarity score**. How well this specific chunk matches your query.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="chunks[].isRelevant" type="boolean">
|
|
Whether this chunk passed the `chunkThreshold`. `true` means the chunk is above the threshold, `false` means it's included for context only.
|
|
</ResponseField>
|
|
</ResponseField>
|
|
|
|
<ResponseField name="metadata" type="object | null">
|
|
Document metadata as key-value pairs. Structure depends on what was stored with the document.
|
|
|
|
```json
|
|
{
|
|
"category": "tutorial",
|
|
"language": "python",
|
|
"difficulty": "intermediate",
|
|
"tags": "web-development,backend"
|
|
}
|
|
```
|
|
</ResponseField>
|
|
|
|
<ResponseField name="createdAt" type="string">
|
|
ISO 8601 timestamp when the document was created.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="updatedAt" type="string">
|
|
ISO 8601 timestamp when the document was last updated.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="content" type="string | null" optional>
|
|
**Full document content**. Only included when `includeFullDocs=true`. Can be very large.
|
|
|
|
<Warning>
|
|
Full document content can make responses extremely large. Use with appropriate limits and only when necessary.
|
|
</Warning>
|
|
</ResponseField>
|
|
|
|
<ResponseField name="summary" type="string | null" optional>
|
|
**AI-generated document summary**. Only included when `includeSummary=true`. Provides a concise overview of the document.
|
|
</ResponseField>
|
|
|
|
## Memory Search Response
|
|
|
|
Response from `client.search.memories()`:
|
|
|
|
When `searchMode="memories"` (default), all results are memory entries:
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"id": "mem_xyz789",
|
|
"memory": "Complete memory content about quantum computing applications...",
|
|
"similarity": 0.87,
|
|
"metadata": {
|
|
"category": "research",
|
|
"topic": "quantum-computing"
|
|
},
|
|
"updatedAt": "2024-01-18T09:15:00Z",
|
|
"version": 3,
|
|
"context": {
|
|
"parents": [
|
|
{
|
|
"memory": "Earlier discussion about quantum theory basics...",
|
|
"relation": "extends",
|
|
"version": 2,
|
|
"updatedAt": "2024-01-17T16:30:00Z"
|
|
}
|
|
],
|
|
"children": [
|
|
{
|
|
"memory": "Follow-up questions about quantum algorithms...",
|
|
"relation": "derives",
|
|
"version": 4,
|
|
"updatedAt": "2024-01-19T11:20:00Z"
|
|
}
|
|
]
|
|
},
|
|
"documents": [
|
|
{
|
|
"id": "doc_quantum_paper",
|
|
"title": "Quantum Computing Applications",
|
|
"type": "pdf",
|
|
"createdAt": "2024-01-10T08:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"timing": 156,
|
|
"total": 1
|
|
}
|
|
```
|
|
|
|
When `searchMode="hybrid"`, results can contain both memory entries and document chunks. **Memory results have a `memory` key, chunk results have a `chunk` key:**
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"id": "mem_xyz789",
|
|
"memory": "Complete memory content about quantum computing applications...",
|
|
"similarity": 0.87,
|
|
"metadata": {
|
|
"category": "research",
|
|
"topic": "quantum-computing"
|
|
},
|
|
"updatedAt": "2024-01-18T09:15:00Z",
|
|
"version": 3,
|
|
"context": {
|
|
"parents": [],
|
|
"children": []
|
|
},
|
|
"documents": [
|
|
{
|
|
"id": "doc_quantum_paper",
|
|
"title": "Quantum Computing Applications",
|
|
"type": "pdf",
|
|
"createdAt": "2024-01-10T08:00:00Z",
|
|
"updatedAt": "2024-01-10T08:00:00Z"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"id": "chunk_abc123",
|
|
"chunk": "This is a chunk of content from a document about quantum computing...",
|
|
"similarity": 0.82,
|
|
"metadata": {
|
|
"category": "research",
|
|
"source": "document"
|
|
},
|
|
"updatedAt": "2024-01-15T10:30:00Z",
|
|
"version": 1,
|
|
"context": {
|
|
"parents": [],
|
|
"children": []
|
|
},
|
|
"documents": [
|
|
{
|
|
"id": "doc_quantum_research",
|
|
"title": "Quantum Computing Research Paper",
|
|
"type": "pdf",
|
|
"metadata": {
|
|
"author": "Dr. Smith"
|
|
},
|
|
"createdAt": "2024-01-15T10:30:00Z",
|
|
"updatedAt": "2024-01-15T10:30:00Z"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"timing": 198,
|
|
"total": 2
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
**Distinguishing Memory vs Chunk Results:**
|
|
|
|
In hybrid mode, check which key exists on the result object:
|
|
- **Memory results**: Have a `memory` key (no `chunk` key)
|
|
- **Chunk results**: Have a `chunk` key (no `memory` key)
|
|
|
|
```typescript
|
|
// TypeScript example
|
|
results.results.forEach(result => {
|
|
if ('memory' in result) {
|
|
// This is a memory result
|
|
console.log('Memory:', result.memory);
|
|
} else if ('chunk' in result) {
|
|
// This is a chunk result
|
|
console.log('Chunk:', result.chunk);
|
|
}
|
|
});
|
|
```
|
|
</Note>
|
|
|
|
### Memory Result Fields
|
|
|
|
<ResponseField name="id" type="string">
|
|
Unique identifier for the memory entry or chunk ID. In hybrid mode, can be either a memory ID (e.g., `mem_xyz789`) or a chunk ID (e.g., `chunk_abc123`).
|
|
</ResponseField>
|
|
|
|
<ResponseField name="memory" type="string" optional>
|
|
**Complete memory content**. Only present for memory results (when `searchMode="memories"` or when a memory result is returned in hybrid mode). This field is not present for chunk results.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="chunk" type="string" optional>
|
|
**Chunk content from a document**. Only present for chunk results when `searchMode="hybrid"`. This field is not present for memory results. Contains the actual text content from the document chunk.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="similarity" type="number" range="0-1">
|
|
**Similarity score** between your query and this memory. Higher scores indicate better matches.
|
|
|
|
- **0.9-1.0**: Extremely similar
|
|
- **0.8-0.9**: Very similar
|
|
- **0.7-0.8**: Similar
|
|
- **0.6-0.7**: Somewhat similar
|
|
- **0.5-0.6**: Marginally similar
|
|
</ResponseField>
|
|
|
|
<ResponseField name="metadata" type="object | null">
|
|
Memory metadata as key-value pairs. Structure depends on what was stored with the memory.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="updatedAt" type="string">
|
|
ISO 8601 timestamp when the memory was last updated.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="version" type="number | null" optional>
|
|
Version number of this memory entry. Used for tracking memory evolution and relationships. For chunk results, this is typically `1`.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="rootMemoryId" type="string | null" optional>
|
|
Root memory ID for memory entries. Only present for memory results. Always `null` for chunk results.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="context" type="object" optional>
|
|
**Contextual memory relationships**. Only included when `include.relatedMemories=true`.
|
|
|
|
<ResponseField name="context.parents" type="Array<ContextMemory>" optional>
|
|
Array of parent memories that this memory extends or derives from.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="context.children" type="Array<ContextMemory>" optional>
|
|
Array of child memories that extend or derive from this memory.
|
|
</ResponseField>
|
|
|
|
### Context Memory Structure
|
|
|
|
<ResponseField name="memory" type="string">
|
|
Content of the related memory.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="relation" type="string">
|
|
Relationship type: `"updates"`, `"extends"`, or `"derives"`.
|
|
|
|
- **updates**: This memory updates/replaces the related memory
|
|
- **extends**: This memory builds upon the related memory
|
|
- **derives**: This memory is derived from the related memory
|
|
</ResponseField>
|
|
|
|
<ResponseField name="version" type="number | null">
|
|
Relative version distance:
|
|
- **Negative values** for parents (-1 = direct parent, -2 = grandparent)
|
|
- **Positive values** for children (+1 = direct child, +2 = grandchild)
|
|
</ResponseField>
|
|
|
|
<ResponseField name="updatedAt" type="string">
|
|
When the related memory was last updated.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="metadata" type="object | null" optional>
|
|
Metadata of the related memory.
|
|
</ResponseField>
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents" type="Array<Document>" optional>
|
|
**Associated documents**. Only included when `include.documents=true`.
|
|
|
|
<ResponseField name="documents[].id" type="string">
|
|
Document identifier.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents[].title" type="string">
|
|
Document title.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents[].type" type="string">
|
|
Document type.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents[].metadata" type="object">
|
|
Document metadata.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents[].createdAt" type="string">
|
|
Document creation timestamp.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="documents[].updatedAt" type="string">
|
|
Document update timestamp.
|
|
</ResponseField>
|
|
</ResponseField>
|