Metadata-Version: 2.4
Name: hypermemory-cli
Version: 1.1.2
Summary: Persistent memory graph for AI agents — store, recall, and connect knowledge across conversations.
Project-URL: Homepage, https://app.hypermemory.io
Project-URL: Documentation, https://app.hypermemory.io/integration
Project-URL: Repository, https://github.com/runstack-ai/hypergraph-memory
Project-URL: Bug Tracker, https://github.com/runstack-ai/hypergraph-memory/issues
Author-email: RunStack <hello@runstack.ai>
License-Expression: MIT
Keywords: agents,ai,claude,cursor,hypergraph,knowledge-graph,llm,mcp,memory,persistent-memory
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install hypermemory-cli
```

Requires Python 3.10+.

## Quick Start

```bash
# 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):**

```bash
hm login
```

Opens your browser for GitHub-based OAuth. Tokens are saved to `~/.config/hypermemory/config.json` and refresh automatically.

**API key:**

```bash
hm config --set-key hm_YOUR_API_KEY
```

Generate API keys at [app.hypermemory.io/api-keys](https://app.hypermemory.io/api-keys).

**Environment variable:**

```bash
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 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:

```bash
# 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:

```bash
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:

```bash
# 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](https://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
