The Open Framework for Building Agents
title: "Build a Memory Provider" description: "Implement the recall, capture, and tools contract so any store or memory service can back an eve memory slot."
A memory provider is an object with a recall handler and optional capture
and tools handlers. eve calls those handlers at fixed points in the agent
lifecycle and passes each one a locked scope key, the projected conversation,
and a stable operation ID. Anything that can read and write under that key can
be a provider. Package one as a library that exports a provider factory, or
write one directly inside an agent.
import { defineMemoryProvider } from "eve/memory";
import { defineTool } from "eve/tools";
import { z } from "zod";
import { notes } from "./notes-db";
export function notesMemory() {
return defineMemoryProvider({
recall: {
async "turn.started"(ctx) {
const rows = await notes.search({
partition: ctx.memory.scope.key,
query: ctx.turn.input,
limit: 5,
});
return {
messages: rows.map((row) => ({ id: row.id, content: row.text })),
};
},
},
capture: {
async "turn.completed"(ctx) {
await notes.ingest({
partition: ctx.memory.scope.key,
idempotencyKey: ctx.operationId,
messages: ctx.messages,
});
},
},
async tools(ctx) {
return {
forget: defineTool({
description: "Delete a remembered note by its ID.",
inputSchema: z.object({ id: z.string() }),
async execute({ id }) {
await notes.delete({ partition: ctx.memory.scope.key, id });
return { deleted: true };
},
}),
};
},
});
}
Bind the provider to a slot like any other:
import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";
import { notesMemory } from "../lib/notes-memory";
export default defineMemory({
description: "Notes the caller has asked the agent to remember.",
provider: notesMemory(),
scope: byPrincipal,
});
The model sees the tool as notes__forget, and the slot description is
prepended to its description.
The provider contract
defineMemoryProvider() accepts three surfaces. Omit any handler the provider
does not need; fileMemory(), for example, implements recall and tools but no
capture.
| Surface | Handlers | Responsibility |
|---|---|---|
recall |
"turn.started" (required), "compaction.completed" |
Return messages to place in model context |
capture |
"turn.completed", "compaction.requested" |
Observe settled history and write to the store |
tools |
one function | Return model-facing operations bound to the locked scope |
Operation context
Every handler receives a MemoryOperationContext:
| Field | Meaning |
|---|---|
memory.scope.key |
Opaque, versioned digest of the namespace and scope. Use it as the partition key for every read and write. |
memory.scope.namespace |
The resolved namespace string |
memory.scope.value |
The resolved scope string or tuple |
memory.slot |
The path-derived slot name |
messages |
Projected conversation history for this phase |
operationId |
Stable per session, turn, step, phase, and slot. Use it as an idempotency key. |
abortSignal |
Cancellation for the operation |
session |
Session ID, authentication, and other SessionContext fields |
Phase-specific fields:
turn.startedandturn.completedaddturnwith the turnid,inputmessages, andsequence.compaction.requestedaddscompaction.modelIdandcompaction.usageInputTokens;turnisnullfor standalone compaction.compaction.completedaddscompaction.modelId;turnmay benull.
tools() receives a MemoryToolsContext with the same memory and turn
fields plus the ordinary dynamic-resolve context.
Recall results
A recall handler returns { messages }, null, or undefined. Each message
has content and an optional id:
return {
messages: [
{ id: "preferred-language", content: "The user prefers Spanish." },
{ content: "A relevant note without a stable identity." },
],
};
eve adds each message to model context as a user-role message attributed to the slot. Provider content is never promoted to system instructions.
Use a stable id for replaceable facts. A later message with the same ID in
the same slot, namespace, and scope supersedes the earlier one; identical
content is a no-op. Messages without an ID accumulate, even when their content
repeats. Omitting an earlier ID from a later result does not delete it; recall
cannot retract, only supersede.
Tools
tools() returns a map of defineTool() values or null. eve qualifies each
key as <slot>__<key>; the qualified name must start with a letter, contain
only letters, digits, underscores, or dashes, and be at most 64 characters.
Schemas, approval, outputSchema, and toModelOutput work as they do for
authored tools.
A tool closes over the locked scope for the current turn, so it cannot be
redirected to another tenant or caller by the model. eve keeps each tool
callback replayable after a process restart or redeployment. On replay, eve
calls tools() again with the captured memory, turn, and session context.
messages is the history the current process resolved the turn's tools with,
so after a mid-turn restart it also includes the turn's earlier tool results.
Lifecycle
| Phase | Handler | messages contains |
|---|---|---|
turn.started |
recall["turn.started"] |
History before recall; the new delivery is in turn.input |
turn.completed |
capture["turn.completed"] |
Settled history after a successful turn |
compaction.requested |
capture["compaction.requested"] |
History before the checkpoint changes |
compaction.completed |
recall["compaction.completed"] |
The checkpoint plus canonical recalled records |
At turn start, eve resolves and locks the scope for every active slot before any recall runs. All slots see the same pre-recall history, and eve commits their validated results atomically.
During compaction, eve excludes recalled records from the summarizer, keeps the
latest value for each keyed record plus every unkeyed record, and then calls
recall["compaction.completed"] against the new checkpoint. This keeps
provider content attributable and prevents a summary from turning it into
ordinary conversation history. During a turn, eve places those recalled records
before the turn's latest user message, as it does at turn start; between turns
they follow the checkpoint. If raw superseded records exceed 512 entries or
256 KiB, eve canonicalizes them without waiting for the normal token threshold;
this changes session history only, not the provider's store.
Calling clear() on a session removes its history, recalled records, locked
scopes, and replay bookkeeping. It does not touch the provider's store; a later
turn recalls the same data again.
Failure behavior
- A throwing or invalid
recall["turn.started"]fails the turn before the model call. No slot's recall results are committed. If the turn'sabortSignalis already aborted, eve treats the error as cancellation and continues with any queued follow-up. AnAbortErrorwith an active signal still fails the turn. - A throwing
capture["compaction.requested"]leaves history unchanged. - A throwing
recall["compaction.completed"]fails an automatic turn. For standalone compaction, eve logs the error and returns the session to waiting, because the checkpoint has already been written. - An invalid or throwing
tools()result is logged and omitted for that turn. - A throwing
capture["turn.completed"]is logged after the response and does not rewrite the completed turn.
Requirements
Providers must:
- Partition every read and write by
memory.scope.key. For semantic retrieval, include the key in the query itself, not as a filter after a global search. - Treat
operationIdas an idempotency key. eve may replay a handler with the same ID; replaying a recall with a different result is an error. - Enforce their own size and retention policies. eve does not truncate or expire provider content.
- Treat recalled content as user-controlled data.
eve enforces these limits on the values it passes to and receives from a provider:
| Value | Limit |
|---|---|
| Namespace | 1,024 UTF-8 bytes |
| Each scope component | 1,024 UTF-8 bytes |
| Scope tuple | 16 components |
| Combined canonical namespace and scope | 4,096 bytes |
Recall message id |
1,024 UTF-8 bytes |
What to read next
- Memory overview: slots, scope, namespace, and visibility.
- File memory: the built-in provider as a reference implementation.
- Dynamic capabilities: the dynamic-tool lifecycle provider tools run through.
- Default harness: compaction in the built-in loop.