CLI

hm (hypermemory-cli) is HyperMemory’s command-line tool. It does three jobs:

• Sets up your agents — Claude Code, Codex, Hermes Agent, Kimi Code and OpenClaw — with the HyperMemory skill, hooks and memory-writer, in one command.
• Reads and writes memory from scripts and shells, with every MCP tool available as a command.
• Gives agents a shell interface to memory, with machine-readable --json output and stable exit codes.

Install

Requires Python 3.10 or newer.

pipx install hypermemory-cli

Check it with hm version.

Sign in

hm login

hm login --api-key

export HYPERMEMORY_API_KEY=hm_...

Credentials are stored in your operating system’s keyring (service hypermemory-cli). Without a keyring — or with HYPERMEMORY_NO_KEYRING=1 — they go in ~/.config/hypermemory/config.json with 0600 permissions.

hm logout clears OAuth tokens and keeps any stored API key; hm config --clear-key removes the key.

Set up your agents

hm setup installs the HyperMemory protocol into the agents on your machine: the skill, the hooks that make the agent recall and save every turn, and the memory-writer.

hm setup all                    # every supported agent it finds
hm setup claude hermes kimi     # only these
hm setup codex --scope project  # this project only, not your whole user
hm setup all --dry-run          # show what would change

Options: --scope user|project (default user), --dry-run, --no-hooks (install the skill without hooks).

hm doctor              # check every installed agent and your connection
hm uninstall kimi      # remove HyperMemory from one agent
hm uninstall all       # remove it everywhere

Organizations

If you belong to several organizations, bind each project to one so recall includes the right organization’s memory:

hm org list            # your organizations
hm org use org_8c1f…   # bind this project (git work tree, else directory)
hm org use none        # personal memory only for this project
hm org show            # the current binding
hm org clear           # remove the binding

Bindings are stored in ~/.config/hypermemory/projects.json and shared with the plugins. Override one call with hm recall "query" --org ID|none.

Memory commands

Every MCP tool has a command.

Any option that takes JSON also accepts @path/to/file.json.

Output for scripts and agents

Add --json anywhere on the command line. Standard output is then the server’s JSON on one line, and errors go to standard error as JSON with error, detail, exit_code, status, retryable and request_id.

hm --json overview | jq '.type_counts'
hm --json recall "decisions about auth" | jq -r '.results[].key'
hm export -o "backup-$(date +%F).json"

Exit codes

Configuration

Credentials are resolved in this order: environment variable, stored API key, stored OAuth token.

hm health checks that the API is reachable; hm ready also checks its dependencies (exit code 8 when not ready).