How to choose an eve memory provider

Every eve memory provider decides how an agent's long-term memory is stored, how relevant context is retrieved before each turn, and whether conversations are captured automatically or only when the model calls a tool.

eve includes a built-in file memory provider and supports hosted providers, including Supermemory, Upstash AgentKit, and Kybernesis Arcana, as well as custom providers you build yourself.

Because eve owns the memory slot, scope, and lifecycle, you can change providers without changing who memory belongs to or how it's isolated. Each provider keeps data in its own backend, so picking the right one early avoids a data migration later.

Copy link to headingOverview

In this guide, you'll learn:

• What an eve memory provider controls and what eve controls
• How the available providers compare on recall, capture, and storage
• Which questions narrow the choice for your agent
• How to install a provider, combine providers, and switch later

Copy link to headingWhat an eve memory provider controls

Each eve memory provider controls storage and retrieval, while eve controls the memory slot around it. You declare a memory slot as a file under agent/memory/, and the slot binds one provider to a scope that decides who shares the memory.

Every provider follows the same lifecycle because of this boundary. eve asks the provider to recall context before each turn, lets it capture what happened after the turn, and exposes any tools it offers to the model. Recalled content enters model context as user-role messages, never as system instructions.

Copy link to headingHow eve memory providers compare

eve memory providers differ mainly in how they recall context, whether they capture conversations automatically, and where they store data.

Copy link to headingFile memory

File memory, built into eve as fileMemory() from eve/memory/file, keeps one small document per scope and recalls the whole document before each turn. The model maintains the document with save_memory and remove_memory tools, because the provider doesn't extract facts automatically.

eve add memory/file

The command writes file.ts and, when you choose Install and set up, creates or reuses a private Edgenivo Blob store for the linked project and connects it using OIDC. When you run the agent locally with eve dev, file memory uses process-local in-memory storage and needs no external service.

import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";
import { fileMemory } from "eve/memory/file";

export default defineMemory({
  description: "Remember stable facts and preferences about the caller.",
  provider: fileMemory(),
  scope: byPrincipal,
});

Copy link to headingSupermemory

Supermemory is a hosted memory service with an eve provider. It recalls relevant context with semantic search before each turn, captures completed turns automatically, and gives the model tools to search, remember, forget, and extract sources.

eve add memory/supermemory

The command installs @supermemory/eve and writes supermemory.ts. The provider reads its API key from SUPERMEMORY_API_KEY.

import supermemory from "@supermemory/eve";
import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";

export default defineMemory({
  description: "Recall and manage durable context for the current user.",
  provider: supermemory({
    apiKey: process.env.SUPERMEMORY_API_KEY!,
  }),
  scope: byPrincipal,
});

Copy link to headingUpstash AgentKit

Upstash AgentKit backs an eve memory slot with your own Upstash Redis database. redisMemory() recalls relevance-ranked facts before each turn, captures user messages after completed turns by default, and gives the model tools to save, search, read past sessions, and forget.

eve add memory/upstash-agentkit

The command installs @upstash/agentkit-eve and writes upstash-agentkit.ts. The topK option sets how many facts the provider recalls.

import { redisMemory } from "@upstash/agentkit-eve/memory";
import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";

export default defineMemory({
  description: "Recall and manage durable context for the current user.",
  provider: redisMemory({ topK: 5 }),
  scope: byPrincipal,
});

redisMemory() uses two environment variables for the connection by default, UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN. To use a different client, pass your own @upstash/redis client as the redis option.

The same package also exports redisDocuments(), a storage backend for eve's built-in fileMemory() provider. Use it when you want file memory's single model-curated document stored in Redis instead of Edgenivo Blob:

import { redisDocuments } from "@upstash/agentkit-eve/memory";
import { defineMemory } from "eve/memory";
import { fileMemory } from "eve/memory/file";
import { byPrincipal } from "eve/memory/scope";

export default defineMemory({
  description: "Stable facts about the caller, curated by the model.",
  provider: fileMemory({ backend: redisDocuments() }),
  scope: byPrincipal,
});

Copy link to headingKybernesis Arcana

Kybernesis Arcana backs an eve memory slot with semantic search and brain notes. It gives the model tools to remember, recall, and search memory, and leaves automatic capture disabled by default.

eve add memory/arcana

The command installs @kybernesis/arcana and writes arcana.ts. The provider reads ARCANA_API_KEY and ARCANA_WORKSPACE. Set capture: { enabled: true } in the provider options to capture completed turns automatically.

import { arcanaMemory } from "@kybernesis/arcana/memory";
import { defineMemory } from "eve/memory";
import { byPrincipal } from "eve/memory/scope";

export default defineMemory({
  description: "Recall and manage durable context for the current user.",
  provider: arcanaMemory({
    apiKey: process.env.ARCANA_API_KEY!,
    workspace: process.env.ARCANA_WORKSPACE!,
  }),
  scope: byPrincipal,
});

Copy link to headingCustom provider

