Metadata-Version: 2.4
Name: memoryhub-cli
Version: 0.11.0
Summary: CLI client for MemoryHub — centralized, governed memory for AI agents
Project-URL: Homepage, https://github.com/redhat-ai-americas/memory-hub
Project-URL: Repository, https://github.com/redhat-ai-americas/memory-hub
Project-URL: Issues, https://github.com/redhat-ai-americas/memory-hub/issues
Author: Wes Jackson
License-Expression: Apache-2.0
Keywords: agents,ai,cli,mcp,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: memoryhub>=0.14.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer[all]>=0.15
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# memoryhub-cli

Command-line client for MemoryHub — centralized, governed memory for AI agents.

## Install

```bash
pip install memoryhub-cli
```

## Authentication

The CLI supports two authentication modes:

**API key (recommended for non-interactive use):**

```bash
# Via environment variable
export MEMORYHUB_API_KEY=mh-dev-abc123

# Or place your key at ~/.config/memoryhub/api-key (mode 0600)
echo "mh-dev-abc123" > ~/.config/memoryhub/api-key
```

API key resolution order: `MEMORYHUB_API_KEY` env var > `~/.config/memoryhub/api-key` file > `api_key` in config.json.

**Server URL:**

The CLI needs to know where the MemoryHub server is. The SessionStart hook for Claude Code also reads from this config.

```bash
# Via environment variable
export MEMORYHUB_URL=https://memoryhub.example.com/mcp/

# Or save to ~/.config/memoryhub/config.json (also set by memoryhub config init)
echo '{"url": "https://memoryhub.example.com/mcp/"}' > ~/.config/memoryhub/config.json
chmod 600 ~/.config/memoryhub/config.json
```

URL resolution: `MEMORYHUB_URL` env var > `url` in `~/.config/memoryhub/config.json`.

**OAuth (interactive setup):**

```bash
memoryhub login
```

When both are available, API key takes precedence.

## Usage

```bash
# Search for memories
memoryhub search "deployment patterns"

# List memories by creation time (no semantic search)
memoryhub list --project-id my-project --max 20

# Read a specific memory
memoryhub read <memory-id>

# Write a new memory
memoryhub write "Use Podman, not Docker" --scope user --weight 0.9

# Campaign-scoped operations (requires project enrollment)
memoryhub search "shared patterns" --project-id my-project --domain React
memoryhub write "Use vLLM for embeddings" --project-id my-project --domain ML

# Compact output for LLM context injection (content only, no metadata)
memoryhub search "project conventions" --output compact

# Set up project-level memory loading
memoryhub config init
memoryhub config regenerate

# Admin: provision and manage agents
memoryhub admin create-agent my-agent --scopes user,project
memoryhub admin list-agents
memoryhub admin rotate-secret my-agent
memoryhub admin disable-agent my-agent
```

The `--project-id` flag enables campaign-scoped memory access. When your project is enrolled in campaigns via `.memoryhub.yaml`, the CLI auto-loads the project identifier from config, so you can omit the flag in most cases. Use `--domain` to tag writes or boost domain-matching results in search.

## Output formats

The `--output` / `-o` flag controls output format on most commands:

- `table` (default) -- Rich-formatted tables for interactive use
- `json` -- Machine-readable JSON envelope (`{"status": "ok", "data": {...}}`)
- `quiet` -- No output (exit code only)
- `compact` -- Content-only text for LLM context injection, no IDs or metadata

## Project configuration

`memoryhub config` generates a project-local `.memoryhub.yaml` and a companion `.claude/rules/memoryhub-loading.md` rule file. Both files are meant to be committed so every contributor's agent inherits the same loading policy.

`memoryhub config init` is an interactive wizard that asks about session shape, loading pattern, focus source, and retrieval defaults, then writes both files at the project root. If a legacy `.claude/rules/memoryhub-integration.md` already exists, it is backed up to `.bak` before the new rule file is written.

`memoryhub config regenerate` re-renders the rule file from `.memoryhub.yaml` after you hand-edit the YAML. It reads the YAML and rewrites the Markdown rule file only; it does not modify `.memoryhub.yaml`.

Per-developer connection params (`url`, `auth_url`, `client_id`, `client_secret`) live separately at `~/.config/memoryhub/config.json` and are managed by `memoryhub login`. They are not stored in `.memoryhub.yaml` and are not committed.

## Further documentation

The CLI is one surface of the [memory-hub](https://github.com/redhat-ai-americas/memory-hub) monorepo. For deeper context:

- **[Architecture overview](https://github.com/redhat-ai-americas/memory-hub/blob/main/docs/ARCHITECTURE.md)** — System design, deployment topology
- **[MCP server tool reference](https://github.com/redhat-ai-americas/memory-hub/blob/main/docs/mcp-server.md)** — The 15 tools the CLI wraps
- **[Agent memory ergonomics design](https://github.com/redhat-ai-americas/memory-hub/blob/main/docs/agent-memory-ergonomics/design.md)** — Full `.memoryhub.yaml` schema, rule file templates, and session-loading patterns
- **[Python SDK](https://pypi.org/project/memoryhub/)** — if you'd rather call the tools from Python

## Links

- **[GitHub repository](https://github.com/redhat-ai-americas/memory-hub)**
- **[Issue tracker](https://github.com/redhat-ai-americas/memory-hub/issues)**
- **[License (Apache 2.0)](https://github.com/redhat-ai-americas/memory-hub/blob/main/LICENSE)**
