Skip to main content

​
Search & Retrieval

Search that understands meaning, not just keywords. Hybrid ranking combines semantic similarity, keywords, recency, usage patterns, and graph connections for intelligent results.
Search understands concepts (not just exact words), weights by importance and recency, and automatically expands context through semantic waypoints.

​
Hybrid Search: 5 Ranking Signals

Traditional search: keywords only. Memory Module: 5 intelligent signals.

Vector Similarity (40%)

Semantic understanding via embeddingsSearch: “state management” Finds: “React hooks,” “Redux,” “Context API”(Even without exact keywords!)

Keyword Matching (30%)

Traditional BM25 algorithmExact phrase matching for precision“JWT token expiration” → Exact matches rank highest

Recency Boost (15%)

Newer = more relevantRecent memories get ranking boostUpdated last week > Created 6 months ago

Access Frequency (10%)

Team usage patternsFrequently accessed = valuableGuide accessed 50 times > Alternative accessed 2 times

Waypoint Bonus (5%)

Context expansionDirect match: 100% 1 hop away: 80% 2 hops: 64% 3 hops: 51%
Combined Score Formula: 
Final Score =
  (0.40 × vector_similarity) +
  (0.30 × keyword_match) +
  (0.15 × recency_boost) +
  (0.10 × access_frequency) +
  (0.05 × waypoint_bonus)
Then filtered by min_salience (default: 0.3) and ranked.

​
Search Modes

  • Semantic (Default)
  • Filtered
  • Context Expansion
  • Precision
Best for: Concept queries, exploration
Search: "how do we handle authentication"
Results: JWT, OAuth, API keys, sessions—even without exact keywordsProcess:
  1. Query vectorized
  2. Vector similarity comparison
  3. Combined with other signals
  4. Ranked by final score

​
Search Parameters

Type: StringTips:
  • Natural language: “How do we deploy?”
  • Keywords: “JWT token expiration”
  • Concepts: “state management patterns”
Examples:
"API authentication methods"
"why we chose PostgreSQL"
"customer support best practices"
Type: Integer (1-100)When to adjust:
  • Lower (5): Quick lookup
  • Default (10): Balanced
  • Higher (50): Comprehensive research
Values: episodic, semantic, procedural, emotional, reflectiveExamples:
Search semantic memories for "documentation"
→ Only facts/concepts, not events

Search reflective for "architectural decisions"
→ Only strategic insights
Type: Array of stringsExamples:
Search tagged ["api", "authentication"]
→ Only memories with both tags

Search tagged ["customer-acme-corp"]
→ All Acme Corp memories
Type: Float (0.0-1.0)When to adjust:
  • Lower (0.1): Include older memories
  • Default (0.3): Balanced
  • Higher (0.7): Only strong memories
Type: BooleanWhen to disable:
  • Speed-critical searches
  • Precise lookups (exact answer)
  • Already have many results
Type: Integer (1-5)Values:
  • 1: Immediate neighbors only
  • 3: Balanced (default)
  • 5: Deep exploration

​
Search Examples

​
Advanced Techniques

​
Combining Filters

Search semantic tagged ["project-alpha", "api"]
created in last 30 days
for "authentication"
Result: Only recent auth memories from Project Alpha

​
Progressive Refinement

Start broad: 
Search "authentication" → 50 results (too many)
Add sector: 
Search semantic for "authentication" → 25 results (better)
Add tags: 
Search semantic tagged ["api"] for "authentication" → 8 results (perfect!)

​
Using Access Patterns

Search memories with access_count ≥ 10 for "coding patterns"
Result: Patterns the team actually uses (not theoretical ones)

​
Best Practices

Use Natural Language

Good: “How do we handle API errors?”Also good: “error handling pattern”Both work! Semantic search understands natural language.

Start Broad, Then Filter

Don’t over-constrain first search.Start broad → See results → Add filters

Waypoints for Exploration

Learning or researching? Enable waypoint expansion.Discover concepts you didn’t know to search for.

Precision for Lookups

Need specific answer fast? Disable waypoints.Speed + precision over context.

Sector Filters Strategically

  • Need “why”? → Reflective
  • Need “how-to”? → Procedural
  • Need facts? → Semantic
  • Need recent events? → Episodic

Trust the Ranking

Hybrid algorithm tuned for relevance.Check top 3-5 results before adjusting.

​
Performance

​
Search Speed

TypeSpeed
Simple (no waypoints)~50ms
With waypoints (3 hops)~100-200ms
Deep exploration (5 hops)~300-500ms
Large result set (50+)~200-400ms

​
Optimization Tips

  1. Appropriate limit: Don’t request 100 if you need 10
  2. Filter first: Sector/tag filters reduce search space
  3. Adjust max_hops: 1-2 for speed, 3-5 for exploration
  4. Cache-friendly: Repeated searches ~10x faster (caching)

​
Troubleshooting

Possible reasons:
  1. Embeddings still generating (wait 10-30s after storing)
  2. Salience below threshold (try min_salience: 0.1)
  3. Filtered out by sector/tags (remove filters)
  4. Query too specific or too vague
Use quotes (if AI assistant supports):
Search: "JWT token expiration"
Or disable waypoints for keyword-focused search.
Common causes:
  1. Waypoint expansion too aggressive (reduce max_hops)
  2. Query too broad (be more specific)
  3. Similarity threshold too low
Solution: Disable waypoint expansion for that search.
Via API: Scores returned with resultsVia MCP: AI assistant sees scores and can share them

​
Next Steps

Semantic Waypoints

Deep dive into context expansion

Best Practices

Search optimization strategies

API Reference

Complete search API docs

Workflows

Real-world search examples
Search that understands what you mean, not just what you type. Explore with waypoints, focus with filters.