Search Strategies

ExoVault provides multiple search tools optimized for different retrieval needs. Choosing the right tool depends on what you are looking for and how precisely you can describe it.

Search Tools Overview#

search_memories (Hybrid)#

The most powerful search tool. Combines three signals via reciprocal rank fusion (RRF):

1. Semantic search -- pgvector cosine similarity on embeddings (weight: 1.0)
2. Blind-index keywords -- privacy-preserving keyword matching (weight: 0.8)
3. Graph expansion -- knowledge graph neighbors of top results (weight: 0.6)

Post-processing applies temporal decay (recency weighting) and MMR (maximal marginal relevance) for diversity.

{
  "query": "database migration strategy",
  "topK": 10,
  "threshold": 0.4,
  "compact": true,
  "decayHalfLife": 30,
  "diversity": 0.7
}

When to use: General knowledge retrieval. This is the default choice for most memory searches.

Options:

• compact: true -- Returns summaries (200 chars) for token efficiency. Follow up with read_memories for full content.
• memoryType -- Filter by type (e.g., "fact", "constraint")
• entity -- Search by entity name using JSONB containment (fast, no embedding needed)
• decayHalfLife -- Days until a memory's recency score drops by half (default: 30)
• diversity -- MMR lambda (0-1). Lower values increase diversity, higher values favor relevance.

semantic_search (Notes)#

Pure vector similarity search across note embeddings. Returns previews with similarity scores.

{
  "query": "how to handle authentication tokens",
  "topK": 10,
  "threshold": 0.5
}

When to use: Finding notes by concept or meaning when you do not know exact keywords. Good for exploring a topic broadly.

search_and_read (Notes)#

Hybrid search (70% semantic + 30% keyword) that returns full note content in one call:

{
  "query": "OAuth2 implementation",
  "maxNotes": 5
}

The fallback chain:

1. Hybrid -- semantic + keyword (when OpenAI key available)
2. Keyword-only -- title (3x weight), tags (2x), content (1x)
3. Recency -- most recently updated notes

When to use: When you need to read the full content of matching notes, not just previews. Saves a round-trip compared to semantic_search + read_note.

search_notes (Keyword)#

Simple keyword search across note titles, content, and tags with blind-index matching:

{
  "query": "API design patterns",
  "vaultId": "vault-uuid",
  "limit": 10
}

When to use: When you know specific keywords or phrases. Faster than semantic search and does not require an embedding API key.

explore_graph#

Multi-hop graph traversal that discovers connected knowledge starting from a semantic query or a specific node:

{
  "query": "authentication architecture",
  "maxHops": 2,
  "maxNodes": 50
}

Returns a graph structure with nodes (memories + notes), edges (typed relations), and entry points.

When to use: When you need to understand how knowledge connects -- following chains of derived_from, refines, contradicts relations. Best for deep context exploration.

get_related_memories#

Single-hop link traversal from a specific memory. Returns direct neighbors only.

{
  "memoryId": "mem-uuid"
}

When to use: When you already have a specific memory and want to see what is directly connected to it. Lighter-weight than explore_graph.

Decision Guide#

Do you know the exact memory ID?
  └─ Yes → get_related_memories or get_links
  └─ No ↓

Are you searching for notes or memories?
  └─ Notes ↓
  │   Do you need full content?
  │     └─ Yes → search_and_read
  │     └─ No → semantic_search or search_notes
  └─ Memories ↓
      Do you need to follow connections?
        └─ Yes → explore_graph
        └─ No → search_memories (with compact: true)

Combining Strategies#

For comprehensive retrieval, combine multiple tools:

1. Start with search_memories (compact) to find relevant knowledge
2. Use explore_graph on the most relevant results to discover connections
3. Use read_memories to get full content for specific IDs
4. Use search_and_read if you need to check notes related to the topic

Next Steps#

• Memory Management -- Write searchable memories
• Knowledge Graph -- Build connections for graph exploration
• Notes & Folders -- Create searchable notes