--- title: How to choose an eve memory provider description: Compare File memory, Supermemory, Upstash AgentKit, and Kybernesis Arcana by recall, capture, and storage to choose an eve memory provider for your agent. url: "https://vercel.com/kb/guide/choose-an-eve-memory-provider" published: 2026-10-13 last_updated: 2026-10-13 authors: Ben Sabic install_vercel_plugin: npx plugins add vercel/vercel-plugin --- 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. ## Overview 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 ## What 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. | eve owns | The provider owns | | --------------------------------------------------- | ------------------------------------- | | Slot names, derived from the file path | Storage and indexing | | Namespace and scope resolution from trusted context | Retrieval, ranking, and formatting | | When recall and capture run, including compaction | What to extract and how to capture it | | Attribution and supersession of recalled messages | Retention and deletion | | Qualifying provider tools as `__` | Which model-facing tools to offer | 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. ## How eve memory providers compare eve memory providers differ mainly in how they recall context, whether they capture conversations automatically, and where they store data. | Provider | Package | Recall | Capture | Storage | | ----------------- | ----------------------- | ------------------------------------------------------ | --------------------------------------------------------- | --------------------------- | | File memory | Built into eve | One bounded document per scope | Model-driven `save_memory` and `remove_memory` tools | Private Vercel Blob store | | Supermemory | `@supermemory/eve` | Semantic search over stored memories | Automatic after each turn, plus tools | Supermemory hosted service | | Upstash AgentKit | `@upstash/agentkit-eve` | Ranked Redis Search recall or a Redis document backend | Automatic user-message capture, or model-driven tools | Your Upstash Redis database | | Kybernesis Arcana | `@kybernesis/arcana` | Semantic search and brain notes | Model-driven tools by default, optional automatic capture | Arcana hosted service | | Custom provider | Your code | Whatever your store returns | Whatever rules you implement | Any store you operate | ### File 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. ```bash eve add memory/file ``` The command writes `file.ts` and, when you choose **Install and set up**, creates or reuses a private Vercel 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. ```typescript 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, }); ``` ### Supermemory 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. ```bash eve add memory/supermemory ``` The command installs `@supermemory/eve` and writes `supermemory.ts`. The provider reads its API key from `SUPERMEMORY_API_KEY`. ```typescript 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, }); ``` ### Upstash 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. ```bash 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. ```typescript 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 Vercel Blob: ```typescript 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, }); ``` ### Kybernesis 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. ```bash 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. ```typescript 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, }); ``` ### Custom 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](https://vercel.com/kb/guide/build-a-custom-eve-memory-provider) walks through each handler, from recalling records before a turn to exposing scoped tools to the model. ## Questions that narrow the choice ### Should 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. ### Does 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. ### Where 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 Vercel 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. ### How 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: | Limit | Value | | ---------------- | ------------------------------------------------ | | Recalled message | `maxCharacters`, default 4,000 | | One entry | 2,048 UTF-8 bytes after whitespace normalization | | Stored document | 65,536 bytes | 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. ### Does 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. ### Do 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](https://vercel.com/kb/guide/build-a-custom-eve-memory-provider) when memory must live in a specific database, follow a retention policy you control, or use retrieval logic. ## Which eve memory provider to start with Match your agent's main requirement to a starting provider: | If your agent needs | Start with | | ----------------------------------------------------------- | ----------------- | | Short list of caller preferences, with no extra services | File memory | | Automatic capture and semantic recall from a hosted service | Supermemory | | Memory stored in a Redis database you already use | Upstash AgentKit | | Semantic search with model-driven saving by default | Kybernesis Arcana | | Memory in your own database, or retention rules you enforce | Custom provider | ## Settings 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. ## Use 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/`: ```plaintext 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. ## Switch 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/` 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. ## Next steps - Read the [eve memory overview](https://eve.dev/docs/memory) for slots, scope, namespace, and visibility. - Configure the built-in provider with the [File memory](https://eve.dev/docs/memory/file) reference. - Scope any provider by tenant and caller with the [Multi-tenant memory](https://eve.dev/docs/patterns/multi-tenant-memory) pattern. - Read the [persistent memory for eve agents](https://vercel.com/changelog/persistent-memory-for-eve-agents) Vercel changelog. ## More eve guides - [How to build a custom eve memory provider](/kb/guide/build-a-custom-eve-memory-provider): Implement the eve memory provider contract with defineMemoryProvider() to back an eve memory slot with your own database, vector index, or memory service. - [Build a software factory with eve](/kb/guide/eve-software-factory): Foreman, a software factory built on eve. It turns GitHub and Linear work items into reviewed draft pull requests through four agent stations, triaging issues and fixing its own red CI along the way. - [Manage Vercel projects with a software factory](/kb/guide/software-factory-vercel-mcp): Add Vercel's hosted MCP to the eve software factory template so Foreman can read build logs, runtime errors, and deployment history for the app your target repository deploys, brokered at app scope through Vercel Connect.