> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# RAG Scoping & Filtering
> Filter retrieval results using user_id, agent_id, and run_id for multi-tenant isolation
RAG scoping enables precise filtering of retrieval results using scope identifiers, allowing multi-tenant isolation and session-specific knowledge retrieval.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "RAG Scoping Flow"
A[📋 Query + Scopes] --> B[🔍 Vector Search]
B --> C[🛡️ Apply Filters]
C --> D[✅ Scoped Results]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B,C process
class D output
```
## Quick Start
Filter knowledge by user, agent, or session:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
# User-specific knowledge
agent = Agent(
name="PersonalAssistant",
instructions="You are a personal assistant.",
knowledge=["./documents/"],
user_id="alice",
)
agent.start("Find my recent notes about the project")
```
Combine multiple scopes for fine-grained isolation:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
# Multi-tenant SaaS support bot
agent = Agent(
name="SupportBot",
instructions="Answer customer questions using their session history.",
knowledge=["./support_docs/"],
user_id="customer_42",
agent_id="support_bot_v1",
run_id="session_2026_05_30",
)
agent.start("What was the status of my refund request?")
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Knowledge
participant VectorDB
User->>Agent: Query with context
Agent->>Knowledge: search(query, user_id, agent_id, run_id)
Knowledge->>VectorDB: Apply scope filters ($and operator)
VectorDB-->>Knowledge: Filtered results
Knowledge-->>Agent: Scoped knowledge
Agent-->>User: Context-aware response
```
| Scope Type | Purpose | Example Use Case |
| ---------- | --------------------- | ------------------------------------------ |
| `user_id` | Per-user isolation | Personal documents, user-specific data |
| `agent_id` | Per-agent isolation | Different bot types sharing infrastructure |
| `run_id` | Per-session isolation | Conversation-specific temporary context |
***
## Configuration Options
Learn about different vector store backends and their scoping support
***
## Common Patterns
### Multi-Tenant SaaS Application
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
def create_customer_agent(customer_id, session_id):
return Agent(
name="CustomerSupportBot",
instructions="Provide customer support using account history.",
knowledge=["./knowledge_base/"],
user_id=customer_id, # Isolate per customer
agent_id="support_bot_v2", # Shared bot knowledge
run_id=session_id, # Session-specific context
)
# Each customer gets isolated knowledge
agent = create_customer_agent("cust_12345", "sess_abc")
```
### Department-Specific Knowledge
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Sales team agent
sales_agent = Agent(
name="SalesAssistant",
instructions="Help with sales inquiries and product information.",
knowledge=["./sales_materials/"],
agent_id="sales_assistant",
user_id="sales_team",
)
# Support team agent
support_agent = Agent(
name="SupportAgent",
instructions="Resolve technical support issues.",
knowledge=["./support_docs/"],
agent_id="support_assistant",
user_id="support_team",
)
```
### Session-Based Memory
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
# Create conversation-specific memory
def start_conversation(user_id):
import uuid
session_id = str(uuid.uuid4())
agent = Agent(
name="ChatBot",
instructions="Remember our conversation context.",
knowledge=[], # Will accumulate during conversation
user_id=user_id,
run_id=session_id,
)
return agent, session_id
```
***
## Best Practices
**Single scope** for simple use cases:
* Use `user_id` for personal documents
* Use `agent_id` for shared knowledge bases
* Use `run_id` for temporary session data
**Combined scopes** for complex multi-tenant applications:
* All three scopes provide maximum isolation
* Omit scopes to broaden access as needed
Use consistent, readable naming patterns:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Good - descriptive and consistent
user_id = "customer_alice_123"
agent_id = "support_bot_v2"
run_id = "session_2026_05_30_14_30"
# Avoid - unclear or inconsistent
user_id = "u123"
agent_id = "bot1"
run_id = "abc"
```
**mem0 backend** requires at least one scope identifier.
**ChromaDB backend** supports all scoping patterns and automatically combines multiple scopes with `$and` operator.
**Internal backend** has limited scoping support.
Choose your backend based on scoping requirements.
More specific scopes = faster queries:
* Narrow scopes reduce the search space
* Combined scopes create more selective filters
* Consider indexing strategies for your vector database
Monitor query performance with different scope combinations.
***
## Related
Configure different vector store backends with scoping support
Learn how agents use knowledge and memory systems