Skip to main content

​
Document Search Response (POST /v3/search)

Response from client.search.documents() and client.search.execute(): 
{
  "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

​
documentId
string
Unique identifier for the document containing the matching chunks.
​
title
string | null
Document title if available. May be null for documents without titles.
​
type
string | null
Document type (e.g., “pdf”, “text”, “webpage”, “notion_doc”). May be null if not specified.
​
score
number
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
​
chunks
Array<Chunk>
Array of matching text chunks from the document. Each chunk represents a portion of the document that matched your query.
​
chunks[].content
string
The actual text content of the matching chunk. May include context from surrounding chunks unless onlyMatchingChunks=true.
​
chunks[].score
number
Chunk-specific similarity score. How well this specific chunk matches your query.
​
chunks[].isRelevant
boolean
Whether this chunk passed the chunkThreshold. true means the chunk is above the threshold, false means it’s included for context only.
​
metadata
object | null
Document metadata as key-value pairs. Structure depends on what was stored with the document.
{
  "category": "tutorial",
  "language": "python",
  "difficulty": "intermediate",
  "tags": "web-development,backend"
}
​
createdAt
string
ISO 8601 timestamp when the document was created.
​
updatedAt
string
ISO 8601 timestamp when the document was last updated.
​
content
string | null
Full document content. Only included when includeFullDocs=true. Can be very large.
Full document content can make responses extremely large. Use with appropriate limits and only when necessary.
​
summary
string | null
AI-generated document summary. Only included when includeSummary=true. Provides a concise overview of the document.

​
Memory Search Response

Response from client.search.memories(): When searchMode="memories" (default), all results are memory entries: 
{
  "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: 
{
  "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
}
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 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);
  }
});

​
Memory Result Fields

​
id
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).
​
memory
string
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.
​
chunk
string
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.
​
similarity
number
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
​
metadata
object | null
Memory metadata as key-value pairs. Structure depends on what was stored with the memory.
​
updatedAt
string
ISO 8601 timestamp when the memory was last updated.
​
version
number | null
Version number of this memory entry. Used for tracking memory evolution and relationships. For chunk results, this is typically 1.
​
rootMemoryId
string | null
Root memory ID for memory entries. Only present for memory results. Always null for chunk results.
​
context
object
Contextual memory relationships. Only included when include.relatedMemories=true.
​
context.parents
Array<ContextMemory>
Array of parent memories that this memory extends or derives from.
​
context.children
Array<ContextMemory>
Array of child memories that extend or derive from this memory.

​
Context Memory Structure

​
memory
string
Content of the related memory.
​
relation
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
​
version
number | null
Relative version distance:
  • Negative values for parents (-1 = direct parent, -2 = grandparent)
  • Positive values for children (+1 = direct child, +2 = grandchild)
​
updatedAt
string
When the related memory was last updated.
​
metadata
object | null
Metadata of the related memory.
​
documents
Array<Document>
Associated documents. Only included when include.documents=true.
​
documents[].id
string
Document identifier.
​
documents[].title
string
Document title.
​
documents[].type
string
Document type.
​
documents[].metadata
object
Document metadata.
​
documents[].createdAt
string
Document creation timestamp.
​
documents[].updatedAt
string
Document update timestamp.