memoryhub-cli 0.4.0__tar.gz → 0.8.0__tar.gz

{memoryhub_cli-0.4.0 → memoryhub_cli-0.8.0}/.gitignore

@@ -35,3 +35,16 @@ seed-clients.json
 NEXT_SESSION_old.md
 NEXT_SESSION.md
 planning/rfe_draft.md
+
+
+# Research drafts not ready for public commit
+research/agent-memory-benchmarks/
+
+# Claude Code worktrees
+.claude/worktrees/
+
+# Local DB backups (created by scripts/backup-db.sh)
+backups/
+
+medium_article_1.pdf
+

memoryhub_cli-0.8.0/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog — memoryhub-cli
+
+All notable changes to the `memoryhub-cli` package.
+
+## [0.8.0] — 2026-06-03
+
+- **New commands (#256)**: `memoryhub promote`, `memoryhub graduate`,
+  `memoryhub checkpoint`, and `memoryhub describe` for memory lifecycle
+  management.
+- **Obsidian export (#245)**: `memoryhub export --format obsidian` generates
+  Obsidian-compatible markdown with wikilinks and frontmatter.
+- **Hook-aware rule templates**: `memoryhub config init` and
+  `memoryhub config regenerate` now generate rule files that check for a
+  `<memoryhub-context>` block from SessionStart hooks before falling back
+  to the manual `register_session` + `search_memory` flow.
+
+## [0.7.0] — 2026-05-19
+
+- **Content type support (#237)**: Write and search commands accept
+  `--content-type` for behavioral memory classification.
+
+## [0.6.0] — 2026-05-07
+
+- **API key authentication (#256)**: The CLI now supports API key auth
+  via `MEMORYHUB_API_KEY` env var, `--api-key` flag, or the file at
+  `~/.config/memoryhub/api-key`. This enables non-interactive use cases
+  like SessionStart hooks.
+- **Compact output (#255)**: `--output compact` on search and list commands
+  produces content-only text wrapped in `<memoryhub-context>` tags for
+  zero-overhead LLM injection.
+- **List command**: `memoryhub list` enumerates memories without semantic
+  ranking, with cursor-based pagination.
+- **Server URL prompt**: `memoryhub config init` now prompts for the
+  server URL and saves it to `~/.config/memoryhub/config.json`.
+
+## [0.5.0] — 2026-04-22
+
+- **Structured output (#200)**: Replaced `--json` flag with `--output`
+  accepting `table`, `json`, `quiet`, and `compact` formats. All commands
+  now return structured JSON envelopes with `--output json`.
+- **New sub-apps**: `memoryhub graph` (relate, list, similar),
+  `memoryhub curation` (report, resolve), `memoryhub session` (status,
+  focus), `memoryhub project` (list, describe, join, leave).
+- **Update command**: `memoryhub update` for modifying existing memories
+  with version history preservation.
+- **Config enhancements**: `--project` and `--non-interactive` flags on
+  `memoryhub config init`.
+
+## [0.4.0] — 2026-04-14
+
+- **Admin subcommands (#186)**: Added `memoryhub admin` command group with
+  `create-agent`, `list-agents`, `rotate-secret`, and `disable-agent` for
+  self-serve agent provisioning via the auth service REST API.
+- **`--version` flag**: `memoryhub --version` now prints the installed version.
+
+## [0.3.0] — 2026-04-09
+
+- **Campaign & domain parameter support (#164)**: Added `--project-id` flag to
+  search, read, write, delete, and history commands. Added `--domain` flag to
+  search and write. When `.memoryhub.yaml` has campaigns configured, `project_id`
+  is auto-loaded from the config so the flag can be omitted.
+
+## [0.2.0] — 2026-04-09
+
+- Added campaign enrollment prompt to `memoryhub config init` (#160).
+- API key check after config init (#153).
+
+## [0.1.1] — 2026-04-09
+
+- Fix ruff lint errors (import sorting, `Optional` → `X | Y` annotations,
+  line length). No functional changes from 0.1.0.
+
+## [0.1.0] — 2026-04-09
+
+- Initial release. Terminal client for MemoryHub with search, read, write,
+  delete, and history commands.
+- `memoryhub config init` — interactive wizard for generating
+  `.memoryhub.yaml` and `.claude/rules/memoryhub-loading.md`.
+- `memoryhub config regenerate` — re-render rule file after editing YAML.
+- `memoryhub login` — one-time credential setup.

{memoryhub_cli-0.4.0 → memoryhub_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memoryhub-cli
-Version: 0.4.0
+Version: 0.8.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
@@ -38,15 +38,54 @@ Command-line client for MemoryHub — centralized, governed memory for AI agents
 pip install memoryhub-cli
 ```
 
-## Usage
+## 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
-# Authenticate to a MemoryHub instance
 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>
 
@@ -57,6 +96,9 @@ memoryhub write "Use Podman, not Docker" --scope user --weight 0.9
 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
@@ -70,6 +112,15 @@ 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_cli-0.4.0 → memoryhub_cli-0.8.0}/README.md

@@ -8,15 +8,54 @@ Command-line client for MemoryHub — centralized, governed memory for AI agents
 pip install memoryhub-cli
 ```
 
-## Usage
+## 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
-# Authenticate to a MemoryHub instance
 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>
 
@@ -27,6 +66,9 @@ memoryhub write "Use Podman, not Docker" --scope user --weight 0.9
 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
@@ -40,6 +82,15 @@ 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_cli-0.4.0 → memoryhub_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memoryhub-cli"
-version = "0.4.0"
+version = "0.8.0"
 description = "CLI client for MemoryHub — centralized, governed memory for AI agents"
 readme = "README.md"
 license = "Apache-2.0"

{memoryhub_cli-0.4.0 → memoryhub_cli-0.8.0}/src/memoryhub_cli/__init__.py

@@ -1,3 +1,3 @@
 """MemoryHub CLI client."""
 
-__version__ = "0.4.0"
+__version__ = "0.8.0"

{memoryhub_cli-0.4.0 → memoryhub_cli-0.8.0}/src/memoryhub_cli/admin.py

@@ -3,23 +3,28 @@
 from __future__ import annotations
 
 import asyncio
-import json
 import os
 
 import httpx
 import typer
-from rich.console import Console
 from rich.table import Table
 
 from memoryhub_cli.config import CONFIG_DIR, load_config
+from memoryhub_cli.output import (
+    EXIT_AUTH_ERROR,
+    EXIT_CLIENT_ERROR,
+    EXIT_SERVER_ERROR,
+    OutputFormat,
+    console,
+    handle_error,
+    json_success,
+)
 
 admin_app = typer.Typer(
     name="admin",
     help="Manage agents and OAuth clients.",
     no_args_is_help=True,
 )
-console = Console()
-err_console = Console(stderr=True)
 
 
 def _run(coro):
@@ -27,7 +32,7 @@ def _run(coro):
     return asyncio.run(coro)
 
 
-def _get_admin_key() -> str:
+def _get_admin_key(output: OutputFormat) -> str:
     """Resolve the admin key from env var or config file."""
     key = os.environ.get("MEMORYHUB_ADMIN_KEY")
     if key:
@@ -38,15 +43,16 @@ def _get_admin_key() -> str:
     if key:
         return key
 
-    err_console.print(
-        "[red]No admin key found.[/red]\n"
-        "Set MEMORYHUB_ADMIN_KEY or add 'admin_key' to "
-        "~/.config/memoryhub/config.json."
+    handle_error(
+        "missing_config",
+        "No admin key found. Set MEMORYHUB_ADMIN_KEY or add 'admin_key' to "
+        "~/.config/memoryhub/config.json.",
+        output,
+        EXIT_CLIENT_ERROR,
     )
-    raise typer.Exit(1)
 
 
-def _get_auth_url() -> str:
+def _get_auth_url(output: OutputFormat) -> str:
     """Resolve the auth service base URL (without trailing slash)."""
     url = os.environ.get("MEMORYHUB_AUTH_URL")
     if url:
@@ -59,16 +65,15 @@ def _get_auth_url() -> str:
 
     url = config.get("url")
     if url:
-        # Fall back to base MCP URL with /admin stripped — assume auth
-        # is co-located at the base URL.
         return url.rstrip("/")
 
-    err_console.print(
-        "[red]No auth URL found.[/red]\n"
-        "Set MEMORYHUB_AUTH_URL, or add 'auth_url' to "
-        "~/.config/memoryhub/config.json."
+    handle_error(
+        "missing_config",
+        "No auth URL found. Set MEMORYHUB_AUTH_URL, or add 'auth_url' to "
+        "~/.config/memoryhub/config.json.",
+        output,
+        EXIT_CLIENT_ERROR,
     )
-    raise typer.Exit(1)
 
 
 def _admin_headers(admin_key: str) -> dict[str, str]:
@@ -97,14 +102,16 @@ def create_agent(
         "--write-config",
         help="Write the client_secret to ~/.config/memoryhub/api-key",
     ),
-    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.table, "--output", "-o", help="Output format: table, json, quiet",
+    ),
 ):
     """Create a new agent (OAuth client).
 
     The client_secret is shown only once. Save it immediately.
     """
-    admin_key = _get_admin_key()
-    auth_url = _get_auth_url()
+    admin_key = _get_admin_key(output)
+    auth_url = _get_auth_url(output)
     scope_list = [s.strip() for s in scopes.split(",") if s.strip()]
 
     body = {
@@ -128,11 +135,13 @@ def create_agent(
     try:
         data = _run(_do())
     except httpx.HTTPStatusError as exc:
-        _handle_http_error(exc)
+        _handle_http_error(exc, output)
         return
 
-    if json_output:
-        console.print_json(json.dumps(data))
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
         return
 
     console.print("[green]Agent created successfully.[/green]\n")
@@ -159,11 +168,13 @@ def create_agent(
 
 @admin_app.command("list-agents")
 def list_agents(
-    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.table, "--output", "-o", help="Output format: table, json, quiet",
+    ),
 ):
     """List all registered agents (OAuth clients)."""
-    admin_key = _get_admin_key()
-    auth_url = _get_auth_url()
+    admin_key = _get_admin_key(output)
+    auth_url = _get_auth_url(output)
 
     async def _do():
         async with httpx.AsyncClient() as client:
@@ -178,11 +189,13 @@ def list_agents(
     try:
         data = _run(_do())
     except httpx.HTTPStatusError as exc:
-        _handle_http_error(exc)
+        _handle_http_error(exc, output)
         return
 
-    if json_output:
-        console.print_json(json.dumps(data))
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
         return
 
     if not data:
@@ -214,14 +227,16 @@ def list_agents(
 @admin_app.command("rotate-secret")
 def rotate_secret(
     client_id: str = typer.Argument(..., help="Client ID of the agent"),
-    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.table, "--output", "-o", help="Output format: table, json, quiet",
+    ),
 ):
     """Rotate the client secret for an agent.
 
     The new secret is shown only once. Save it immediately.
     """
-    admin_key = _get_admin_key()
-    auth_url = _get_auth_url()
+    admin_key = _get_admin_key(output)
+    auth_url = _get_auth_url(output)
 
     async def _do():
         async with httpx.AsyncClient() as client:
@@ -236,11 +251,13 @@ def rotate_secret(
     try:
         data = _run(_do())
     except httpx.HTTPStatusError as exc:
-        _handle_http_error(exc)
+        _handle_http_error(exc, output)
         return
 
-    if json_output:
-        console.print_json(json.dumps(data))
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
         return
 
     console.print(f"[green]Secret rotated for {data['client_id']}.[/green]\n")
@@ -255,10 +272,13 @@ def rotate_secret(
 @admin_app.command("disable-agent")
 def disable_agent(
     client_id: str = typer.Argument(..., help="Client ID of the agent to disable"),
+    output: OutputFormat = typer.Option(
+        OutputFormat.table, "--output", "-o", help="Output format: table, json, quiet",
+    ),
 ):
     """Disable an agent (set active=false)."""
-    admin_key = _get_admin_key()
-    auth_url = _get_auth_url()
+    admin_key = _get_admin_key(output)
+    auth_url = _get_auth_url(output)
 
     async def _do():
         async with httpx.AsyncClient() as client:
@@ -274,7 +294,13 @@ def disable_agent(
     try:
         data = _run(_do())
     except httpx.HTTPStatusError as exc:
-        _handle_http_error(exc)
+        _handle_http_error(exc, output)
+        return
+
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
         return
 
     console.print(
@@ -285,8 +311,8 @@ def disable_agent(
 # ── Helpers ──────────────────────────────────────────────────────────────────
 
 
-def _handle_http_error(exc: httpx.HTTPStatusError) -> None:
-    """Print a user-friendly error for HTTP failures."""
+def _handle_http_error(exc: httpx.HTTPStatusError, output: OutputFormat) -> None:
+    """Emit a structured error for HTTP failures and exit."""
     status = exc.response.status_code
     try:
         detail = exc.response.json().get("detail", exc.response.text)
@@ -294,14 +320,17 @@ def _handle_http_error(exc: httpx.HTTPStatusError) -> None:
         detail = exc.response.text
 
     if status == 401:
-        err_console.print(
-            "[red]Authentication failed.[/red] Check your admin key."
+        handle_error(
+            "auth_failed",
+            "Authentication failed. Check your admin key.",
+            output,
+            EXIT_AUTH_ERROR,
         )
     elif status == 404:
-        err_console.print(f"[red]Not found:[/red] {detail}")
+        handle_error("not_found", str(detail), output, EXIT_CLIENT_ERROR)
     elif status == 409:
-        err_console.print(f"[red]Conflict:[/red] {detail}")
+        handle_error("conflict", str(detail), output, EXIT_CLIENT_ERROR)
+    elif status >= 500:
+        handle_error("server_error", f"HTTP {status}: {detail}", output, EXIT_SERVER_ERROR)
     else:
-        err_console.print(f"[red]HTTP {status}:[/red] {detail}")
-
-    raise typer.Exit(1)
+        handle_error("http_error", f"HTTP {status}: {detail}", output, EXIT_CLIENT_ERROR)

{memoryhub_cli-0.4.0 → memoryhub_cli-0.8.0}/src/memoryhub_cli/config.py

@@ -1,10 +1,14 @@
 """Configuration management for MemoryHub CLI."""
 
+from __future__ import annotations
+
 import json
+import os
 from pathlib import Path
 
 CONFIG_DIR = Path.home() / ".config" / "memoryhub"
 CONFIG_FILE = CONFIG_DIR / "config.json"
+API_KEY_FILE = CONFIG_DIR / "api-key"
 
 
 def load_config() -> dict:
@@ -18,18 +22,40 @@ def save_config(config: dict) -> None:
     """Save config to disk."""
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
     CONFIG_FILE.write_text(json.dumps(config, indent=2) + "\n")
-    # Restrict permissions — contains secrets
     CONFIG_FILE.chmod(0o600)
 
 
+def get_api_key() -> str | None:
+    """Resolve API key from env var, key file, or config.
+
+    Precedence: MEMORYHUB_API_KEY env var > ~/.config/memoryhub/api-key file
+    > api_key in config.json.
+    """
+    key = os.environ.get("MEMORYHUB_API_KEY", "").strip()
+    if key:
+        return key
+
+    if API_KEY_FILE.exists():
+        key = API_KEY_FILE.read_text().strip()
+        if key:
+            return key
+
+    return load_config().get("api_key") or None
+
+
+def get_server_url() -> str | None:
+    """Resolve server URL from env var or config."""
+    url = os.environ.get("MEMORYHUB_URL", "").strip()
+    if url:
+        return url
+    return load_config().get("url") or None
+
+
 def get_connection_params() -> dict:
-    """Get connection parameters, preferring env vars over config file.
+    """Get OAuth connection parameters, preferring env vars over config file.
 
     Required keys: url, auth_url, client_id, client_secret.
-    Env vars: MEMORYHUB_URL, MEMORYHUB_AUTH_URL, MEMORYHUB_CLIENT_ID, MEMORYHUB_CLIENT_SECRET.
     """
-    import os
-
     config = load_config()
     return {
         "url": os.environ.get("MEMORYHUB_URL", config.get("url", "")),