# getzep/zep architecture

> Architecture diagram of the GitHub repository getzep/zep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getzep/zep
- Repository: https://github.com/getzep/zep

## Overview

#### 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: [`ingestion/src/zep_ingest/pipeline.py`](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/pipeline.py) (Ingestion pipeline), [`.github/workflows/release-integrations.yml`](https://github.com/getzep/zep/blob/main/.github/workflows/release-integrations.yml) (Integrations release), [`ingestion/src/zep_ingest/transforms/canonicalizer.py`](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/transforms/canonicalizer.py) (Transforms), [`ingestion/src/zep_ingest/submitters/batch.py`](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/submitters/batch.py) (Submitters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Bulk ingestion"]
  node_ingest_pipeline["Ingestion pipeline<br/>Python orchestration<br/>[pipeline.py]"]
  node_ingest_contracts["Ingestion contracts<br/>Python types<br/>[protocols.py]"]
  node_source_loaders["Source loaders<br/>Python adapters<br/>[text.py]"]
  node_transforms["Transforms<br/>Python processing<br/>[canonicalizer.py]"]
  node_submitters["Submitters<br/>Python delivery<br/>[batch.py]"]
end

subgraph group_integrations["Framework integrations"]
  node_adk_adapters["Google ADK adapters<br/>Go/Python/TypeScript integration<br/>[memory_service.py]"]
  node_python_adapters["Python framework adapters<br/>Python integrations<br/>[persistence.py]"]
  node_ts_adapters["TypeScript framework adapters<br/>TypeScript integrations<br/>[middleware.ts]"]
end

subgraph group_mcp["MCP access layer"]
  node_mcp_entrypoint["MCP server entrypoint<br/>Go CLI service<br/>[main.go]"]
  node_mcp_tool_server["Tool registration<br/>Go MCP server<br/>[tools.go]"]
  node_mcp_handlers["Domain handlers<br/>Go handlers<br/>[search.go]"]
  node_mcp_transform_client["Parameter transform and client<br/>Go Zep boundary<br/>[client.go]"]
end

subgraph group_evaluation["Evaluation and benchmarks"]
  node_eval_harness["Evaluation harness<br/>Python evaluation pipeline<br/>[zep_evaluate.py]"]
  node_locomo["LoCoMo benchmark<br/>Python benchmark<br/>[benchmark.py]"]
  node_longmemeval["LongMemEval benchmark<br/>Python benchmark"]
end

node_zep_cloud{{"Zep Cloud<br/>external platform"}}
node_official_sdks["Official SDKs<br/>external client SDKs"]
node_examples["Runtime examples<br/>[simple.py]"]
node_release_ingestion["Ingestion release<br/>GitHub workflow"]
node_release_integrations["Integrations release<br/>GitHub workflow"]

node_examples -->|"uses"| node_official_sdks
node_official_sdks -->|"calls"| node_zep_cloud
node_source_loaders -->|"source material"| node_ingest_pipeline
node_ingest_contracts -->|"defines contracts"| node_ingest_pipeline
node_ingest_pipeline -->|"normalizes and transforms"| node_transforms
node_transforms -->|"prepared records"| node_submitters
node_submitters -->|"ingests records"| node_zep_cloud
node_adk_adapters -->|"adapts to"| node_official_sdks
node_python_adapters -->|"adapts to"| node_official_sdks
node_ts_adapters -->|"adapts to"| node_official_sdks
node_mcp_entrypoint -->|"starts"| node_mcp_tool_server
node_mcp_tool_server -->|"dispatches tools"| node_mcp_handlers
node_mcp_handlers -->|"translates requests"| node_mcp_transform_client
node_mcp_transform_client -->|"calls"| node_zep_cloud
node_eval_harness -->|"ingests and evaluates"| node_zep_cloud
node_locomo -->|"measures"| node_zep_cloud
node_longmemeval -->|"measures"| node_zep_cloud
node_release_ingestion -.->|"releases"| node_ingest_pipeline
node_release_integrations -.->|"releases"| node_adk_adapters
node_release_integrations -.->|"releases"| node_python_adapters
node_release_integrations -.->|"releases"| node_ts_adapters

