Upstash AgentKit builds AI agents on Upstash Redis: memory, conversation history, caching, and RAG, with no separate vector database. Memory recall is hybrid search in Upstash Redis Search: keyword and semantic results merged, with the text embedded by Redis itself. Memory and chat history share one search index, so they work on a database that allows only one (the Free plan).
Upgrading from an earlier AgentKit version? See Upgrading from full-text memory recall.
@upstash/agentkit-ai-sdk is the Vercel AI SDK adapter — drop-ins for
generateText / streamText. redis defaults to Redis.fromEnv(), so you import only from this
package.
| Import | Feature |
|---|---|
createChatHistory | Durable chat history on Redis Search — save, list, and $smart-search a user’s transcripts. |
createAgentMemory | An AI SDK memory provider: memory tools plus automatic recall into the instructions. |
createMemoryTools | recall_memory + save_memory tools so the model reads and writes long-term memory. |
createSearchTools | search / aggregate / count tools over a Redis Search index (this is how you do RAG). |
createRateLimit | A configured Upstash Ratelimit to call before the model. |
cachedTools | Memoize a map of AI SDK tools’ results in Redis. |
AgentKit reads UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN from the environment by default.
Pass your own @upstash/redis client as redis to any helper to override.
How to store chat history with the AI SDK#
A Redis-backed ChatHistory<UIMessage>, the durable source of truth for your conversations. userId
comes from your auth session; chatId is the useChat id that the client posts. Save the full
transcript from your route’s onFinish:
To load a chat, take chatId from the page route and userId from the session, then seed useChat:
Config and how it's stored
Each chat is one JSON doc at agentkit:chat:<userId>:<sessionId> (keyed per user, so two users
can’t collide on a sessionId). By default chats and memories share one index, agentkit. Chats are
indexed over userId + sessionId (filters) and userMessages +
modelMessages ($smart fuzzy text); the raw messages array rides along unindexed. saveChat
overwrites the whole array (no delta merge) — useChat sends the full conversation. Other
methods: getChat / deleteChat ({ userId, sessionId }), listChats / searchChats
({ userId }).
Security — userId is the tenant boundary
Every method takes a single object; userId is required, non-empty, and may not contain :.
Derive it from a verified server-side auth source — the subject/user id from your auth provider
(Clerk, Auth.js/NextAuth, Supabase Auth, Auth0, …) — and never from a client-supplied header,
query param, or body (read it from the session in your route). A chat can’t be read or
overwritten under a different userId.
How to add agent memory with the AI SDK#
createAgentMemory() is an AI SDK memory provider.
Create it once. Then, per request, give the model the recall_memory and save_memory tools, have the
memories relevant to the latest user message added to the instructions automatically, or both:
The model is not wrapped: recall runs in prepareStep and adds a <memories> block to the instructions on
the first step. It works the same with generateText and streamText. A failed recall never fails the call.
Recall is hybrid: it finds memories by keyword and by meaning, so “What should I cook?” finds “The user is
vegetarian.” Saving stays explicit.
createAgentMemory options
createAgentMemory({ redis?, prefix?, indexName?, topK?, minScore?, recallToolName?, saveToolName?, enableTelemetry? })memory.tools({ userId }): the same tools ascreateMemoryTools.memory.prepareStep({ userId, query?, onError? }):userIdcan be a function of the step options, such as({ runtimeContext }) => runtimeContext.userIdon a shared agent.querydefaults to the text of the last user message. A failed recall goes toonError(defaultconsole.warn).memory.instructions: guidance on when to use the tools, with your tool names.memory.store: the underlyingAgentMemory, foradd/list/get/forget.
To use the tools alone, createMemoryTools gives you recall_memory and save_memory:
Options and the userId tenant boundary
userId(required) — a string, or(input, options) => string.redis— defaults toRedis.fromEnv().topK— max memoriesrecallreturns.minScore— a BM25 floor. Set it to recall by keyword only, above that floor; leave it unset for hybrid recall.recallToolName/saveToolName— override the tool names.
userId is the only tenant boundary (required, non-empty, no :). Derive it from a verified
server-side auth source (Clerk, Auth.js/NextAuth, Supabase Auth, Auth0, …) — never a
client-supplied value. Memories are stored at agentkit:memory:<userId>:<id>.
How to add RAG with the AI SDK#
search / aggregate / count tools over an Upstash Redis Search index; the model-facing
descriptions are generated from your schema.
Options
schema(required) — built withsfrom@upstash/redis.redis— defaults toRedis.fromEnv().indexName— defaults to"agentkit:search".prefix— key prefix for indexed JSON docs (defaults to"<indexName>:").defaultLimit— default page size forsearch(10).
The index is created (and waitIndexing-ed) reactively on first use — no setup step.
How to add rate limiting with the AI SDK#
A configured Upstash Ratelimit. Call .limit(identifier) before
the model and short-circuit when over the limit.
Options
limiter(required) — e.g.Ratelimit.slidingWindow(20, "1 m")orfixedWindow(...).redis— defaults toRedis.fromEnv().prefix— base key prefix; keys are<prefix>:<identifier>(defaultagentkit:rateLimit).
There’s no model wrapper. Pass a per-user identifier to .limit() to throttle per user.
How to cache tools with the AI SDK#
Memoize a map of AI SDK tools’ results in Redis. Each tool is cached under its map key, scoped to
userId.
Options
Pass tools built with the AI SDK’s tool() (so each keeps full input/output inference). Second arg:
userId(required) — a string, or(input, options) => string; scopes every entry to this user.redis— defaults toRedis.fromEnv().ttlSeconds— default per-result TTL for every tool.
Cache keys are agentkit:toolCache:<userId>:<toolName>:<hash-of-input> — the toolName is the map
key, so you never pass a name yourself.
How to put it all together with the AI SDK#
A single streamText route can wire every feature: rate limit first, then memory, search, and cached
tools, persisting the whole conversation in onFinish:
A complete, runnable Next.js demo (useChat UI, chat sidebar with fuzzy search, inline tool calls)
lives in examples/ai-sdk-demo.
Upgrading from full-text memory recall#
@upstash/agentkit-ai-sdk 0.15 and earlier indexed memory text as a full-text field, and gave memory
and chat history separate indexes, agentkit_memory and agentkit_chat. Newer versions index text as
a hybrid field and, with default settings, keep memory and chat history in one index, agentkit. Keys
and documents are unchanged, so there is no data to migrate: only the search indexes change.
| Your setup | On upgrade | What to do |
|---|---|---|
| Default settings | A new agentkit index is created, and finds the memories and chats saved earlier. | Nothing. Drop agentkit_memory and agentkit_chat when convenient; they are no longer used. |
| Default settings on the Free plan (one index) | The first read fails with the database has no index slots left. | Run SEARCH.DROP agentkit_memory and SEARCH.DROP agentkit_chat. |
Memory with a custom prefix or indexName | The first read fails with exists with a different definition. | Run SEARCH.DROP <index> with the index the error names. |
Chat history with a custom prefix or indexName | Nothing: its index is the same as before. | Nothing. |
createSearchTools | Nothing. | Nothing. |
Dropping an index keeps its documents. The next read creates the new index, which indexes and embeds the existing memories again; on a large store, recall can miss some of them until that finishes. A client that hit the error retries on its next read, so nothing needs a restart.
Drop old indexes once every deployment runs the new version: an instance still on the old version recreates its index on its next read, which on the Free plan takes the only slot again. Until they are dropped, unused old indexes keep indexing new writes.
Run SEARCH.DROP from the CLI in the Upstash Console, from redis-cli, or from code:
minScore changed meaning. It was a BM25 floor on keyword recall; now setting it switches recall to
keyword only, above that floor. Hybrid scores have no relevance cutoff, so remove minScore to get
hybrid recall.