> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & Retrieval

> Find exactly what you need with intelligent hybrid search

# Search & Retrieval

**Search that understands meaning, not just keywords.** Hybrid ranking combines semantic similarity, keywords, recency, usage patterns, and graph connections for intelligent results.

<Note>
  Search understands concepts (not just exact words), weights by importance and recency, and automatically expands context through semantic waypoints.
</Note>

***

## Hybrid Search: 5 Ranking Signals

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

<CardGroup cols={2}>
  <Card title="Vector Similarity (40%)" icon="brain">
    **Semantic understanding via embeddings**

    Search: "state management"
    Finds: "React hooks," "Redux," "Context API"

    (Even without exact keywords!)
  </Card>

  <Card title="Keyword Matching (30%)" icon="text">
    **Traditional BM25 algorithm**

    Exact phrase matching for precision

    "JWT token expiration" → Exact matches rank highest
  </Card>

  <Card title="Recency Boost (15%)" icon="clock">
    **Newer = more relevant**

    Recent memories get ranking boost

    Updated last week > Created 6 months ago
  </Card>

  <Card title="Access Frequency (10%)" icon="chart-line">
    **Team usage patterns**

    Frequently accessed = valuable

    Guide accessed 50 times > Alternative accessed 2 times
  </Card>

  <Card title="Waypoint Bonus (5%)" icon="sitemap">
    **Context expansion**

    Direct match: 100%
    1 hop away: 80%
    2 hops: 64%
    3 hops: 51%
  </Card>
</CardGroup>

**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

<Tabs>
  <Tab title="Semantic (Default)">
    **Best for:** Concept queries, exploration

    ```
    Search: "how do we handle authentication"
    ```

    **Results:** JWT, OAuth, API keys, sessions—even without exact keywords

    **Process:**

    1. Query vectorized
    2. Vector similarity comparison
    3. Combined with other signals
    4. Ranked by final score
  </Tab>

  <Tab title="Filtered">
    **Best for:** Narrowing by type, sector, tags

    ```
    Search semantic memories tagged "architecture"
    for "database choice"
    ```

    **Filters:**

    * Sector: episodic, semantic, procedural, emotional, reflective
    * Tags: Any assigned tags
    * Min salience: Exclude faded memories
    * Date range: Created/accessed timeframe
  </Tab>

  <Tab title="Context Expansion">
    **Best for:** Research, comprehensive understanding

    ```
    Search "React state" with waypoint expansion
    ```

    **Process:**

    1. Find direct matches (hybrid)
    2. Traverse waypoints (BFS, up to 3 hops)
    3. Apply salience decay per hop
    4. Aggregate and rank all

    **Results:** 10-30 related memories forming knowledge graph
  </Tab>

  <Tab title="Precision">
    **Best for:** Exact lookups, speed

    ```
    Search "JWT expiration" without waypoints
    ```

    **Fast:** \~50ms vs \~200ms with waypoints

    **Results:** Precise answer, no related context
  </Tab>
</Tabs>

***

## Search Parameters

