Tavus CVI Knowledge Base & Memories

Give your personas access to documents and persistent memory.

Knowledge Base (RAG)

Upload documents that personas can reference during conversations.

Step 1: Create Document

curl -X POST https://tavusapi.com/v2/documents \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "document_name": "Product FAQ",
    "document_url": "https://example.com/faq.pdf",
    "tags": ["support", "faq"]
  }'

Response:

{
  "document_id": "d1234567890",
  "status": "processing"
}

Supported Sources

• PDFs: Direct URL to PDF file
• Text files: Plain text documents
• Websites: Single page or crawled

Website Crawling

Single page (default):

{
  "document_name": "Landing Page",
  "document_url": "https://example.com/features"
}

Multi-page crawl:

{
  "document_name": "Full Docs",
  "document_url": "https://docs.example.com",
  "crawl_pages": true
}

Step 2: Use in Conversation

By document IDs:

{
  "persona_id": "p123",
  "replica_id": "r456",
  "document_ids": ["d1234567890", "d0987654321"]
}

By tags:

{
  "persona_id": "p123",
  "replica_id": "r456",
  "document_tags": ["support", "faq"]
}

Attach to Persona (Always Available)

Documents available in ALL conversations with this persona:

curl -X POST https://tavusapi.com/v2/personas \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "persona_name": "Support Agent",
    "pipeline_mode": "full",
    "system_prompt": "You are a helpful support agent...",
    "document_ids": ["d1234567890"],
    "document_tags": ["support"]
  }'

Retrieval Strategy

Optimize search speed vs quality:

{
  "persona_id": "p123",
  "document_ids": ["d123"],
  "retrieval_strategy": "balanced"
}

Options:

• speed - Fastest, good for simple lookups
• quality - Best results, slower
• balanced - Default, good tradeoff

Manage Documents

# List documents
curl https://tavusapi.com/v2/documents \
  -H "x-api-key: YOUR_API_KEY"

# Get document status
curl https://tavusapi.com/v2/documents/{document_id} \
  -H "x-api-key: YOUR_API_KEY"

# Delete document
curl -X DELETE https://tavusapi.com/v2/documents/{document_id} \
  -H "x-api-key: YOUR_API_KEY"

Memories (Persistent Context)

Remember information across conversations with the same user.

How It Works

1. Assign a memory_store key to a conversation
2. Persona forms memories during conversation
3. Future conversations with same key access those memories

Create Conversation with Memory

{
  "persona_id": "p123",
  "replica_id": "r456",
  "memory_stores": ["user_alice_persona_sales"]
}

Memory Store Naming

Use consistent, unique identifiers:

• user_{user_id}_persona_{persona_id} - Per user, per persona
• user_{user_id} - Per user across personas
• session_{session_id} - Per session

Important: Don't use persona names in keys (they might change).

Example: Returning User

First conversation:

{
  "persona_id": "p_coach",
  "memory_stores": ["user_alice_coaching"]
}

User mentions: "I'm training for a marathon in April."

Second conversation (days later):

{
  "persona_id": "p_coach", 
  "memory_stores": ["user_alice_coaching"]
}

Persona remembers the marathon goal and can reference it.

Multiple Memory Stores

Share memories across contexts:

{
  "persona_id": "p123",
  "memory_stores": [
    "user_alice_global",
    "user_alice_sales_specific"
  ]
}

Use Case: Multi-Persona Memory

User talks to Sales persona, then Support persona:

// Sales conversation
{
  "persona_id": "p_sales",
  "memory_stores": ["user_alice"]
}

// Support conversation (later)
{
  "persona_id": "p_support",
  "memory_stores": ["user_alice"]
}

Support persona knows what Sales discussed.

Combining Knowledge + Memories

Full-featured support agent:

# Create persona with knowledge base
curl -X POST https://tavusapi.com/v2/personas \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "persona_name": "Premium Support",
    "pipeline_mode": "full",
    "system_prompt": "You are a premium support agent. Reference the knowledge base for product info. Remember user preferences and past issues.",
    "document_tags": ["support", "product-docs"],
    "default_replica_id": "rfe12d8b9597"
  }'

# Start conversation with user memory
curl -X POST https://tavusapi.com/v2/conversations \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "persona_id": "p_premium_support",
    "memory_stores": ["user_12345_support"],
    "document_ids": ["d_urgent_issue_docs"]
  }'

Now the persona can:

• Look up product info from documents
• Remember this user's past issues
• Build on previous conversations