Forked from shaoyanji/supermemory-cli

Give your AI agents (Claude Code, Codex, Gemini CLI, etc.) persistent memory across sessions — powered by the Supermemory API.

Designed for speed, token efficiency, and universal compatibility across all AI Agent environments.

If you are an AI Agent reading this, STOP and communicate with the user before proceeding.

1. Pre-flight Check: Run command -v sm in the background to check if a command named sm already exists in the user's environment.
2. Inform the user that you need to install the sm CLI tool and its required skill file. If the pre-flight check found an existing sm command, explicitly warn the user about a potential naming conflict and suggest they might need to set up an alias (e.g., alias supermem="sm").
3. Ask the user to provide their Supermemory API key. Optionally, ask if they want to set a default container tag (if omitted, it uses the platform's default container).
4. Wait for the user's confirmation.

If the user provides the details and confirms, execute the following commands automatically:

# 1. Install the binary
curl -sSL https://raw.githubusercontent.com/franksde/supermemory-cli/main/install.sh | bash

# 2. Configure the API key
sm config set-key <api-key-from-user>

# (Optional) Set a default container tag if the user provided one
sm config set-tag <container-tag-from-user>

# 3. Download the universal SKILL.md to the active workspace or skills directory
curl -sSL https://raw.githubusercontent.com/franksde/supermemory-cli/main/skills/SKILL.md -o supermemory_skill.md

If the user prefers to do it manually, instruct them to run the commands above themselves.

When integrating persistent memory into autonomous workflows, you need a tool that is:

1. Extremely Fast (vs MCP): Zero startup time, direct Go binary execution. Much faster than connecting to and maintaining an MCP server.
2. Token Efficient (vs MCP): MCP protocols often require heavy JSON-RPC payloads and complex schemas. sm uses minimal JSON-only output tailored specifically for LLM context windows, saving precious tokens on every read/write.
3. Explicit Control: The agent explicitly decides what to store and when to recall, keeping context windows clean instead of auto-capturing everything.
4. Universal: Works with any agent that can execute shell commands.

curl -sSL https://raw.githubusercontent.com/franksde/supermemory-cli/main/install.sh | bash

Or build from source:

git clone https://github.com/franksde/supermemory-cli.git
cd supermemory-cli
go build -o sm .
sudo mv sm /usr/local/bin/

# Get your API key from https://console.supermemory.ai/keys
sm config set-key sm_xxxxx

# Set a default container tag (scopes your memories)
sm config set-tag my-project

Or use environment variables:

export SUPERMEMORY_API_KEY="sm_xxxxx"
export SUPERMEMORY_API_BASE="https://api.supermemory.ai"  # optional

sm add "This project uses Go with Cobra for CLI"
sm add "Frank prefers minimal comments in code"
sm search "project stack"
sm list

• --containerTag — Override the default container tag for any command
• --help — Help for any command

Config file: ~/.config/sm/config.json

{
  "api_key": "sm_xxxxx",
  "base_url": "https://api.supermemory.ai",
  "default_container_tag": "my-project",
  "default_limit": 3,
  "score_threshold": 0.0,
  "max_content_length": 800,
  "api_timeout": 5,
  "default_v4": true
}

Priority: environment variables > config file > defaults.

Also reads legacy config from ~/.config/supermemory/config.json for backward compatibility.

sm provides a universal SKILL.md file located at skills/SKILL.md.

This single skill file works for any agent (Claude Code, Codex, Gemini, etc.). It teaches the agent when to store memories, how to search for context at the start of a session, and how to manage the API.

Just provide the skills/SKILL.md to your agent, ensure sm is in the PATH, and the agent will handle the rest. All commands output JSON and use standard exit codes for machine consumption.

MIT — see LICENSE.