Eve
Eve is a framework for building agents. This guide is for developers who want an eve agent to recall a user’s prior conversations or search shared knowledge. It uses eve’s memory provider API and the Zep TypeScript SDK.
Zep does not ship a separate eve package. Copy the provider code into your app and adapt the identity resolver to your storage.
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 for provider-specific placement.
To build an agent that plans its retrieval and uses several Zep tools, read Build an Agent with Zep. The guide shows how to add domain knowledge, design tools, and evaluate the agent.
How the provider works
The provider uses eve’s memory lifecycle. It adds messages to Zep, returns a Context Block as recalled data, and exposes graph search tools.
The provider runs recall before the first model call of every turn. eve can run recall again when the caller changes.
Recall adds the user message to the Zep thread before it gets the Context Block, so Zep searches with the new message. If you add the message after the reply, the block matches the previous message, not the current one.
The provider returns recalled messages with the memory slot. eve places them before the turn input and keeps them for the rest of the session.
Each recalled message has the user role. It does not become a system instruction. Treat all Zep memory as untrusted user data. Do not follow commands in retrieved memory.
Choose how the agent retrieves context
Use a Context Block for conversation grounding. Use search tools when the agent must choose when and what to search. You can use both methods.
All modes add the current user input to the Zep thread. The contextBlock option controls whether recall returns a Context Block.
The provider defaults to contextBlock: true, userGraphTool: true, graphs: [], and no ignored roles. Each graph search requests up to 10 results.
Keep the prompt cache
Do not put the Context Block in eve dynamic instructions or in the system prompt. The memory security guide forbids retrieved data in a privileged channel. A block that changes on each turn at the start of the request also breaks the prompt cache for the full history. Agent memory placement can cut your token bill up to 2x explains the cost.
Recall with a fixed ID keeps the cache. On each turn, eve removes the earlier block and adds the new block before the current user message. The history before the previous turn does not change, so the model provider reads it from the cache. Each turn writes only the previous turn, the new block, and the new user message to the cache.
eve sets the cache options for you:
- Claude through Anthropic, Amazon Bedrock, or Google Vertex AI: eve adds cache breakpoints to each model call.
- AI Gateway: eve turns on Gateway automatic caching.
- OpenAI: OpenAI caches a matching prompt prefix automatically. eve sends a
promptCacheKeyfor each session.
Do not set gateway.caching to false.
Setup
Use Node.js 24 or later and eve 0.84.0 or later.
Map eve identities to Zep
Use byPrincipal to scope memory to the authenticated eve principal. The example stores the Zep user UUID by ctx.memory.scope.key. It stores the thread UUID by the scope key and ctx.session.id, so a different caller in the same eve session gets a separate Zep thread. The user name comes from trusted authentication data in ctx.session.auth.current, not from model input.
The example uses in-memory maps as a stand-in for your application database. Replace them with durable, concurrency-safe storage. Store each UUID after Zep creates the resource. A repeated create without a stored UUID can create another resource.
Zep assigns the user and thread UUIDs. The example does not send a client identifier to user.create or thread.create.
The user graph tool uses the Zep user UUID as its graph UUID. The model supplies the search query, not the graph UUID.
Create the memory provider
agent/lib/zep-memory.ts
eve can run a handler again with the same ctx.operationId. Zep requires a UUIDv4 idempotency key, so the provider hashes ctx.operationId into a deterministic UUIDv4 and passes it to thread.addMessages. A retried handler does not add the same message twice. It uses the current user graph UUID or a configured shared graph UUID for search. The model supplies only a query and an optional scope.
agent/memory/zep.ts
Set assistantName to the product name that users know, such as Acme Assistant. Message names improve entity deduplication and help Zep connect each fact to the correct entity. The assistant name helps Zep distinguish the assistant from the user and the user’s business. User messages use the trusted userName value.
Set ignoreRoles: ["assistant"] to stop Zep from extracting facts from assistant messages. Ignored assistant messages stay in the thread. Zep uses them as context when it extracts facts from later user messages, so a user reply such as “Yes” keeps the meaning of the question that it answers.
The example uses the defaults: Context Block recall and a user graph search tool.
Add one object to graphs for each shared graph. Set name to a unique lowercase identifier, such as company_knowledge. The provider rejects the reserved name user_graph and duplicate names. Set graphUuid to the UUID from application configuration. Set description to text that explains the search purpose.
For example: { name: "company_knowledge", graphUuid: "graph-uuid-from-config", description: "Search approved company knowledge." }. eve exposes the tool as zep__search_company_knowledge.
eve exposes the user graph tool as zep__search_user_graph.
Keep Zep memory untrusted
Add instructions that keep retrieved memory separate from trusted instructions.
agent/instructions.md
Seed shared Context Graphs
Create and seed each shared Context Graph outside the eve provider with the Zep SDK. Use graph.create and graph.episode.add. These operations start asynchronous indexing. Wait until Zep has processed the episode before you expect a search tool to return its facts or entities. Store each graph UUID in application configuration and pass it through the provider’s graphs option.
Production notes
- Message size: Zep accepts up to 4,096 characters in a thread message. The provider truncates user and assistant messages to 4,000 characters.
- Search query size: The provider truncates a graph search query to 400 characters.
- Indexing delay: Zep indexes messages and episodes asynchronously. A later search can return newly added data after indexing completes. Do not depend on read-after-write in the same turn.
- Stable recall ID: The provider returns the Context Block with the ID
zep-context-block. eve replaces an earlier recalled message with the same ID. A recalled message without an ID accumulates. - Session context: eve 0.84.0 and later keeps recalled memory outside durable history. The recalled message remains in the session and counts toward each model call.
- Failure handling: A recall handler that throws fails the turn. This provider catches Zep errors and returns
null, so the turn continues without new memory. When recall returnsnull, eve keeps the Context Block from an earlier turn of the same session, so the model can read an older block. eve starts again with no recalled messages for a new scope, such as a different caller, so an old block does not go to a different user. To remove the old block when Zep fails, return a message with the IDzep-context-blockthat tells the model that memory is not available. eve logs an uncaught capture error, but this provider catches Zep errors in capture. - History size: Zep ingests messages asynchronously, so the latest Context Block may not contain facts from the last several messages. Send at least the last four to six messages to the model with the block. eve sends the full session history by default, and more messages are fine. Above that minimum, the trade-off is cost and latency. Read Provide the last four to six messages.
- Untrusted data: Zep memory can contain user input. Do not treat retrieved memory as instructions.