Command Reference

Every Supermemory CLI command, subcommand, and flag.

All commands below assume you’ve authenticated. Use the bare supermemory form if installed globally, or prefix with npx. Every command accepts the global flags --json, --tag, and --help.

Core memory operations

add — Ingest content

Ingest text, files, or URLs and extract memories into a container tag.

# 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.

# 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.

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

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

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.

supermemory profile                                   # default tag
supermemory profile user_123                          # specific tag
supermemory profile user_123 --query "programming preferences"

Document management

docs — Manage documents

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.

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

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.

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.

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

supermemory team list
supermemory team invite [e-mail] --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

supermemory status
supermemory status --period 7d    # 24h, 7d, 30d, all

Shows memory count, document count, API usage, and storage.

logs — Request logs

supermemory logs
supermemory logs --period 7d
supermemory logs --status error
supermemory logs --type search
supermemory logs get req_abc123

billing — Usage and billing

supermemory billing            # overview
supermemory billing usage      # detailed breakdown
supermemory billing invoices   # past invoices

Utility

# 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

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:

supermemory search "query" --json
supermemory tags list --json
supermemory status --json | jq '.memoryCount'

CI/CD integration

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'