Supermemory Cli

by supermemoryai10d5e16780b4No license108 starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 6 days ago

Use the Supermemory CLI to programmatically manage memories, documents, profiles, tags, connectors, keys, and teams from the terminal. Covers all commands, flags, and usage patterns.

Instructions onlyProductivity & Workflow

AI-generated overview

Documents the Supermemory CLI for managing memories, documents, profiles, tags, connectors, keys and teams from the terminal.

What it does: Explains how to install and authenticate the Supermemory CLI, then use its commands to ingest text, files or URLs, run semantic searches, and store, update or delete individual memories. It also covers document management, container tags, API keys, external connectors, IDE plugins, team administration, monitoring, billing and JSON output for scripting. The deliverable is reference guidance on commands, flags and usage patterns rather than generated files.
When to use it: Use when an agent or developer needs to operate Supermemory from the terminal, for example to add or search memories, manage documents and tags, or script memory operations in CI/CD. Also useful for looking up exact command syntax, flags and configuration scopes. Not intended for tasks unrelated to the Supermemory service.
Requirements: Requires the Supermemory CLI installed globally via npm (npm install -g @supermemory/cli), a Node.js/npm runtime, and Supermemory authentication through browser OAuth login or an API key (SUPERMEMORY_API_KEY). Network access is needed for all commands; no scripts ship with the skill.

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 globallynpm install -g @supermemory/cli
# Authenticate (opens browser OAuth flow)supermemory login
# Or use an API key directlysupermemory login --api-key sm_abc_xxx
# Check auth statussupermemory whoami

# Install globallynpm install -g @supermemory/cli
# Authenticate (opens browser OAuth flow)supermemory login
# Or use an API key directlysupermemory login --api-key sm_abc_xxx
# Check auth statussupermemory 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 wizardsupermemory init
# Non-interactivesupermemory init --scope project --tag my-botsupermemory init --scope team --tag shared-projectsupermemory init --scope global --output json
# View/set config valuessupermemory configsupermemory config set tag my-projectsupermemory config set verbose truesupermemory config get tag

# Interactive setup wizardsupermemory init
# Non-interactivesupermemory init --scope project --tag my-botsupermemory init --scope team --tag shared-projectsupermemory init --scope global --output json
# View/set config valuessupermemory configsupermemory config set tag my-projectsupermemory config set verbose truesupermemory config get tag

Environment Variables

Global Flags

Core Commands

`add` — Ingest content

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

bash

# Add textsupermemory add "User prefers TypeScript over JavaScript"
# Add a file (PDF, markdown, text, etc.)supermemory add ./meeting-notes.pdf --tag meetings
# Add a URLsupermemory add https://docs.example.com/api --tag docs
# Read from stdincat file.txt | supermemory add --stdinecho "some content" | supermemory add --stdin --tag notes
# With metadatasupermemory add "Design doc v2" --metadata '{"category": "engineering", "priority": "high"}'
# Custom document IDsupermemory add "My doc" --id custom-doc-id --tag project
# Batch mode (JSONL from stdin, each line: {"content": "...", "tag": "..."})cat batch.jsonl | supermemory add --batch

# Add textsupermemory add "User prefers TypeScript over JavaScript"
# Add a file (PDF, markdown, text, etc.)supermemory add ./meeting-notes.pdf --tag meetings
# Add a URLsupermemory add https://docs.example.com/api --tag docs
# Read from stdincat file.txt | supermemory add --stdinecho "some content" | supermemory add --stdin --tag notes
# With metadatasupermemory add "Design doc v2" --metadata '{"category": "engineering", "priority": "high"}'
# Custom document IDsupermemory 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 searchsupermemory search "authentication patterns"
# Scoped to a tag with limitsupermemory search "auth" --tag api --limit 5
# With reranking for better relevancesupermemory search "database migrations" --rerank
# Query rewriting (LLM rewrites query for better results)supermemory search "how do we handle auth" --rewrite
# Different search modessupermemory search "user prefs" --mode memories    # extracted memories onlysupermemory search "user prefs" --mode hybrid      # memories + document chunkssupermemory search "user prefs" --mode documents   # full documents only
# Include specific fieldssupermemory search "api design" --include summary,chunks,memories
# Metadata filteringsupermemory search "design" --filter '{"AND": [{"key": "category", "value": "engineering"}]}'
# Similarity threshold (0-1)supermemory search "preferences" --threshold 0.5

