hypermemory-cli 1.0.0

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

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
hm relate --from person_alice --to decision_jwt --rel responsible_for

# 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 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 overview	Show graph stats and top nodes
hm export [--no-ontology]	Export the full graph as JSON

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
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, preferences, patterns
artifact	Documents, repos, configs, files

Relationships

Common relationship names for --rel:

knows          works_at        part_of         depends_on
responsible_for decided_at     motivated_by    implements
produced       scoped_by       mentions

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. Every message: hm store new facts, decisions, or preferences before responding
3. As needed: hm update to correct information, hm relate to build the graph, hm forget to remove outdated info

Download the agent skill file from app.hypermemory.io/integration for automatic integration with Claude, Cursor, and other AI tools.

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'

# 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