Merge 2711aeecd1 into f355dc8039

2026-10-26 06:04:08 +00:00 · 2026-10-25 01:13:14 +00:00 · 2026-10-25 01:13:14 +00:00 · 27013d3441
commit 27013d3441
parent f355dc8039 2711aeecd1
2 changed files with 234 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,232 @@
+# 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](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 -U 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. 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](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 (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](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 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](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
+```
+
+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
+```
+
+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](CONTRIBUTING.md).
--- 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.