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+.

Quick Start

# Authenticate (opens browser → GitHub OAuth)
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 GitHub-based OAuth. Tokens are saved to ~/.config/hypermemory/config.json and refresh automatically.

API key:

hm config --set-key hm_YOUR_API_KEY

Generate API keys at app.hypermemory.io/api-keys.

Environment variable:

export HYPERMEMORY_API_KEY=hm_YOUR_KEY
hm recall "recent decisions"

Commands

Memory Operations

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

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 check --variant general --current-version 0.5.4

Available variants: general, openai, software-development, marketing, legal, cursor, cli, and project.

Pipe-Friendly Output

All data commands output JSON to stdout. Errors go to stderr. This makes hm composable with jq, scripts, and other tools:

# Count total nodes
hm overview | jq '.total_nodes'

# Get all decision keys
hm recall "decisions" | jq '.nodes[] | select(.node_type == "decision") | .key'

# Hydrate known keys with full details
hm nodes fact_a fact_b | jq '.nodes.fact_a.node'

# Export and filter
hm export | jq '.nodes | length'

# Backup
hm export > memory-backup-$(date +%F).json

Configuration

Config is stored at ~/.config/hypermemory/config.json. Auth priority:

1. $HYPERMEMORY_API_KEY environment variable
2. Config file (API key or OAuth tokens)
3. Defaults (API URL only)

Links

• Web app: app.hypermemory.io
• API endpoint: https://api.hypermemory.io
• Claude Connector: Add https://api.hypermemory.io/mcp as an MCP server in Claude Desktop

License

MIT