supermemory-cli

What this skill does

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 sy