supermemory/AGENTS.md

AGENTS.md

Context for AI coding agents (Claude Code, Cursor, Codex, OpenCode, Copilot and others) working with supermemory.

supermemory is a memory engine for AI agents: a memory graph that updates and forgets facts, user profiles, and retrieval over your documents, through one API. Documentation · Docs index for agents · Console and API keys

Two jobs, two sections:

• Adding supermemory to another project? Read Use supermemory in an app.
• Changing code in this repository? Read Work in this repository.

Use supermemory in an app

Start here

• Check the docs index or the docs MCP (below) before writing any endpoint.
• npx supermemory setup --prompt prints the integration prompt for the current project. Plain npx supermemory setup launches a separate coding agent, so use --prompt when you are already an agent.
• npx supermemory help --json lists every CLI command in a machine-readable form.
• The official skill teaches the current (v5) API surface:

npx skills add https://github.com/supermemoryai/skills --skill supermemory

Install and first calls

Set SUPERMEMORY_API_KEY (create a key in the console), then install SDK version 5 or later:

npm i supermemory           # TypeScript / JavaScript
pip install -U supermemory  # Python (3.10 or later)

Every memory call (add, search, profile, list, documents) takes a namespace first: one user, workspace or tenant.

import { Supermemory } from "supermemory";

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY });

await supermemory.add("user_123", {
  content: "User prefers TypeScript",
  dreaming: "instant", // processed right away (one extra operation per document); the default "dynamic" batches extraction
});

const { results } = await supermemory.search("user_123", { query: "language preference" });
const { profile } = await supermemory.profile("user_123");

import os
from supermemory import Supermemory

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

client.add("user_123", content="User prefers TypeScript", dreaming="instant")
response = client.search("user_123", query="language preference")
profile = client.profile("user_123").profile

API rules

• Auth: Authorization: Bearer $SUPERMEMORY_API_KEY is the only supported header.
• Write: POST https://api.supermemory.ai/ns/{namespace}/document
• Search: POST https://api.supermemory.ai/ns/{namespace}/search
• Profile: POST https://api.supermemory.ai/ns/{namespace}/profile
• Scoping: every write and every search names exactly one namespace, in the URL path. Never in the body or a header.
• Search modes: "chunks" for RAG, "memories" for extracted memories, "hybrid" (default) for both. The option is searchMode in the API and TypeScript, search_mode in Python.
• Readiness: processing is async. Wait until system.status is done before searching chunks, and until system.dreamingStatus is done before reading memories or the profile. These are the API and TypeScript field names.

Do NOT use

These are deprecated, undocumented or made up:

• Endpoints: /v1/..., /v3/documents, /v3/search, /v4/search, /v4/profile, /v4/memories
• Headers: x-supermemory-api-key, x-api-key, x-sm-user-id
• Body keys: containerTag, containerTags, customId (use id), entityContext (use supportingContext), filterByMetadata (use group), documentDate (use date), q (use query), filters (use filter), userId, spaces. One exception: scoped-key creation (POST /v3/auth/scoped-key) still takes containerTag or containerTags (API keys & auth).
• SDK calls: client.add({ containerTag }), client.search.execute, client.memories.add, client.memories.updateMemory, client.profile({ q })

Code on v3/v4 moves with npx supermemory@latest migrate --prompt, which prints the migration prompt for you to follow (migration guide).

Docs MCP

Searches these docs while you code. Server: https://supermemory.ai/docs/mcp

claude mcp add --transport http supermemory-docs https://supermemory.ai/docs/mcp   # Claude Code
codex mcp add supermemory-docs --url https://supermemory.ai/docs/mcp               # Codex

Cursor (~/.cursor/mcp.json) and most other clients:

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

This is not the memory MCP. The docs MCP only searches documentation.

Memory for the coding agent itself

One command installs the supermemory plugin for every coding agent it finds on this machine (Claude Code, Cursor, OpenCode and Codex), then signs in through the browser:

npx supermemory plugin --all

For one agent or a few, name them with --only (claude, cursor, opencode, codex):

npx supermemory plugin --only claude

• Plain npx supermemory plugin asks which agents to install for.
• --dry-run shows what would run without installing anything.
• --no-auth skips the browser sign-in; run npx supermemory plugin login later.

To install a single plugin by hand, or for an agent the CLI doesn't cover (Hermes, OpenClaw, any MCP client):

Agent	Install	Guide
Claude Code	/plugin marketplace add supermemoryai/claude-supermemory, then /plugin install supermemory	docs
Cursor	/add-plugin cursor-supermemory, or Supermemory in the Cursor Marketplace	docs
Codex	npx codex-supermemory@latest install, then restart Codex CLI	docs
OpenCode	bunx opencode-supermemory@latest install --no-tui	docs
Hermes	hermes plugins install supermemoryai/hermes-supermemory, hermes plugins enable supermemory, then hermes memory setup	repo
OpenClaw	openclaw plugins install @supermemory/openclaw-supermemory	docs
Any MCP client	Remote server https://mcp.supermemory.ai/mcp (OAuth sign-in, no API key)	docs

Each plugin handles its own sign-in (a browser login or an API key, not always SUPERMEMORY_API_KEY), so follow its guide.

