[Blog](https://supermemory.ai/blog) · [Learning](https://supermemory.ai/blog/tag/learning)

# How to Use Supermemory with AI SDK

Add persistent user context to an AI SDK application, then test continuity, isolation, corrections, and retrieval failures.

By Shardul Mane May 11, 2026 · 5 min read 

![How to Use Supermemory with AI SDK](https://supermemory.ai/_astro/cover.EmAf2Lf9_ZU7wOH.webp)

Add persistent memory to an AI SDK application by using a stable memory scope across conversations, a separate identifier for each conversation, and an explicit policy for what gets saved. Supermemory's middleware can retrieve user context before generation and save conversation text afterward. Your application still owns authentication, chat-history storage, and the decisions that require authoritative business data.

This guide uses the middleware path. Start there when every request should receive relevant memory; use individual memory tools when the agent needs to choose specific memory operations.

## What persists between AI SDK conversations?

Your application stores the chat messages needed to reopen a conversation. Supermemory stores and retrieves selected context that can be useful in other conversations. Keep a stable, authorized `containerTag` for the user or workspace and a distinct `customId` for each conversation. Reusing the conversation ID as the user scope prevents the intended continuity when a new chat starts.

This example adds memory to an application built with AI SDK. It does not configure memory in the consumer ChatGPT or Claude apps. Start with the [user-preference example](https://supermemory.ai/blog/how-to-make-ai-remember-user-preferences-across-conversations/) for the behavior to test and the [isolation guide](https://supermemory.ai/blog/multi-tenant-memory-noisy-neighbor-isolation/) for shared applications.

## Install the integration package

```
npm install ai@6.0.285 @ai-sdk/openai@3.0.113 @supermemory/tools@2.3.0
```

Keep model-provider and Supermemory credentials on the server. Configure `OPENAI_API_KEY` and `SUPERMEMORY_API_KEY` in your runtime's secret settings. Installing the `supermemory` client alone does not install the `@supermemory/tools/ai-sdk` integration imported below.

The [official integration documentation](https://supermemory.ai/docs/integrations/ai-sdk) describes the middleware and tools separately. Use the compatible package versions in the install command for this example. The current AI SDK 7 model interface is not accepted by this integration version; do not upgrade that combination without checking compatibility.

## Wrap the model for one authorized conversation

The following helper belongs in server-side code. `memoryScope` and `conversationId` must come from application logic that has already authenticated the request and checked access to the conversation.

```
import { generateText, type ModelMessage } from "ai";
import { openai } from "@ai-sdk/openai";
import { withSupermemory } from "@supermemory/tools/ai-sdk";

export async function answerWithMemory(input: {
  memoryScope: string;
  conversationId: string;
  messages: ModelMessage[];
}) {
  const apiKey = process.env.SUPERMEMORY_API_KEY;
  if (!apiKey) throw new Error("SUPERMEMORY_API_KEY is required");

  const model = withSupermemory(openai("gpt-5"), {
    apiKey,
    containerTag: input.memoryScope,
    customId: input.conversationId,
    mode: "full",
    addMemory: "always",
    skipMemoryOnError: false,
  });

  const result = await generateText({
    model,
    messages: input.messages,
  });

  return result.text;
}
```

The caller must supply a scope it is authorized to use. A privileged API key combined with a client-chosen scope is not a safe multi-user design.

Keep the same scope when a user starts a new conversation that should share memory. Change the conversation identifier so unrelated chats do not become one document. Check that your identifier scheme remains unambiguous across tenants.

## Choose saving and failure behavior deliberately

The example enables conversation saving and combines profile context with query-based retrieval. If your workflow should retrieve without saving new conversation text, use `addMemory: "never"` and implement an explicit write path for approved content.

It also sets `skipMemoryOnError: false`. That makes a memory error fail the operation instead of silently continuing without context. An application may prefer a fallback, but that should be a product decision. A support agent should not pretend to remember an earlier ticket when retrieval failed.

Distinguish temporary retrieval failure from missing evidence. The first may justify a retry or a degraded response; the second may require a clarifying question.

## Keep chat persistence and memory separate

Persist the messages needed to display or resume a conversation in your application. Retrieved memory supplies selected context from other interactions; it is not necessarily a complete transcript or an exact replay of every tool call.

Similarly, check current permissions, account state, and transactional data against their authoritative systems. A remembered subscription tier should not grant an entitlement.

The [AI SDK memory guide](https://ai-sdk.dev/docs/agents/memory) describes memory patterns alongside the agent loop. Keep the application's existing history store when adding the memory layer.

## Test across two sessions

Use synthetic data before a customer pilot:

1. In conversation A, save a harmless preference such as “use concise bullet points.”
2. Wait for the documented processing state rather than assuming immediate availability.
3. Start conversation B with the same memory scope and a new conversation ID.
4. Verify the preference is retrieved and used when relevant.
5. Repeat with another user's scope and verify the preference is absent.
6. Correct the preference and check both current behavior and any historical question your product supports.

Add a retrieval-outage case and a deletion case. Inspect the context sent to the model, not only the final answer.

## Measure the cost of adding memory

Record retrieval latency, time to first output, total response time, and context tokens separately. A published retrieval figure does not guarantee that a stream has no additional delay.

Compare a baseline that sends your existing conversation context with the memory-enhanced version. Keep the questions and model configuration the same. If context becomes smaller, check that difficult questions still retain the evidence they need.

Use [the debugging guide](https://supermemory.ai/blog/debugging-agent-memory-retrieval-postmortem/) when a test fails. The target is reliable continuity for the same authorized user, with visible failure behavior and a cost you can measure.

## Add memory to an existing TypeScript app incrementally

Keep your current chat-history store and introduce memory at one server-side generation boundary. Derive the memory scope from authenticated tenant and user identity, while retaining the application's existing conversation ID. A request body must not choose which other user's memories to retrieve.

This standalone helper makes the scope encoding unambiguous. It does not authenticate a request; call it only with trusted identifiers that have already passed your access checks.

```
export function memoryScope(tenantId: string, userId: string): string {
  if (!tenantId.trim() || !userId.trim()) {
    throw new Error("Tenant and user identifiers are required");
  }
  return ["tenant", encodeURIComponent(tenantId),
    "user", encodeURIComponent(userId)].join(":");
}
```

Encoding each identifier avoids delimiter collisions, such as a tenant ID containing a colon. A workspace-wide feature needs a separately authorized workspace scope; do not silently reuse a personal scope for shared knowledge.

Start with one route and a synthetic user. Compare the assembled context and answer with the existing path, then enable the feature for a controlled cohort. Avoid saving each interaction through both middleware and a separate write hook unless you have verified their deduplication behavior. Decide how to handle timeouts and roll back the read path without losing the original conversation records.

Plan the rollout around authentication, streaming, retries, background ingestion and deletion. Use the middleware above at the generation boundary and test each surrounding application path. For the broader implementation choice, compare [three ways to add long-term memory](https://supermemory.ai/blog/3-ways-to-build-llms-with-long-term-memory/).

For other agent frameworks, follow the [OpenAI Agents SDK](https://supermemory.ai/blog/supermemory-with-openai-agents-sdk/) or [Mastra](https://supermemory.ai/blog/supermemory-with-mastra/) integration guide.

Ready to add this to your app? [Get your API key in the Supermemory console](https://console.supermemory.ai/) and connect the middleware to one server-side route. Use a fictional user to run the two-session, correction, and deletion checks before expanding the rollout.

## Other posts.

1. [We're open sourcing the company brain. Here's how we designed the multiplayer harness Company Brain is now open source. A walkthrough of the multiplayer harness behind its Slack experience, from proactivity and memory boundaries to approvals and recovery. NewsSep 25, 2026 ](https://supermemory.ai/blog/open-sourcing-company-brain)
2. [Jev changes a lot in memory & context engineering. Here's exactly how. We tested Jev across reranking, chunking, observation, and harness decisions. Here is where fast decision models help memory systems, where they cost more, and where they still fall short. EngineeringSep 24, 2026 ](https://supermemory.ai/blog/jev-memory-context-engineering)
3. [I reverse-engineered Instinct's memory. Here's exactly how it works Instinct keeps its memory as git-tracked markdown files, found with grep rather than vectors. Here is the whole system as far as black-box probing can reconstruct it, and how to rebuild it on supermemory in about 60 lines. EngineeringSep 20, 2026 ](https://supermemory.ai/blog/reverse-engineering-instinct-memory)
4. [An update to supermemory We've discontinued the supermemory company brain and Nova. Everyone who was charged has been refunded, our MCP and plugins continue to run, and we're going all in on the memory engine. NewsSep 10, 2026 ](https://supermemory.ai/blog/an-update-to-supermemory)
5. [Scaling Conversations: How Adapta Grew Usage Without Losing Context Adapta added Supermemory as a persistent memory layer so every conversation keeps its context — letting the team scale usage without losing the thread. Case StudyJun 12, 2026 ](https://supermemory.ai/blog/adapta-scaling-conversations)
6. [How Chatarmin Ditched RAG and Went Memory-Only with Supermemory Chatarmin replaced a heavy RAG pipeline with Supermemory's memory layer — cutting average AI response time from 40s to 12s and token usage by 40–50%. Case StudyJun 10, 2026 ](https://supermemory.ai/blog/chatarmin-memory-only)
7. [SMFS: making agentic retrieval 55% cheaper AND more accurate We launched SMFS.ai (Supermemory Filesystem) a few weeks ago, with a simple bet: We can redesign the filesystem specifically for agents, with special files, structures, and commands that it can use for it's tasks. Today, SMFS is used by hundreds of companies to power their agents. EngineeringMay 28, 2026 ](https://supermemory.ai/blog/smfs-making-agentic-retrieval-55-cheaper-and-more-accurate)
8. [Introducing Dynamic Dreaming: supermemory now connects the dots, for you. Dreaming is magical. TLDR: We're launching Dynamic Dreaming in supermemory today, which automatically works if you're using supermemory in any way - API, OpenClaw, Hermes agent, etc. EngineeringMay 25, 2026 ](https://supermemory.ai/blog/introducing-dynamic-dreaming-supermemory-now-connects-the-dots-for-you)
9. [Dear reader, we just made supermemory insanely cheap... the Context Cloud When I first started building supermemory, I had one goal: To build the best memory system for AI. I would talk to customers, and find out that memory was not the only thing they needed - They were all setting up 7-8 different vendors at the same time. EngineeringMay 18, 2026 ](https://supermemory.ai/blog/dear-reader-we-just-made-supermemory-insanely-cheap-the-context-cloud)
10. [Introducing @supermemory/tools v2.0.0 Today we're releasing v2.0.0\. This release unifies the API across all agents sdk integrations from AI SDK to Mastra, makes conversation identity a first-class concept, and ships with memory saving on by default. EngineeringApr 27, 2026 ](https://supermemory.ai/blog/introducing-supermemory-tools-v2-0-0)
11. [Solving the Precision-Recall Tradeoff: Search Result Aggregation When you're building memory for AI, search is your foundational layer. The way search generally works is straightforward: the user defines a query, and then sets a limit (top-K) on how many search results they want returned. Usually, this is set to 10 or 20. EngineeringApr 5, 2026 ](https://supermemory.ai/blog/solving-the-precision-recall-tradeoff-search-result-aggregation)
12. [OpenClaw Memory Problems: Why It Forgets and How to Fix It (2026) TLDR: Today, we are releasing a new version of our openclaw plugin - https://github.com/supermemoryai/openclaw-supermemory. This post is going to be a bit technical, so bear with me (or bookmark for later!) In this post, I will talk about what we do about OpenClaw memory, and how we fix it. EngineeringFeb 19, 2026 ](https://supermemory.ai/blog/why-everyone-is-complaining-about-openclaws-memory-it-sucks-and-why-supermemory-fixes-it)
13. [Stateful Coding Agents with Memory: Build Long-Running Agents (2026) We built a plugin for Claude Code and OpenCode that gives your coding agent persistent memory. It remembers your preferences, learns your codebase, and never loses context mid-conversation. The result is an agent you can run for months without starting over. EngineeringFeb 18, 2026 ](https://supermemory.ai/blog/infinitely-running-stateful-coding-agents)
14. [Clawd / Molt bot's memory SUCKS. We gave it supermemory. I'm the founder of supermemory. Clawd/Molt bot is blowing up right now, with many, many use cases. I set it up, too, and have been using it through telegram. TLDR: just go to https://supermemory.ai/docs/integrations/clawdbot to set up supermemory for your clawd bot. EngineeringJan 28, 2026 ](https://supermemory.ai/blog/clawd-molt-bots-memory-sucks-we-gave-it-supermemory)
15. [Catch up with our UNFORGETTABLE Launch Week Over the last year, one belief has guided almost everything we’ve built at Supermemory AI becomes meaningfully useful only when it remembers. Memory shouldn’t be something developers rebuild from scratch. It shouldn’t be fragile, expensive, or trapped inside a single tool. NewsJan 4, 2026 ](https://supermemory.ai/blog/catch-up-with-our-unforgettable-launch-week)
16. [Empowering the Next Generation of Founders: Supermemory Startup Program If there’s one thing we’ve learned while building Supermemory, it’s that most startups don’t fail because they didn't build features; they fail when infrastructure slows them down, or they built too slow. NewsDec 31, 2025 ](https://supermemory.ai/blog/empowering-the-next-generation-of-founders-supermemory-startup-program)
17. [Building code-chunk: AST Aware Code Chunking At Supermemory, we're building context engineering infrastructure for AI. A huge part of that is dealing with code: ingesting repos, understanding structure, and making it searchable. The problem is that most code chunking solutions are terrible. We built code-chunk to fix this. EngineeringDec 29, 2025 ](https://supermemory.ai/blog/building-code-chunk-ast-aware-code-chunking)
18. [Supermemory raises $3 million with the best memory engine for LLMs Today, I am excited to announce our first funding round to accelerate our mission of building an interoperable, scalable and reliable memory for LLMs and agents. Memory is one of the hardest challenges in AI right now. NewsOct 6, 2025 ](https://supermemory.ai/blog/supermemory-raises-3-million-and-building-the-best-memory-engine-for-llms)
19. [Mem0 vs Supermemory: Why Scira Switched Scira AI moved its production memory layer from Mem0 to Supermemory. This is what failed, what improved, and how the team evaluated the two systems. Case StudyOct 2, 2025 ](https://supermemory.ai/blog/why-scira-ai-switched)
20. [Never Record Again: How Montra Uses Supermemory to Rethink Video Creation Campbell Baron, the founder of Montra, has been making videos since he was twelve. By thirteen, he was already doing brand work. Today, he’s betting on a very different future for creators: a world where recording is the exception, and most videos are generated from scratch. Case StudyAug 21, 2025 ](https://supermemory.ai/blog/never-record-again-how-montra-uses-supermemory-to-rethink-video-creation)
21. [Unified Memory That Works Where You Work: Your Second Brain With Supermemory Hi everyone, I’m Dhravya, the founder of Supermemory. I want to start with a little story behind why this product means so much to me. You can also skip straight to what it is and how it works below. EngineeringJul 25, 2025 ](https://supermemory.ai/blog/unified-memory-that-works-where-you-work-your-second-brain-with-supermemory)
22. [Supermemory just got faster on PlanetScale What is Supermemory? Supermemory completes the missing part of the LLM puzzle: memory. Just as memory is crucial for human intelligence, it's essential for truly intelligent AI systems. EngineeringJul 18, 2025 ](https://supermemory.ai/blog/supermemory-just-got-faster-on-planetscale)
23. [Faster, smarter, reliable infinite chat: Supermemory IS context engineering. People are obsessed with prompts and prompt engineering. Sure, what you say is important, but what the model knows when you say it is the difference between a stateless text generator and an intelligent AI system. In short, context is the most crucial component. NewsJul 9, 2025 ](https://supermemory.ai/blog/faster-smarter-reliable-infinite-chat-supermemory-is-context-engineering)
24. [We solved AI API interoperability One API to rule them all, One spec to find them, One library to bring them all and in the TypeScript, bind them. When we were building the Infinite Chat API, initially, we only supported the OpenAI format. This was fine, until a lot of our customers started asking for more. EngineeringJul 7, 2025 ](https://supermemory.ai/blog/we-solved-ai-api-interoperability)
25. [The Wow Factor of Memory - How Flow Used Supermemory To Build Smarter, Stickier Products Overview: Flow is a note-taking app built around a bold vision: to create a more personal, context-aware writing experience powered by AI. At the heart of this mission is memory. Case StudyJun 14, 2025 ](https://supermemory.ai/blog/the-wow-factor-of-memory-how-flow-used-supermemory-to-build-smarter-stickier-products)
26. [The UX and technicalities of awesome MCPs Last month, we launched the Supermemory MCP, mostly to test our own infrastructure and get some initial traction. It blew up. To my absolute surprise, the initial launch itself got half a million impressions (!!!). Then, we launched and got #2 on ProductHunt too. EngineeringJun 8, 2025 ](https://supermemory.ai/blog/the-ux-and-technicalities-of-awesome-mcps)
27. [Architecting a memory engine inspired by the human brain Language is at the heart of intelligence, but what truly powers meaningful interaction is memory — the ability to accumulate, recall, and contextualize information over time. Large Language Models (LLMs) have mastered language, but memory remains their Achilles’ heel. EngineeringJun 5, 2025 ](https://supermemory.ai/blog/memory-engine)

## Start building with supermemory.

Memory and continual learning for any model, any harness. Available through our API, plugins, and MCP.

[Build with supermemory ](https://console.supermemory.ai/)