Guide · Open source

How to use Supermemory: API, MCP server and self-hosting

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Supermemory is an open-source memory and context engine that gives AI assistants and apps long-term memory, so they do not start from zero each conversation. This guide explains the three ways to use it: as an MCP server for AI tools like Cursor or Claude Code, through the client library in TypeScript or Python, or self-hosted. By the end you will know which path fits your setup and how to make the first call.

Supermemorysupermemoryai/supermemory · ★ 31.5k · MIT Install options & downloads

Quick start

1Pick your path. Decide between the MCP server for an AI tool, the client library for an app, or self-hosting.
2Add the MCP server. For a supported client, add the server URL https://mcp.supermemory.ai/mcp to its MCP configuration.
3Install the client. Run npm install supermemory or pip install supermemory, depending on your language.
4Store content. Call add with content and a containerTag such as user_123 to save information for that user.
5Read the profile. Call profile with the same containerTag and a query q to get static facts, dynamic context and search results.
6Check the self-host docs. If you need local data, follow the self-hosting overview at supermemory.ai/docs/self-hosting/overview.

Choose how you want to use Supermemory

Supermemory can be used through a hosted API, an MCP server for AI tools, or self-hosted, according to the README. Pick the path that matches your work.

If you use AI tools such as Cursor or Claude Code and want persistent context, the MCP server or a plugin is the simplest route. If you are building an agent or chat app with per-user memory, use the client library. If you need to keep data on your own machine, look at the self-hosting docs.

AI tool user: MCP server or a plugin for Claude Code, Cursor, Codex, OpenCode and others
Developer: the npm or pip client library with a single API
Self-hosting: run it on your own machine, with the setup described in the self-host docs

Connect Supermemory to an AI tool through MCP

Plugins and the MCP server give a compatible AI assistant persistent memory. The README lists supported clients including Claude Desktop, Cursor, Windsurf, VS Code, Claude Code, OpenCode, OpenClaw and Hermes. For clients that take a server URL, add the Supermemory MCP server to the client's configuration.

The MCP server exposes three tools. memory saves or forgets information. recall searches memories and returns your profile summary. context injects your full profile at the start of a conversation. In Cursor and Claude Code you can type /context.

Save or forget information with the memory tool; the AI calls it when you share something worth remembering
Search with recall, which returns relevant memories plus a profile summary
Inject your profile with context; in Cursor and Claude Code, type /context
Use projects (container tags) to separate work and personal memory, or split by client or repo

{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp"
    }
  }
}

Install the Supermemory client library

For developers, the client library is the entry point. The README gives two install commands: one for the npm package and one for the Python package. The README excerpt does not state the required Node.js or Python versions, so check the docs before you start.

Once installed, you create a client and call add to store content and profile to get a user profile plus relevant search results in one call. You do not need to configure a vector database, write embedding pipelines or choose chunking strategies, according to the README.

npm install supermemory # or: pip install supermemory

Store memories and read a user profile

The TypeScript example below stores a statement under a container tag, then asks for the profile and search results for that tag. The profile returns static facts (long-term) and dynamic context (recent activity). The Python client follows the same pattern with snake_case arguments such as container_tag.

Container tags, such as user_123 in the examples, keep each user's memory separate. Supermemory extracts the memories from what you send, so you pass content rather than pre-built records.

add stores content under a containerTag
profile returns profile.static, profile.dynamic and searchResults
Python uses container_tag and result.profile.static / result.profile.dynamic

import Supermemory from "supermemory";

const client = new Supermemory();

await client.add({
  content: "User loves TypeScript and prefers functional patterns",
  containerTag: "user_123",
});

const { profile, searchResults } = await client.profile({
  containerTag: "user_123",
  q: "What programming style does the user prefer?",
});

Use framework integrations

If you already use an AI framework, the README describes drop-in wrappers. Examples in the source are for the Vercel AI SDK and Mastra. The README also lists LangChain, LangGraph and the OpenAI Agents SDK as supported frameworks.

The wrappers accept options such as a containerTag and a customId for the Vercel AI SDK, or a mode option for Mastra. Check the framework's package documentation for the exact setup.

Vercel AI SDK: withSupermemory from @supermemory/tools/ai-sdk
Mastra: withSupermemory from @supermemory/tools/mastra
Also listed: LangChain, LangGraph, OpenAI Agents SDK

import { withSupermemory } from "@supermemory/tools/ai-sdk";
const model = withSupermemory(openai("gpt-4o"), { containerTag: "user_123", customId: "conv-1" });

Run Supermemory yourself

The README says Supermemory can be self-hosted and described as running fully locally. The README's quick-install section shows a single curl command that pipes an install script to bash, and mentions using Ollama to run fully offline. Before running any install script, read it and confirm it matches the project's self-hosting docs.

The self-host overview is at supermemory.ai/docs/self-hosting/overview. The hosted path, by contrast, depends on Supermemory's cloud.

Self-host docs: https://supermemory.ai/docs/self-hosting/overview
Read the install script before piping it to bash
Hosted users rely on Supermemory's cloud

curl -fsSL https://supermemory.ai/install | bash

What people use it for

Giving Claude Code or Cursor a memory of your preferences and past projects across sessions
Adding per-user memory to a chat app so each user's context is stored under their own container tag
Combining knowledge base documents and personal context in one search with hybrid search
Keeping a team's memory for different clients or repos by using separate projects

Frequently asked questions

Is Supermemory free and open source?

The README lists the licence as MIT and the language as TypeScript. The README excerpt does not describe pricing for the hosted service, so check the official docs for current plan details.

What do I need to install Supermemory?

For the client library, the README says you need Node.js or Python, depending on whether you use the npm or pip package. It does not state specific versions, so check the docs for those.

How do I connect Supermemory to Cursor or Claude Code?

Add the MCP server URL https://mcp.supermemory.ai/mcp to your client's MCP configuration. In Cursor and Claude Code, you can then type /context to load your profile.

Can I run Supermemory fully offline?

The README says it can be self-hosted and mentions running fully offline with Ollama. The hosted path depends on Supermemory's cloud, so self-hosting is the option for keeping data on your own machine.

How does Supermemory compare to Mem0, Letta, Zep or LangMem?

These are comparable projects in the same space. The README's benchmark figures come from the authors and were not independently verified here, so test with your own data before deciding.

Why does my AI not seem to remember anything?

The source does not list troubleshooting steps. Check that the MCP server URL is in your client config, that the client supports MCP, and that you are using the same container tag or project when you save and recall memories.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Supermemory suits developers building agents or chat apps with per-user memory, and people who use supported AI tools and want persistent context. It is probably more than you need if you only want chat history or a plain notes app. Teams that cannot use a third-party cloud should check the self-hosting path first, and treat the benchmark claims as the authors' figures rather than guarantees for your data.

Install options & downloads