# Technical Documentation: getzep/zep > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/getzep/zep) ### Overview (README.md)

Zep Logo

Zep Cloud: Examples & Integrations

Chat on Discord Twitter Follow

## About This Repository This repository is **not** Zep's product or service. It contains **example code, framework integrations, and tools** for building agent memory with [Zep Cloud](https://www.getzep.com/), Zep's managed agent memory platform. To use Zep Cloud, sign up at [www.getzep.com](https://www.getzep.com/) and read the documentation at [help.getzep.com](https://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](https://github.com/getzep/graphiti). ## Contents | Project / directory | Description | |---------------------|-------------| | [`examples/`](examples/) | Example apps and snippets in Python, TypeScript, and Go | | [`integrations/`](integrations/) | Agent-framework integration packages | | [`ingestion/`](ingestion/) | `zep-ingest` — bulk data ingestion pipeline (Slack, documents, email, JSON/CSV, fact triples) | | [`ontology/`](ontology/) | Default ontology definitions | | [Build with Zep](https://github.com/getzep/building-with-zep-plugin) | Agent plugin for Claude Code, Codex, and Cursor (separate repository) | | [Zep Memory](https://github.com/getzep/zep-memory-plugin) | Agent plugin for Claude Desktop/Cowork and ChatGPT Work (separate repository) | | [`benchmarks/`](benchmarks/) | Memory benchmarks (LoCoMo, LongMemEval) | | [`zep-eval-harness/`](zep-eval-harness/) | Evaluation harness for ingestion and retrieval | | [`legacy/`](legacy/) | Deprecated Zep Community Edition (unsupported) | ## Integrations Framework integration packages live under [`integrations/`](integrations/), organized framework-first then language: `integrations///`. 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`](integrations/README.md) for packages, release status, and links, and [`integrations/CLAUDE.md`](integrations/CLAUDE.md) for conventions. ## Contributing We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines covering code, documentation, bug reports, and community examples. ## Community Edition (Deprecated) Zep Community Edition is no longer supported. Its code has been moved to the [`legacy/`](legacy/) folder. Read more in [Announcing a New Direction for Zep's Open Source Strategy](https://blog.getzep.com/announcing-a-new-direction-for-zeps-open-source-strategy/). --- ### Mcp Zep Mcp Server Docs DOCKER (`mcp/zep-mcp-server/docs/DOCKER.md`) # Docker Deployment Guide This guide covers deploying the Zep MCP Server using Docker and Docker Compose. ## Quick Start 1. **Create environment file:** ```bash cp .env.example .env # Edit .env and add your ZEP_API_KEY ``` 2. **Start with Docker Compose:** ```bash docker-compose up ``` The server will be available at `http://localhost:8080`. ## Docker Build ### Building the Image Build the Docker image manually: ```bash docker build -t zep-mcp-server:latest . ``` Or use the build script: ```bash ./scripts/build.sh ``` ### Build Arguments - `VERSION`: Set the version string (default: 0.1.0) ```bash docker build --build-arg VERSION=1.0.0 -t zep-mcp-server:1.0.0 . ``` ### Multi-Platform Builds Build for multiple platforms: ```bash docker buildx build \ --platform linux/amd64,linux/arm64 \ -t zep-mcp-server:latest \ . ``` ## Running with Docker ### Run with Environment Variables ```bash 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 ```bash docker run -d \ --name zep-mcp-server \ --env-file .env \ -p 8080:8080 \ zep-mcp-server:latest ``` ### Run with Custom Port ```bash 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 For use with Claude Desktop or Cline: ```bash docker run -i \ --name zep-mcp-server \ -e ZEP_API_KEY=your-key-here \ zep-mcp-server:latest \ --stdio ``` ## Docker Compose ### Starting the Server Start in background: ```bash docker-compose up -d ``` Start with logs: ```bash docker-compose up ``` ### Stopping the Server ```bash docker-compose down ``` ### Viewing Logs ```bash docker-compose logs -f ``` ### Checking Status ```bash docker-compose ps ``` ### Restarting the Server ```bash docker-compose restart ``` ## Configuration ### Environment Variables 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 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 Edit resource limits: ```yaml deploy: resources: limits: cpus: '2' memory: 256M ``` Change port mapping: ```yaml ports: - "9000:8080" ``` ## Health Checks The Docker container includes health checks that verify the server is responding on port 8080. Check health status: ```bash docker inspect --format='{{.State.Health.Status}}' zep-mcp-server ``` View health check logs: ```bash docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' zep-mcp-server ``` ## Security ### Non-Root User The container runs as user `zep` (UID 1001) for security. ### Read-Only Filesystem The container uses a read-only root filesystem with only `/tmp` as writable. ### Security Options - `no-new-privileges`: Prevents privilege escalation - Minimal Alpine base image with only essential packages ## Troubleshooting ### Container Won't Start Check logs: ```bash docker-compose logs ``` Verify environment variables: ```bash docker-compose config ``` ### Connection Issues Verify port mapping: ```bash docker ps ``` Test connectivity: ```bash curl http://localhost:8080 ``` ### Health Check Failures Check health status: ```bash docker inspect zep-mcp-server | grep -A 10 Health ``` ### Permission Issues Ensure the container can write to /tmp: ```bash docker exec zep-mcp-server ls -la /tmp ``` ## Production Deployment ### Using Docker Compose The included `docker-compose.yml` is configured for production with: - Automatic restarts - Resource limits - Health checks - Security hardening - Log rotation ### Best Practices 1. **Use secrets management** for ZEP_API_KEY: - Docker secrets - Kubernetes secrets - Cloud provider secret managers 2. **Monitor resource usage**: ```bash 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 docker build -t zep-mcp-server:1.0.0 . ``` ## Makefile Integration Use make commands for common Docker operations: ```bash # 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 ### Tag for Registry ```bash docker tag zep-mcp-server:latest your-registry.com/zep-mcp-server:latest ``` ### Push to Registry ```bash docker push your-registry.com/zep-mcp-server:latest ``` ### Pull from Registry ```bash docker pull your-registry.com/zep-mcp-server:latest ``` ## Advanced Usage ### Custom Entrypoint Override the entrypoint for debugging: ```bash docker run -it --entrypoint /bin/sh zep-mcp-server:latest ``` ### Volume Mounting Mount configuration files: ```bash docker run -v $(pwd)/.env:/app/.env zep-mcp-server:latest ``` ### Network Configuration Use custom networks: ```bash docker network create zep-network docker run --network zep-network zep-mcp-server:latest ``` ## CI/CD Integration ### GitHub Actions Example ```yaml - 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 For issues or questions: - Check the main [README.md](../README.md) - Review [TOOLS.md](TOOLS.md) for API documentation - Open an issue on GitHub --- ### Mcp Zep Mcp Server Docs TOOLS (`mcp/zep-mcp-server/docs/TOOLS.md`) # Tool Reference Complete reference for all tools provided by the Zep MCP Server. ## Table of Contents - [search_graph](#search_graph) - [get_user_context](#get_user_context) - [get_user](#get_user) - [list_threads](#list_threads) - [get_user_nodes](#get_user_nodes) - [get_user_edges](#get_user_edges) - [get_episodes](#get_episodes) - [get_thread_messages](#get_thread_messages) - [get_node](#get_node) - [get_edge](#get_edge) - [get_episode](#get_episode) - [get_node_edges](#get_node_edges) - [get_episode_mentions](#get_episode_mentions) --- ## search_graph Search the Zep knowledge graph for relevant information about a user. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User ID to search within | | `query` | string | Yes | Search query text | | `scope` | string | No | Search scope: `edges`, `nodes`, or `episodes` (default: `edges`) | | `limit` | integer | No | Maximum results (default: 10, max: 50) | | `reranker` | string | No | Reranking strategy: `rrf`, `mmr`, `node_distance`, `episode_mentions`, `cross_encoder` | | `min_fact_rating` | number | No | Minimum fact rating threshold for filtering results | | `mmr_lambda` | number | No | Weighting for maximal marginal relevance reranking | | `center_node_uuid` | string | No | Node UUID to rerank around for `node_distance` reranking | | `node_labels` | array[string] | No | Filter results by node labels | | `edge_types` | array[string] | No | Filter results by edge types | ### Returns JSON object containing edges, nodes, and/or episodes depending on the search scope. ### Example ```javascript { "user_id": "alice_123", "query": "What are Alice's dietary preferences?", "scope": "edges", "limit": 5, "reranker": "cross_encoder", "edge_types": ["PREFERS", "LIKES"] } ``` ### Use Cases - 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 Retrieve formatted context string for a conversation thread. Returns facts and entities relevant to the thread. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `thread_id` | string | Yes | Thread (conversation) identifier | | `template_id` | string | No | Context template ID for custom context rendering | ### Returns JSON object containing: - `context`: Formatted context string with facts and entities ### Example ```javascript { "thread_id": "conversation_456", "template_id": "my_custom_template" } ``` ### Use Cases - Getting conversation-relevant context for prompts - Building context-aware AI responses - Using custom templates for structured context output --- ## get_user Retrieve user information and metadata from Zep. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User identifier | ### Returns JSON object containing user properties including `user_id`, `email`, `first_name`, `last_name`, `created_at`, and associated metadata. ### Example ```javascript { "user_id": "alice_123" } ``` ### Use Cases - Getting user profile information - Checking if a user exists - Retrieving user metadata --- ## list_threads List all conversation threads for a specific user. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User identifier | ### Returns JSON array of thread objects containing `thread_id`, `user_id`, `created_at`, `updated_at`, and metadata. ### Example ```javascript { "user_id": "alice_123" } ``` ### Use Cases - Browsing user's conversation history - Thread discovery - Analyzing conversation patterns --- ## get_user_nodes Retrieve entity nodes from a user's knowledge graph. Nodes represent people, places, concepts, and other entities. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User identifier | | `limit` | integer | No | Maximum nodes to return (default: 20) | ### Returns JSON array of node objects containing `uuid`, `name`, `labels`, `summary`, `created_at`, and additional properties. ### Example ```javascript { "user_id": "alice_123", "limit": 10 } ``` ### Use Cases - Exploring entities in user's knowledge graph - Understanding user's context and relationships - Finding specific types of entities --- ## get_user_edges Retrieve edges (relationships/facts) from a user's knowledge graph. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User identifier | | `limit` | integer | No | Maximum edges to return (default: 20) | ### Returns JSON array of edge objects containing `uuid`, `source_node_uuid`, `target_node_uuid`, `edge_type`, `fact`, `valid_at`, and `created_at`. ### Example ```javascript { "user_id": "alice_123", "limit": 10 } ``` ### Use Cases - Examining relationships between entities - Understanding fact provenance - Temporal fact analysis --- ## get_episodes Retrieve temporal episodes (events) from a user's knowledge graph history. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `user_id` | string | Yes | User identifier | | `lastn` | integer | No | Return the last N episodes (default: 10) | ### Returns JSON array of episode objects containing `uuid`, `content`, `source`, `created_at`, and metadata. ### Example ```javascript { "user_id": "alice_123", "lastn": 5 } ``` ### Use Cases - Accessing temporal data ingestion events - Understanding conversation history context - Analyzing data provenance --- ## get_thread_messages Retrieve messages from a conversation thread. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `thread_id` | string | Yes | Thread identifier | | `lastn` | integer | No | Number of most recent messages to return (overrides limit) | | `limit` | integer | No | Maximum number of messages to return | ### Returns JSON object containing messages with `role`, `content`, `uuid`, and timestamps. ### Example ```javascript { "thread_id": "conversation_456", "lastn": 10 } ``` ### Use Cases - Reading conversation history - Retrieving recent messages for context - Auditing conversation content --- ## get_node Retrieve a specific knowledge graph node (entity) by its UUID. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `uuid` | string | Yes | The UUID of the node to retrieve | ### Returns JSON object containing the full node details including `uuid`, `name`, `labels`, `summary`, and properties. ### Example ```javascript { "uuid": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Use Cases - Getting full details of a node discovered via search - Following up on entities returned by other tools --- ## get_edge Retrieve a specific knowledge graph edge (relationship/fact) by its UUID. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `uuid` | string | Yes | The UUID of the edge to retrieve | ### Returns JSON object containing the full edge details including `uuid`, `source_node_uuid`, `target_node_uuid`, `edge_type`, `fact`, and temporal data. ### Example ```javascript { "uuid": "550e8400-e29b-41d4-a716-446655440001" } ``` ### Use Cases - Getting full details of an edge discovered via search - Understanding a specific relationship or fact --- ## get_episode Retrieve a specific episode by its UUID. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `uuid` | string | Yes | The UUID of the episode to retrieve | ### Returns JSON object containing the full episode details including `uuid`, `content`, `source`, and metadata. ### Example ```javascript { "uuid": "550e8400-e29b-41d4-a716-446655440002" } ``` ### Use Cases - Getting full details of a specific episode - Examining episode content and metadata --- ## get_node_edges Retrieve all edges (relationships/facts) connected to a specific node. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `node_uuid` | string | Yes | The UUID of the node to get edges for | ### Returns JSON array of edge objects connected to the specified node. ### Example ```javascript { "node_uuid": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Use Cases - Exploring all relationships of a specific entity - Graph traversal from a node - Understanding an entity's connections --- ## get_episode_mentions Retrieve nodes and edges mentioned in a specific episode. ### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `uuid` | string | Yes | The UUID of the episode | ### Returns JSON object containing `nodes` and `edges` arrays — the entities and relationships mentioned in the episode. ### Example ```javascript { "uuid": "550e8400-e29b-41d4-a716-446655440002" } ``` ### Use Cases - Understanding what entities and facts were extracted from an episode - Tracing data provenance from episodes to graph elements - Auditing knowledge graph construction --- ## Common Patterns ### Combining Tools Tools can be combined for powerful workflows: ```javascript // 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 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 - 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 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? - [Zep Cloud Documentation](https://help.getzep.com/) - [GitHub Issues](https://github.com/getzep/zep/issues) - [Discord Community](https://discord.gg/W8Kw6bsgXQ) --- ### Ingestion Examples Data Docs Company Handbook (`ingestion/examples/data/docs/company_handbook.md`) # Alder Ridge Robotics — Company Handbook ## Purpose 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 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 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 OPERATIONS-DASHBOARD provides equipment status, utilization, and alert history. Engineering owns release quality, while customer operations manages access and onboarding. ## Supplier relationship 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 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 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