Technical Documentation: getzep/zep

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Zep Cloud: Examples & Integrations

About This Repository Copy Chapter

This repository is not Zep's product or service. It contains example code, framework
integrations, and tools for building agent memory with Zep Cloud,
Zep's managed agent memory platform.

To use Zep Cloud, sign up at www.getzep.com and read the
documentation at help.getzep.com. Zep's official SDKs are:

• Python: pip install zep-cloud
• TypeScript/JavaScript: npm install @getzep/zep-cloud
• Go: go get github.com/getzep/zep-go/v3

Looking for the open-source temporal knowledge graph framework that powers Zep? See
Graphiti.

Contents Copy Chapter

Integrations Copy Chapter

Framework integration packages live under integrations/, organized
framework-first then language: integrations/<framework>/<language>/. Each package is built,
tested, and released independently.

• Python: Google ADK, Microsoft Agent Framework, Microsoft AutoGen, AG2, CrewAI, LangGraph, LiveKit, Pydantic AI, Strands Agents
• TypeScript: Google ADK, Mastra, Vercel AI SDK
• Go: Google ADK

See integrations/README.md for packages, release status, and
links, and integrations/CLAUDE.md for conventions.

Contributing Copy Chapter

We welcome contributions. See CONTRIBUTING.md for guidelines covering code,
documentation, bug reports, and community examples.

Community Edition (Deprecated) Copy Chapter

Zep Community Edition is no longer supported. Its code has been moved to the
legacy/ folder. Read more in
Announcing a New Direction for Zep's Open Source Strategy.

Mcp Zep Mcp Server Docs DOCKER (`mcp/zep-mcp-server/docs/DOCKER.md`) Copy Section

Docker Deployment Guide

This guide covers deploying the Zep MCP Server using Docker and Docker Compose.

Quick Start Copy Chapter

1. Create environment file:

   bash Copy

   cp .env.example .env
   # Edit .env and add your ZEP_API_KEY

2. Start with Docker Compose:

   bash Copy

   docker-compose up

The server will be available at http://localhost:8080.

Docker Build Copy Chapter

Building the Image Copy Section

Build the Docker image manually:

docker build -t zep-mcp-server:latest .

Or use the build script:

./scripts/build.sh

Build Arguments Copy Section

• VERSION: Set the version string (default: 0.1.0)

docker build --build-arg VERSION=1.0.0 -t zep-mcp-server:1.0.0 .

Multi-Platform Builds Copy Section

Build for multiple platforms:

docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t zep-mcp-server:latest \
    .

Running with Docker Copy Chapter

Run with Environment Variables Copy Section

docker run -d \
    --name zep-mcp-server \
    -e ZEP_API_KEY=your-key-here \
    -p 8080:8080 \
    zep-mcp-server:latest

Run with Environment File Copy Section

docker run -d \
    --name zep-mcp-server \
    --env-file .env \
    -p 8080:8080 \
    zep-mcp-server:latest

Run with Custom Port Copy Section

docker run -d \
    --name zep-mcp-server \
    -e ZEP_API_KEY=your-key-here \
    -p 9000:8080 \
    zep-mcp-server:latest \
    --port 8080

Run in Stdio Mode Copy Section

For use with Claude Desktop or Cline:

docker run -i \
    --name zep-mcp-server \
    -e ZEP_API_KEY=your-key-here \
    zep-mcp-server:latest \
    --stdio

Docker Compose Copy Chapter

Starting the Server Copy Section

Start in background:

docker-compose up -d

Start with logs:

docker-compose up

Stopping the Server Copy Section

docker-compose down

Viewing Logs Copy Section

docker-compose logs -f

Checking Status Copy Section

docker-compose ps

Restarting the Server Copy Section

docker-compose restart

Configuration Copy Chapter

Environment Variables Copy Section

Set these in .env file or pass via -e flag:

• ZEP_API_KEY (required): Your Zep Cloud API key
• LOG_LEVEL (optional): Logging level (debug, info, warn, error) - default: info

docker-compose.yml Copy Section

The compose file includes:

• Health checks: Automatic health monitoring
• Resource limits: CPU and memory constraints
• Security: Non-root user, read-only filesystem, no new privileges
• Logging: Configured with rotation (10MB max, 3 files)
• Restart policy: Automatically restarts unless stopped manually

Customizing docker-compose.yml Copy Section