You create a custom eve memory provider with defineMemoryProvider() from eve/memory by supplying a required recall handler and optional capture and tools handlers. eve passes each handler a locked scope key, the projected conversation, and a stable operation ID, so any store that can read and write under that key can back a slot.

The custom eve memory provider guide walks through each handler, from recalling records before a turn to exposing scoped tools to the model.

Copy link to headingQuestions that narrow the choice

Copy link to headingShould memory be captured automatically or only when the model saves it?

Automatic capture builds memory from every conversation without relying on the model to decide what's worth keeping. Supermemory captures completed turns, Upstash AgentKit captures user messages by default, and Kybernesis Arcana captures turns when you enable it.

Model-driven capture stores only what the model explicitly saves through a tool call, which gives you tighter control over what ends up in storage. File memory works this way, as does Kybernesis Arcana's default configuration and Upstash AgentKit's tools. Choose model-driven capture when the agent handles sensitive conversations and you want saving to be a deliberate, visible action.

Copy link to headingDoes the agent need semantic retrieval?

File memory recalls the entire document for the scope on every turn, capped at 4,000 characters by default. That works well for a short list of preferences and stable facts. When memory grows beyond what fits in every turn, choose a provider that retrieves only the relevant records, such as Supermemory or Kybernesis Arcana for semantic search, or Upstash AgentKit for ranked Redis Search recall.

Copy link to headingWhere should memory data live?

File memory, Upstash AgentKit, and custom providers keep data in infrastructure you already control, whether that's a Blob store in your Edgenivo project, your own Redis database, or any store you operate. Supermemory and Kybernesis Arcana keep data in their own hosted services, which you access with an API key. That split affects billing, data residency, and who operates the infrastructure.

Copy link to headingHow much memory does each scope need?

File memory enforces fixed size limits and rejects writes that exceed them instead of truncating or evicting older entries:

Raise the recall cap with fileMemory({ maxCharacters: 8_000 }) if you need more room. If your agent needs to remember more than a single bounded document per caller can hold, choose a provider with retrieval.

Copy link to headingDoes the agent need to run without external services during local development?

File memory runs during eve dev with process-local in-memory storage and needs no account, credentials, or network service. The hosted providers need their credentials configured before memory works locally, such as SUPERMEMORY_API_KEY for Supermemory, UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN for Upstash AgentKit, or ARCANA_API_KEY and ARCANA_WORKSPACE for Kybernesis Arcana.

Copy link to headingDo you need custom retrieval, retention, or compliance controls?

eve doesn't truncate or expire provider content, so retention and deletion are the provider's responsibility. Build a custom provider when memory must live in a specific database, follow a retention policy you control, or use retrieval logic.

Copy link to headingWhich eve memory provider to start with

Match your agent's main requirement to a starting provider:

Copy link to headingSettings that stay the same across providers

Scope, namespace, visibility, and description are memory slot settings on defineMemory(), not provider options. They behave the same way regardless of which provider you choose:

• scope decides who shares the slot's memory. byPrincipal scopes memory per authenticated caller, and a resolver can return a tenant and caller tuple for multi-tenant applications. Returning null disables the slot.
• namespace separates the application's memory domains. The default combines the slot name, the graph node, and a deployment-aware identity, so Preview branches don't share memory with production.
• visibility controls whether recalled messages from an earlier scope stay visible after the scope changes within a session. The default "scope" hides them.
• description is prepended to every provider tool description to tell the model what belongs in the slot.

Whichever provider you choose, tell the model in agent/instructions.md that recalled memory contains user-provided facts rather than instructions, and list what it should never save, such as passwords, access tokens, or payment data.

Copy link to headingUse more than one memory provider

eve memory slots are independent, so an agent can use a different provider for each kind of memory. Create one file per slot under agent/memory/:

agent/
  memory/
    profile.ts
    knowledge.ts

For example, profile.ts can use fileMemory() for a short list of caller preferences while knowledge.ts uses Supermemory for semantic recall of past conversations. Each slot gets its own recalled context and its own qualified tools, such as profile__save_memory. Because the default namespace includes the slot name, the two slots stay separate even when they resolve to the same scope.

Declaring a single agent/memory.ts file creates one slot named memory, and that form can't be combined with an agent/memory/ directory.

Copy link to headingSwitch memory providers later

Switching providers means changing the provider field in a slot's definition, while the scope, namespace, and visibility settings stay the same. Existing memories stay in the previous provider's backend and don't transfer to the new one, so plan a data migration or run both providers in separate slots during the transition.

The eve add memory/<provider> commands name each slot after its provider, such as supermemory or upstash-agentkit, and the default namespace includes the slot name. Renaming the slot file changes the default namespace, which makes earlier memories unreachable. Set an explicit namespace string, when you want memory to stay reachable across slot renames or deployments.

Copy link to headingNext steps

• Read the eve memory overview for slots, scope, namespace, and visibility.
• Configure the built-in provider with the File memory reference.
• Scope any provider by tenant and caller with the Multi-tenant memory pattern.
• Read the persistent memory for eve agents Edgenivo changelog.