HyperMemory CLI

Persistent memory graph for AI agents — store, recall, and connect knowledge across conversations.

HyperMemory gives AI assistants (Claude, Cursor, ChatGPT, custom agents) a long-term memory layer. The hm CLI is the primary interface for reading and writing to that memory, both for humans and for AI agents running shell commands.

Installation

pip install hypermemory-cli

Requires Python 3.10+ (tested on 3.10–3.14).

Quick Start

# Authenticate (opens your browser) — or: hm login --api-key
hm login

# Store a fact
hm store person_alice "Alice, senior backend engineer at Acme" --type person

# Store a decision
hm store decision_jwt "We chose JWT over session cookies for auth" --type decision

# Connect them — describe WHY
hm relate --from person_alice --to decision_jwt --rel "Alice drove the JWT decision based on her scaling experience"

# Search by natural language
hm recall "authentication decisions"

# Traverse the graph
hm find person_alice --depth 2

# Check what you have
hm overview

Authentication

Browser login (recommended):

hm login

Opens your browser for OAuth 2.1 + PKCE login. A temporary server on 127.0.0.1 receives the callback; tokens refresh automatically.

API key (headless machines, CI, agents):

hm login --api-key hm_YOUR_API_KEY      # or
echo "$HM_KEY" | hm login --api-key     # read from stdin, keeps the key out of shell history
hm login --api-key                      # hidden prompt

The key is checked with an authenticated request before it is saved; a rejected key is never stored. Generate API keys at app.hypermemory.io/api-keys.

Environment variables (override anything stored):

export HYPERMEMORY_API_KEY=hm_YOUR_KEY
export HYPERMEMORY_API_URL=https://api.hypermemory.io   # optional
hm recall "recent decisions"

Where credentials are stored: in the OS keyring (macOS Keychain, Windows Credential Locker, Secret Service on Linux) when one is available. Otherwise — or with HYPERMEMORY_NO_KEYRING=1 — they go to ~/.config/hypermemory/config.json with mode 0600. Config files written by earlier releases keep working; their secrets move to the keyring the next time the CLI saves credentials (login or token refresh). hm config shows which store is in use.

Commands

Memory Operations

Options that take JSON (--data, --rels, --meta, the hm_tokens report) also accept @path/to/file.json.

Spreadsheets and CSV (hm tabular)

hm tabular outline FILE_ID [--no-regions] [--max-sheets N]            # workbook → sheets → regions
hm tabular range FILE_ID --sheet S --range A1:D20 [--max-cells N]     # cells of an exact range
hm tabular search FILE_ID "revenue" [--sheet S] [--limit N]           # regions, headers, labels, values
hm tabular trace FILE_ID --sheet S --cell F12 [--direction precedents|dependents] [--max-depth N] [--max-nodes N]

FILE_ID is the file_id reported by hm upload / hm files.

Export

The server builds exports in the background. hm export starts one, polls it until it is published, downloads the document, and verifies its size and SHA-256:

hm export -o memory-backup.json          # summary JSON on stdout, document in the file
hm export | jq '.nodes | length'         # document on stdout
hm export --no-wait                      # print {export_id, status, status_url} and exit
hm export --export-id EXPORT_ID -o b.json  # resume / download an export started earlier

A failed or expired export, or one still running after --timeout seconds (default 600), exits with code 10.

Auth & Config

Node Types

Every node requires a --type:

Relationships

Describe connections in plain language with --rel. Be specific about why the connection exists:

# BAD — bare verb, no context
hm relate --from component_api --to tech_redis --rel depends_on

# GOOD — explains why the connection exists
hm relate --from component_api --to tech_redis --rel "API depends on Redis for session caching and rate limiting"
hm relate --from person_alice --to decision_jwt --rel "Alice chose JWT because it supports stateless scaling"
hm relate --from project_app --to tech_sveltekit --rel "frontend built with SvelteKit for SSR and progressive enhancement"

The server automatically summarizes long labels into shorter searchable versions.

