From beb6ae1a811287e7ad53b2d9c91149eca87027e8 Mon Sep 17 00:00:00 2001 From: Muskan Date: Thu, 22 Oct 2026 20:01:09 +0530 Subject: [PATCH 1/2] docs: add AGENTS.md for coding agents Two sections: using supermemory in an app (v5 SDK, API rules, docs MCP, plugins, self-hosting) and working in this repo (requirements, do-nots, repo map, CI commands). Checked against the live docs, supermemory@5.0.2, the CLI and this repo's workflows. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..76479e31 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,217 @@ +# AGENTS.md + +Context for AI coding agents (Claude Code, Cursor, Codex, OpenCode, Copilot and others) working with supermemory. + +**supermemory** is context infrastructure for AI agents: memory, retrieval and user profiles through one API. +[Documentation](https://supermemory.ai/docs) · [Docs index for agents](https://supermemory.ai/docs/llms.txt) · +[Console and API keys](https://console.supermemory.ai) + +Two jobs, two sections: + +- **Adding supermemory to another project?** Read [Use supermemory in an app](#use-supermemory-in-an-app). +- **Changing code in this repository?** Read [Work in this repository](#work-in-this-repository). + +## Use supermemory in an app + +### Start here + +- Check the [docs index](https://supermemory.ai/docs/llms.txt) 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: + +```bash +npx skills add https://github.com/supermemoryai/skills --skill supermemory +``` + +### Install and first calls + +Set `SUPERMEMORY_API_KEY` (create a key in the [console](https://console.supermemory.ai)), then install SDK version 5 +or later: + +```bash +npm i supermemory # TypeScript / JavaScript +pip install supermemory # Python (3.10 or later) +``` + +Every memory call (add, search, profile, list, documents) takes a **namespace** first: one user, workspace or tenant. + +```typescript +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"); +``` + +```python +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. + +### 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](https://supermemory.ai/docs/authentication)). +- **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](https://supermemory.ai/docs/migration/api-v5)). + +### Docs MCP + +Searches these docs while you code. Server: `https://supermemory.ai/docs/mcp` + +```bash +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: + +```json +{ "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 + +| Agent | Install | Guide | +| --- | --- | --- | +| Claude Code | `/plugin marketplace add supermemoryai/claude-supermemory`, then `/plugin install supermemory` | [docs](https://supermemory.ai/docs/integrations/claude-code) | +| Cursor | `/add-plugin cursor-supermemory`, or Supermemory in the Cursor Marketplace | [docs](https://supermemory.ai/docs/integrations/cursor) | +| Codex | `npx codex-supermemory@latest install`, then restart Codex CLI | [docs](https://supermemory.ai/docs/integrations/codex) | +| OpenCode | `bunx opencode-supermemory@latest install --no-tui` | [docs](https://supermemory.ai/docs/integrations/opencode) | +| Hermes | `hermes plugins install supermemoryai/hermes-supermemory`, `hermes plugins enable supermemory`, then `hermes memory setup` | [repo](https://github.com/supermemoryai/hermes-supermemory) | +| OpenClaw | `openclaw plugins install @supermemory/openclaw-supermemory` | [docs](https://supermemory.ai/docs/integrations/openclaw) | +| Any MCP client | Remote server `https://mcp.supermemory.ai/mcp` (OAuth sign-in, no API key) | [docs](https://supermemory.ai/docs/supermemory-mcp/mcp) | + +Each plugin handles its own sign-in (browser login or its own key variable), so follow its guide rather than assuming +`SUPERMEMORY_API_KEY`. + +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](https://supermemory.ai/docs/llms.txt). + +### 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](https://supermemory.ai/docs/self-hosting/overview) + +## 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, 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. Most of them still target supermemory 3.x/4.x and use + `container_tag` on purpose. +- 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`: memory tools for the AI SDK, OpenAI, VoltAgent and Mastra | +| `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/` | 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](https://github.com/supermemoryai/skills) | + +`CLAUDE.md` in this repo predates the v5 API. Where it differs from this file, follow this file. + +### Setup and commands + +```bash +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 +``` + +`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: + +```bash +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 +bun run --cwd packages/memory-graph check-types +bun run --cwd packages/memory-graph test +``` + +`bun run format-lint` rewrites the whole repo with Biome and already reports errors on a clean `main`, 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. +- More in [CONTRIBUTING.md](CONTRIBUTING.md). From 2711aeecd164199a3019cdfc56b7d70c5bb572de Mon Sep 17 00:00:00 2001 From: Muskan Date: Sun, 25 Oct 2026 06:43:06 +0530 Subject: [PATCH 2/2] AGENTS.md: fact-checked against main and the live docs; CLAUDE.md imports it so Claude Code reads it - CLAUDE.md now starts with `@AGENTS.md`. Claude Code reads only CLAUDE.md when a repo has both (code.claude.com/docs memory, "AGENTS.md"), so without the import it never saw this file. - The opening line leads with memory: a memory graph that updates and forgets facts, user profiles, and retrieval over documents. - Corrections from a line-by-line check (150 claims, all against sources): - Python 3.11+ for apps/sdk-playground - per-package SDK pins: agent-framework-python is already on v5; livekit is uncapped - the @supermemory/tools description (adds Claude's memory tool) - the two missing CI steps, and when each runs - dev:local rather than dev (portless binds :443) - CONTRIBUTING's format-lint/build advice - the Auto Fix CI Failures workflow - `pip install -U` - the readiness field names - plugin sign-in - livekit's package name - Removed one claim that couldn't be verified (format-lint erroring on a clean main). Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 43 +++++++++++++++++++++++++++++-------------- CLAUDE.md | 2 ++ 2 files changed, 31 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 76479e31..211f194e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,8 @@ Context for AI coding agents (Claude Code, Cursor, Codex, OpenCode, Copilot and others) working with supermemory. -**supermemory** is context infrastructure for AI agents: memory, retrieval and user profiles through one API. +**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](https://supermemory.ai/docs) · [Docs index for agents](https://supermemory.ai/docs/llms.txt) · [Console and API keys](https://console.supermemory.ai) @@ -31,8 +32,8 @@ Set `SUPERMEMORY_API_KEY` (create a key in the [console](https://console.superme or later: ```bash -npm i supermemory # TypeScript / JavaScript -pip install supermemory # Python (3.10 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. @@ -73,7 +74,8 @@ profile = client.profile("user_123").profile - **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. + `system.dreamingStatus` is `done` before reading memories or the profile. These are the API and TypeScript field + names. ### Do NOT use @@ -120,8 +122,8 @@ This is not the memory MCP. The docs MCP only searches documentation. | OpenClaw | `openclaw plugins install @supermemory/openclaw-supermemory` | [docs](https://supermemory.ai/docs/integrations/openclaw) | | Any MCP client | Remote server `https://mcp.supermemory.ai/mcp` (OAuth sign-in, no API key) | [docs](https://supermemory.ai/docs/supermemory-mcp/mcp) | -Each plugin handles its own sign-in (browser login or its own key variable), so follow its guide rather than assuming -`SUPERMEMORY_API_KEY`. +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 @@ -141,7 +143,8 @@ A Bun + Turbo monorepo. The `supermemory` SDKs on npm and PyPI are built in sepa - Bun 1.3.6 (the `packageManager` field). Use Bun only; the lockfile is `bun.lock`. - Node 20 or later. -- Python 3.10 or later, plus `uv` for `packages/openai-sdk-python` and `apps/sdk-playground`. +- 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 @@ -149,8 +152,10 @@ A Bun + Turbo monorepo. The `supermemory` SDKs on npm and PyPI are built in sepa - 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. Most of them still target supermemory 3.x/4.x and use - `container_tag` on purpose. +- 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 @@ -162,13 +167,13 @@ A Bun + Turbo monorepo. The `supermemory` SDKs on npm and PyPI are built in sepa | `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`: memory tools for the AI SDK, OpenAI, VoltAgent and Mastra | +| `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/` | LiveKit Agents 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 | @@ -187,24 +192,30 @@ bun run check-types # TypeScript across the monorepo bunx turbo run build # build everything ``` -`dev:local` also needs Python and `uv` (the sdk playground runs `uv run server.py`) and network access (the docs run +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: ```bash +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 ``` -`bun run format-lint` rewrites the whole repo with Biome and already reports errors on a clean `main`, so prefer the -changed-files check above. +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`). @@ -214,4 +225,8 @@ suite from the package folder (`packages/openai-sdk-python` uses `uv` and its `u - 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](CONTRIBUTING.md). diff --git a/CLAUDE.md b/CLAUDE.md index da9208e5..32a6d504 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,5 @@ +@AGENTS.md + # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.