Conversation Memory

Overview

Conversation Memory allows your agent to remember information from previous conversations with each user. Instead of starting every session fresh, your agent can recall past interactions, preferences, and context — creating a truly personalized experience. TalkifAI uses Graphiti — a knowledge graph memory system backed by FalkorDB — to store and retrieve conversational context across sessions. Best for:

Customer support (remember previous issues, account history)
Sales agents (track where each lead is in the pipeline)
Personal assistants (remember preferences, past requests)
Healthcare (maintain patient context across appointments)
Any use case where continuity matters

Memory is a global setting — when enabled, it applies to ALL agents in your deployment. There is currently no per-agent toggle in the Studio UI.

How It Works

Session 1 (User: "My order #1234 is delayed")
    │
    ▼
Agent handles conversation
    │
    ▼
Session ends → Memory ingestion triggered (background task)
    │
    ▼
Graphiti stores: User → had issue → Order #1234 (delayed)
    │
    ▼
Session 2 (Same user returns)
    │
    ▼
Memory retrieval → Agent knows about order #1234
    │
    ▼
Agent: "Welcome back! I see you previously contacted us about order #1234. Was that resolved?"

Memory Architecture

Graphiti Knowledge Graph

Memory is stored as a knowledge graph — not just raw conversation logs. The system extracts meaningful relationships:

User Node
  ├── "prefers" → Email communication
  ├── "has" → Account #ACCT-789
  ├── "reported" → Issue: Login not working (resolved Jan 2024)
  ├── "ordered" → Product: Wireless Headphones
  └── "located in" → New York

This structured approach means the agent can answer contextual questions like “What has this user bought before?” or “What issues did they report last month?”

Memory Scoping

Memory is scoped per user + agent + organization:

group_id = "org_{orgId}_agent_{agentId}_user_{userId}"

Same user, different agents → separate memory graphs
Different users, same agent → isolated memory (no cross-user leakage)
Different organizations → completely isolated (multi-tenant)
All memory stored securely in FalkorDB

Infrastructure Requirements

FalkorDB
Redis

Graphiti requires FalkorDB (RedisGraph fork) for graph storage.Environment variables:

FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_PASSWORD=your_password  # Optional

Docker:

docker run -p 6379:6379 falkordb/falkordb:latest

FalkorDB uses Redis as its underlying storage. You can also use Redis directly for simpler deployments.Environment variables:

REDIS_HOST=localhost
REDIS_PORT=6379

Enable Conversation Memory

Via Environment Variables (Backend)

Memory is enabled globally via environment variables in your backend service:

# .env file in Livekit-Production-Agent
GRAPHITI_ENABLED=true
GRAPHITI_LLM_MODEL=gpt-4o-mini
GRAPHITI_EMBEDDING_MODEL=text-embedding-3-small
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_PASSWORD=your_password  # Optional

Configuration options:

Variable	Default	Description
`GRAPHITI_ENABLED`	`true`	Enable/disable memory system globally
`GRAPHITI_LLM_MODEL`	`gpt-4o-mini`	LLM for entity extraction
`GRAPHITI_EMBEDDING_MODEL`	`text-embedding-3-small`	Embeddings for semantic search
`FALKORDB_HOST`	`localhost`	FalkorDB/Redis host
`FALKORDB_PORT`	`6379`	FalkorDB/Redis port
`FALKORDB_PASSWORD`	—	Optional authentication

No Studio UI toggle exists — Memory configuration is done via environment variables only. Per-agent memory settings are planned for a future release.

Verify Memory is Enabled

Check the system health endpoint:

GET /health

Response:

{
  "components": {
    "graphiti": {
      "status": "healthy",
      "message": "FalkorDB connected"
    }
  }
}

Status	Meaning
`healthy`	Graphiti is enabled and FalkorDB is connected
`skipped`	Graphiti is disabled (`GRAPHITI_ENABLED=false`)
`unhealthy`	Graphiti is enabled but FalkorDB connection failed

Memory Lifecycle

During a Session

When a conversation starts, the system automatically:

Constructs the user’s graph ID: org_{orgId}_agent_{agentId}_user_{sanitizedUserId}
Connects to the user’s memory graph in FalkorDB
Searches for relevant facts using multiple queries:
- “user personal information age name preferences”
- “what the user told me about themselves”
- “facts about the user”
- “user mentioned said told”
Formats retrieved facts into a memory context string
Appends memory context to the agent’s system prompt

Example memory context injected:

## Memory Context

Relevant facts about this user from previous conversations:
- User prefers email communication over phone calls
- User has account number ACCT-789
- User previously reported login issues (resolved in January 2024)
- User ordered Wireless Headphones last month

