diff --git a/apps/docs/cli/commands.mdx b/apps/docs/cli/commands.mdx new file mode 100644 index 000000000..74cf7382d --- /dev/null +++ b/apps/docs/cli/commands.mdx @@ -0,0 +1,318 @@ +--- +title: "Command Reference" +sidebarTitle: "Command Reference" +description: "Every Supermemory CLI command, subcommand, and flag." +icon: "list" +--- + +All commands below assume you've [authenticated](/cli/overview#authenticate). Use the bare `supermemory` form if installed globally, or prefix with `npx`. Every command accepts the [global flags](/cli/overview#global-flags) `--json`, `--tag`, and `--help`. + +## Core memory operations + +### `add` — Ingest content + +Ingest text, files, or URLs and extract memories into a container tag. + +```bash +# Add text +supermemory add "User prefers TypeScript over JavaScript" + +# Add a file (PDF, markdown, text, etc.) +supermemory add ./meeting-notes.pdf --tag meetings + +# Add a URL +supermemory add https://docs.example.com/api --tag docs + +# Read from stdin +cat file.txt | supermemory add --stdin +echo "some content" | supermemory add --stdin --tag notes + +# With metadata, title, and custom ID +supermemory add "Design doc v2" \ + --title "Design Doc" \ + --metadata '{"category": "engineering", "priority": "high"}' \ + --id custom-doc-id --tag project + +# Batch mode (JSONL from stdin, one {"content": "...", "tag": "..."} per line) +cat batch.jsonl | supermemory add --batch +``` + +| Flag | Description | +|---|---| +| `--tag ` | Container tag | +| `--stdin` | Read content from stdin | +| `--title ` | Document title | +| `--metadata ` | JSON metadata object | +| `--id ` | Custom document ID | +| `--batch` | Batch mode, reads JSONL from stdin | + +### `search` — Search memories + +Semantic search across memories with filtering and reranking. + +```bash +# Basic search +supermemory search "authentication patterns" + +# Scoped to a tag, with a limit +supermemory search "auth" --tag api --limit 5 + +# Reranking and LLM query rewriting for better relevance +supermemory search "database migrations" --rerank +supermemory search "how do we handle auth" --rewrite + +# Search modes +supermemory search "user prefs" --mode memories # extracted memories only +supermemory search "user prefs" --mode hybrid # memories + document chunks +supermemory search "user prefs" --mode documents # full documents only + +# Include specific fields and filter by metadata +supermemory search "api design" --include summary,chunks,memories +supermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}' + +# Similarity threshold (0-1) +supermemory search "preferences" --threshold 0.5 +``` + +| Flag | Description | +|---|---| +| `--tag ` | Filter by container tag | +| `--limit ` | Max results (default: 10) | +| `--threshold ` | Similarity threshold 0-1 (default: 0) | +| `--rerank` | Enable reranking for better relevance | +| `--rewrite` | Rewrite the query using an LLM | +| `--mode ` | `memories` \| `hybrid` \| `documents` (default: `memories`) | +| `--include ` | Fields: `summary`, `chunks`, `memories`, `document` | +| `--filter ` | Metadata filter object | + +### `remember` — Store a memory directly + +Store a specific fact without ingesting a full document. + +```bash +supermemory remember "User prefers dark mode" --tag user_123 + +# Permanent / static memory (won't decay) +supermemory remember "User is a senior engineer at Acme Corp" --static --tag user_123 + +# With metadata +supermemory remember "Discussed Q3 roadmap" --tag meetings --metadata '{"type": "decision"}' +``` + +| Flag | Description | +|---|---| +| `--tag ` | Container tag | +| `--static` | Mark as a permanent memory | +| `--metadata ` | JSON metadata | + +### `forget` — Delete a memory + +```bash +supermemory forget mem_abc123 --tag default +supermemory forget --content "outdated preference" --tag default +supermemory forget mem_abc123 --reason "User corrected this information" +``` + +| Flag | Description | +|---|---| +| `--tag ` | Container tag | +| `--reason ` | Reason for forgetting | +| `--content ` | Forget by content match instead of ID | + +### `update` — Update an existing memory + +```bash +supermemory update mem_123 "Updated preference: prefers Bun over Node" +supermemory update mem_123 "New content" --metadata '{"updated": true}' +``` + +| Flag | Description | +|---|---| +| `--tag ` | Container tag | +| `--metadata ` | Updated metadata | +| `--reason ` | Reason for the update | + +### `profile` — Get a user profile + +Retrieve the auto-generated user profile (static facts + dynamic context) for a container tag. + +```bash +supermemory profile # default tag +supermemory profile user_123 # specific tag +supermemory profile user_123 --query "programming preferences" +``` + +## Document management + +### `docs` — Manage documents + +```bash +supermemory docs list --tag default --limit 20 +supermemory docs get doc_abc123 +supermemory docs status doc_abc123 # processing status +supermemory docs chunks doc_abc123 # view chunks +supermemory docs delete doc_abc123 --yes +``` + +**Subcommands:** `list`, `get`, `delete`, `chunks`, `status` + +## Container tags + +### `tags` — Manage container tags + +Container tags scope memories to users, projects, or any logical grouping. + +```bash +supermemory tags list +supermemory tags info user_123 # counts and metadata +supermemory tags create my-new-project +supermemory tags context user_123 --set "This user is a premium customer" +supermemory tags context user_123 --clear +supermemory tags merge old-tag --into new-tag --yes +supermemory tags delete old-tag --yes +``` + +**Subcommands:** `list`, `info`, `create`, `delete`, `context`, `merge` + +## API keys + +### `keys` — Manage API keys + +```bash +supermemory keys list +supermemory keys create --name my-agent --permission write +supermemory keys create --name bot-key --tag user_123 --expires 30 # scoped + expiring +supermemory keys revoke key_abc123 --yes +supermemory keys toggle key_abc123 # enable/disable +``` + +**Subcommands:** `list`, `create`, `revoke`, `toggle` + +## Connectors + +### `connectors` — External data sources + +Connect Google Drive, Notion, OneDrive, and other services to sync documents automatically. + +```bash +supermemory connectors list +supermemory connectors connect google-drive --tag docs # opens OAuth flow +supermemory connectors sync conn_abc123 +supermemory connectors history conn_abc123 --limit 10 +supermemory connectors resources conn_abc123 +supermemory connectors disconnect conn_abc123 --yes +``` + +**Subcommands:** `list`, `connect`, `sync`, `history`, `disconnect`, `resources` + +## Plugins + +### `plugins` — IDE and tool integrations + +Connect the CLI to Claude Code, Cursor, and other tools. + +```bash +supermemory plugins list +supermemory plugins connect claude-code --auto-configure +supermemory plugins status claude-code +supermemory plugins revoke claude-code --yes +``` + +**Subcommands:** `list`, `connect`, `revoke`, `status` + +## Team management + +### `team` — Manage team members + +```bash +supermemory team list +supermemory team invite user@example.com --role admin +supermemory team role member_123 admin +supermemory team remove member_123 --yes +supermemory team invitations +``` + +**Subcommands:** `list`, `invite`, `remove`, `role`, `invitations` + +## Monitoring + +### `status` — Account dashboard + +```bash +supermemory status +supermemory status --period 7d # 24h, 7d, 30d, all +``` + +Shows memory count, document count, API usage, and storage. + +### `logs` — Request logs + +```bash +supermemory logs +supermemory logs --period 7d +supermemory logs --status error +supermemory logs --type search +supermemory logs get req_abc123 +``` + +### `billing` — Usage and billing + +```bash +supermemory billing # overview +supermemory billing usage # detailed breakdown +supermemory billing invoices # past invoices +``` + +## Utility + +```bash +# Open the console in your browser +supermemory open +supermemory open graph # also: billing, settings, docs, keys + +# Machine-readable help (useful for LLM agents) +supermemory help --json +supermemory help --all + +# Per-command help +supermemory search --help +supermemory tags --help --json +``` + +## Scoped keys mode + +When you authenticate with a scoped API key (restricted to a single container tag), only these commands are available, and the tag is taken automatically from the key's scope — no `--tag` needed: + +`search`, `add`, `remember`, `forget`, `update`, `profile`, `whoami` + +## Common patterns + +### Pipe content from other tools + +```bash +git log --oneline -20 | supermemory add --stdin --tag git-history +curl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs +supermemory search "auth" --json | jq '.results[].memory' +``` + +### Scripting with JSON output + +Every command supports `--json` for machine-readable output: + +```bash +supermemory search "query" --json +supermemory tags list --json +supermemory status --json | jq '.memoryCount' +``` + +### CI/CD integration + +```bash +export SUPERMEMORY_API_KEY=sm_xxx + +# Ingest docs on deploy, replacing the previous version by ID +supermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest + +# Gate on status +supermemory status --json | jq '.memoryCount' +``` diff --git a/apps/docs/cli/local.mdx b/apps/docs/cli/local.mdx new file mode 100644 index 000000000..12a81b394 --- /dev/null +++ b/apps/docs/cli/local.mdx @@ -0,0 +1,86 @@ +--- +title: "Local server" +sidebarTitle: "Local server" +description: "npx supermemory local — run the full memory engine on your own machine. One binary, zero config." +icon: "server" +--- + +`npx supermemory local` downloads and runs Supermemory's self-hosted memory engine on your machine. It's the same engine behind the [hosted platform](https://console.supermemory.ai) — ingestion, memory extraction, hybrid semantic search, and the full API — as a single self-contained binary. + +No Docker, no database to provision, no config files. It boots in seconds with everything built in, and it's [open source](https://git.new/memory). + +## Run it + + + +```bash +npx supermemory local +``` + + +```bash +bunx supermemory local +``` + + +```bash +curl -fsSL https://supermemory.ai/install | bash +``` + + + +The installer detects your OS and architecture, downloads the right binary, verifies it, and (when run interactively) prompts you for an LLM API key. Then start the server: + +```bash +supermemory-server +``` + +First boot sets everything up — the embedded graph engine, local embeddings, and your credentials — and prints an API key: + +``` + ┌──────────────────────────────────────────────────┐ + │ url http://localhost:6767 │ + │ database ./.supermemory │ + │ api key sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │ + │ org id xxxxxxxxxxxxxxxxxxxxxx │ + └──────────────────────────────────────────────────┘ +``` + +Save that API key — it's your bearer token for every request. Then point any Supermemory SDK at your local server with a one-line change: + +```typescript +const client = new Supermemory({ + apiKey: "sm_...", // printed on first boot + baseURL: "http://localhost:6767", // that's the only change +}) +``` + +## Cloud CLI vs. local server + +Both ship under `npx supermemory`, but they're different things: + +| | `supermemory ` | `supermemory local` | +|---|---|---| +| What it talks to | The [hosted platform](https://console.supermemory.ai) | A server running on your machine | +| Auth | Your account ([`login`](/cli/overview#authenticate)) | Auto-generated key on first boot | +| Use case | Manage cloud memory from the terminal | Local-first, air-gapped, privacy-sensitive workloads | +| Reference | [Command reference](/cli/commands) | This page + [Self-hosting docs](/self-hosting/overview) | + +## Learn more + +The local server has its own full documentation — bringing your own model (or running fully offline with Ollama), configuration, and how it compares to Enterprise: + + + + Install, run, and store your first memory in under two minutes. + + + Every environment variable: LLM providers, local models, storage, tuning. + + + What's built in, what runs offline, and how it matches the platform API. + + + When to run it yourself and when to move to the managed platform. + + diff --git a/apps/docs/cli/overview.mdx b/apps/docs/cli/overview.mdx new file mode 100644 index 000000000..c32585018 --- /dev/null +++ b/apps/docs/cli/overview.mdx @@ -0,0 +1,125 @@ +--- +title: "Supermemory CLI" +sidebarTitle: "Overview" +description: "Supermemory from the terminal. One command — npx supermemory — for your cloud memory and a local server." +icon: "square-terminal" +--- + +The Supermemory CLI is the complete interface to Supermemory from your terminal. Add memories, search, manage documents, configure projects, connect data sources, administer teams — all programmatically, all from `npx supermemory`. + +It does two things: + + + + `npx supermemory ` talks to the [hosted platform](https://console.supermemory.ai). Add, search, and manage memories, documents, tags, keys, connectors, and teams. + + + `npx supermemory local` downloads and runs the self-hosted memory engine on your machine — one binary, zero config. + + + +## Install + +You can run every command through `npx` with no install: + +```bash +npx supermemory whoami +npx supermemory search "authentication patterns" +npx supermemory local +``` + +Or install it globally and drop the `npx`: + + +```bash npm +npm install -g supermemory +``` + +```bash bun +bun add -g supermemory +``` + + +```bash +supermemory whoami +``` + +The rest of these docs use the bare `supermemory` form — prefix with `npx` if you haven't installed globally. + +## Authenticate + +Most commands act on your cloud account, so authenticate first: + +```bash +# Browser OAuth flow +supermemory login + +# Or pass an API key directly +supermemory login --api-key sm_xxx + +# Confirm who you are +supermemory whoami +``` + +In CI or scripts, set the API key as an environment variable instead of logging in: + +```bash +export SUPERMEMORY_API_KEY=sm_xxx +``` + + +`npx supermemory local` does **not** require authentication — it runs entirely on your machine and generates its own API key on first boot. See [Local server](/cli/local). + + +## Configuration + +The CLI resolves config from three scopes, most specific wins: + +| Scope | File | Use case | +|---|---|---| +| `project` | `.supermemory/config.json` (gitignored) | Per-machine secrets, API keys | +| `team` | `.supermemory/team.json` (committed) | Shared container tag, team-wide defaults | +| `global` | `~/.config/supermemory/config.json` | Defaults for all projects on this machine | + +```bash +# Interactive setup wizard +supermemory init + +# Non-interactive +supermemory init --scope project --tag my-bot +supermemory init --scope team --tag shared-project + +# View / get / set values +supermemory config +supermemory config get tag +supermemory config set tag my-project +``` + +### Environment variables + +| Variable | Description | +|---|---| +| `SUPERMEMORY_API_KEY` | API key for authentication | +| `SUPERMEMORY_TAG` | Override the default container tag | +| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint | + +### Global flags + +Available on every command: + +| Flag | Description | +|---|---| +| `--json` | Force machine-readable JSON output | +| `--tag ` | Override the default container tag for this command | +| `--help` | Show help for any command | + +## Next steps + + + + Every command and flag — add, search, docs, tags, keys, connectors, teams, and more. + + + `npx supermemory local` — run the memory engine on your own machine. + + diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 6be467ff7..b4dbbc7ed 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -43,6 +43,10 @@ "name": "supermemory | Memory API for the AI era", "navbar": { "links": [ + { + "href": "/self-hosting/overview", + "label": "Self-host" + }, { "href": "mailto:support@supermemory.com", "label": "Support" @@ -72,12 +76,17 @@ "pages": ["intro", "quickstart", "vibe-coding"] }, { - "group": "Self-Hosting", + "group": "Core Features", "pages": [ - "self-hosting/overview", - "self-hosting/quickstart", - "self-hosting/configuration", - "self-hosting/local-vs-enterprise" + "add-memories", + "search", + "user-profiles", + { + "group": "Manage Content", + "icon": "folder-cog", + "pages": ["document-operations", "memory-operations"] + }, + "overview/use-cases" ] }, { @@ -95,20 +104,6 @@ "authentication" ] }, - { - "group": "Using supermemory", - "pages": [ - "add-memories", - "search", - "user-profiles", - { - "group": "Manage Content", - "icon": "folder-cog", - "pages": ["document-operations", "memory-operations"] - }, - "overview/use-cases" - ] - }, { "group": "Connectors and sync", "pages": [ @@ -140,6 +135,42 @@ "pages": ["migration/from-mem0", "migration/from-zep"] } ] + }, + { + "group": "Self-Hosting", + "pages": [ + "self-hosting/overview", + "self-hosting/quickstart", + "self-hosting/configuration", + "self-hosting/local-vs-enterprise" + ] + }, + { + "group": "Command Line (CLI)", + "icon": "square-terminal", + "pages": ["cli/overview", "cli/commands", "cli/local"] + }, + { + "group": "SMFS (Memory Filesystem)", + "icon": "database", + "pages": [ + "smfs/overview", + "smfs/install", + "smfs/mount", + "smfs/bash-tool", + "smfs/bash-tool-python", + { + "group": "Providers", + "icon": "cloud", + "pages": [ + "smfs/providers/daytona", + "smfs/providers/e2b", + "smfs/providers/vercel", + "smfs/providers/cloudflare" + ] + }, + "smfs/examples" + ] } ] }, @@ -155,28 +186,6 @@ "pages": ["supermemory-mcp/claude-desktop"] } ] - }, - { - "anchor": "SMFS", - "icon": "database", - "pages": [ - "smfs/overview", - "smfs/install", - "smfs/mount", - "smfs/bash-tool", - "smfs/bash-tool-python", - { - "group": "Providers", - "icon": "cloud", - "pages": [ - "smfs/providers/daytona", - "smfs/providers/e2b", - "smfs/providers/vercel", - "smfs/providers/cloudflare" - ] - }, - "smfs/examples" - ] } ], "tab": "Developer Platform" diff --git a/apps/docs/intro.mdx b/apps/docs/intro.mdx index 319a55eac..20eef3816 100644 --- a/apps/docs/intro.mdx +++ b/apps/docs/intro.mdx @@ -4,86 +4,112 @@ sidebarTitle: "Overview" icon: "book-open" --- -Supermemory is the long-term and short-term memory and context infrastructure for AI agents. It is the [state of the art](https://supermemory.ai/research) across multiple different benchmarks, like LongMemEval and LoCoMo. +Supermemory is the memory and context engine for AI agents — and it's the state of the art, ranked **#1 on every major memory benchmark**: [LongMemEval](https://github.com/xiaowu0162/LongMemEval), [LoCoMo](https://github.com/snap-research/locomo), and [ConvoMem](https://github.com/Salesforce/ConvoMem). -With supermemory, developers can provide perfect recall about their users to build AI agents that are more intelligent, more personalized, and more consistent. Additionally, *supermemory* has all the pieces of the context stack built in: -- [Agent memory](/concepts/graph-memory) -- [Content extraction](/concepts/content-types) -- [Connectors and syncing](/connectors/overview) -- [Managed RAG platform](/concepts/super-rag) +Your AI forgets everything between conversations. Supermemory fixes that. It learns from every interaction, **reasons over a directed knowledge graph** to resolve contradictions and track how facts change over time, forgets what's expired, and serves the right context at the right moment — through one API. -All this, coming together, makes supermemory the best abstraction to provide to agents. +## State of the art, by the numbers -## How does it work? (at a glance) +Most memory systems claim to be better. Supermemory is measurably ahead — first place across all three independent benchmarks the field uses to grade AI memory. -![](/images/232.png) +| Benchmark | What it measures | Supermemory | +|---|---|---| +| [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | Long-term memory across sessions, with knowledge updates | **81.6% — #1** | +| [LoCoMo](https://github.com/snap-research/locomo) | Fact recall across long conversations (multi-hop, temporal, adversarial) | **#1** | +| [ConvoMem](https://github.com/Salesforce/ConvoMem) | Personalization and preference learning | **#1** | -- You send Supermemory text, files, and chats. -- Supermemory [intelligently indexes them](/concepts/how-it-works) and builds a semantic understanding graph on top of an entity (e.g., a user, a document, a project, an organization). -- At query time, we fetch only the most relevant context and pass it to your models. +Read the full methodology on the [research page](https://supermemory.ai/research), or reproduce it yourself with [MemoryBench](/memorybench/overview), our open-source benchmarking framework. + +## What makes Supermemory different + +Most "memory layers" are a vector store that retrieves the nearest chunk. Supermemory is an engine that *understands* — which is why it tops the benchmarks instead of just claiming to. + + + + Resolves contradictions, tracks temporal change, follows multi-hop relationships, and forgets expired facts automatically. Reasoning is why it wins every benchmark. + + + One evolving directed graph and a single ontology across all your data — not a flat vector store, and not a raw graph you have to traverse yourself. + + + Memory, user profiles, hybrid search (RAG), connectors, and file processing — together, sharing one context pool. No stitching five tools together. + + + Text, conversations, PDFs, images (OCR), video (transcription), and code (AST-aware chunking). Upload it and it just works. + + + One API, plus SDKs, a CLI, a memory filesystem, and MCP. Infrastructure you ship products on — not a closed box. + + + Hosted for zero-ops scale, or the full engine as one self-hosted binary — fully offline if you want, same API either way. + + -## Supermemory is context engineering. + +**Hosted or self-hosted — same API.** Use the [managed platform](https://console.supermemory.ai) for zero-ops scale, or [run the entire engine on your own machine](/self-hosting/overview) — one binary, zero config, fully offline. Move between them by changing a single `baseURL`. + -#### Ingestion and Extraction +## How does it work? (at a glance) + +![](/images/232.png) -Supermemory handles all the extraction, for [any data type that you have](/concepts/content-types). -- Text -- Conversations -- Files (PDF, Images, Docs) -- Even videos! +- You send Supermemory text, files, and chats. +- It [indexes them intelligently](/concepts/how-it-works) and builds a directed knowledge graph on top of an entity (a user, document, project, or organization). +- At query time, it fetches only the most relevant context and passes it to your models. -... and then, +## Three ways to add context -We offer three ways to add context to your LLMs: +Memory, profiles, and search all draw from the **same context pool** for a given user (`containerTag`) — so they reinforce each other instead of living in silos. Mix and match as your use case needs. -#### Memory API — Learned user context +#### Memory API — learned user context ![memory graph](/images/memory-graph.png) -Supermemory learns and builds the memory for the user. These are extracted facts about the user, that: +Supermemory learns and builds memory for each user — extracted facts that: - [Evolve on top of existing context about the user](/concepts/graph-memory), **in real time** -- Handle **knowledge updates, temporal changes, forgetfulness** -- Creates a **user profile** as the default context provider for the LLM. - -_This can then be provided to the LLM, to give more contextual, personalized responses._ +- Handle **knowledge updates, temporal changes, and contradictions** +- Power a **user profile** that acts as the default context provider for the LLM #### User profiles -Having the latest, evolving context about the user allows us to also create a [**User Profile**](/concepts/user-profiles). This is a combination of static and dynamic facts about the user, that the agent should **always know** -Developers can configure supermemory with what static and dynamic contents are, depending on their use case. - -- Static: Information that the agent should **always** know. -- Dynamic: **Episodic** information, about last few conversations etc. +The evolving context produces a [**User Profile**](/concepts/user-profiles) — the facts your agent should **always** know, in one ~50ms call: -This leads to a much better retrieval system, and extremely personalized responses. +- **Static:** stable facts the agent should always know. +- **Dynamic:** episodic context from the last few conversations. -#### RAG - Advanced semantic search +#### RAG — advanced semantic search -Along with the user context, developers can also choose to do a search on the raw context. We provide full RAG-as-a-service, along with -- Full advanced metadata filtering -- Contextual chunking -- Works well with the memory engine +Run hybrid [search](/search) over the raw content too: advanced metadata filtering, contextual chunking, and reranking — tightly integrated with the memory engine, in a single query. - - See the full API Reference tab for detailed endpoint documentation. - +## Start building + + + Make your first API call in minutes. + + + Ingest text, files, and conversations into a container. + + + Retrieve the most relevant context with hybrid semantic search. + + - -All three approaches share the **same context pool** when using the same user ID (`containerTag`). You can mix and match based on your needs. - +## Ways to use Supermemory -## Next steps +The API is the core — but you don't have to talk to it directly. Reach Supermemory however fits your workflow: - - Make your first API call in minutes + + Official TypeScript and Python SDKs, plus drop-in plugins for the AI SDK, OpenAI, LangChain, and more. + + + Manage memories, search, and scripting from your terminal — it's all `npx supermemory`. - - Understand the knowledge graph architecture + + Mount a container as a real directory your agent can `ls`, `cat`, and semantically `grep`. - Run Supermemory on your own machine — one binary, zero config, fully offline + Run the full memory engine on your own machine — one binary, zero config, fully offline. -