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

# Memory Advanced Search

> Learn how to use advanced search parameters for memory retrieval including reranking and relevance filtering.

Memory search in PraisonAI Agents provides advanced parameters for better control over search results, including reranking for improved relevance and cutoff thresholds for quality control.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="Search and retrieve with quality filtering.",
    memory={"backend": "rag", "use_embedding": True},
)

agent.start("What is the capital of France?")
```

The user asks a question; advanced search reranks and filters memory hits before the agent answers.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Memory Advanced Search"
        Query[🔍 Search Query] --> Search[📡 Vector Search]
        Search --> Rerank[🔄 Reranking]
        Search --> Filter[🎯 Relevance Filter]
        Rerank --> Score[📊 Quality Score]
        Filter --> Cutoff[✂️ Cutoff Threshold]
        Score --> Results[📤 Top Results]
        Cutoff --> Results
    end

    classDef query fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef option fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef filter fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Query query
    class Search process
    class Rerank,Filter option
    class Score,Cutoff filter
    class Results result
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Memory Advanced Search

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        instructions="Search and retrieve with quality filtering.",
        memory={"backend": "rag", "use_embedding": True}
    )

    agent.start("Paris is the capital of France")
    response = agent.start("What is the capital of France?")
    ```
  </Step>

  <Step title="With Configuration">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Memory

    memory = Memory(config={
        "provider": "rag",
        "use_embedding": True,
        "rag_db_path": ".praison/memory_db"
    })

    memory.store_long_term("Paris is the capital of France")

    results = memory.search_long_term(
        "What is the capital of France?",
        relevance_cutoff=0.7,
        limit=5
    )
    ```
  </Step>
</Steps>

## Advanced Search Parameters

The `search_long_term` method supports several advanced parameters:

### Method Signature

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def search_long_term(
    self, 
    query: str, 
    limit: int = 5, 
    relevance_cutoff: float = 0.0,
    min_quality: float = 0.0,
    rerank: bool = False,
    **kwargs
) -> List[Dict[str, Any]]:
```

### Parameter Details

<ParamField path="query" type="string" required>
  The search query to find relevant memories
</ParamField>

<ParamField path="limit" type="integer" default="5">
  Maximum number of results to return
</ParamField>

<ParamField path="relevance_cutoff" type="float" default="0.0">
  Minimum relevance score (0.0 to 1.0) for results to be included
</ParamField>

<ParamField path="min_quality" type="float" default="0.0">
  Minimum quality score for results (used with quality tracking)
</ParamField>

<ParamField path="rerank" type="boolean" default="false">
  Enable reranking for improved relevance (only works with Mem0 provider)
</ParamField>

## Provider-Specific Features

### ChromaDB (Local Storage)

ChromaDB is the default local storage provider that supports relevance filtering:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Memory

# Initialize ChromaDB memory
memory = Memory(config={
    "provider": "rag",
    "use_embedding": True,
    "rag_db_path": ".praison/memory_db"
})

# Store memories with metadata
memory.store_long_term(
    "The Eiffel Tower is 330 meters tall",
    metadata={"category": "landmarks", "city": "Paris"}
)

memory.store_long_term(
    "The Statue of Liberty is 93 meters tall",
    metadata={"category": "landmarks", "city": "New York"}
)

# Search with relevance cutoff
results = memory.search_long_term(
    "How tall is the Eiffel Tower?",
    relevance_cutoff=0.6,  # Filter out low-relevance results
    limit=10
)

# ChromaDB calculates score as: 1.0 - distance
# Higher scores mean better relevance
```

### Mem0 (Cloud Provider)

Mem0 is a cloud-based provider that supports both relevance filtering and reranking:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Memory

# Initialize Mem0 memory
mem0_memory = Memory(config={
    "provider": "mem0",
    "config": {
        "api_key": "your-mem0-api-key",
        "org_id": "your-org-id",  # Optional
        "project_id": "your-project-id"  # Optional
    }
})

# Search with reranking enabled
results = mem0_memory.search(
    query="What are the key features of our product?",
    agent_id="agent-123",  # Required for Mem0
    rerank=True,          # Enable reranking for better results
    limit=5
)

# Reranking adds 150-200ms latency but improves result quality
```

<Warning>
  Reranking is only available with the Mem0 provider. When using ChromaDB, the `rerank` parameter is ignored.
</Warning>

## Relevance Scoring

### How Relevance Scores Work

<CardGroup cols={2}>
  <Card title="ChromaDB Scoring" icon="database">
    * Uses vector similarity (cosine distance)
    * Score = 1.0 - distance
    * Range: 0.0 to 1.0
    * Higher scores = better matches
  </Card>

  <Card title="Mem0 Scoring" icon="cloud">
    * Uses proprietary scoring algorithm
    * Includes semantic understanding
    * Reranking uses additional context
    * Optimized for accuracy
  </Card>
</CardGroup>

### Setting Appropriate Cutoffs

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Conservative cutoff - only very relevant results
high_quality_results = memory.search_long_term(
    "important company policies",
    relevance_cutoff=0.8
)

# Moderate cutoff - balanced results
balanced_results = memory.search_long_term(
    "product features",
    relevance_cutoff=0.6
)

# Low cutoff - more inclusive results
inclusive_results = memory.search_long_term(
    "general information",
    relevance_cutoff=0.3
)
```

## Complete Examples

### Example 1: Knowledge Base Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Memory

# Create a knowledge base
knowledge_memory = Memory(config={
    "provider": "rag",
    "use_embedding": True
})

# Store various facts
facts = [
    "Python was created by Guido van Rossum in 1991",
    "JavaScript was created by Brendan Eich in 1995",
    "Java was created by James Gosling in 1995",
    "C++ was created by Bjarne Stroustrup in 1985",
    "Ruby was created by Yukihiro Matsumoto in 1995"
]

for fact in facts:
    knowledge_memory.store_long_term(fact)

# Search with different relevance thresholds
query = "Who created Python?"

# High relevance - only direct matches
strict_results = knowledge_memory.search_long_term(
    query,
    relevance_cutoff=0.8,
    limit=3
)
print(f"Strict search found {len(strict_results)} results")

# Medium relevance - related programming languages
related_results = knowledge_memory.search_long_term(
    query,
    relevance_cutoff=0.5,
    limit=5
)
print(f"Related search found {len(related_results)} results")
```

### Example 2: Agent Memory with Quality Tracking

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Memory, Task, AgentTeam

# Create agent with memory
agent = Agent(
    name="Research Assistant",
    role="Information specialist",
    goal="Provide accurate information from memory",
    backstory="An AI with perfect recall and organization skills"
)

# Create memory instance
memory = Memory(config={
    "provider": "rag",
    "use_embedding": True
})

# Task that stores high-quality information
def research_and_store(topic: str):
    # Simulate research with quality score
    research_data = f"Comprehensive research on {topic}"
    quality_score = 0.85  # High quality
    
    # Store with quality metadata
    memory.store_long_term(
        research_data,
        metadata={
            "topic": topic,
            "quality_score": quality_score,
            "agent_id": agent.id
        }
    )
    return f"Stored research on {topic}"

# Search with quality filtering
def search_quality_info(query: str):
    results = memory.search_long_term(
        query,
        relevance_cutoff=0.6,
        min_quality=0.8,  # Only high-quality results
        limit=3
    )
    return results

# Create tasks
store_task = Task(
    description="Research and store information about artificial intelligence",
    expected_output="Confirmation of stored research",
    agent=agent,
    execute_function=lambda: research_and_store("artificial intelligence")
)

search_task = Task(
    description="Find high-quality information about AI",
    expected_output="Top quality search results",
    agent=agent,
    execute_function=lambda: search_quality_info("artificial intelligence")
)

# Run workflow
workflow = AgentTeam(
    agents=[agent],
    tasks=[store_task, search_task],
    process="sequential"
)

results = workflow.start()
```

### Example 3: Multi-Provider Setup

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Memory
import os

# Setup both providers
local_memory = Memory(config={
    "provider": "rag",
    "use_embedding": True
})

cloud_memory = Memory(config={
    "provider": "mem0",
    "config": {
        "api_key": os.getenv("MEM0_API_KEY")
    }
})

# Function to search both providers
def search_all_memory(query: str, use_rerank: bool = True):
    # Search local memory with relevance cutoff
    local_results = local_memory.search_long_term(
        query,
        relevance_cutoff=0.6,
        limit=5
    )
    
    # Search cloud memory with reranking
    cloud_results = cloud_memory.search(
        query=query,
        agent_id="global",
        rerank=use_rerank,  # Only works with Mem0
        limit=5
    )
    
    # Combine and deduplicate results
    all_results = []
    seen_content = set()
    
    for result in local_results + cloud_results:
        content = result.get('memory', '')
        if content not in seen_content:
            seen_content.add(content)
            all_results.append(result)
    
    # Sort by relevance score
    all_results.sort(
        key=lambda x: x.get('score', 0), 
        reverse=True
    )
    
    return all_results[:10]  # Top 10 results

# Use the multi-provider search
results = search_all_memory(
    "What are the main features of our product?",
    use_rerank=True
)

for i, result in enumerate(results, 1):
    print(f"{i}. {result['memory']}")
    print(f"   Score: {result.get('score', 'N/A')}")
    print(f"   Provider: {result.get('provider', 'unknown')}")
```

## Performance Considerations

<CardGroup cols={2}>
  <Card title="Reranking Impact" icon="clock">
    * Adds 150-200ms latency
    * Improves result quality by 20-30%
    * Best for critical searches
    * Not suitable for real-time applications
  </Card>

  <Card title="Relevance Cutoff" icon="filter">
    * No performance impact
    * Reduces result set size
    * Improves signal-to-noise ratio
    * Can filter out useful edge cases
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Choose the Right Provider">
    Use ChromaDB for local, fast searches. Use Mem0 for cloud-based deployments when you need reranking.
  </Accordion>

  <Accordion title="Set Appropriate Cutoffs">
    Start with 0.6–0.7 for general searches, 0.8+ for precise matching, and 0.3–0.5 for exploratory searches.
  </Accordion>

  <Accordion title="Optimise for Your Use Case">
    Use tighter cutoffs and smaller limits for UI quick search; enable reranking and higher limits for analysis workloads.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Reranking not working">
    * Verify you're using Mem0 provider
    * Check API key is valid
    * Ensure agent\_id is provided
    * Monitor API quota limits
  </Accordion>

  <Accordion title="No results returned">
    * Lower relevance\_cutoff threshold
    * Check if memories exist
    * Verify embedding model is working
    * Try broader search terms
  </Accordion>

  <Accordion title="Poor relevance scores">
    * Ensure quality embeddings
    * Store more context with memories
    * Use more specific queries
    * Consider reranking (Mem0 only)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Memory Management" icon="brain" href="./memory">
    Learn about memory storage and retrieval basics
  </Card>

  <Card title="Knowledge Base" icon="book" href="./knowledge">
    Explore knowledge management features
  </Card>
</CardGroup>

## Related

<CardGroup cols={2}>
  <Card icon="brain" href="/features/memory">
    Store and recall agent memory across turns and sessions.
  </Card>

  <Card icon="database" href="/features/rag">
    Retrieve relevant chunks from large document sets at query time.
  </Card>
</CardGroup>