How to Add Memory to a Vercel Eve Agent with Redis
In a session, an Eve agent remembers everything that happened. But if the user opens a session tomorrow again, the agent has empty context. If the user said "I'm vegetarian", the agent doesn't remember this.
To address this, we want to provide the agent with chat history of past conversations and long-term facts about the user.
Using Upstash AgentKit Eve extension, we can use Upstash Redis as the storage mechanism for both of those and connect it to an Eve agent with a single file. (See also other memory providers listed by Eve which offer different tradeoffs.)
What memory does an Eve agent need?
Eve agents need conversational history as well as long-term memory about the user. While long-term memory is short facts about the user that the Eve agent loads into every new conversation, chat history is what was said in those conversations. These types of data need to persist across sessions, so we store them in Redis and not in Eve's session store.
The two kinds behave differently:
| Chat history | Long-term memory | |
|---|---|---|
| Scope | One Eve session | One user, across all sessions |
| What gets stored | Every user and assistant message, in order | Short facts ("The user is vegetarian.") |
| Who writes it | An extension hook, as each message streams | The model, through a tool call |
| How it's read | The model searches past chats with a tool, and your app lists them for a sidebar | The model calls a recall tool at the start of a conversation |
Eve prunes its own workflow store at the end of runs, so the long-term record needs to live somewhere else. Redis is good for both roles because it's fast enough to read from every turn, and you can keep the transcripts and the memories (as well as the search index on top of them) in one database.
Set up the project
Start from a new Eve project and add the AgentKit extension. The @upstash/agentkit-sdk package is only for reading chats from your own app code later:
npx eve@latest init my-agent --non-interactive
cd my-agent
npm install @upstash/agentkit-eve-extension @upstash/agentkit-sdk @upstash/redisCreate a Redis database in the Upstash Console and set its REST URL and token in the agent's environment, next to your model key:
UPSTASH_REDIS_REST_URL="https://..."
UPSTASH_REDIS_REST_TOKEN="..."
ANTHROPIC_API_KEY="..."We call Anthropic directly with Eve's built-in model helper, so no AI Gateway setup is needed:
// agent/agent.ts
import { defineAgent } from "eve";
import { anthropic } from "eve/models/anthropic";
export default defineAgent({
model: anthropic("claude-haiku-5-5"),
});Store chat history
The extension is one file under agent/extensions/. Turning on chat history adds a hook that saves every user and assistant message to Redis as the session streams:
// agent/extensions/agentkit.ts
import agentkit from "@upstash/agentkit-eve-extension";
export default agentkit({ chatHistory: true });The filename provides the tool prefix so the model gets the following tools:
agentkit__save_memoryagentkit__recall_memoryagentkit__search_chat_historyagentkit__read_chat_history
The extension injects a short section into the system prompt instructing the model on when to use them.
The extension keys every memory and chat by the caller that Eve's channel auth verified. Under eve dev, the localDev() authenticator that eve init sets up accepts local requests as one stand-in local-dev caller, so there is nothing to configure while you build. In production, the caller comes from the auth you put in agent/channels/eve.ts: vercelOidc() on Vercel, or a small function that maps your app's signed-in user to an Eve caller. The Eve auth guide covers both. The caller ID is the only thing separating one user's data from another's, and it always comes from verified auth, never from what the client sends.
Each session is one JSON document at agentkit:chat:<userId>:<sessionId>. Your app reads the same store with ChatHistory, for example to build a sidebar of past chats:
import { Redis } from "@upstash/redis";
import { ChatHistory } from "@upstash/agentkit-sdk";
type StoredMessage = { role: "user" | "assistant"; content: string; createdAt: number };
const history = new ChatHistory<StoredMessage>({ redis: Redis.fromEnv() });
const userId = "local-dev"; // the caller id the agent saw; in production, your signed-in user id
const chats = await history.listChats({ userId, limit: 50 });
for (const c of chats) console.log(c.sessionId, c.messageCount, JSON.stringify(c.title));
const chat = await history.getChat({ userId, sessionId: chats[0].sessionId });
chat?.messages.forEach((m) => console.log(`${m.role}: ${m.content.slice(0, 80)}`));After the two conversations in the next section, it printed:
wrun_01M75P1XDF7E5EMZPEM8JZRW90 2 "Suggest a dinner place for me tonight."
wrun_01M75NZ2AS4RZW9KRZCNRCP8B3 2 "I'm vegetarian and I live in Lisbon."
user: Suggest a dinner place for me tonight.
assistant: Since you're vegetarian and in Lisbon, try a vegetarian-focused spot in PríncipeNote these do not help with session resumption (which Eve does with its own session ID) but the extension uses the title of the chat from the first user message. These tools are used for getting existing chats.
Give the agent long-term memory
The memory tools need no extra config. agentkit__save_memory stores one fact about the user, and agentkit__recall_memory gets the facts back. We add one line to the agent's instructions so it loads what it knows at the start of each conversation:
<!-- agent/instructions.md -->
You are a helpful assistant. Keep answers short.
At the start of every conversation, call agentkit__recall_memory with no query to load what you know about the user.We started the agent with npx eve dev --no-ui and ran two separate sessions with Eve's client SDK. Both come from the same local-dev caller, so they share one user's memory. The first one shares two facts, and the second one, 90 seconds later, asks a question that needs them:
import { Client } from "eve/client";
// `eve dev` accepts local requests as the `local-dev` caller, so no token is needed here.
const client = new Client({ baseUrl: "http://127.0.0.1:2000" });
async function ask(label: string, message: string) {
const { delivery } = await client.sessions.create({ message });
const calls: string[] = [];
for await (const event of delivery.stream()) {
if (event.type === "call.requested") {
calls.push(`${event.data.capability.name}(${JSON.stringify(event.data.input)})`);
}
}
const { reply } = await delivery.result();
console.log(`[${label}] tools: ${calls.join(", ")}`);
console.log(`[${label}] answer: ${reply}\n`);
}
await ask("chat-1", "I'm vegetarian and I live in Lisbon.");
await new Promise((r) => setTimeout(r, 90_000)); // a new conversation, 90 seconds later
await ask("chat-2", "Suggest a dinner place for me tonight.");The output, trimmed:
[chat-1] tools: agentkit__recall_memory({}), agentkit__save_memory({"text":"The user is vegetarian."}), agentkit__save_memory({"text":"The user lives in Lisbon."})
[chat-1] answer: Thanks, I've noted that you're vegetarian and live in Lisbon. I'll keep that in mind for things like restaurant suggestions, recipes, and travel tips. What can I help you with?
[chat-2] tools: agentkit__recall_memory({})
[chat-2] answer: Since you're vegetarian and in Lisbon, try a vegetarian-focused spot in Príncipe Real or Chiado...Redis stores these memories as JSON documents at agentkit:memory:<userId>:<id>, here agentkit:memory:local-dev:<id>. You can see them in the Upstash Console Data Browser.
In the second session, we didn't say anything about the diet and the city. But the agent knew it from Redis.
How recall finds the right memories
agentkit__recall_memory uses Upstash Redis Search to find memories based on keyword matching, ranked by BM25 (a standard text relevance score). It doesn't use embeddings, which means it doesn't need to depend on an embedding model and can run fast, but also means that to find a memory, the query used needs to have some words in common with the memory.
Before adding the extra instruction line, we ran the demo with just the block of prompt that the extension adds. In the second session of that run, the model tried calling agentkit__recall_memory with the query "dinner food preferences location". Since that query has no words in common with "The user is vegetarian." or "The user lives in Lisbon.", the recall results were empty and the agent had to ask the user where they live.
If an agent stores facts about the user that number in the tens, the simplest way is to load all of them at the beginning of the conversation. If no query is provided, agentkit__recall_memory returns all memories for the user. That's what the instruction line is asking the agent to do. If the user has more memories than can fit in the prompt, then a search query helps.
Another quirk about Redis Search is that new documents are indexed in the background, and the recall tool uses the index to find documents even if no query is provided. If we save a memory and then poll the recall tool, how long before we see the new memory? We tried this seven times, and the recall tool started returning the new memory after 19 to 60 seconds (it was around 59 seconds for five of the seven trials). That's why we added the 90 seconds wait to the demo. This also affects listChats: immediately after the demo, the most recent chat is missing from the list; we checked again about 30 seconds later and it was there. This is fine across conversations, but might make things tricky if we save a fact during one turn and immediately use recall in the next turn.
Eve memory providers vs the AgentKit extension
Eve has some memory slots, stored in a file in agent/memory/. Eve calls it before and after each turn, with the data stored by a provider (the docs list its built-in file memory, Supermemory, Upstash AgentKit, and Kybernesis Arcana, a memory service with semantic search).
They differ from the extension in where data lives and how recall works:
| AgentKit extension | Eve file memory | AgentKit memory slot | |
|---|---|---|---|
| Ships as | @upstash/agentkit-eve-extension | Built into Eve | @upstash/agentkit-eve |
| Where data lives | Your Upstash Redis | Vercel Blob on Vercel, in-process memory under eve dev | Your Upstash Redis |
| How memories are recalled | The model calls a recall tool | The whole document is added before every turn | Search on the user's message before every turn |
| How memories are saved | The model calls a save tool | The model calls a save tool | User messages saved after each turn, plus a save tool |
| Chat history | Searchable transcripts per session | None | A tool replays a past session |
| Recall limit | topK memories per search | 4,000 characters by default, 64 KB per document | 5 memories and 4,000 characters by default |
When we ran the two-conversation demo against the AgentKit memory slot — redisMemory() — without any extra instructions, the agent fell back on asking the user for their city.
The AgentKit memory slot uses keywords from the user’s new message to recall from memory. In this case, “Suggest a dinner place for me tonight.” did not have enough keywords to retrieve the saved fact. The model then tried searching memory for "dinner food preferences location city", but that failed too, and the agent gave up and asked. AgentKit’s keyword approach works best when there’s some overlap between the user’s words and the stored facts.
AgentKit also includes a redisDocuments() backend for the file memory provider, which replays an entire short document to the model on each turn, so it never misses a fact because of wording. File memory uses a Vercel Blob store in deployment, and does not include chat history. Supermemory automatically records turns, recalls memories with semantic search before each turn, and uses its own service to store memory instead of the user’s database.
Which one to use
For most Eve agents, the extension covers both types of memory: the chat history is turned on with chatHistory: true and what the agent knows about the user can be loaded by calling agentkit__recall_memory without a query. A full example app that uses the extension can be found in the AgentKit repo, and the full range of options are described in the AgentKit Eve docs.
If you’re looking to add RAG with your own documents in an Eve agent, check out our guide on how we built Ask HackerNews with Eve.
The AgentKit extension is a good solution if you want to allow full control of the memory and chat history data in a way that’s easily viewable, manipulable, and deletable. No black boxes here, it’s just JSON documents stored at well-known keys. Use it if you’d like to use the same Redis database for rate limits, RAG, and more, as well as if you need the ability to list and search past conversations in your app with ChatHistory.
Use Eve’s file memory if you only need a small list of facts per user, and are already deploying on Vercel with Blob.
Use Supermemory if you want a more managed solution to determine what facts are relevant and use semantic search to recall them.