Edit resource limits:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 256M

Change port mapping:

ports:
  - "9000:8080"

Health Checks Copy Chapter

The Docker container includes health checks that verify the server is responding on port 8080.

Check health status:

docker inspect --format='{{.State.Health.Status}}' zep-mcp-server

View health check logs:

docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' zep-mcp-server

Security Copy Chapter

Non-Root User Copy Section

The container runs as user zep (UID 1001) for security.

Read-Only Filesystem Copy Section

The container uses a read-only root filesystem with only /tmp as writable.

Security Options Copy Section

• no-new-privileges: Prevents privilege escalation
• Minimal Alpine base image with only essential packages

Troubleshooting Copy Chapter

Container Won't Start Copy Section

Check logs:

docker-compose logs

Verify environment variables:

docker-compose config

Connection Issues Copy Section

Verify port mapping:

docker ps

Test connectivity:

curl http://localhost:8080

Health Check Failures Copy Section

Check health status:

docker inspect zep-mcp-server | grep -A 10 Health

Permission Issues Copy Section

Ensure the container can write to /tmp:

docker exec zep-mcp-server ls -la /tmp

Production Deployment Copy Chapter

Using Docker Compose Copy Section

The included docker-compose.yml is configured for production with:

• Automatic restarts
• Resource limits
• Health checks
• Security hardening
• Log rotation

Best Practices Copy Section

1. Use secrets management for ZEP_API_KEY:

   • Docker secrets
   • Kubernetes secrets
   • Cloud provider secret managers

2. Monitor resource usage:

   bash Copy

   docker stats zep-mcp-server

3. Set up log aggregation:

   • Configure Docker logging driver for your platform
   • Use centralized logging (CloudWatch, Datadog, etc.)

4. Enable automatic updates:

   • Use Watchtower or similar tools
   • Set up CI/CD pipeline

5. Use specific version tags:

   bash Copy

   docker build -t zep-mcp-server:1.0.0 .

Makefile Integration Copy Chapter

Use make commands for common Docker operations:

# Build Docker image
make docker-build

# Run with Docker Compose
make docker-run

# Stop Docker Compose
make docker-down

# Clean Docker resources
make docker-clean

Registry Publishing Copy Chapter

Tag for Registry Copy Section

docker tag zep-mcp-server:latest your-registry.com/zep-mcp-server:latest

Push to Registry Copy Section

docker push your-registry.com/zep-mcp-server:latest

Pull from Registry Copy Section

docker pull your-registry.com/zep-mcp-server:latest

Advanced Usage Copy Chapter

Custom Entrypoint Copy Section

Override the entrypoint for debugging:

docker run -it --entrypoint /bin/sh zep-mcp-server:latest

Volume Mounting Copy Section

Mount configuration files:

docker run -v $(pwd)/.env:/app/.env zep-mcp-server:latest

Network Configuration Copy Section

Use custom networks:

docker network create zep-network
docker run --network zep-network zep-mcp-server:latest

CI/CD Integration Copy Chapter

GitHub Actions Example Copy Section

- name: Build Docker image
  run: docker build -t zep-mcp-server:${{ github.sha }} .

- name: Run tests
  run: docker run zep-mcp-server:${{ github.sha }} make test

- name: Push to registry
  run: |
    docker tag zep-mcp-server:${{ github.sha }} registry/zep-mcp-server:latest
    docker push registry/zep-mcp-server:latest

Support Copy Chapter

For issues or questions:

• Check the main README.md
• Review TOOLS.md for API documentation
• Open an issue on GitHub

Mcp Zep Mcp Server Docs TOOLS (`mcp/zep-mcp-server/docs/TOOLS.md`) Copy Section

Tool Reference

Complete reference for all tools provided by the Zep MCP Server.

Table of Contents Copy Chapter

• search_graph
• get_user_context
• get_user
• list_threads
• get_user_nodes
• get_user_edges
• get_episodes
• get_thread_messages
• get_node
• get_edge
• get_episode
• get_node_edges
• get_episode_mentions

search_graph Copy Chapter

Search the Zep knowledge graph for relevant information about a user.

Parameters Copy Section

Returns Copy Section

JSON object containing edges, nodes, and/or episodes depending on the search scope.

Example Copy Section

