supermemory-cli

CLI 内置于 supermemory npm 包中，并调用 v5 API。每条内容命令都在一个命名空间中运行：用户 ID、项目 ID，或任何你想要隔离的边界。

安装和身份验证

# Run without installing
npx supermemory --version

# Or install globally
npm i -g supermemory

# Browser login, stores credentials in ~/.supermemory/credentials.json
supermemory login

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

# Show who you are, the key prefix and whether the key is scoped
supermemory whoami

supermemory logout

调用 API 的命令需要先登录，或设置 SUPERMEMORY_API_KEY。help、local 和 plugin 命令不需要。

配置

有三个作用域。init 会写入配置，config set 会编辑配置。

作用域	文件	内容
project	~/.supermemory/projects/<encoded-cwd>/config.json（每台机器独有，不会进入 git）	namespace、可选的 apiKey
team	<git root>/.supermemory/config.json（提交此文件）	namespace
global	~/.supermemory/config.json	output、apiUrl、consoleUrl、telemetry

命名空间解析顺序：--namespace 标志、SUPERMEMORY_NAMESPACE、团队配置、项目配置。如果这些都没有，内容命令会停止并显示“需要指定命名空间”。

# Interactive wizard
supermemory init

# Non-interactive
supermemory init --scope project --namespace meetings-bot
supermemory init --scope team --namespace my-project
supermemory init --scope global --output json

# Show resolved config and where each value came from
supermemory config

# Set a value; keys: apiKey, namespace, output, apiUrl, consoleUrl, telemetry
supermemory config set namespace my-project --scope project
supermemory config set output json --scope global
supermemory config set telemetry off --scope global

# Read one resolved value; keys: apiKey, namespace, apiUrl, consoleUrl, output
supermemory config get namespace

环境变量

变量	作用
SUPERMEMORY_API_KEY	API 密钥。会覆盖已存储的凭据；如果两者不同，会打印警告。
SUPERMEMORY_NAMESPACE	默认命名空间。此前名为 SUPERMEMORY_TAG。
SUPERMEMORY_API_URL	API 基础 URL，用于可自托管的服务。
SUPERMEMORY_CONSOLE_URL	open 和登录使用的控制台 URL。
DO_NOT_TRACK=1	禁用匿名使用情况遥测（命令名称、结果、版本、操作系统；绝不包含内容或密钥）。
OTEL_EXPORTER_OTLP_ENDPOINT	将 CLI 跟踪信息导出到 OpenTelemetry 收集器。

全局标志

标志	作用
--namespace <name>	覆盖此命令使用的命名空间
--json	强制使用 JSON 输出
--help	查看任意命令的帮助；--help --json 会提供机器可读的架构

当标准输出不是终端时，会自动使用 JSON 输出，因此管道和 Agent 无需添加 --json 也能获取 JSON。supermemory config set output human --scope global 会强制使用文本输出。

核心命令

add

将文本、文件或 URL 导入命名空间。参数会自动识别：http:// 或 https:// 开头的是 URL；已存在的路径会作为文件上传；其他内容均视为文本。

supermemory add "User prefers TypeScript over JavaScript"
supermemory add ./meeting-notes.pdf --namespace meetings
supermemory add https://docs.example.com/api --namespace docs

# From stdin
cat notes.txt | supermemory add --stdin --namespace notes

# Metadata and a stable id; repeating the id updates the same document
supermemory add "Design doc v2" --metadata '{"category":"engineering"}' --id design-doc

# Memories ready right away instead of batched in the background
supermemory add "Alex moved to Berlin" --dreaming instant

# Index for retrieval only, no memory extraction
supermemory add ./handbook.md --task-type superrag

# Batch: JSON array on stdin, items {content, id?, metadata?, namespace?}
echo '[{"content":"first","id":"d1"},{"content":"second"}]' | supermemory add --batch

标志：--namespace、--stdin、--metadata <json>、--id <string>、--dreaming dynamic|instant（默认值为 dynamic）、--task-type memory|superrag（默认值为 memory）、--batch。

命令返回后，处理仍会继续。使用 docs status <id> 查看状态。

search

supermemory search "authentication patterns"
supermemory search "auth" --namespace api --limit 5 --rerank order
supermemory search "how do we handle auth" --rewrite

# Modes: hybrid (default, memories + chunks), memories, chunks
supermemory search "user prefs" --mode memories
supermemory search "refund policy" --mode chunks --include documents

