supermemory-cli

The Supermemory CLI is the complete interface to Supermemory from the terminal. It lets you add memories, search, manage documents, configure projects, connect external data sources, and administer teams — all programmatically.

Installation & Auth

# Install globally
npm install -g @supermemory/cli

# Authenticate (opens browser OAuth flow)
supermemory login

# Or use an API key directly
supermemory login --api-key sm_abc_xxx

# Check auth status
supermemory whoami

Configuration

The CLI supports three config scopes:

Scope	File	Use Case
project	.supermemory/config.json (gitignored)	Per-machine secrets, API keys
team	.supermemory/team.json (committed)	Shared tag, team-wide defaults
global	~/.config/supermemory/config.json	All projects on this machine

# Interactive setup wizard
supermemory init

# Non-interactive
supermemory init --scope project --tag my-bot
supermemory init --scope team --tag shared-project
supermemory init --scope global --output json

# View/set config values
supermemory config
supermemory config set tag my-project
supermemory config set verbose true
supermemory config get tag

Environment Variables

Variable	Description
SUPERMEMORY_API_KEY	API key for authentication
SUPERMEMORY_TAG	Override default container tag
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry collector endpoint

Global Flags

Flag	Description
--json	Force JSON output (machine-readable)
--tag	Override default container tag for this command
--help	Show help for any command

---

Core Commands

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
supermemory add "Design doc v2" --metadata '{"category": "engineering", "priority": "high"}'

# Custom document ID
supermemory add "My doc" --id custom-doc-id --tag project

# Batch mode (JSONL from stdin, each line: {"content": "...", "tag": "..."})
cat batch.jsonl | supermemory add --batch

Options:

• --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 limit
supermemory search "auth" --tag api --limit 5

# With reranking for better relevance
supermemory search "database migrations" --rerank

# Query rewriting (LLM rewrites query for better results)
supermemory search "how do we handle auth" --rewrite

# Different 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
supermemory search "api design" --include summary,chunks,memories

# Metadata filtering
supermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}'

# Similarity threshold (0-1)
supermemory search "preferences" --threshold 0.5

Options:

• --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 query using 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 or memory without ingesting a full document.

# Store a memory
supermemory remember "User prefers dark mode" --tag user_123

# Mark as permanent/static (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"}'

Options:

• --tag <string> — Container tag
• --static — Mark as permanent memory
• --metadata <json> — JSON metadata

forget — Delete a memory

# Forget by memory ID
supermemory forget mem_abc123 --tag default

# Forget by content match
supermemory forget --content "outdated preference" --tag default

# With reason
supermemory forget mem_abc123 --reason "User corrected this information"

Options:

• --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}'

Options:

• --tag <string> — Container tag
• --metadata <json> — Updated metadata
• --reason <string> — Reason for update

profile — Get user profile

Retrieve the auto-generated user profile for a container tag.

# Get profile for default tag
supermemory profile

# Get profile for specific tag
supermemory profile user_123

# Search within the profile
supermemory profile user_123 --query "programming preferences"

Returns static facts (long-term) and dynamic context (recent activity).

---

Document Management

docs — Manage documents

# List documents
supermemory docs list --tag default --limit 20

# Get a specific document
supermemory docs get doc_abc123

# Check processing status
supermemory docs status doc_abc123

# View document chunks
supermemory docs chunks doc_abc123

# Delete a document
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.

# List all tags
supermemory tags list

# Get tag info (memory count, doc count, etc.)
supermemory tags info user_123

# Create a new tag
supermemory tags create my-new-project

# Set context on a tag (injected into profile responses)
supermemory tags context user_123 --set "This user is a premium customer"

# Clear context
supermemory tags context user_123 --clear

# Merge tags (moves all memories from source to target)
supermemory tags merge old-tag --into new-tag --yes

# Delete a tag
supermemory tags delete old-tag --yes

Subcommands: list, info, create, delete, context, merge

---

API Keys

keys — Manage API keys

# List all keys
supermemory keys list

# Create a new key
supermemory keys create --name my-agent --permission write

# Create a scoped key (restricted to one container tag)
supermemory keys create --name bot-key --tag user_123 --expires 30

# Revoke a key
supermemory keys revoke key_abc123 --yes

# Toggle a key on/off
supermemory keys toggle key_abc123

Subcommands: list, create, revoke, toggle

---

Connectors

connectors — External data sources

Connect Google Drive, Notion, OneDrive, and other services to automatically sync documents.

# List connected services
supermemory connectors list

# Connect a service (opens OAuth flow)
supermemory connectors connect google-drive --tag docs
supermemory connectors connect notion --tag notes

# Trigger a sync
supermemory connectors sync conn_abc123

# View sync history
supermemory connectors history conn_abc123 --limit 10

# List synced resources
supermemory connectors resources conn_abc123

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

# List available plugins
supermemory plugins list

# Connect a plugin (with auto-configuration)
supermemory plugins connect claude-code --auto-configure
supermemory plugins connect cursor --auto-configure

# Check plugin status
supermemory plugins status claude-code

# Revoke a plugin connection
supermemory plugins revoke claude-code --yes

Subcommands: list, connect, revoke, status

---

Team Management

team — Manage team members

# List team members
supermemory team list

# Invite a member
supermemory team invite user@example.com --role admin
supermemory team invite user@example.com --role member

# Change a member's role
supermemory team role member_123 admin

# Remove a member
supermemory team remove member_123 --yes

# View pending invitations
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

# Recent logs
supermemory logs

# Filter by time period
supermemory logs --period 7d

# Filter by status
supermemory logs --status error

# Filter by request type
supermemory logs --type search

# Get a specific log entry
supermemory logs get req_abc123

billing — Usage and billing

supermemory billing          # Overview
supermemory billing usage    # Detailed usage breakdown
supermemory billing invoices # Past invoices

---

Utility Commands

# Open Supermemory console in browser
supermemory open
supermemory open graph       # Memory graph view
supermemory open billing
supermemory open settings
supermemory open docs
supermemory open 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 using a scoped API key (restricted to a single container tag), only these commands are available:

search, add, remember, forget, update, profile, whoami

The tag is automatically set from the key's scope — no need to pass --tag.

---

Common Patterns

Pipe content from other tools

# Ingest git log
git log --oneline -20 | supermemory add --stdin --tag git-history

# Ingest command output
curl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs

# Pipe search results to jq
supermemory search "auth" --json | jq '.results[].memory'

Scripting with JSON output

# All commands support --json for machine-readable output
supermemory search "query" --json
supermemory tags list --json
supermemory profile user_123 --json
supermemory status --json

CI/CD integration

# Use env var for auth
export SUPERMEMORY_API_KEY=sm_abc_xxx

# Ingest docs on deploy
supermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest

# Check status
supermemory status --json | jq '.memoryCount'