{
  "user_id": "alice_123",
  "query": "What are Alice's dietary preferences?",
  "scope": "edges",
  "limit": 5,
  "reranker": "cross_encoder",
  "edge_types": ["PREFERS", "LIKES"]
}

Use Cases Copy Section

• Finding specific facts about a user
• Retrieving relationship information
• Discovering relevant entities
• Building context for conversations
• Filtering by entity or relationship type

get_user_context Copy Chapter

Retrieve formatted context string for a conversation thread. Returns facts and entities relevant to the thread.

Parameters Copy Section

Returns Copy Section

JSON object containing:

• context: Formatted context string with facts and entities

Example Copy Section

{
  "thread_id": "conversation_456",
  "template_id": "my_custom_template"
}

Use Cases Copy Section

• Getting conversation-relevant context for prompts
• Building context-aware AI responses
• Using custom templates for structured context output

get_user Copy Chapter

Retrieve user information and metadata from Zep.

Parameters Copy Section

Returns Copy Section

JSON object containing user properties including user_id, email, first_name, last_name, created_at, and associated metadata.

Example Copy Section

{
  "user_id": "alice_123"
}

Use Cases Copy Section

• Getting user profile information
• Checking if a user exists
• Retrieving user metadata

list_threads Copy Chapter

List all conversation threads for a specific user.

Parameters Copy Section

Returns Copy Section

JSON array of thread objects containing thread_id, user_id, created_at, updated_at, and metadata.

Example Copy Section

{
  "user_id": "alice_123"
}

Use Cases Copy Section

• Browsing user's conversation history
• Thread discovery
• Analyzing conversation patterns

get_user_nodes Copy Chapter

Retrieve entity nodes from a user's knowledge graph. Nodes represent people, places, concepts, and other entities.

Parameters Copy Section

Returns Copy Section

JSON array of node objects containing uuid, name, labels, summary, created_at, and additional properties.

Example Copy Section

{
  "user_id": "alice_123",
  "limit": 10
}

Use Cases Copy Section

• Exploring entities in user's knowledge graph
• Understanding user's context and relationships
• Finding specific types of entities

get_user_edges Copy Chapter

Retrieve edges (relationships/facts) from a user's knowledge graph.

Parameters Copy Section

Returns Copy Section

JSON array of edge objects containing uuid, source_node_uuid, target_node_uuid, edge_type, fact, valid_at, and created_at.

Example Copy Section

{
  "user_id": "alice_123",
  "limit": 10
}

Use Cases Copy Section

• Examining relationships between entities
• Understanding fact provenance
• Temporal fact analysis

get_episodes Copy Chapter

Retrieve temporal episodes (events) from a user's knowledge graph history.

Parameters Copy Section

Returns Copy Section

JSON array of episode objects containing uuid, content, source, created_at, and metadata.

Example Copy Section

{
  "user_id": "alice_123",
  "lastn": 5
}

Use Cases Copy Section

• Accessing temporal data ingestion events
• Understanding conversation history context
• Analyzing data provenance

get_thread_messages Copy Chapter

Retrieve messages from a conversation thread.

Parameters Copy Section

Returns Copy Section

JSON object containing messages with role, content, uuid, and timestamps.

Example Copy Section

{
  "thread_id": "conversation_456",
  "lastn": 10
}

Use Cases Copy Section

• Reading conversation history
• Retrieving recent messages for context
• Auditing conversation content

get_node Copy Chapter

Retrieve a specific knowledge graph node (entity) by its UUID.

Parameters Copy Section

Returns Copy Section

JSON object containing the full node details including uuid, name, labels, summary, and properties.

Example Copy Section

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Use Cases Copy Section

• Getting full details of a node discovered via search
• Following up on entities returned by other tools

get_edge Copy Chapter

Retrieve a specific knowledge graph edge (relationship/fact) by its UUID.

Parameters Copy Section

Returns Copy Section

JSON object containing the full edge details including uuid, source_node_uuid, target_node_uuid, edge_type, fact, and temporal data.

Example Copy Section

{
  "uuid": "550e8400-e29b-41d4-a716-446655440001"
}

Use Cases Copy Section

• Getting full details of an edge discovered via search
• Understanding a specific relationship or fact

get_episode Copy Chapter

Retrieve a specific episode by its UUID.

Parameters Copy Section

Returns Copy Section

JSON object containing the full episode details including uuid, content, source, and metadata.