# Basic searchsupermemory search "authentication patterns"
# Scoped to a tag with limitsupermemory search "auth" --tag api --limit 5
# With reranking for better relevancesupermemory search "database migrations" --rerank
# Query rewriting (LLM rewrites query for better results)supermemory search "how do we handle auth" --rewrite
# Different search modessupermemory search "user prefs" --mode memories    # extracted memories onlysupermemory search "user prefs" --mode hybrid      # memories + document chunkssupermemory search "user prefs" --mode documents   # full documents only
# Include specific fieldssupermemory search "api design" --include summary,chunks,memories
# Metadata filteringsupermemory 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 memorysupermemory 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 metadatasupermemory remember "Discussed Q3 roadmap" --tag meetings --metadata '{"type": "decision"}'

# Store a memorysupermemory 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 metadatasupermemory 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 IDsupermemory forget mem_abc123 --tag default
# Forget by content matchsupermemory forget --content "outdated preference" --tag default
# With reasonsupermemory forget mem_abc123 --reason "User corrected this information"

# Forget by memory IDsupermemory forget mem_abc123 --tag default
# Forget by content matchsupermemory forget --content "outdated preference" --tag default
# With reasonsupermemory 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}'

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 tagsupermemory profile
# Get profile for specific tagsupermemory profile user_123
# Search within the profilesupermemory profile user_123 --query "programming preferences"

# Get profile for default tagsupermemory profile
# Get profile for specific tagsupermemory profile user_123
# Search within the profilesupermemory profile user_123 --query "programming preferences"

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

Document Management

`docs` — Manage documents

bash

# List documentssupermemory docs list --tag default --limit 20
# Get a specific documentsupermemory docs get doc_abc123
# Check processing statussupermemory docs status doc_abc123
# View document chunkssupermemory docs chunks doc_abc123
# Delete a documentsupermemory docs delete doc_abc123 --yes

# List documentssupermemory docs list --tag default --limit 20
# Get a specific documentsupermemory docs get doc_abc123
# Check processing statussupermemory docs status doc_abc123
# View document chunkssupermemory docs chunks doc_abc123
# Delete a documentsupermemory 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 tagssupermemory tags list
# Get tag info (memory count, doc count, etc.)supermemory tags info user_123
# Create a new tagsupermemory 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 contextsupermemory 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 tagsupermemory tags delete old-tag --yes

# List all tagssupermemory tags list
# Get tag info (memory count, doc count, etc.)supermemory tags info user_123
# Create a new tagsupermemory 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 contextsupermemory 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 tagsupermemory tags delete old-tag --yes

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

API Keys

`keys` — Manage API keys

bash

# List all keyssupermemory keys list
# Create a new keysupermemory 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 keysupermemory keys revoke key_abc123 --yes
# Toggle a key on/offsupermemory keys toggle key_abc123

# List all keyssupermemory keys list
# Create a new keysupermemory 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 keysupermemory keys revoke key_abc123 --yes
# Toggle a key on/offsupermemory 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 servicessupermemory connectors list
# Connect a service (opens OAuth flow)supermemory connectors connect google-drive --tag docssupermemory connectors connect notion --tag notes
# Trigger a syncsupermemory connectors sync conn_abc123
# View sync historysupermemory connectors history conn_abc123 --limit 10
# List synced resourcessupermemory connectors resources conn_abc123
# Disconnectsupermemory connectors disconnect conn_abc123 --yes

# List connected servicessupermemory connectors list
# Connect a service (opens OAuth flow)supermemory connectors connect google-drive --tag docssupermemory connectors connect notion --tag notes
# Trigger a syncsupermemory connectors sync conn_abc123
# View sync historysupermemory connectors history conn_abc123 --limit 10
# List synced resourcessupermemory connectors resources conn_abc123
# Disconnectsupermemory 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 pluginssupermemory plugins list
# Connect a plugin (with auto-configuration)supermemory plugins connect claude-code --auto-configuresupermemory plugins connect cursor --auto-configure
# Check plugin statussupermemory plugins status claude-code
# Revoke a plugin connectionsupermemory plugins revoke claude-code --yes

