> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkifai.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Conversation Memory
> Enable long-term memory so your agent remembers users across multiple conversations using Graphiti's knowledge graph.
## 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
Graphiti requires **FalkorDB** (RedisGraph fork) for graph storage.
**Environment variables:**
```bash theme={null}
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_PASSWORD=your_password # Optional
```
**Docker:**
```bash theme={null}
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:**
```bash theme={null}
REDIS_HOST=localhost
REDIS_PORT=6379
```
***
## Enable Conversation Memory
### Via Environment Variables (Backend)
Memory is enabled globally via environment variables in your backend service:
```bash theme={null}
# .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:
```bash theme={null}
GET /health
```
**Response:**
```json theme={null}
{
"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:
1. Constructs the user's graph ID: `org_{orgId}_agent_{agentId}_user_{sanitizedUserId}`
2. Connects to the user's memory graph in FalkorDB
3. 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"
4. Formats retrieved facts into a memory context string
5. 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:
1. Buffers all conversation messages during the session
2. When session ends, starts a background ingestion task
3. Formats messages as an episode:
```
User: My order #1234 is delayed
Assistant: I apologize for the delay. Let me check the status...
```
4. Calls `client.add_episode()` to extract entities and relationships
5. 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:
```bash theme={null}
# 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:
```bash theme={null}
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
Write system prompts that guide the agent to use memory naturally, not robotically. "I recall you..." sounds better than "According to my records..."
Memory enriches conversations — it doesn't replace good conversation design. Agents should still ask clarifying questions when needed.
After enabling memory, test by having the same user start two separate conversations. Verify the agent recalls context correctly.
Avoid storing sensitive PII in your system prompt. Memory is powerful, but user trust is more important.
Memory ingestion takes 18-25 seconds. Wait at least 30 seconds between test conversations to ensure ingestion completes.
Graph storage grows over time. Monitor your FalkorDB instance and implement retention policies for production deployments.
***
## Troubleshooting
**Check:**
1. Is `GRAPHITI_ENABLED=true` in your backend environment?
2. Is FalkorDB running and accessible? (`GET /health` → check `graphiti.status`)
3. Did the previous session end properly (not abandoned)?
4. Is the same user identifier being used across sessions?
5. Wait at least 30 seconds between sessions for ingestion to complete
**Debug:**
```bash theme={null}
# Check health endpoint
curl http://localhost:8000/health
# Check FalkorDB connection
redis-cli -h localhost -p 6379 PING
```
**Cause:** FalkorDB is not running or connection failed.
**Fix:**
1. Start FalkorDB: `docker run -p 6379:6379 falkordb/falkordb:latest`
2. Verify `FALKORDB_HOST` and `FALKORDB_PORT` environment variables
3. Check firewall/network connectivity
4. Restart the backend service
**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.
```
**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
**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
**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:
```python theme={null}
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
```python theme={null}
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
Set `GRAPHITI_ENABLED=true` in your backend environment and ensure FalkorDB is running.
Check `GET /health` endpoint to confirm Graphiti status is "healthy".
Run two separate conversations with the same user (wait 30s between) to verify memory works.
Set up monitoring for FalkorDB storage growth in production.
***
## Related Documentation
* [System Health API](/api-reference/health) — Monitor Graphiti status
* [Environment Configuration](/platform/environment-variables) — All backend environment variables
* [FalkorDB Documentation](https://falkordb.com/) — Graph database documentation
* [Graphiti GitHub](https://github.com/graphiti-orchestrator/graphiti) — Graphiti source code