> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-beta.getzep.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-beta.getzep.com/_mcp/server.

# Eve

[Eve](https://eve.dev) is Vercel's framework for building production agents. This guide shows how to wire Zep into an Eve agent with the Zep TypeScript SDK. The pattern uses hooks for persistence and authored tools for retrieval.

> **Keep retrieved context out of privileged instructions**
>
> Zep context can include content that your users, documents, or tools supplied. A system or developer message gives that content higher instruction priority than ordinary input. Some convenience integrations use system-message injection. Use direct SDK retrieval or an actual retrieval tool call unless all stored content is application-authored and trusted. Follow [Memory security best practices](/memory-security) for provider-specific placement.

> **Build an agent with Zep tools**
>
> To build an agent that plans its retrieval and uses several Zep tools, read [Build an Agent with Zep](/build-an-agent-with-zep). The guide shows how to add domain knowledge, design tools, and evaluate the agent.

## Why this pattern

Eve hooks are observe-only. They can persist side effects, but they cannot add model input. Authored tools preserve the distinction between application instructions and retrieved data.

| Concern       | Eve primitive                                   | Zep API                          |
| ------------- | ----------------------------------------------- | -------------------------------- |
| Persist turns | Hook (`message.received` / `message.completed`) | `thread.addMessages`             |
| Warm cache    | Hook (`session.started`)                        | `user.warm` (fire-and-forget)    |
| Recall        | Authored tool                                   | `graph.search` (`scope: "auto"`) |

Do not use Eve dynamic instructions or channel `context` for retrieved memory. Dynamic instructions enter a privileged channel. Channel context enters durable session history and accumulates.

Identity mapping stays outside the model:

* Eve `session.id` → Zep `threadId` (for example `eve-<sessionId>`)
* Eve session auth principal (or your app's user id) → Zep `userId`

Never accept `userId` or `threadId` from the model.

## Architecture

```text
Eve HTTP message
  │
  ├─ session.started → ensure user/thread, fire-and-forget warm
  ├─ message.received / message.completed → thread.addMessages
  └─ authored tools → graph.search on user or shared Context Graph
```

An authored tool passes its current query directly to `graph.search`. Pin the user or graph identity from authenticated session state.

## Setup

```bash
npm install @getzep/zep-cloud eve
```

> **Info**
>
> Requires Node.js 24+ (Eve), `@getzep/zep-cloud`, and a Zep Cloud API key from [app.getzep.com](https://app.getzep.com).

```bash
export ZEP_API_KEY="your-zep-api-key"
```

Provision users and threads with your own create-then-catch-conflict helper, shown here as `ensureZepUserAndThread`, so repeats are safe. After the helper returns, warm the user cache as fire-and-forget:

```typescript
await ensureZepUserAndThread({ userId, userName, threadId });
void zep.user.warm(userId).catch(() => {});
```

## Automatic message capture

Persist each turn with a hook. Skip interim narration before tool calls (`finishReason === "tool-calls"`); persist other completions (`stop`, `length`, and similar):

```typescript
export default defineHook({
  events: {
    async "session.started"(_event, ctx) {
      const identity = resolveZepIdentity(ctx);
      await ensureZepUserAndThread(identity);
      void zep.user.warm(identity.userId).catch(() => {});
    },

    async "message.received"(event, ctx) {
      const text = event.data.message?.trim()?.slice(0, 4000);
      if (!text) return;
      const { threadId, userName } = resolveZepIdentity(ctx);
      await zep.thread.addMessages(threadId, {
        messages: [{ role: "user", name: userName, content: text }],
      });
    },

    async "message.completed"(event, ctx) {
      if (event.data.finishReason === "tool-calls") return;
      const text = event.data.message?.trim()?.slice(0, 4000);
      if (!text) return;
      const { threadId } = resolveZepIdentity(ctx);
      await zep.thread.addMessages(threadId, {
        messages: [{ role: "assistant", name: "Eve Agent", content: text }],
      });
    },
  },
});
```

Wrap each Zep call in try/catch so a Zep outage never fails the Eve turn.

> **Info**
>
> Zep indexes knowledge asynchronously. Facts from a turn are not reliably searchable until processing finishes — often tens of seconds. Confirm facts in the [Zep app](https://app.getzep.com) before expecting preference recall in a new session.

## On-demand search tools

Expose `graph.search` as authored tools when the turn's memory section is incomplete. Pin `userId` / `graphId` from session auth or config — never from the model:

```typescript
// User graph
await zep.graph.search({
  userId,
  query: query.slice(0, 400), // Zep rejects queries over 400 chars
  scope: "auto",
  maxCharacters: 4000,
});

// Standalone company graph (seed once outside Eve, then search)
await zep.graph.search({
  graphId: process.env.ZEP_COMPANY_GRAPH_ID || "eve-demo-company",
  query: query.slice(0, 400), // Zep rejects queries over 400 chars
  scope: "auto",
  maxCharacters: 4000,
});
```

For shared organization knowledge, create and seed a [Context Graph](/graph-overview) with the Zep SDK. Wait for episodes to process before the tool searches the graph.

## Production notes

* **Replace demo identity** — resolve `userId` from real auth in multi-tenant production.
* **Idempotent ensure** — catch "already exists" on user and thread create.
* **Message size** — Zep rejects thread messages over 4,096 characters; truncate to \~4,000 before `thread.addMessages`.
* **Search query size** — Zep rejects `graph.search` queries over 400 characters; truncate before calling.
* **Async indexing** — do not expect read-after-write within the same turn.

## Learn more

* [Searching the graph](/searching-the-graph)
* [Eve multi-tenant memory](https://eve.dev/docs/patterns/multi-tenant-memory)
* [Eve dynamic capabilities](https://eve.dev/docs/guides/dynamic-capabilities)
* [Eve hooks](https://eve.dev/docs/guides/hooks)
* [Architecture patterns](/architecture-patterns)