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

Command	Description
hm store KEY "desc" --type TYPE	Create a new memory node
hm recall "query"	Search memory by natural language or keywords
hm nodes KEY...	Fetch full details for known exact node keys
hm update KEY --desc "new info"	Update an existing node
hm forget KEY [--cascade]	Delete a node (and optionally its edges)
hm relate --from A --to B --rel R	Create a relationship between nodes
hm find KEY [--depth N]	Traverse the graph from a starting node
hm relationships KEY	List all edges connected to a node
hm ingest "text" [--context "label"]	Auto-extract nodes from free-form text
hm hm_tokens '{"provider":"openai",...}'	Submit a canonical token-usage report
hm overview	Show graph stats and top nodes
hm export [--no-ontology]	Export the full graph as JSON
hm skill list	List current HyperMemory agent skills
hm skill get --variant general	Retrieve the latest skill instructions
hm skill check --current-version X	Check whether a skill update is available

Auth & Config

Command	Description
hm login	Authenticate via browser (OAuth 2.1 + PKCE)
hm logout	Clear saved tokens
hm config	Show current configuration
hm config --set-key KEY	Save an API key
hm config --set-url URL	Override the API endpoint
hm health	Check server connectivity
hm version	Print CLI version

Node Types

Every node requires a --type:

Type	Use for
user	The primary user (singleton user_profile node)
person	People — teammates, contacts, users
organization	Companies, teams, departments
component	Software components, services, libraries
event	Meetings, launches, incidents
decision	Architecture choices, policy decisions
concept	Ideas, patterns, abstract topics
artifact	Documents, repos, configs, files
project	Projects, initiatives, products
technology	Languages, frameworks, tools, platforms
preference	User preferences and settings
fact	Verified facts, data points, measurements
skill	Skills, expertise, capabilities

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