When a Session Ends

After every conversation (voice or text), the system automatically:

Buffers all conversation messages during the session
When session ends, starts a background ingestion task

Formats messages as an episode:

User: My order #1234 is delayed
Assistant: I apologize for the delay. Let me check the status...

Calls client.add_episode() to extract entities and relationships
Updates the user’s knowledge graph in FalkorDB

Ingestion time: ~18-25 seconds (runs in background, doesn’t delay session end)

Important: Always call the session end API explicitly. If sessions expire via idle timeout, memory ingestion may not complete.

What Gets Remembered

Automatically Extracted

The memory system automatically identifies and stores:

Category	Examples
User Information	Name, email, location, account numbers
Preferences	Communication style, preferred products, language
Issues & Resolutions	Support tickets, complaints, solutions provided
Orders & Transactions	Purchase history, order numbers, amounts
Appointments	Scheduled meetings, bookings, follow-ups
Decisions Made	Choices made during previous conversations

Not Stored

Credit card numbers or financial credentials (automatically filtered)
Passwords or sensitive authentication data
Content explicitly marked as confidential by your system prompt

Memory in Your System Prompt

You can guide the agent on how to use memory by including instructions in the system prompt:

## Memory Usage

You have access to long-term memory about this user. When relevant:

1. **Reference past interactions naturally:**
   - "Last time you called, we resolved your billing issue."
   - "I see you've ordered from us twice before."

2. **Avoid repeating questions:**
   - If you already know the user's account number, don't ask again.
   - If they've stated their preference before, use it.

3. **Show continuity:**
   - If an issue was "in progress" last time, ask about its status.
   - If they were considering an upgrade, follow up on that.

4. **Respect privacy:**
   - Don't mention sensitive details unless the user brings them up.
   - Use memory to help, not to demonstrate surveillance.

Returning User Experience

Example Conversation

Without Memory:

Agent: Hello! How can I help you today?
User: I'm calling about my delayed shipment again.
Agent: I'm sorry to hear that. Can you give me your order number?
User: It's the same one from last week — #1234!
Agent: I apologize, I don't have any record of that...

With Memory:

Agent: Welcome back, Sarah! I see your shipment #1234 was delayed last week.
       Did that get resolved, or are you still experiencing issues?
User: Still delayed!
Agent: I'm so sorry. Since this is a recurring issue, let me escalate this
       immediately and arrange priority shipping for you.

Privacy & Data Control

Data Retention

Memory is retained indefinitely by default (until manually deleted)
Each user’s data is isolated in their own graph
Users can request memory deletion (GDPR compliance)

Clear User Memory (Manual)

There is currently no API endpoint to delete individual user memory. This feature is planned for a future release.Workaround: Directly delete the user’s graph from FalkorDB:

# Connect to FalkorDB/Redis
redis-cli -h localhost -p 6379

# Delete the user's graph database
SELECT {graph_number}
FLUSHALL

Caution: This is a destructive operation. Use with care.

List User Memory (Manual)

There is currently no API endpoint to view individual user memory. This feature is planned for a future release.Workaround: Query FalkorDB directly:

redis-cli -h localhost -p 6379

# List all nodes
GRAPH.QUERY {graph_name} "MATCH (n) RETURN n"

# List all relationships
GRAPH.QUERY {graph_name} "MATCH ()-[r]->() RETURN r"

Best Practices

Prompt for Natural Recall

Write system prompts that guide the agent to use memory naturally, not robotically. “I recall you…” sounds better than “According to my records…”

Don't Over-Rely on Memory

Memory enriches conversations — it doesn’t replace good conversation design. Agents should still ask clarifying questions when needed.

Test with Returning Users

After enabling memory, test by having the same user start two separate conversations. Verify the agent recalls context correctly.

Respect Sensitive Data

Avoid storing sensitive PII in your system prompt. Memory is powerful, but user trust is more important.

Wait Between Test Sessions

Memory ingestion takes 18-25 seconds. Wait at least 30 seconds between test conversations to ensure ingestion completes.

Monitor FalkorDB Storage

Graph storage grows over time. Monitor your FalkorDB instance and implement retention policies for production deployments.

Troubleshooting

Agent doesn't remember previous conversations

Check:

Is GRAPHITI_ENABLED=true in your backend environment?
Is FalkorDB running and accessible? (GET /health → check graphiti.status)
Did the previous session end properly (not abandoned)?
Is the same user identifier being used across sessions?
Wait at least 30 seconds between sessions for ingestion to complete

Debug:

# Check health endpoint
curl http://localhost:8000/health

# Check FalkorDB connection
redis-cli -h localhost -p 6379 PING

Graphiti health check shows 'unhealthy'

