Search with Filters & Scoring

​

Search Endpoints Overview

​

Documents vs Memories Search: What’s the Difference?

• Documents: Refer to the data you ingest like text, pdfs, videos, images, etc. They are sources of ground truth.
• Memories: They are automatically extracted from your documents by Supermemory. Smaller information chunks inferred from documents and related to each other.

​

Documents Search (/v3/search)

• Use cases: Use this endpoint for use cases where “literal” document search is required.
  • Looking through legal/finance documents
  • Searching through items in google drive
  • Chat with documentation
• With this endpoint, you get Full Control over
  • Thresholds,
  • Filtering
  • Reranking
  • Query rewriting

// Documents search
const results = await client.search.documents({
  q: "machine learning accuracy",
  limit: 10,
  documentThreshold: 0.7,
  chunkThreshold: 0.8,
  rerank: true,
  rewriteQuery: true,
  includeFullDocs: true,
  includeSummary: true,
  onlyMatchingChunks: false,
  containerTags: ["research"],
  filters: {
    AND: [{ key: "category", value: "ai", negate: false }]
  }
});

{
  "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
}

​

Memories Search (/v4/search)

• Use cases: Use this endpoint for use cases where understanding user context / preferences / memories is more important than literal document search.
  • Personalized chatbots (AI Companions)
  • Auto selecting based on what the user wants
  • Setting the tone of the conversation

// Memories search
const results = await client.search.memories({
  q: "machine learning accuracy",
  limit: 5,
  containerTag: "research",
  threshold: 0.7,
  rerank: true
});

{
  "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
}

​

Search Flow Architecture

​

Document Search (/v3/search) Flow

​

Memory Search (/v4/search) Flow

​

Key Concepts You Need to Understand

​

1. Thresholds (Sensitivity Control)

• 0.0 = Least sensitive (more results, lower quality)
• 1.0 = Most sensitive (fewer results, higher quality)

// Different threshold strategies
const broadSearch = await client.search.documents({
  q: "machine learning",
  chunkThreshold: 0.2,      // Return more chunks
  documentThreshold: 0.1    // From more documents
});

const preciseSearch = await client.search.documents({
  q: "machine learning",
  chunkThreshold: 0.8,      // Only highly relevant chunks
  documentThreshold: 0.7    // From closely matching documents
});

​

2. Chunk Context vs Exact Matching

// Default: includes surrounding chunks for context
const contextualResults = await client.search.documents({
  q: "neural networks",
  onlyMatchingChunks: false  // Default
});

// Precise: only the exact matching text
const exactResults = await client.search.documents({
  q: "neural networks",
  onlyMatchingChunks: true
});

​

3. Query Rewriting & Reranking

• Expands your query to find more relevant results
• “ML” becomes “machine learning artificial intelligence”
• Useful for abbreviations and domain-specific terms

• Re-scores results using a different algorithm
• More accurate but slower
• Recommended for critical searches

​

4. Container Tags vs Metadata Filters

• The user understanding graph is built on top of container tags. The graph is formed on top of container tags.
• Container tags are used for organizational grouping and exact matching.
• They are useful for categorizing content and ensuring precise results. When to use metadata filters:
• When you need flexible conditions beyond exact matches.
• Useful for filtering by attributes like date, author, or category.

// Container tags: Organizational grouping (exact array matching)
const userContent = await client.search.documents({
  q: "python tutorial",
  containerTag "user_123"  // Must match exactly
});

// Metadata filters: SQL-based queries (flexible conditions)
const filteredContent = await client.search.documents({
  q: "python tutorial",
  filters: JSON.stringify({
    AND: [
      { key: "language", value: "python", negate: false },
      { key: "difficulty", value: "beginner", negate: false }
    ]
  })
});