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

bash

# 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

bash

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

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

bash

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

bash

# 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

bash

# 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

bash

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.

bash

# 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

bash

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

bash

# 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

bash

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

bash

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

bash

# 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

bash

# 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

bash

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

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

logs

— Request logs

bash

# 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

bash

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

Utility Commands

bash

# 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

bash

# 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

bash

# 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

bash

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

supermemory-cli

NPX Install

Tags

SKILL.md Content

Installation & Auth

Configuration

Environment Variables

Global Flags

Core Commands

`add`
— Ingest content

`search`
— Search memories

`remember`
— Store a memory directly

`forget`
— Delete a memory

`update`
— Update an existing memory

`profile`
— Get user profile

Document Management

`docs`
— Manage documents

Container Tags

`tags`
— Manage container tags

API Keys

`keys`
— Manage API keys

Connectors

`connectors`
— External data sources

Plugins

`plugins`
— IDE and tool integrations

Team Management

`team`
— Manage team members

Monitoring

`status`
— Account dashboard

`logs`
— Request logs

`billing`
— Usage and billing

Utility Commands

Scoped Keys Mode

Common Patterns

Pipe content from other tools

Scripting with JSON output

CI/CD integration