Key Format

Use descriptive, namespaced keys: {type}_{name}

person_alice          decision_jwt_auth       component_redis
pref_dark_mode        event_2025_launch       org_acme

AI Agent Integration

HyperMemory is designed to be used by AI agents as a persistent memory layer. The typical agent workflow:

1. Start of conversation: hm overview + hm recall "relevant keywords" to load context
2. When meaningful info appears: hm recall first to check for duplicates, then hm store new facts, decisions, or preferences
3. As needed: hm update to correct information, hm forget to remove outdated info
4. Always: run with --json and branch on the exit code (see below)

The server automatically enriches stored nodes with structured data, edges, and hyperedges — agents just provide the key, description, and type.

Agents can retrieve current skill instructions directly:

hm skill list
hm skill get --variant general --raw
hm skill get --variant software-development --output hypermemory-skill.md
hm skill get --name my-team-skill --raw          # one of your published agent skills
hm skill check --variant general --current-version 0.7.1

Built-in variants: general, openai, software-development, marketing, legal, cursor, cli, project, audit, and memorize-full-chat.

Claude Code and Codex (hm setup)

hm setup wires HyperMemory into Claude Code and Codex with the hm CLI as the only memory interface (no MCP server):

hm setup claude                    # user scope: ~/.claude (or $CLAUDE_CONFIG_DIR)
hm setup codex --scope project     # this git repository: .codex/, .agents/skills/, AGENTS.md
hm setup all --dry-run             # show the planned changes
hm doctor                          # verify auth, the API, the skill and every install (--json for machines)
hm uninstall claude                # remove exactly what setup wrote

It installs SessionStart, UserPromptSubmit and Stop hooks (through a small shell shim), the hypermemory-cli skill, a marked block in CLAUDE.md / AGENTS.md and, for Claude Code, a hypermemory-memory-writer agent. The prompt hook runs a recall with your prompt and injects the results; the Stop hook asks Claude Code to dispatch the memory writer and Codex to run hm timeline-write and hm hm_tokens, blocking a turn at most twice. With an OAuth login the hooks refresh an expired access token once, like every other command. Every write is recorded in ~/.config/hypermemory/setup-manifest.json; other hooks and settings are never touched.

The skill ships inside this package and matches the commands of this release. When the server publishes a newer cli skill version, hm setup and hm doctor cache and install that instead.

Output, --json, and Exit Codes

By default, data commands print the server's JSON answer pretty-printed on stdout (syntax-highlighted on a terminal, indented when piped) and write errors and progress as readable text on stderr.

For agents and scripts, add --json anywhere on the command line (hm --json recall q or hm recall q --json):

• stdout: the server's JSON answer, unchanged, as one line;
• stderr: errors as one JSON object, e.g. {"error":"not_found","detail":"node not found: k","exit_code":5,"status":404,"retryable":false,"request_id":"..."};
• no progress messages or spinners.

hm --json overview | jq '.nodes'
hm --json recall "decisions" | jq '.results[].key'
hm --json nodes fact_a fact_b | jq '.nodes.fact_a.node'
hm --json relationships component_redis | jq '.binary_edges[].relationship'
hm export > memory-backup-$(date +%F).json

Exit codes are stable:

Configuration

Settings live in ~/.config/hypermemory/config.json (mode 0600); secrets live in the OS keyring when one is available (see Authentication). Priority:

1. $HYPERMEMORY_API_KEY / $HYPERMEMORY_API_URL environment variables
2. Stored API key, then stored OAuth tokens
3. Defaults (API URL https://api.hypermemory.io)

HYPERMEMORY_NO_KEYRING=1 stores secrets in the config file instead of the keyring.

Links

• Web app: app.hypermemory.io
• Integration guide and agent skills: app.hypermemory.io/integration
• API endpoint: https://api.hypermemory.io
• Claude Connector: Add https://api.hypermemory.io/mcp as an MCP server in Claude Desktop

License

MIT