How getzep/zep works
Purpose and Scope
This is a multi-language companion repository for Zep Cloud, a managed agent-memory platform—not the Zep service itself. It ships reusable framework integrations, a bulk-ingestion library, examples, evaluation/benchmark tooling, and an MCP server. Zep Cloud and its official Python, TypeScript, and Go SDKs are the primary external boundary.
Primary Entry Surfaces
• Application examples demonstrate direct Zep Cloud usage across runtimes: examples/python/simple.py, examples/typescript/memory/memory_example.ts, examples/go/main.go.
• Production-oriented packages are independently scoped under ingestion/ and integrations/<framework>/<language>/.
• CLI/service entry points include mcp/zep-mcp-server/cmd/server/main.go and evaluation scripts such as zep-eval-harness/zep_evaluate.py.
Bulk Ingestion Pipeline
zep-ingest is the central data-processing subsystem. It accepts heterogeneous source material, normalizes it into internal nodes/types, applies optional transforms, and submits records to Zep Cloud.
• Orchestration and contracts: ingestion/src/zep_ingest/pipeline.py, ingestion/src/zep_ingest/protocols.py, ingestion/src/zep_ingest/types.py.
• Source adapters cover text, email, Slack, JSON records, transcripts, and composition: ingestion/src/zep_ingest/loaders/text.py, ingestion/src/zep_ingest/loaders/slack.py, ingestion/src/zep_ingest/loaders/email.py.
• Transform boundary handles canonicalization, chunking, contextualization, and limits before remote submission: ingestion/src/zep_ingest/transforms/canonicalizer.py, ingestion/src/zep_ingest/transforms/chunker.py, ingestion/src/zep_ingest/transforms/contextualizer.py.
• Submission supports sequential or batched delivery, making throughput/retry behavior separate from source parsing: ingestion/src/zep_ingest/submitters/sequential.py, ingestion/src/zep_ingest/submitters/batch.py.
Agent Framework Integrations
Each integration adapts a host agent framework’s lifecycle, memory/context abstractions, tools, identity, and provisioning onto Zep Cloud APIs. Packages are framework-first and independently versioned/released.
• Google ADK has Go, Python, and TypeScript implementations, including memory services, callbacks, context/search tools, and provisioning: integrations/adk/python/src/zep_adk/memory_service.py, integrations/adk/typescript/src/memory-service.ts, integrations/adk/go/memory.go.
• Python adapters follow a common shape: memory or persistence/store integration plus graph search/context tools and resource provisioning; e.g. integrations/langgraph/python/src/zep_langgraph/persistence.py, integrations/autogen/python/src/zep_autogen/tools.py, integrations/crewai/python/src/zep_crewai/graph_storage.py.
• TypeScript integrations expose middleware/processors/tools to Vercel AI and Mastra: integrations/vercel-ai/typescript/src/middleware.ts, integrations/mastra/typescript/src/processors.ts.
MCP Access Layer
The standalone Go MCP server exposes Zep context, search, users, messages, threads, graph nodes/edges, and episodes as MCP tools. It translates MCP parameters/results to a Zep client boundary.
• Server/tool registration: mcp/zep-mcp-server/internal/server/server.go, mcp/zep-mcp-server/internal/server/tools.go.
• Domain handlers: mcp/zep-mcp-server/internal/handlers/search.go, mcp/zep-mcp-server/internal/handlers/context.go, mcp/zep-mcp-server/internal/handlers/nodes.go.
• Remote client and request transformation: mcp/zep-mcp-server/pkg/zep/client.go, mcp/zep-mcp-server/internal/transform/params.go.
Evaluation and Benchmarking
Two evaluation areas measure memory ingestion/retrieval quality against datasets and persist reproducible run artifacts.
• The evaluation harness stages document chunking, user ingestion, document ingestion, graph inspection, and response evaluation: zep-eval-harness/zep_chunk_documents.py, zep-eval-harness/zep_ingest_documents.py, zep-eval-harness/zep_evaluate.py.
• Benchmarks target LoCoMo and LongMemEval: benchmarks/locomo/benchmark.py, benchmarks/locomo/ingestion.py, benchmarks/longmemeval/zep_longmem_eval.py.
Legacy Boundary and Delivery
legacy/ is explicitly deprecated, unsupported Community Edition code; it contains a separate Go HTTP server and PostgreSQL-backed persistence and should not be treated as the active architecture: legacy/src/main.go, legacy/src/api/routes.go, legacy/src/lib/pg/db.go. Active code spans Python, TypeScript/Node.js, Go, and occasional React/Next.js example UIs. GitHub workflows release ingestion and integration packages independently: .github/workflows/release-ingestion.yml, .github/workflows/release-integrations.yml.
Main entry points: pipeline.py Ingestion pipeline · release-integrations.yml Integrations release · canonicalizer.py Transforms · batch.py Submitters
Components 20
Bulk ingestion
zep-ingest normalizes source material and delivers it to Zep Cloud.
- Ingestion pipeline · Coordinates loading, transformation, and submission.
ingestion/src/zep_ingest/pipeline.py - Ingestion contracts · Internal protocols and normalized node types.
ingestion/src/zep_ingest/protocols.py - Source loaders · Text, Slack, email, and other heterogeneous inputs.
ingestion/src/zep_ingest/loaders/text.py - Transforms · Canonicalization, chunking, contextualization, and limits.
ingestion/src/zep_ingest/transforms/canonicalizer.py - Submitters · Sequential or batched remote delivery.
ingestion/src/zep_ingest/submitters/batch.py
Framework integrations
Independently released adapters map agent frameworks onto Zep APIs.
- Google ADK adapters · Memory services, callbacks, tools, and provisioning.
integrations/adk/python/src/zep_adk/memory_service.py - Python framework adapters · Persistence, storage, search/context tools, and provisioning.
integrations/langgraph/python/src/zep_langgraph/persistence.py - TypeScript framework adapters · Vercel AI middleware and Mastra processors/tools.
integrations/vercel-ai/typescript/src/middleware.ts
MCP access layer
Standalone Go server exposes Zep capabilities as MCP tools.
- MCP server entrypoint · Starts the standalone Zep MCP server.
mcp/zep-mcp-server/cmd/server/main.go - Tool registration · Registers Zep capabilities as MCP tools.
mcp/zep-mcp-server/internal/server/tools.go - Domain handlers · Context, search, graph, user, message, thread, and episode operations.
mcp/zep-mcp-server/internal/handlers/search.go - Parameter transform and client · Converts MCP requests and calls the Zep client.
mcp/zep-mcp-server/pkg/zep/client.go
Evaluation and benchmarks
Dataset-driven ingestion and retrieval quality measurement.
- Evaluation harness · Chunks documents, ingests users/documents, inspects graphs, and evaluates responses.
zep-eval-harness/zep_evaluate.py - LoCoMo benchmark · Memory quality benchmark with ingestion flow.
benchmarks/locomo/benchmark.py - LongMemEval benchmark · Long-memory evaluation against Zep.
benchmarks/longmemeval/zep_longmem_eval.py
Other components
- Zep Cloud · Managed memory platform and primary remote boundary.
- Official SDKs · Python, TypeScript, and Go client boundary.
- Runtime examples · Direct Zep Cloud usage in Python, TypeScript, and Go.
examples/python/simple.py - Ingestion release · Independently releases the ingestion package.
.github/workflows/release-ingestion.yml - Integrations release · Independently releases framework packages.
.github/workflows/release-integrations.yml
Connections 21
- Runtime examples → Official SDKs: uses
- Official SDKs → Zep Cloud: calls
- Source loaders → Ingestion pipeline: source material
- Ingestion contracts → Ingestion pipeline: defines contracts
- Ingestion pipeline → Transforms: normalizes and transforms
- Transforms → Submitters: prepared records
- Submitters → Zep Cloud: ingests records
- Google ADK adapters → Official SDKs: adapts to
- Python framework adapters → Official SDKs: adapts to
- TypeScript framework adapters → Official SDKs: adapts to
- MCP server entrypoint → Tool registration: starts
- Tool registration → Domain handlers: dispatches tools
- Domain handlers → Parameter transform and client: translates requests
- Parameter transform and client → Zep Cloud: calls
- Evaluation harness → Zep Cloud: ingests and evaluates
- LoCoMo benchmark → Zep Cloud: measures
- LongMemEval benchmark → Zep Cloud: measures
- Ingestion release → Ingestion pipeline: releases
- Integrations release → Google ADK adapters: releases
- Integrations release → Python framework adapters: releases
- Integrations release → TypeScript framework adapters: releases