Related Pages

Related topics: Agent Framework Integrations, Zep MCP Server & Claude/Cursor Plugin, Evaluation Harness & Ontology

Repository Overview & Examples Catalog

The getzep/zep repository is a multi-package monorepo centered on Zep's long-term memory service for AI agents. Beyond the core server, it distributes reference examples, framework integrations, an evaluation harness, and an MCP server. The examples/ and integrations/ directories form a curated catalog that demonstrates how to attach Zep's temporal knowledge graph, user-summary generation, and contextual retrieval to real applications. Source: examples/python/user-summary-instructions-example/README.md:1-40.

Examples by Language

The examples/ tree provides runnable, end-to-end patterns in three languages. The Python directory covers the broadest surface: a user-summary-instructions-example (a real estate sales agent chatbot driven by thread.get_user_context()), a chunking-example that demonstrates Anthropic-style contextualized retrieval, plus memory, search, and assistant demos. Source: examples/python/user-summary-instructions-example/README.md:21-39. The TypeScript directory mirrors the contextualized retrieval pattern via examples/typescript/chunking-example, useful for Node.js-based agents. Source: examples/typescript/chunking-example/README.md:1-15. The Go directory offers a chunking-example for Go services, illustrating that the same pipeline (chunk → contextualize → ingest) is reproducible outside Python. Source: examples/go/chunking-example/README.md:1-15.

Each example expects a .env containing ZEP_API_KEY and an LLM provider key (e.g., OPENAI_API_KEY), and uses Zep's AsyncZep client for asynchronous ingestion. The chunking examples share a common design: prepending a brief document context to each chunk before embedding, which materially improves retrieval recall. Source: examples/python/chunking-example/README.md:9-37.

Framework Integrations

The integrations/ directory packages Zep as a drop-in component for popular agent frameworks.

CrewAI's integration exposes per-user memory and a generic knowledge graph, with tool factories create_search_tool and create_add_data_tool bound to either a user_id or graph_id at construction time. Source: integrations/crewai/python/README.md:13-58. The zep-crewai v1.1.1 release fixed a regression where external memory search results returned a "memory" key; the result key is now "context" for CrewAI v0.186.0+. Source: community release notes (zep-crewai v1.1.1).

LiveKit's adapter supports two memory models—ZepUserAgent for thread-based per-user memory, and ZepGraphAgent for direct graph manipulation—and both work against the same underlying temporal knowledge graph. Source: integrations/livekit/python/README.md:24-66. AutoGen uses ZepUserMemory registered via the framework's memory=[...] slot on an AssistantAgent. Source: integrations/autogen/python/README.md:7-39.

The Google ADK integration (Python and TypeScript) provides two complementary tools. ZepContextTool injects context on every turn, while ZepGraphSearchTool is model-callable: search parameters can be *pinned* at construction time and hidden from the schema, locking the tool to a fixed graph_id or user_id. Source: integrations/adk/python/src/zep_adk/graph_search_tool.py:1-31 and integrations/adk/typescript/src/graph-search-tool.ts:11-37. The ADK packages require zep-cloud>=3.23.0 and google-adk>=1.0.0. Source: integrations/adk/python/README.md:55-58.

The Vercel AI SDK adapter is a thin TypeScript package that depends on @getzep/zep-cloud ^3.23.0 and peers on ai ^6.0.0, targeting Node 20+. Source: integrations/vercel-ai/typescript/package.json:1-43. Finally, mcp/zep-mcp-server is a Go implementation of the Model Context Protocol, built on zep-go v3, exposing Zep's tools to any MCP-compatible client. Source: mcp/zep-mcp-server/README.md:1-15.

Evaluation Harness

zep-eval-harness/ is a reproducible pipeline for benchmarking memory quality. It separates configuration into document_ingestion_config/, user_ingestion_config/, document_chunking_config/, and evaluation_config/, and writes each run to a timestamped directory under runs/ with a snapshot of the active config, ensuring reproducibility even if configs change later. Source: zep-eval-harness/README.md:1-35. The pipeline executes: user ingestion → document chunking → document ingestion → evaluation, with optional custom ontologies, custom instructions, and user-summary-instructions. The evaluation step is concurrency-tunable (default 15) and emits results.json plus an evaluation_config_snapshot/. Source: zep-eval-harness/README.md:35-95.

Repository Topology

graph TD
  Repo[getzep/zep monorepo]
  Repo --> Ex[examples/]
  Repo --> Int[integrations/]
  Repo --> Eval[zep-eval-harness/]
  Repo --> MCP[mcp/zep-mcp-server/]
  Ex --> PyEx[python/<br/>user-summary, chunking]
  Ex --> TsEx[typescript/<br/>chunking]
  Ex --> GoEx[go/<br/>chunking]
  Int --> CrewAI[CrewAI]
  Int --> LK[LiveKit]
  Int --> AG[AutoGen]
  Int --> ADK[Google ADK<br/>py + ts]
  Int --> Vercel[Vercel AI SDK]