Framework guides (Vercel AI SDK, OpenAI SDK, OpenAI Agents SDK, LangChain, LangGraph, Mastra, CrewAI, Agno, Microsoft Agent Framework, VoltAgent, Convex, Pipecat, LiveKit and more) are listed in the docs index.

Self-hosted

npx supermemory local runs a local server, at http://localhost:6767 by default. Point the SDK at it with baseUrl: "http://localhost:6767" (TypeScript) or base_url="http://localhost:6767" (Python). The v5 SDKs need supermemory-server v0.0.9 or later. Guide

Work in this repository

A Bun + Turbo monorepo. The supermemory SDKs on npm and PyPI are built in separate repositories, not here.

Requirements

• Bun 1.3.6 (the packageManager field). Use Bun only; the lockfile is bun.lock.
• Node 20 or later.
• Python 3.10 or later for the packages/*-python packages and 3.11 or later for apps/sdk-playground, plus uv for packages/openai-sdk-python and apps/sdk-playground.

Do NOT

• Use npm, yarn or pnpm in this repo.
• Bump versions in packages/tools/package.json, packages/memory-graph/package.json or packages/*-python/pyproject.toml unless asked. The publish-*.yml workflows publish when those change on main.
• Edit the workflows in .github/workflows/ unless asked.
• Migrate the Python packages to the v5 SDK unless asked. openai-sdk-python, pipecat-sdk-python and cartesia-sdk-python pin supermemory<5 (the 3.x SDK) on purpose, and livekit-sdk-python still makes uncapped 3.x SDK calls; all of them use container_tag. agent-framework-python 2.0 is already on v5 (supermemory>=5.0.0,<6) and passes its container_tag as the namespace.
• Commit .env files, API keys or credentials.

Repository map

Path	What it is
apps/web/	Redirects to the console (needs no env)
apps/mcp/	The MCP server (workspace supermemory-mcp; not the npm package of that name). Hosted at https://mcp.supermemory.ai/mcp
apps/docs/	Documentation site
apps/memory-graph-playground/	Demo app for the memory graph component
apps/sdk-playground/	Playground for the SDK integrations
packages/tools/	@supermemory/tools (3.x, v5 API): memory tools and middleware for the AI SDK, OpenAI, Mastra, VoltAgent and Claude's memory tool
packages/memory-graph/	@supermemory/memory-graph: interactive memory graph component
packages/openai-sdk-python/	supermemory-openai-sdk: memory tools for OpenAI function calling
packages/agent-framework-python/	supermemory-agent-framework: Microsoft Agent Framework integration
packages/pipecat-sdk-python/	supermemory-pipecat: Pipecat integration
packages/cartesia-sdk-python/	supermemory-cartesia: Cartesia Line integration
packages/livekit-sdk-python/	supermemory-livekit (not on PyPI yet): LiveKit Agents integration
packages/ui/	Shared UI components
packages/lib/	Shared utilities and logic
packages/hooks/	Shared React hooks
packages/validation/	Zod schemas and validation
packages/docs-test/	Runs the code samples from the docs
skills/	Older copy of the supermemory skill, still on the v3/v4 API. The current skill is supermemoryai/skills

CLAUDE.md in this repo predates the v5 API. Where it differs from this file, follow this file.

Setup and commands

bun install
bun run dev:local      # every app on localhost: web 3000, mcp 8788, docs 3003, graph playground 3004, sdk playground 3005
bun run check-types    # TypeScript across the monorepo
bunx turbo run build   # build everything

Use dev:local, not bun run dev: dev runs through portless, which binds port 443 and trusts a local CA. dev:local also needs Python and uv (the sdk playground runs uv run server.py) and network access (the docs run Mintlify). Use bunx turbo run build rather than bun run build: the root postbuild step uploads Sentry sourcemaps.

Checks that CI runs:

bun install --frozen-lockfile                                          # fails if bun.lock is out of date
bunx biome ci --changed --since=origin/main --no-errors-on-unmatched   # lint and format, changed files only
bun run --cwd packages/tools test:unit
bun run --cwd packages/tools build
bun run --cwd packages/tools test:compat
bun run --cwd apps/sdk-playground check-types:app
bun run --cwd apps/sdk-playground build:app
(cd apps/sdk-playground/python && uv sync --locked --python 3.12 \
  && .venv/bin/python -m py_compile server.py && .venv/bin/python -c "import server")
bun run --cwd packages/memory-graph check-types
bun run --cwd packages/memory-graph test

The tools steps run when packages/tools changes and the sdk-playground steps when apps/sdk-playground changes (the tools build runs for either); memory-graph and Biome run on every pull request.

bun run format-lint rewrites files across the whole repo with Biome, so prefer the changed-files check above.

Python packages: CI builds each package's wheel, installs it with a pinned supermemory version and runs its pytest suite from the package folder (packages/openai-sdk-python uses uv and its uv.lock).

Before a pull request

• Branch from main (feature/... or fix/...) and keep it up to date with main.
• Run the CI checks above for the areas you touched, plus bun run check-types.
• Add tests if applicable, and update the docs if needed.
• CONTRIBUTING.md suggests bun run format-lint and bun run build; use the changed-files Biome check and bunx turbo run build above instead.
• If CI fails on a branch in this repo, the Auto Fix CI Failures workflow (claude-auto-fix-ci.yml) can push fixes to it, so pull before you push again.
• More in CONTRIBUTING.md.