click node_examples "https://github.com/getzep/zep/blob/main/examples/python/simple.py"
click node_ingest_pipeline "https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/pipeline.py"
click node_ingest_contracts "https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/protocols.py"
click node_source_loaders "https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/loaders/text.py"
click node_transforms "https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/transforms/canonicalizer.py"
click node_submitters "https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/submitters/batch.py"
click node_adk_adapters "https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/memory_service.py"
click node_python_adapters "https://github.com/getzep/zep/blob/main/integrations/langgraph/python/src/zep_langgraph/persistence.py"
click node_ts_adapters "https://github.com/getzep/zep/blob/main/integrations/vercel-ai/typescript/src/middleware.ts"
click node_mcp_entrypoint "https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/cmd/server/main.go"
click node_mcp_tool_server "https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/internal/server/tools.go"
click node_mcp_handlers "https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/internal/handlers/search.go"
click node_mcp_transform_client "https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/pkg/zep/client.go"
click node_eval_harness "https://github.com/getzep/zep/blob/main/zep-eval-harness/zep_evaluate.py"
click node_locomo "https://github.com/getzep/zep/blob/main/benchmarks/locomo/benchmark.py"
click node_longmemeval "https://github.com/getzep/zep/blob/main/benchmarks/longmemeval/zep_longmem_eval.py"
click node_release_ingestion "https://github.com/getzep/zep/blob/main/.github/workflows/release-ingestion.yml"
click node_release_integrations "https://github.com/getzep/zep/blob/main/.github/workflows/release-integrations.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ingest_pipeline,node_ingest_contracts,node_source_loaders,node_transforms,node_submitters toneBlue
class node_adk_adapters,node_python_adapters,node_ts_adapters toneAmber
class node_mcp_entrypoint,node_mcp_tool_server,node_mcp_handlers,node_mcp_transform_client toneMint
class node_eval_harness,node_locomo,node_longmemeval toneRose
class node_zep_cloud,node_official_sdks,node_examples,node_release_ingestion,node_release_integrations toneNeutral
```

## Components

### Bulk ingestion

zep-ingest normalizes source material and delivers it to Zep Cloud.

- [Ingestion pipeline](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/pipeline.py): Python orchestration · Coordinates loading, transformation, and submission. · `ingestion/src/zep_ingest/pipeline.py`
- [Ingestion contracts](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/protocols.py): Python types · Internal protocols and normalized node types. · `ingestion/src/zep_ingest/protocols.py`
- [Source loaders](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/loaders/text.py): Python adapters · Text, Slack, email, and other heterogeneous inputs. · `ingestion/src/zep_ingest/loaders/text.py`
- [Transforms](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/transforms/canonicalizer.py): Python processing · Canonicalization, chunking, contextualization, and limits. · `ingestion/src/zep_ingest/transforms/canonicalizer.py`
- [Submitters](https://github.com/getzep/zep/blob/main/ingestion/src/zep_ingest/submitters/batch.py): Python delivery · 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](https://github.com/getzep/zep/blob/main/integrations/adk/python/src/zep_adk/memory_service.py): Go/Python/TypeScript integration · Memory services, callbacks, tools, and provisioning. · `integrations/adk/python/src/zep_adk/memory_service.py`
- [Python framework adapters](https://github.com/getzep/zep/blob/main/integrations/langgraph/python/src/zep_langgraph/persistence.py): Python integrations · Persistence, storage, search/context tools, and provisioning. · `integrations/langgraph/python/src/zep_langgraph/persistence.py`
- [TypeScript framework adapters](https://github.com/getzep/zep/blob/main/integrations/vercel-ai/typescript/src/middleware.ts): TypeScript integrations · 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](https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/cmd/server/main.go): Go CLI service · Starts the standalone Zep MCP server. · `mcp/zep-mcp-server/cmd/server/main.go`
- [Tool registration](https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/internal/server/tools.go): Go MCP server · Registers Zep capabilities as MCP tools. · `mcp/zep-mcp-server/internal/server/tools.go`
- [Domain handlers](https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/internal/handlers/search.go): Go handlers · Context, search, graph, user, message, thread, and episode operations. · `mcp/zep-mcp-server/internal/handlers/search.go`
- [Parameter transform and client](https://github.com/getzep/zep/blob/main/mcp/zep-mcp-server/pkg/zep/client.go): Go Zep boundary · 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](https://github.com/getzep/zep/blob/main/zep-eval-harness/zep_evaluate.py): Python evaluation pipeline · Chunks documents, ingests users/documents, inspects graphs, and evaluates responses. · `zep-eval-harness/zep_evaluate.py`
- [LoCoMo benchmark](https://github.com/getzep/zep/blob/main/benchmarks/locomo/benchmark.py): Python benchmark · Memory quality benchmark with ingestion flow. · `benchmarks/locomo/benchmark.py`
- [LongMemEval benchmark](https://github.com/getzep/zep/blob/main/benchmarks/longmemeval/zep_longmem_eval.py): Python benchmark · Long-memory evaluation against Zep. · `benchmarks/longmemeval/zep_longmem_eval.py`

### Other components

- **Zep Cloud**: external platform · Managed memory platform and primary remote boundary.
- **Official SDKs**: external client SDKs · Python, TypeScript, and Go client boundary.
- [Runtime examples](https://github.com/getzep/zep/blob/main/examples/python/simple.py): examples · Direct Zep Cloud usage in Python, TypeScript, and Go. · `examples/python/simple.py`
- [Ingestion release](https://github.com/getzep/zep/blob/main/.github/workflows/release-ingestion.yml): GitHub workflow · Independently releases the ingestion package. · `.github/workflows/release-ingestion.yml`
- [Integrations release](https://github.com/getzep/zep/blob/main/.github/workflows/release-integrations.yml): GitHub workflow · Independently releases framework packages. · `.github/workflows/release-integrations.yml`

## Connections

- 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