See Also

• CrewAI integration release notes (v1.1.1) for context vs. memory key changes.
• ADK Python and TypeScript source for ZepGraphSearchTool parameter pinning.
• Evaluation harness config snapshots under runs/ for reproducibility.

Related Pages

Related topics: Repository Overview & Examples Catalog, Zep MCP Server & Claude/Cursor Plugin

Agent Framework Integrations

Zep ships a dedicated integrations/ monorepo of framework adapters that wrap its agent-memory platform for popular agent runtimes. Each adapter is a separate, installable package so consumers add only what their stack requires. The integrations expose two capabilities — automatic context injection and on-demand tool calls — over Zep's high-level SDK.

Repository Layout and Supported Frameworks

Integration packages are organized framework-first, then language at integrations/<framework>/<language>/, as documented in integrations/README.md. Each package ships a README, a SETUP.md, a runnable example, a test suite, and a changelog.

Source: integrations/README.md

Per the same file, planned adapters include Microsoft Agent Framework (Python), Pydantic AI (Python), LangGraph (Python), Mastra (TypeScript), and Google ADK (Go). Verified extension points for each planned target are catalogued in integrations/SPIKE_FINDINGS.md. The LangGraph CLI example at examples/typescript/langgraph/ demonstrates the same Zep memory pattern outside the official integrations namespace.

Common Integration Patterns

Across frameworks, adapters converge on two primitives.

1. Memory-backed context injection. The framework receives a Zep Memory/storage object that is consulted on every turn. In CrewAI, ZepUserStorage returns Zep's auto-assembled context block via thread.get_user_context, while ZepGraphStorage composes context for shared knowledge graphs (integrations/crewai/python/README.md). AutoGen follows the same shape: ZepUserMemory(client, user_id, thread_id) is added to an AssistantAgent's memory= list (integrations/autogen/python/README.md).

2. On-demand search and write tools. Agents that need explicit recall receive a search tool — and optionally an add tool — that wraps client.graph.search() or client.user.search(). The ADK Python implementation pins selected parameters to keep the model schema lean while exposing a configurable query (integrations/adk/python/src/zep_adk/graph_search_tool.py). The TypeScript counterpart ZepGraphSearchTool follows an identical contract, resolving the search target to either a pinned graphId or the current user's graph (integrations/adk/typescript/src/graph-search-tool.ts).

Reference: Google ADK Integration

The ADK adapter is the most complete cross-language example. The Python package exposes ZepContextTool (auto-injected on every turn) and ZepGraphSearchTool (model-callable on demand); the TypeScript package — built with tsup and tested with vitest against @google/adk 1.2.0 (integrations/adk/typescript/package.json) — provides the same surface.

flowchart LR
    User[User message] --> Agent[ADK Agent]
    Agent -->|every turn| CT[ZepContextTool]
    CT -->|inject context block| Agent
    Agent -->|on demand| ST[ZepGraphSearchTool]
    ST -->|graph.search| Zep[(Zep Graph)]
    Agent -->|graph.add| Zep

Search targets resolve as follows: a pinned graph_id/graphId always wins, otherwise the adapter looks up zep_user_id from ADK session state (Python) or the ADK userId (TypeScript). This dual mode lets the same agent operate over a shared documentation graph or a per-user personal graph without code changes (integrations/adk/python/src/zep_adk/graph_search_tool.py).

Storage Classes and Ontology

CrewAI exposes the broadest storage API and is the canonical reference for patterns other adapters adopt. ZepUserStorage saves messages to a thread and parallel-searches thread + user graph; ZepGraphStorage adds multi-scope search (edges, nodes, episodes) with label and attribute filters, and supports structured entity ontologies through client.graph.set_ontology(entities=..., edges=...) (integrations/crewai/python/README.md). The latest zep-crewai release (v1.1.1) renamed the external memory search key from "memory" to "context" to stay compatible with CrewAI v0.186.0+, a change that affects every ZepUserStorage, ZepGraphStorage, and ZepStorage consumer.

Development and Release Workflow

Each integration builds and tests in isolation. Python packages use uv sync --extra dev && uv run pytest && uv build; TypeScript uses npm ci && npm test; Go uses go test ./.... CI paths are wired via .github/workflows/test-integrations.yml using paths-filter, and releases are cut per-package so a CrewAI patch does not ship through ADK. To add a new adapter, create integrations/<framework>/<language>/, implement the framework's memory/context extension point listed in SPIKE_FINDINGS.md, add tests plus a runnable example, and wire CI (integrations/README.md).

See Also