# List available pluginssupermemory plugins list
# Connect a plugin (with auto-configuration)supermemory plugins connect claude-code --auto-configuresupermemory plugins connect cursor --auto-configure
# Check plugin statussupermemory plugins status claude-code
# Revoke a plugin connectionsupermemory plugins revoke claude-code --yes

Subcommands: list, connect, revoke, status

Team Management

`team` — Manage team members

bash

# List team memberssupermemory team list
# Invite a membersupermemory team invite [email protected] --role adminsupermemory team invite [email protected] --role member
# Change a member's rolesupermemory team role member_123 admin
# Remove a membersupermemory team remove member_123 --yes
# View pending invitationssupermemory team invitations

# List team memberssupermemory team list
# Invite a membersupermemory team invite [email protected] --role adminsupermemory team invite [email protected] --role member
# Change a member's rolesupermemory team role member_123 admin
# Remove a membersupermemory team remove member_123 --yes
# View pending invitationssupermemory team invitations

Subcommands: list, invite, remove, role, invitations

Monitoring

`status` — Account dashboard

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

`logs` — Request logs

bash

# Recent logssupermemory logs
# Filter by time periodsupermemory logs --period 7d
# Filter by statussupermemory logs --status error
# Filter by request typesupermemory logs --type search
# Get a specific log entrysupermemory logs get req_abc123

# Recent logssupermemory logs
# Filter by time periodsupermemory logs --period 7d
# Filter by statussupermemory logs --status error
# Filter by request typesupermemory logs --type search
# Get a specific log entrysupermemory logs get req_abc123

`billing` — Usage and billing

bash

supermemory billing          # Overviewsupermemory billing usage    # Detailed usage breakdownsupermemory billing invoices # Past invoices

supermemory billing          # Overviewsupermemory billing usage    # Detailed usage breakdownsupermemory billing invoices # Past invoices

Utility Commands

bash

# Open Supermemory console in browsersupermemory opensupermemory open graph       # Memory graph viewsupermemory open billingsupermemory open settingssupermemory open docssupermemory open keys
# Machine-readable help (useful for LLM agents)supermemory help --jsonsupermemory help --all
# Per-command helpsupermemory search --helpsupermemory tags --help --json

# Open Supermemory console in browsersupermemory opensupermemory open graph       # Memory graph viewsupermemory open billingsupermemory open settingssupermemory open docssupermemory open keys
# Machine-readable help (useful for LLM agents)supermemory help --jsonsupermemory help --all
# Per-command helpsupermemory search --helpsupermemory 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 loggit log --oneline -20 | supermemory add --stdin --tag git-history
# Ingest command outputcurl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs
# Pipe search results to jqsupermemory search "auth" --json | jq '.results[].memory'

# Ingest git loggit log --oneline -20 | supermemory add --stdin --tag git-history
# Ingest command outputcurl -s https://api.example.com/docs | supermemory add --stdin --tag api-docs
# Pipe search results to jqsupermemory search "auth" --json | jq '.results[].memory'

Scripting with JSON output

bash

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

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

CI/CD integration

bash

# Use env var for authexport SUPERMEMORY_API_KEY=sm_abc_xxx
# Ingest docs on deploysupermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest
# Check statussupermemory status --json | jq '.memoryCount'

# Use env var for authexport SUPERMEMORY_API_KEY=sm_abc_xxx
# Ingest docs on deploysupermemory add ./docs/api-reference.md --tag api-docs --id api-ref-latest
# Check statussupermemory status --json | jq '.memoryCount'

Source and attribution

Source:supermemoryai/skillsinsupermemory-cliat commit10d5e16

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

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

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

Supermemory Cli

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

Source and attribution

More from supermemoryai/skills

Svg Animations

More in Productivity & Workflow

Dd Meeting Prep

Dd Checklist

Deal Tracker

Client Review

Morning Note

Notion Spec To Implementation

`add` — Ingest content

`search` — Search memories

`remember` — Store a memory directly

`forget` — Delete a memory

`update` — Update an existing memory

`profile` — Get user profile

`docs` — Manage documents

`tags` — Manage container tags

`keys` — Manage API keys

`connectors` — External data sources

`plugins` — IDE and tool integrations

`team` — Manage team members

`status` — Account dashboard

`logs` — Request logs

`billing` — Usage and billing