# Typed filter
supermemory search "design" --filter '{"field":"category","operator":"eq","value":"engineering"}'
supermemory search "design" --filter '{"operator":"and","operands":[{"field":"source","operator":"eq","value":"slack"},{"field":"priority","operator":"gte","value":3}]}'

supermemory search "preferences" --threshold 0.5

标志：--namespace、--limit（默认值为 10）、--threshold 0 到 1（默认值为 0.3）、--rerank none|order|aggregate（默认值为 none）、--rewrite、--mode hybrid|memories|chunks（默认值为 hybrid）、--include documents,related,forgotten、--filter <json>。

profile

命名空间的维护型档案：static 事实、dynamic 近期上下文和命名的 buckets。不接受查询参数；要获取排序结果，请使用 search。

supermemory profile
supermemory profile --namespace user_alex

# Build the profile from matching memories only
supermemory profile --filter '{"field":"region","operator":"eq","value":"us-west"}'

forget

# By memory id, comma-separated for several
supermemory forget mem_abc123 --namespace user_alex
supermemory forget mem_1,mem_2

# By meaning: preview first, then run without --dry-run
supermemory forget --query "old office address" --dry-run
supermemory forget --query "old office address"

标志：--namespace、--query <text>、--dry-run。没有 --reason，也不能直接写入记忆；记忆来自文档，因此要更改记忆，请修改源文档。

文档

supermemory docs list --namespace default --limit 20 --page 2
supermemory docs get doc_abc123
supermemory docs status doc_abc123        # pipeline stage: queued, extracting, chunking, embedding, indexing, done, failed
supermemory docs chunks doc_abc123
supermemory docs delete doc_abc123 --yes  # comma-separated ids for several

子命令：list、get、delete、chunks、status。标志：--namespace、--limit（默认值为 20）、--page、--yes。

命名空间

此前名为 tags。首次使用某个名称添加内容时，会创建对应的命名空间；没有 create 子命令。

supermemory namespaces list
supermemory namespaces info user_alex

# Supporting context guides memory extraction in this namespace
supermemory namespaces context user_alex --set "Paying customer on the Pro plan"
supermemory namespaces context user_alex --clear

# Delete, or move everything into another namespace first (replaces tags merge)
supermemory namespaces delete old-project --yes
supermemory namespaces delete old-project --move-to new-project --yes

子命令：list、info、delete、context。标志：--set <text>、--clear、--move-to <namespace>、--yes。

连接器

提供方：google-drive、notion、onedrive、gmail、github、web-crawler、s3、granola。OAuth 提供方会打开浏览器；web-crawler 和 s3 接受 --config 并立即开始同步。

supermemory connectors list
supermemory connectors list --namespace docs

supermemory connectors connect google-drive --namespace docs
supermemory connectors connect notion --namespace notes --no-browser
supermemory connectors connect web-crawler --namespace docs --config '{"startUrl":"https://docs.example.com"}'
supermemory connectors connect github --namespace code --document-limit 500

supermemory connectors sync conn_abc123
supermemory connectors history conn_abc123
supermemory connectors picker conn_abc123        # choose what the connector syncs
supermemory connectors disconnect conn_abc123 --delete-documents --yes

子命令：list、connect、sync、history、picker、disconnect。标志：--namespace、--document-limit <n>、--config <json>、--no-browser、--delete-documents、--yes。

API 密钥

supermemory keys list
supermemory keys create --name my-agent --permission write

# Scoped key: one or more namespaces, expires in 30 days
supermemory keys create --name bot-key --permission read --namespace user_123 --expires 30

supermemory keys revoke key_abc123 --yes
supermemory keys toggle key_abc123

子命令：list、create、revoke、toggle。标志：--name（创建时必填）、--permission read|write（默认值为 write）、--namespace <a,b>、--expires <days>、--yes。

限定范围的密钥

使用限定到某个命名空间的密钥时，只能使用 search、add、forget、profile 和 whoami，且命名空间由密钥设置。help 只显示这些命令。

团队

supermemory team list
supermemory team invite [email protected] --role admin
supermemory team role member_123 admin
supermemory team remove member_123 --yes
supermemory team invitations

子命令：list、invite、remove、role、invitations。标志：--role admin|member（默认值为 member）、--yes。

状态、日志、账单

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

supermemory logs                          # last 24h
supermemory logs --period 7d --status error --type search --limit 50 --page 2
supermemory logs get req_abc123