Example Copy Section

{
  "uuid": "550e8400-e29b-41d4-a716-446655440002"
}

Use Cases Copy Section

• Getting full details of a specific episode
• Examining episode content and metadata

get_node_edges Copy Chapter

Retrieve all edges (relationships/facts) connected to a specific node.

Parameters Copy Section

Returns Copy Section

JSON array of edge objects connected to the specified node.

Example Copy Section

{
  "node_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Use Cases Copy Section

• Exploring all relationships of a specific entity
• Graph traversal from a node
• Understanding an entity's connections

get_episode_mentions Copy Chapter

Retrieve nodes and edges mentioned in a specific episode.

Parameters Copy Section

Returns Copy Section

JSON object containing nodes and edges arrays — the entities and relationships mentioned in the episode.

Example Copy Section

{
  "uuid": "550e8400-e29b-41d4-a716-446655440002"
}

Use Cases Copy Section

• Understanding what entities and facts were extracted from an episode
• Tracing data provenance from episodes to graph elements
• Auditing knowledge graph construction

Common Patterns Copy Chapter

Combining Tools Copy Section

Tools can be combined for powerful workflows:

// 1. Get user threads
const threads = await tools.list_threads({ user_id: "alice_123" });

// 2. Get context for most recent thread
const context = await tools.get_user_context({
  thread_id: threads[0].thread_id
});

// 3. Search graph for specific information
const preferences = await tools.search_graph({
  user_id: "alice_123",
  query: "dietary preferences",
  scope: "edges"
});

// 4. Drill into a specific node
const node = await tools.get_node({
  uuid: preferences.nodes[0].uuid
});

// 5. Get all relationships for that node
const relationships = await tools.get_node_edges({
  node_uuid: node.uuid
});

Error Handling Copy Section

All tools return standard MCP errors:

• 400 Bad Request: Invalid parameters
• 401 Unauthorized: Invalid API key
• 404 Not Found: User, thread, or resource not found
• 500 Internal Server Error: Server or API error

Performance Optimization Copy Section

• Limit results with limit and lastn parameters
• Use search filters (node_labels, edge_types) to narrow results
• Use specific UUIDs when you know the exact entity you need

Temporal Queries Copy Section

Many results include temporal information:

• valid_at: When a fact is valid (edges)
• created_at: When data was created
• updated_at: When data was last modified

Use this information for temporal reasoning and context.

Need Help? Copy Chapter

• Zep Cloud Documentation
• GitHub Issues
• Discord Community

Ingestion Examples Data Docs Company Handbook (`ingestion/examples/data/docs/company_handbook.md`) Copy Section

Alder Ridge Robotics — Company Handbook

Purpose Copy Chapter

Alder Ridge Robotics designs automation systems for fulfillment centers. The
company's current product portfolio includes ROBOT-101, ROBOT-202, and the
OPERATIONS-DASHBOARD monitoring service.

Organization Copy Chapter

Avery Brown is vice president of engineering and works from North Campus.
Blake Carter leads the ROBOT-202 program. Casey Nguyen is chief technology
officer and owns the software portfolio, including OPERATIONS-DASHBOARD.

Robotics portfolio Copy Chapter

ROBOT-101 is the company's standard picking arm. ROBOT-202 is the next model
in the product line and was called PROTOTYPE-202 during early development.
Internal documentation should use ROBOT-202 as the canonical name.

Operations software Copy Chapter

OPERATIONS-DASHBOARD provides equipment status, utilization, and alert history.
Engineering owns release quality, while customer operations manages access and
onboarding.

Supplier relationship Copy Chapter

Westbridge Components supplies the ACTUATOR-09 assembly used by ROBOT-202.
Devon Brooks manages the account. Component orders require a six-week lead time,
and engineering must approve substitutions before purchase orders are issued.

Fulfillment evaluation Copy Chapter

Clearwater Fulfillment operates four ROBOT-101 units at South Warehouse. Morgan
Lee manages the site evaluation and coordinates weekly reviews with Alder Ridge
Robotics. Evertrail Freight Group uses the same support process for its regional
operations team.

Information handling Copy Chapter

Operational reports are shared only with project members. Do not place access
tokens, credentials, or personal contact information in project notes. Report
security concerns to the engineering lead.

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~5700 tokens
• Canonical Reference: https://codewiki.google/github.com/getzep/zep