search

Hybrid search combining semantic similarity with full-text keyword matching using Reciprocal Rank Fusion (RRF). Optionally search across entity memories and past conversations with weighted fusion.

ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Document-Only Search (Default)Copy Anchor Link

{
  "query": "quarterly planning meeting notes",
  "limit": 5,
  "fullTextWeight": 1.0,
  "semanticWeight": 1.5,
  "tags": ["work", "planning"],
  "sourceType": "note",
  "minScore": 0.5
}

Cross-Source SearchCopy Anchor Link

{
  "query": "database architecture decisions",
  "includeMemories": true,
  "includeConversations": true,
  "memoryWeight": 1.5,
  "limit": 10
}

ResponseCopy Anchor Link

Document-Only ResponseCopy Anchor Link

{
  "query": "quarterly planning meeting notes",
  "totalResults": 3,
  "results": [
    {
      "documentId": "550e8400-e29b-41d4-a716-446655440000",
      "documentTitle": "Q4 Planning Notes",
      "sourceType": "note",
      "tags": ["work", "planning", "q4"],
      "chunkId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "content": "In the Q4 planning meeting, we discussed the roadmap for...",
      "score": 0.89
    }
  ]
}

Cross-Source ResponseCopy Anchor Link

When includeMemories or includeConversations is true, results are fused by score:

{
  "query": "database architecture decisions",
  "counts": { "documents": 3, "memories": 2, "conversations": 1 },
  "results": [
    { "type": "document", "score": 0.91, "data": { "id": "...", "title": "DB Design Doc", "content": "..." } },
    { "type": "memory", "score": 0.85, "data": { "entityName": "Database", "content": "Uses PostgreSQL with pgvector" } },
    { "type": "conversation", "score": 0.42, "data": { "sessionKey": "db-planning", "title": "DB Planning Session" } }
  ]
}

Output SchemaCopy Anchor Link

This tool MUST return structuredContent alongside the text response. The structuredContent object MUST use canonical verbose keys regardless of the COMPACT_RESPONSES setting.

How It WorksCopy Anchor Link

Reciprocal Rank Fusion (RRF)Copy Anchor Link

textrawl runs two parallel searches:

1. Full-Text Search: PostgreSQL tsvector matching for exact keywords
2. Semantic Search: pgvector cosine similarity for meaning

Results are combined using RRF:

RRF_score = (fullTextWeight / (k + fts_rank)) + (semanticWeight / (k + semantic_rank))

Where k = 60 (standard RRF constant).

Weight TuningCopy Anchor Link

Tip: Start with default weights and adjust based on results. Higher semantic weight helps with paraphrased queries.

FilteringCopy Anchor Link

By TagsCopy Anchor Link

Filter to documents containing ALL specified tags:

{
  "query": "project update",
  "tags": ["work", "project-x"]
}

Only returns documents tagged with both work AND project-x.

By Source TypeCopy Anchor Link

By Content TypeCopy Anchor Link

By Score ThresholdCopy Anchor Link

Filter out low-relevance results:

{
  "query": "specific topic",
  "minScore": 0.7
}

Caution: Scores are relative. A 0.7 threshold may filter out relevant results for broad queries.

Error ResponsesCopy Anchor Link

Best PracticesCopy Anchor Link

1. Start broad, then narrow: Begin without filters, add them if too many results
2. Use semantic weight for questions: Increase semanticWeight for natural language queries
3. Use full-text weight for keywords: Increase fullTextWeight for specific terms
4. Combine with get_document: Search returns chunks, use get_document for full context
5. Use cross-source sparingly: Enable includeMemories/includeConversations only when you need context from those sources
6. Check score distribution: If all scores are low, try rephrasing the query