Skip to main content

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).

Note

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.

ImportFeature
createChatHistoryDurable chat history on Redis Search — save, list, and $smart-search a user’s transcripts.
createAgentMemoryAn AI SDK memory provider: memory tools plus automatic recall into the instructions.
createMemoryToolsrecall_memory + save_memory tools so the model reads and writes long-term memory.
createSearchToolssearch / aggregate / count tools over a Redis Search index (this is how you do RAG).
createRateLimitA configured Upstash Ratelimit to call before the model.
cachedToolsMemoize a map of AI SDK tools’ results in Redis.
Note

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 as createMemoryTools.
  • memory.prepareStep({ userId, query?, onError? }): userId can be a function of the step options, such as ({ runtimeContext }) => runtimeContext.userId on a shared agent. query defaults to the text of the last user message. A failed recall goes to onError (default console.warn).
  • memory.instructions: guidance on when to use the tools, with your tool names.
  • memory.store: the underlying AgentMemory, for add / 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 to Redis.fromEnv().
  • topK — max memories recall returns.
  • 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 with s from @upstash/redis.
  • redis — defaults to Redis.fromEnv().
  • indexName — defaults to "agentkit:search".
  • prefix — key prefix for indexed JSON docs (defaults to "<indexName>:").
  • defaultLimit — default page size for search (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") or fixedWindow(...).
  • redis — defaults to Redis.fromEnv().
  • prefix — base key prefix; keys are <prefix>:<identifier> (default agentkit: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 to Redis.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 setupOn upgradeWhat to do
Default settingsA 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 indexNameThe 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 indexNameNothing: its index is the same as before.Nothing.
createSearchToolsNothing.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.