mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-09-05 08:06:19 +00:00
docs: add Supermemory CLI docs and embed SMFS into main nav
Document the Supermemory CLI (npx supermemory) — previously undocumented. Adds a "Command Line (CLI)" group under the Developer Platform tab: - cli/overview: install, auth, config scopes, the cloud-CLI vs local-server split - cli/commands: full command/flag reference (add, search, tags, keys, etc.) - cli/local: npx supermemory local, cross-linked to self-hosting docs Also moves SMFS from a standalone top-level anchor into a group inside the main Developer Platform anchor so it's embedded rather than feeling detached. Page URLs are unchanged, so no redirects are needed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
5eed4bcbf3
commit
d62d9cc5ac
4 changed files with 556 additions and 22 deletions
318
apps/docs/cli/commands.mdx
Normal file
318
apps/docs/cli/commands.mdx
Normal file
|
|
@ -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 <string>` | Container tag |
|
||||
| `--stdin` | Read content from stdin |
|
||||
| `--title <string>` | Document title |
|
||||
| `--metadata <json>` | JSON metadata object |
|
||||
| `--id <string>` | 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 <string>` | Filter by container tag |
|
||||
| `--limit <number>` | Max results (default: 10) |
|
||||
| `--threshold <number>` | Similarity threshold 0-1 (default: 0) |
|
||||
| `--rerank` | Enable reranking for better relevance |
|
||||
| `--rewrite` | Rewrite the query using an LLM |
|
||||
| `--mode <string>` | `memories` \| `hybrid` \| `documents` (default: `memories`) |
|
||||
| `--include <string>` | Fields: `summary`, `chunks`, `memories`, `document` |
|
||||
| `--filter <json>` | 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 <string>` | Container tag |
|
||||
| `--static` | Mark as a permanent memory |
|
||||
| `--metadata <json>` | 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 <string>` | Container tag |
|
||||
| `--reason <string>` | Reason for forgetting |
|
||||
| `--content <string>` | 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 <string>` | Container tag |
|
||||
| `--metadata <json>` | Updated metadata |
|
||||
| `--reason <string>` | 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'
|
||||
```
|
||||
86
apps/docs/cli/local.mdx
Normal file
86
apps/docs/cli/local.mdx
Normal file
|
|
@ -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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="npx">
|
||||
```bash
|
||||
npx supermemory local
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="bunx">
|
||||
```bash
|
||||
bunx supermemory local
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="curl">
|
||||
```bash
|
||||
curl -fsSL https://supermemory.ai/install | bash
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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 <command>` | `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:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Self-hosting quickstart" icon="play" href="/self-hosting/quickstart">
|
||||
Install, run, and store your first memory in under two minutes.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="settings" href="/self-hosting/configuration">
|
||||
Every environment variable: LLM providers, local models, storage, tuning.
|
||||
</Card>
|
||||
<Card title="Overview" icon="server" href="/self-hosting/overview">
|
||||
What's built in, what runs offline, and how it matches the platform API.
|
||||
</Card>
|
||||
<Card title="Local vs. Enterprise" icon="building-2" href="/self-hosting/local-vs-enterprise">
|
||||
When to run it yourself and when to move to the managed platform.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
125
apps/docs/cli/overview.mdx
Normal file
125
apps/docs/cli/overview.mdx
Normal file
|
|
@ -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:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Manage your cloud memory" icon="cloud" href="/cli/commands">
|
||||
`npx supermemory <command>` talks to the [hosted platform](https://console.supermemory.ai). Add, search, and manage memories, documents, tags, keys, connectors, and teams.
|
||||
</Card>
|
||||
<Card title="Run a local server" icon="server" href="/cli/local">
|
||||
`npx supermemory local` downloads and runs the self-hosted memory engine on your machine — one binary, zero config.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 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`:
|
||||
|
||||
<CodeGroup>
|
||||
```bash npm
|
||||
npm install -g supermemory
|
||||
```
|
||||
|
||||
```bash bun
|
||||
bun add -g supermemory
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
<Note>
|
||||
`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).
|
||||
</Note>
|
||||
|
||||
## 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 <string>` | Override the default container tag for this command |
|
||||
| `--help` | Show help for any command |
|
||||
|
||||
## Next steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Command reference" icon="list" href="/cli/commands">
|
||||
Every command and flag — add, search, docs, tags, keys, connectors, teams, and more.
|
||||
</Card>
|
||||
<Card title="Local server" icon="server" href="/cli/local">
|
||||
`npx supermemory local` — run the memory engine on your own machine.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
|
@ -71,6 +71,11 @@
|
|||
"group": "Getting Started",
|
||||
"pages": ["intro", "quickstart", "vibe-coding"]
|
||||
},
|
||||
{
|
||||
"group": "Command Line (CLI)",
|
||||
"icon": "square-terminal",
|
||||
"pages": ["cli/overview", "cli/commands", "cli/local"]
|
||||
},
|
||||
{
|
||||
"group": "Self-Hosting",
|
||||
"pages": [
|
||||
|
|
@ -131,6 +136,28 @@
|
|||
"memory-api/connectors/managing-resources"
|
||||
]
|
||||
},
|
||||
{
|
||||
"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"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Migration Guides",
|
||||
"pages": [
|
||||
|
|
@ -155,28 +182,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"
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue