Installation

npm install @supermemory/tools

Quick Comparison

User Profiles with Middleware

Automatically inject user profiles into every LLM call for instant personalization.

import { generateText } from "ai"
import { withSupermemory } from "@supermemory/tools/ai-sdk"
import { openai } from "@ai-sdk/openai"

const modelWithMemory = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conversation-456",
})

const result = await generateText({
  model: modelWithMemory,
  messages: [{ role: "user", content: "What do you know about me?" }]
})

Required fields

Both containerTag and customId are required.

• containerTag — who the memories belong to. Use a stable identifier per user, workspace, or tenant (e.g. "user-123", "acme-workspace"). Memory search and writes are scoped to this tag.
• customId — which conversation this turn belongs to. Use it to group messages from the same chat session into a single document (e.g. "chat-2026-04-25", a thread ID, or a UUID per session).

Memory saving is enabled by default (addMemory: "always"). New conversations are persisted automatically. To opt out, set `addMemory: "never":

const modelWithMemory = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conversation-456",
  addMemory: "never",
})

Memory Search Modes

Profile Mode (Default) - Retrieves the user’s complete profile:

const model = withSupermemory(openai("gpt-4"), { containerTag: "user-123", customId: "conv-1", mode: "profile" })

Query Mode - Searches memories based on the user’s message:

const model = withSupermemory(openai("gpt-4"), { containerTag: "user-123", customId: "conv-1", mode: "query" })

Full Mode - Combines profile AND query-based search:

const model = withSupermemory(openai("gpt-4"), { containerTag: "user-123", customId: "conv-1", mode: "full" })

Custom Prompt Templates

Customize how memories are formatted. The template receives userMemories, generalSearchMemories, and searchResults (raw array for filtering by metadata):

import { withSupermemory, type MemoryPromptData } from "@supermemory/tools/ai-sdk"

const claudePrompt = (data: MemoryPromptData) => `
<context>
  <user_profile>
    ${data.userMemories}
  </user_profile>
  <relevant_memories>
    ${data.generalSearchMemories}
  </relevant_memories>
</context>
`.trim()

const model = withSupermemory(anthropic("claude-3-sonnet"), {
  containerTag: "user-123",
  customId: "conv-1",
  mode: "full",
  promptTemplate: claudePrompt,
})

Verbose Logging

const model = withSupermemory(openai("gpt-4"), {
  containerTag: "user-123",
  customId: "conv-1",
  verbose: true,
})
// Console output shows memory retrieval details

When Supermemory errors (default: continue without memories)

If the Supermemory API returns an error, is unreachable, or retrieval hits the internal time limit, memory injection is skipped. skipMemoryOnError defaults to true, so the LLM call still runs with the original prompt (no injected memories). Use verbose: true if you want console output when that happens. To fail the call when memory retrieval fails instead, set skipMemoryOnError: false:

const model = withSupermemory(openai("gpt-5"), {
  containerTag: "user-123",
  customId: "conv-1",
  skipMemoryOnError: false,
})

Memory Tools

Add memory capabilities to AI agents with search, add, and fetch operations.

import { streamText } from "ai"
import { createAnthropic } from "@ai-sdk/anthropic"
import { supermemoryTools } from "@supermemory/tools/ai-sdk"

const anthropic = createAnthropic({ apiKey: "YOUR_ANTHROPIC_KEY" })

const result = await streamText({
  model: anthropic("claude-3-sonnet"),
  prompt: "Remember that my name is Alice",
  tools: supermemoryTools("YOUR_SUPERMEMORY_KEY")
})

Available Tools

Search Memories - Semantic search through user memories:

const result = await streamText({
  model: openai("gpt-5"),
  prompt: "What are my dietary preferences?",
  tools: supermemoryTools("API_KEY")
})
// AI will call: searchMemories({ informationToGet: "dietary preferences" })

Add Memory - Store new information:

const result = await streamText({
  model: anthropic("claude-3-sonnet"),
  prompt: "Remember that I'm allergic to peanuts",
  tools: supermemoryTools("API_KEY")
})
// AI will call: addMemory({ memory: "User is allergic to peanuts" })

Using Individual Tools

For more control, import tools separately:

import {
  searchMemoriesTool,
  addMemoryTool
} from "@supermemory/tools/ai-sdk"

const result = await streamText({
  model: openai("gpt-5"),
  prompt: "What do you know about me?",
  tools: {
    searchMemories: searchMemoriesTool("API_KEY", { projectId: "personal" }),
    createEvent: yourCustomTool,
  }
})

Tool Results

// searchMemories result
{ success: true, results: [...], count: 5 }

// addMemory result
{ success: true, memory: { id: "mem_123", ... } }