<AccordionGroup>
  <Accordion title="query (required)" icon="magnifying-glass">
    **Type:** String

    **Tips:**

    * 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"
    ```
  </Accordion>

  <Accordion title="limit (optional, default: 10)" icon="list">
    **Type:** Integer (1-100)

    **When to adjust:**

    * Lower (5): Quick lookup
    * Default (10): Balanced
    * Higher (50): Comprehensive research
  </Accordion>

  <Accordion title="sector (optional)" icon="layer-group">
    **Values:** episodic, semantic, procedural, emotional, reflective

    **Examples:**

    ```
    Search semantic memories for "documentation"
    → Only facts/concepts, not events

    Search reflective for "architectural decisions"
    → Only strategic insights
    ```
  </Accordion>

  <Accordion title="tags (optional)" icon="tags">
    **Type:** Array of strings

    **Examples:**

    ```
    Search tagged ["api", "authentication"]
    → Only memories with both tags

    Search tagged ["customer-acme-corp"]
    → All Acme Corp memories
    ```
  </Accordion>

  <Accordion title="min_salience (optional, default: 0.3)" icon="filter">
    **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
  </Accordion>

  <Accordion title="expand_waypoints (optional, default: true)" icon="diagram-project">
    **Type:** Boolean

    **When to disable:**

    * Speed-critical searches
    * Precise lookups (exact answer)
    * Already have many results
  </Accordion>

  <Accordion title="max_hops (optional, default: 3)" icon="arrows-left-right">
    **Type:** Integer (1-5)

    **Values:**

    * 1: Immediate neighbors only
    * 3: Balanced (default)
    * 5: Deep exploration
  </Accordion>
</AccordionGroup>

***

## Search Examples

<Tabs>
  <Tab title="Concept Search">
    **Query:**

    ```
    Search: "state management in React"
    ```

    **Results:**

    ```
    1. React hooks (useState, useEffect) - 0.92
       Tags: react, hooks, state | Sector: semantic

    2. Context API for global state - 0.87
       Tags: react, context-api | Sector: semantic

    3. When to use Redux vs Context - 0.84
       Tags: react, redux, architecture | Sector: reflective

    4. State lifting patterns - 0.79
       Tags: react, patterns, state | Sector: procedural
    ```
  </Tab>

  <Tab title="Filtered Search">
    **Query:**

    ```
    Search reflective tagged "architecture"
    for "database choice"
    ```

    **Results:**

    ```
    1. Why we chose PostgreSQL over MongoDB - 0.95
       Sector: reflective | Tags: architecture, database, postgresql

    2. Database per service pattern - 0.88
       Sector: reflective | Tags: architecture, database, microservices
    ```

    Only reflective + architecture tagged results.
  </Tab>

  <Tab title="Precision">
    **Query:**

    ```
    Search "JWT token expiration" without waypoints, limit 3
    ```

    **Results:**

    ```
    1. JWT tokens expire after 30 days - 0.97
       Direct answer, no context

    2. Token refresh endpoint: POST /api/auth/refresh - 0.85

    3. JWT config in .env file - 0.78
    ```

    **Speed:** \~50ms (fast!)
  </Tab>

  <Tab title="Research">
    **Query:**

    ```
    Search "microservices architecture"
    with waypoints, max_hops 5, limit 50
    ```

    **Results:**

    ```
    Direct (3): Why we chose microservices, comparison, best practices

    1-hop (8): Service discovery, API gateway, database per service

    2-hop (12): Docker, Kubernetes, monitoring, logging

    3-hop (15): CI/CD, testing, deployment patterns

    4-hop (10): Team organization, Conway's Law, DevOps

    5-hop (8): Scaling strategies, architectural decisions

    Total: 56 memories (limited to 50)
    ```

    Comprehensive knowledge graph!
  </Tab>
</Tabs>

***

## 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

<CardGroup cols={2}>
  <Card title="Use Natural Language" icon="comment">
    **Good:** "How do we handle API errors?"

    **Also good:** "error handling pattern"

    Both work! Semantic search understands natural language.
  </Card>

  <Card title="Start Broad, Then Filter" icon="funnel">
    Don't over-constrain first search.

    Start broad → See results → Add filters
  </Card>

  <Card title="Waypoints for Exploration" icon="compass">
    Learning or researching? Enable waypoint expansion.

    Discover concepts you didn't know to search for.
  </Card>

  <Card title="Precision for Lookups" icon="bullseye">
    Need specific answer fast? Disable waypoints.

    Speed + precision over context.
  </Card>

  <Card title="Sector Filters Strategically" icon="filter">
    * Need "why"? → Reflective
    * Need "how-to"? → Procedural
    * Need facts? → Semantic
    * Need recent events? → Episodic
  </Card>

  <Card title="Trust the Ranking" icon="ranking-star">
    Hybrid algorithm tuned for relevance.

    Check top 3-5 results before adjusting.
  </Card>
</CardGroup>

***

## Performance

### Search Speed

| Type                      | Speed       |
| ------------------------- | ----------- |
| 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

<AccordionGroup>
  <Accordion title="Memory not in search results">
    **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
  </Accordion>

  <Accordion title="Search for exact phrases">
    Use quotes (if AI assistant supports):

    ```
    Search: "JWT token expiration"
    ```

    Or disable waypoints for keyword-focused search.
  </Accordion>

  <Accordion title="Unrelated results">
    **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.
  </Accordion>

  <Accordion title="See relevance scores">
    **Via API:** Scores returned with results

    **Via MCP:** AI assistant sees scores and can share them
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Semantic Waypoints" icon="sitemap" href="/memory/semantic-waypoints">
    Deep dive into context expansion
  </Card>

  <Card title="Best Practices" icon="star" href="/memory/best-practices">
    Search optimization strategies
  </Card>

  <Card title="API Reference" icon="code" href="/memory/api-reference">
    Complete search API docs
  </Card>

  <Card title="Workflows" icon="list-check" href="/memory/workflows">
    Real-world search examples
  </Card>
</CardGroup>

***

*Search that understands what you mean, not just what you type. Explore with waypoints, focus with filters.*