• integrations/CLAUDE.md — per-language conventions for contributors
• integrations/SPIKE_FINDINGS.md — verified framework extension points
• plugins/building-with-zep/README.md — Claude Code skill that guides Zep integration work

Related Pages

Related topics: Repository Overview & Examples Catalog, Agent Framework Integrations

Zep MCP Server & Claude/Cursor Plugin

Overview

The Zep repository ships two complementary developer-experience surfaces that expose Zep Cloud to AI coding assistants and external agent runtimes: a read-only MCP (Model Context Protocol) server written in Go, and a Claude Code plugin named building-with-zep. Both surfaces are designed to give AI agents safe, structured access to Zep's temporal knowledge graph and conversation memory, but they serve different audiences — the MCP server targets any MCP-compatible client (Claude Desktop, Cline, custom Go services, etc.), while the Claude Code plugin is purpose-built for authoring Zep integration code from inside Claude Code.

Source: mcp/zep-mcp-server/README.md ; plugins/building-with-zep/README.md

Related Pages

Related topics: Repository Overview & Examples Catalog, Zep MCP Server & Claude/Cursor Plugin

Evaluation Harness & Ontology

Purpose and Scope

The Evaluation Harness is a Python-based pipeline for benchmarking Zep's long-term memory layer against user-defined question/answer test cases. It ingests synthetic user profiles and conversations into Zep's user graphs, optionally builds a separate document knowledge graph with a configurable ontology, and then grades an LLM's responses against Zep-retrieved context. The result is a reproducible, LLM-judged quality score for memory-augmented assistants.

The harness ships alongside the rest of the repository, in zep-eval-harness/. It exposes a sequence of CLI scripts (uv run zep_*.py) and a structured config/ tree that lets users tune ontology, custom instructions, chunking parameters, and evaluation prompts independently.

High-Level Architecture

The harness is organized as seven discrete pipeline steps, each producing a timestamped, snapshot-versioned run directory under runs/. This design makes every evaluation fully reproducible even after the active config files change.

flowchart LR
  A[Discover Test Cases] --> B[Ingest Users]
  C[Chunk Documents] --> D[Ingest Documents]
  B --> E[Evaluate]
  D --> E
  E --> F[Inspect Graph]
  E --> G[results.json]

Each stage is independently invokable, supports --resume from checkpoints, and writes a copy of its active config (*_config_snapshot/) into the run directory (Source: [zep-eval-harness/README.md]).

Pipeline Stages

1. User Ingestion

zep_ingest_users.py reads data/users.json, generates random suffixes for idempotency, and creates Zep users with full names and metadata. It can also enable a custom ontology (entity/edge types), custom instructions (extraction directives), and user summary instructions that bias the long-form user summary toward specific questions:

uv run zep_ingest_users.py --custom-ontology --custom-instructions --user-summary-instructions

A run is written to runs/users/{N}_{timestamp}/manifest.json, including the full user_ingestion_config_snapshot/ (Source: [zep-eval-harness/README.md]).

2. Document Chunking

zep_chunk_documents.py splits source documents into chunks and (optionally) calls an LLM to generate a context prefix for each chunk — Anthropic's contextualized retrieval technique. Chunks are streamed into chunks.jsonl so a parallel ingestion script can tail the file. Resumable via --resume runs/chunk_sets/{N}_{timestamp} (Source: [zep-eval-harness/README.md]).

The contextualized-retrieval pattern is also documented as a standalone example: each chunk is prepended with a brief description so the embedding model can disambiguate references such as "the policy" (Source: [examples/typescript/chunking-example/README.md]).

3. Document Ingestion

zep_ingest_documents.py ingests chunks into a standalone Zep graph. It supports three modes:

Both --custom-ontology and --custom-instructions flags are accepted, and ingestion writes to runs/documents/{N}_{timestamp}/manifest.json with a snapshot of the active ontology/instructions (Source: [zep-eval-harness/README.md]).

4. Evaluation

zep_evaluate.py ties the pipeline together. For each test case it:

1. Searches the user graph and (optionally) the document graph.
2. Generates an answer with a configurable LLM_RESPONSE_MODEL using get_response_system_prompt().
3. Grades the answer with a separate LLM_JUDGE_MODEL.

Concurrency is bounded by an asyncio semaphore (default --concurrency 15). The script accepts --user-run N and --doc-run N to combine prior user and document ingestion runs, and saves results to runs/evaluations/{N}_{timestamp}/results.json (Source: [zep-eval-harness/README.md]).

5. Graph Inspection

zep_graph_inspect.py is an operator's tool — it accepts either a user ID or a graph_id (from a manifest) and prints the contents of the resulting graph for debugging (Source: [zep-eval-harness/README.md]).

Configuration Layout

The config/ tree is split by concern so a single change does not bleed across pipeline stages:

config/
├── user_ingestion_config/
│   ├── ontology.py                 # Document graph entity/edge types + set_document_custom_ontology()
│   └── custom_instructions.py       # Document graph custom instructions
├── document_chunking_config/
│   └── constants.py                # CHUNK_SIZE, CHUNK_OVERLAP, LLM_CONTEXTUALIZATION_MODEL
└── evaluation_config/
    ├── constants.py                # Search limits, LLM_RESPONSE_MODEL, LLM_JUDGE_MODEL
    └── response_prompt.py          # get_response_system_prompt() — system prompt for AI responses

The response prompt used during evaluation is defined in config/evaluation_config/response_prompt.py and can be customized independently from the evaluation logic itself (Source: [zep-eval-harness/README.md]).

Ontology & Custom Instructions

The harness exposes two complementary levers for shaping the document graph:

• Custom ontology — declares entity types (e.g. Concept, Topic, Process) and edge types (e.g. DESCRIBES, DEPENDS_ON, PART_OF, REFERENCES, IMPLEMENTS) so the extraction LLM produces structured, typed nodes/edges.
• Custom instructions — named instruction sets (e.g. real_estate_reference_domain, home_buying_process, financial_concepts) that bias the extractor toward domain-specific vocabulary and relationships.

Both are stored as part of the run manifest so a later reproduction can replay extraction verbatim (Source: [zep-eval-harness/README.md]).

User Summary Instructions

A related, but distinct, Zep feature is User Summary Instructions, which causes the long-form user summary to always answer a curated set of questions (budget, must-haves, location priorities in the real-estate example). The examples/python/user-summary-instructions-example/ app demonstrates this with a Streamlit dashboard that compares agent behavior with and without the instructions (Source: [examples/python/user-summary-instructions-example/README.md]).

Resilience, Concurrency, and Run Tracking

All four pipeline scripts include retry logic with exponential backoff (up to 8 retries, max 5-minute delay) for handling rate limits and transient API errors. The concurrency knobs are:

Every pipeline step writes a numbered, timestamped subdirectory under runs/. Each subdirectory carries a config snapshot — a copy of the active config files — guaranteeing that even if config files change later, the original run remains reproducible. Manifest files reference their parent user and document ingestion runs, forming a complete provenance chain from raw data to graded results (Source: [zep-eval-harness/README.md]).

Data Contracts

The harness auto-discovers data files by naming convention:

• Users — data/users.json, a JSON array of {user_id, first_name, last_name, email, metadata}.
• Conversations — data/conversations/{user_id}_{conversation_id}.json, with a messages array suitable for memory.add().
• Documents — arbitrary paths resolved by the chunking script.
• Test cases — discovered by zep_evaluate.py, each producing a single graded result entry.

Random suffixes added during user ingestion make ingestion idempotent — re-running the script does not create duplicate users (Source: [zep-eval-harness/README.md]).

Common Failure Modes

1. Stale snapshots — If you edit config/ontology.py after creating users, the snapshot in the user run will not match the new file. New user runs will use the updated config; old ones remain frozen.
2. Rate limits during evaluation — Default concurrency of 15 may exceed model quotas on large test sets. Lower --concurrency or rely on the built-in exponential backoff.
3. Resume mismatch — --resume paths must point at an existing run directory whose chunk set status matches the requested mode (completed for reuse, in_progress for follow).
4. Ontology drift — Changing entity/edge types between user and document runs can produce graphs the judge cannot compare fairly; keep ontology stable across the runs you intend to evaluate together.

See Also

• Zep Documentation — Retrieving Memory
• Zep Documentation — Customizing Context Blocks
• examples/python/chunking-example/README.md
• examples/go/chunking-example/README.md
• examples/python/user-summary-instructions-example/README.md
• integrations/crewai/python/README.md

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/getzep/zep

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/getzep/zep

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/getzep/zep

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/getzep/zep

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/getzep/zep

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/getzep/zep

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using zep with real data or production workflows.

• zep-crewai v1.1.1 - github / github_release
• v1.0.2 - Add URL escaping to db connection string - github / github_release
• v1.0.1 - github / github_release
• v1.0.0 - Zep Community Edition - github / github_release
• v0.27.2 - Use appropriate token limit for gpt-4o-mini model - github / github_release
• v0.27.1 - Default openai model to gpt-4o-mini - github / github_release
• v0.27.0 - Support for new OpenAI models; dependency security update - github / github_release
• v0.26.0 - Fix Azure Embedding Issue; Support for New OpenAI and Anthropi - github / github_release
• v0.25.0 - Use Exponential Backoff for Metadata Lock Fails - github / github_release
• v0.24.0 - Experimental locking approach for high-concurrency user metada - github / github_release
• Capability evidence risk requires verification - GitHub / issue