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

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

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.