Zep

Overview

Zep is a long-term memory service for AI applications that automatically extracts and stores structured memory from conversations. Unlike simple vector storage, Zep uses AI to extract entities, facts, and relationships from conversations, then organizes them into a searchable memory graph.

Zep enables AI agents and chatbots to maintain context across sessions, remember user preferences, and build cumulative knowledge about their users. It's designed for production use with high performance, scalability, and framework-agnostic APIs.

Built by Zep AI, the platform offers both cloud-hosted and self-hosted options, with SDKs for Python, JavaScript, Go, and REST APIs for any language.

Features

• Automatic Entity Extraction: AI-powered extraction of people, places, organizations, and custom entities
• Built-in Summarization: Configurable conversation summarization with sliding windows
• Semantic Search: Vector search with hybrid keyword + semantic matching
• Memory Snapshots: Time-travel to any point in conversation history
• Framework-Agnostic: Works with any LLM framework (LangChain, CrewAI, AutoGen, etc.)
• REST and SDK APIs: Multiple integration options
• Self-Hostable: Docker deployment for full data control
• Scalable Architecture: Built for production workloads

Installation

Python

pip install zep-python

JavaScript/TypeScript

npm install @getzep/zep-cloud

Go

go get github.com/getzep/zep-go

Self-Hosted (Docker)

docker compose up -d

Quick Start

Basic Usage

from zep_python import ZepClient, MemorySearchScope

client = ZepClient(base_url="http://localhost:8000", api_key="your-api-key")

# Create a session
session = client.memory.add_session(session_id="user-123")

# Add a message
client.memory.add_memory(
    session_id="user-123",
    messages=[
        {"role": "user", "content": "Hi, my name is Alice and I work at Acme Corp."},
        {"role": "assistant", "content": "Nice to meet you, Alice! What do you do at Acme?"},
    ],
)

# Search memory
results = client.memory.search_memory(
    session_id="user-123",
    query="What does Alice do?",
    scope=MemorySearchScope.summary,
)
print(results)

With LangChain

from langchain_community.chat_message_histories import ZepChatMessageHistory

history = ZepChatMessageHistory(
    session_id="user-123",
    url="http://localhost:8000",
)

# Use with any LangChain chain
chain = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant. Use the following context: {context}"),
    ("human", "{input}"),
]).pipe(model)

Core Concepts

Sessions

Sessions are the top-level container for memory. Each user or conversation gets a unique session ID.

Messages

Messages are stored with their role (user/assistant) and content. Zep automatically extracts entities and facts from messages.

Summaries

Zep maintains both short-term and long-term summaries:

• Short-Term: Last N messages (configurable)
• Long-Term: AI-generated summary of the entire conversation

Entities

Zep automatically extracts entities like:

• People (names, roles)
• Organizations
• Locations
• Dates and times
• Custom entity types

Memory Search

Search memory using semantic similarity, keyword matching, or both:

results = client.memory.search_memory(
    session_id="user-123",
    query="What projects is Alice working on?",
    scope=MemorySearchScope.messages,
    k=5,
)

Advanced Features

Custom Entity Extraction

from zep_python import EntityExtractor

client.memory.set_entity_extractors(
    session_id="user-123",
    extractors=[
        EntityExtractor(name="project", prompt="Extract project names from the conversation"),
        EntityExtractor(name="technologies", prompt="Extract programming languages and frameworks mentioned"),
    ],
)

Memory Snapshots

# Create a snapshot at a specific point
snapshot_id = client.memory.create_snapshot(session_id="user-123")

# Restore to a previous snapshot
client.memory.restore_snapshot(session_id="user-123", snapshot_id=snapshot_id)

Fact Extraction

# Extract and store structured facts
facts = client.memory.extract_facts(
    session_id="user-123",
    prompt="Extract all facts about Alice's work preferences and goals",
)
print(facts)

Examples

Customer Support Bot

# Store customer interaction
client.memory.add_memory(
    session_id="customer-456",
    messages=[
        {"role": "user", "content": "I'm having trouble with my subscription."},
        {"role": "assistant", "content": "I can help with that. What's your account email?"},
        {"role": "user", "content": "alice@example.com"},
    ],
)

# Retrieve context for follow-up
context = client.memory.search_memory(
    session_id="customer-456",
    query="What was the customer's issue?",
    scope=MemorySearchScope.summary,
)

# Use context in response
prompt = f"Previous context: {context}\n\nNew message: {new_message}"

Personal Assistant

# Remember user preferences
client.memory.add_memory(
    session_id="user-789",
    messages=[
        {"role": "user", "content": "I prefer meetings in the morning and like to review docs beforehand."},
    ],
)

# Retrieve preferences when scheduling
prefs = client.memory.search_memory(
    session_id="user-789",
    query="What are this user's meeting preferences?",
)

Pros

• ✅ Automatic Memory Extraction: Reduces manual work for memory management
• ✅ Structured Memory: Entities and facts, not just raw text
• ✅ Framework-Agnostic: Works with any LLM framework
• ✅ Self-Hostable: Full data control with Docker deployment
• ✅ Production-Ready: Scalable architecture for enterprise use
• ✅ Time-Travel: Restore conversation state to any point
• ✅ Multi-Language SDKs: Python, JavaScript, Go support

Cons

• ❌ Additional Infrastructure: Requires running a Zep server
• ❌ Less Flexible: Pre-built extraction may miss domain-specific concepts
• ❌ Smaller Community: Less community support than Mem0
• ❌ Entity Extraction Limits: May not capture all relevant entities
• ❌ Learning Curve: More concepts to understand than simple storage

Use Cases

Use Case	Why Zep
Customer Support	Remember customer history and preferences
Personal Assistants	Track user preferences and schedules
Production Chatbots	Scalable memory for enterprise deployments
Multi-session Applications	Maintain context across conversation sessions
Framework Integration	Memory layer for any LLM framework

Comparison with Alternatives

Feature	Zep	Mem0	AgentMemory	LangChain Memory
Paradigm	Entity extraction	Self-improving	Persistent storage	Conversation buffer
Entity Extraction	✅ Automatic	⚠️ Via LLM	❌ No	❌ No
Time-travel	✅ Yes	❌ No	⚠️ Via snapshots	❌ No
Framework Agnostic	✅ Yes	✅ Yes	✅ Yes	⚠️ LangChain only
Self-hostable	✅ Yes	⚠️ Cloud only	✅ Yes	✅ Yes
Learning Curve	Medium	Low	Medium	Low
Best for	Structured memory	Personalization	Coding agents	Simple conversations

Best Practices

1. Set up sessions early — Create sessions before adding memory
2. Use entity extractors — Define custom extractors for domain entities
3. Search with scope — Use appropriate scope (messages, summary, entities)
4. Enable summarization — Configure short-term and long-term summaries
5. Use snapshots for debugging — Create checkpoints for time-travel
6. Monitor extraction quality — Review extracted entities regularly

Troubleshooting

Issue	Solution
Entities not extracted	Configure entity extractors explicitly
Memory not persisting	Verify session_id is consistent
Slow search	Use hybrid search with keyword + semantic
Summaries missing	Enable summarization in session config
REST API errors	Check base_url and api_key configuration

Resources

• Official Documentation
• GitHub Repository
• Python SDK
• Docker Deployment Guide