supermemory billing                        # plan and usage summary
supermemory billing usage
supermemory billing invoices

编码 Agent 插件

plugin 会将 Supermemory 集成安装到此计算机上的编码 Agent，并通过浏览器 OAuth 将它们连接起来。plugins 则从控制台管理基于 API 密钥的连接。

# Detect installed agents and pick interactively
supermemory plugin

# Non-interactive, targets: claude, cursor, opencode, codex
supermemory plugin --all
supermemory plugin --only claude,cursor --dry-run
supermemory plugin --all --no-auth                # install only, connect later
supermemory plugin --only codex --force           # run even if the app is not detected

supermemory plugin login --all
supermemory plugin login --only codex --no-browser
supermemory plugin uninstall --only cursor --dry-run
supermemory plugin uninstall --all

plugin 标志：--all、--only <list>、--dry-run、--force、--no-auth。plugin login：--all、--only、--no-browser。plugin uninstall：--all、--only、--dry-run。

# Key-based plugin connections; ids: claude-code, cursor, opencode, openclaw
supermemory plugins list
supermemory plugins connect claude-code --auto-configure
supermemory plugins status
supermemory plugins revoke claude-code --yes

setup 和 migrate

两者都会检测项目、构建提示词，并启动编码 Agent 来处理提示词。Agent：claude-code、codex、cline、aider、opencode、goose、amp。

# Integrate Supermemory into this project
supermemory setup
supermemory setup --prompt                 # print the prompt instead

# Move this project from the v3/v4 API to v5
supermemory migrate
supermemory migrate --agent codex
supermemory migrate --prompt

migrate 会扫描旧版包和名称（containerTag、customId、/v3/、/v4/），若无内容需要迁移，则会提前退出。

本地可自托管服务

在 macOS 或 Linux 上安装并运行免费的单二进制文件 supermemory-server。目前尚不支持 Windows；请从 GitHub Releases 下载 .exe，或改用 Docker。

supermemory local                          # same as local start
supermemory local install
supermemory local install --version 0.0.9
supermemory local start --port 9000
supermemory local start --no-install
supermemory local start -- --log-level debug   # args after -- go to the server
supermemory local upgrade
supermemory local status
supermemory local status --url http://localhost:9000
supermemory local version
supermemory local path
supermemory local env

子命令：start、install、upgrade、status、version、path、env。使用 SUPERMEMORY_API_URL=http://localhost:6767 将 CLI 指向该服务。

open 和 help

supermemory open                           # console
supermemory open graph                     # pages: console, billing, graph, connectors, settings, docs, keys, team, agents
supermemory open billing --no-browser      # print the URL

supermemory help
supermemory help --json                    # full command schema for agents
supermemory search --help --json

脚本编写

export SUPERMEMORY_API_KEY=sm_xxx
export SUPERMEMORY_NAMESPACE=api-docs

# Pipes are JSON by default
git log --oneline -20 | supermemory add --stdin --id git-history
supermemory search "auth" | jq '.results[] | .memory // .chunk'
supermemory profile | jq '.profile.static[].memory'

# Ingest on deploy with a stable id so the doc updates in place
supermemory add ./docs/api-reference.md --id api-ref-latest

# Wait for processing
until supermemory docs status "$ID" | jq -e '.status == "done"' >/dev/null; do sleep 2; done

退出代码

代码	含义
0	成功
1	错误，包括验证错误和 API 错误
2	需要身份验证
3	权限不足
4	未找到

错误会以 ✗ message 的形式输出到 stderr；若有后续步骤，还会显示一行 hint:，以确保 stdout 输出干净的 JSON。

自 1.x 起重命名或移除的内容

之前	现在
npm i -g @supermemory/cli	npm i -g supermemory 或 npx supermemory
--tag、SUPERMEMORY_TAG	--namespace、SUPERMEMORY_NAMESPACE
`tags list	info
tags create	使用新命名空间添加内容
tags merge a --into b	namespaces delete a --move-to b
remember、update	已移除；请添加或更新源文档
forget --content、--reason	使用带 --dry-run 的 forget --query；不再有原因字段
search --mode documents、--rerank（布尔值）	--mode chunks、`--rerank order
search --filter '{"AND":[{"key":..}]}'	类型化筛选器 {"operator":"and","operands":[{"field":..,"operator":"eq","value":..}]}
profile <namespace> --query	profile --namespace <name>；查询请使用 search
connectors resources	connectors picker