Cause: FalkorDB is not running or connection failed.Fix:

Start FalkorDB: docker run -p 6379:6379 falkordb/falkordb:latest
Verify FALKORDB_HOST and FALKORDB_PORT environment variables
Check firewall/network connectivity
Restart the backend service

Agent over-references old information

Problem: Agent brings up outdated or irrelevant past context.Solution: Add to system prompt:

Use memory selectively — only reference past context when it's directly
relevant to the current conversation. Don't bring up old issues unless
the user mentions them first.

Memory contains incorrect information

Problem: The knowledge graph extracted wrong facts.Solution:

Clear user memory from FalkorDB and let it rebuild from fresh conversations
Be more explicit in conversations about key facts
Adjust GRAPHITI_LLM_MODEL to a more capable model if extraction is poor

Memory not available for text chat sessions

Problem: Text chat API sessions not ingesting memory.Solution:

Always call POST /v1/chat/sessions/{id}/end explicitly
Avoid letting sessions expire via idle timeout (memory won’t ingest)
Verify GRAPHITI_ENABLED=true in backend environment

Ingestion takes too long or times out

Problem: Memory ingestion exceeds the worker shutdown timeout.Solution:

The backend already runs ingestion in parallel with transcription/analysis
Ingestion timeout is set to 18 seconds by default
If consistently timing out, check LLM API latency (Graphiti uses GPT-4o-mini by default)
Consider using a faster LLM for entity extraction

Technical Details

Group ID Format

Each user’s memory is stored in a separate FalkorDB graph with this ID format:

org_{orgId}_agent_{agentId}_user_{sanitizedUserId}

Sanitization rules:

Phone numbers: +923136488867 → p923136488867 (replaces + with p)
Special characters: Replaced with underscore _
Only alphanumeric, dashes, and underscores allowed

Memory Search Queries

When retrieving context, Graphiti searches with multiple queries:

search_queries = [
    "user personal information age name preferences",
    "what the user told me about themselves",
    "facts about the user",
    "user mentioned said told",
]

If user name is available, it’s prepended to improve recall.

Ingestion Process

await client.add_episode(
    name=f"session_{session_id}_{timestamp}",
    episode_body="User: ...\nAssistant: ...",
    source=EpisodeType.message,
    source_description="Voice/Chat conversation",
    reference_time=datetime.now(timezone.utc),
    group_id="org_{orgId}_agent_{agentId}_user_{userId}"
)

Graphiti’s LLM client extracts entities and relationships from the episode body.

Next Steps

Enable Graphiti

Set GRAPHITI_ENABLED=true in your backend environment and ensure FalkorDB is running.

Verify Health

Check GET /health endpoint to confirm Graphiti status is “healthy”.

Test Returning Users

Run two separate conversations with the same user (wait 30s between) to verify memory works.

Monitor Storage

Set up monitoring for FalkorDB storage growth in production.

System Health API — Monitor Graphiti status
Environment Configuration — All backend environment variables
FalkorDB Documentation — Graph database documentation
Graphiti GitHub — Graphiti source code

​Overview

​How It Works

​Memory Architecture

​Graphiti Knowledge Graph

​Memory Scoping

​Infrastructure Requirements

​Enable Conversation Memory

​Via Environment Variables (Backend)

​Verify Memory is Enabled

​Memory Lifecycle

​During a Session

​When a Session Ends

​What Gets Remembered

​Automatically Extracted

​Not Stored

​Memory in Your System Prompt

​Returning User Experience

​Example Conversation

​Privacy & Data Control

​Data Retention

​Clear User Memory (Manual)

​List User Memory (Manual)

​Best Practices

Prompt for Natural Recall

Don't Over-Rely on Memory

Test with Returning Users

Respect Sensitive Data

Wait Between Test Sessions

Monitor FalkorDB Storage

​Troubleshooting

​Technical Details

​Group ID Format

​Memory Search Queries

​Ingestion Process

​Next Steps

Enable Graphiti

Verify Health

Test Returning Users

Monitor Storage

​Related Documentation

Overview

How It Works

Memory Architecture

Graphiti Knowledge Graph

Memory Scoping

Infrastructure Requirements

Enable Conversation Memory

Via Environment Variables (Backend)

Verify Memory is Enabled

Memory Lifecycle

During a Session

When a Session Ends

What Gets Remembered

Automatically Extracted

Not Stored

Memory in Your System Prompt

Returning User Experience

Example Conversation

Privacy & Data Control

Data Retention

Clear User Memory (Manual)

List User Memory (Manual)

Best Practices

Troubleshooting

Technical Details

Group ID Format

Memory Search Queries

Ingestion Process

Next Steps

Related Documentation