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

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

@@ -34,3 +34,17 @@ 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.3.0 → memoryhub_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memoryhub-cli
-Version: 0.3.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
@@ -18,6 +18,7 @@ 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.3.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
@@ -37,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>
 
@@ -56,13 +96,31 @@ 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
+
+# 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_cli-0.3.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,13 +66,31 @@ 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
+
+# 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_cli-0.3.0 → memoryhub_cli-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memoryhub-cli"
-version = "0.3.0"
+version = "0.8.0"
 description = "CLI client for MemoryHub — centralized, governed memory for AI agents"
 readme = "README.md"
 license = "Apache-2.0"
@@ -18,6 +18,7 @@ dependencies = [
     "typer[all]>=0.15",
     "rich>=13.0",
     "pyyaml>=6.0",
+    "httpx>=0.27",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

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

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

memoryhub_cli-0.8.0/src/memoryhub_cli/admin.py

@@ -0,0 +1,336 @@
+"""Admin subcommands for managing agents and OAuth clients."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+import httpx
+import typer
+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,
+)
+
+
+def _run(coro):
+    """Run an async coroutine."""
+    return asyncio.run(coro)
+
+
+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:
+        return key
+
+    config = load_config()
+    key = config.get("admin_key")
+    if key:
+        return key
+
+    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,
+    )
+
+
+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:
+        return url.rstrip("/")
+
+    config = load_config()
+    url = config.get("auth_url")
+    if url:
+        return url.rstrip("/")
+
+    url = config.get("url")
+    if url:
+        return url.rstrip("/")
+
+    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,
+    )
+
+
+def _admin_headers(admin_key: str) -> dict[str, str]:
+    return {"X-Admin-Key": admin_key}
+
+
+# ── Commands ─────────────────────────────────────────────────────────────────
+
+
+@admin_app.command("create-agent")
+def create_agent(
+    name: str = typer.Argument(..., help="Agent name (used as client_id and client_name)"),
+    scopes: str = typer.Option(
+        "user,project",
+        "--scopes",
+        help="Comma-separated default scopes",
+    ),
+    project_id: str | None = typer.Option(
+        None, "--project-id", "-p", help="Project ID to associate with the agent",
+    ),
+    tenant_id: str = typer.Option(
+        "default", "--tenant-id", "-t", help="Tenant ID",
+    ),
+    write_config: bool = typer.Option(
+        False,
+        "--write-config",
+        help="Write the client_secret to ~/.config/memoryhub/api-key",
+    ),
+    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(output)
+    auth_url = _get_auth_url(output)
+    scope_list = [s.strip() for s in scopes.split(",") if s.strip()]
+
+    body = {
+        "client_id": name,
+        "client_name": name,
+        "default_scopes": scope_list,
+        "tenant_id": tenant_id,
+    }
+
+    async def _do():
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                f"{auth_url}/admin/clients",
+                json=body,
+                headers=_admin_headers(admin_key),
+                timeout=30,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = _run(_do())
+    except httpx.HTTPStatusError as exc:
+        _handle_http_error(exc, output)
+        return
+
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
+        return
+
+    console.print("[green]Agent created successfully.[/green]\n")
+    console.print(f"  Client ID:     [bold]{data['client_id']}[/bold]")
+    console.print(f"  Client Name:   {data['client_name']}")
+    console.print(f"  Tenant:        {data['tenant_id']}")
+    console.print(f"  Scopes:        {', '.join(data['default_scopes'])}")
+    console.print(f"  Active:        {data['active']}")
+    console.print()
+    console.print(
+        f"  [yellow bold]Client Secret:   {data['client_secret']}[/yellow bold]"
+    )
+    console.print(
+        "\n  [dim]Save this secret now. It will not be shown again.[/dim]"
+    )
+
+    if write_config:
+        api_key_path = CONFIG_DIR / "api-key"
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        api_key_path.write_text(data["client_secret"])
+        api_key_path.chmod(0o600)
+        console.print(f"\n  [green]Secret written to {api_key_path}[/green]")
+
+
+@admin_app.command("list-agents")
+def list_agents(
+    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(output)
+    auth_url = _get_auth_url(output)
+
+    async def _do():
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(
+                f"{auth_url}/admin/clients",
+                headers=_admin_headers(admin_key),
+                timeout=30,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = _run(_do())
+    except httpx.HTTPStatusError as exc:
+        _handle_http_error(exc, output)
+        return
+
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
+        return
+
+    if not data:
+        console.print("[dim]No agents registered.[/dim]")
+        return
+
+    table = Table(title="Registered Agents")
+    table.add_column("Client ID", style="bold")
+    table.add_column("Name")
+    table.add_column("Active", justify="center")
+    table.add_column("Scopes")
+    table.add_column("Created", style="dim")
+
+    for agent in data:
+        active = "[green]Yes[/green]" if agent.get("active") else "[red]No[/red]"
+        scopes = ", ".join(agent.get("default_scopes", []))
+        created = str(agent.get("created_at", "-"))[:19]
+        table.add_row(
+            agent["client_id"],
+            agent.get("client_name", "-"),
+            active,
+            scopes,
+            created,
+        )
+
+    console.print(table)
+
+
+@admin_app.command("rotate-secret")
+def rotate_secret(
+    client_id: str = typer.Argument(..., help="Client ID of the agent"),
+    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(output)
+    auth_url = _get_auth_url(output)
+
+    async def _do():
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                f"{auth_url}/admin/clients/{client_id}/rotate-secret",
+                headers=_admin_headers(admin_key),
+                timeout=30,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = _run(_do())
+    except httpx.HTTPStatusError as exc:
+        _handle_http_error(exc, output)
+        return
+
+    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")
+    console.print(
+        f"  [yellow bold]New Secret:   {data['client_secret']}[/yellow bold]"
+    )
+    console.print(
+        "\n  [dim]Save this secret now. It will not be shown again.[/dim]"
+    )
+
+
+@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(output)
+    auth_url = _get_auth_url(output)
+
+    async def _do():
+        async with httpx.AsyncClient() as client:
+            resp = await client.patch(
+                f"{auth_url}/admin/clients/{client_id}",
+                json={"active": False},
+                headers=_admin_headers(admin_key),
+                timeout=30,
+            )
+            resp.raise_for_status()
+            return resp.json()
+
+    try:
+        data = _run(_do())
+    except httpx.HTTPStatusError as exc:
+        _handle_http_error(exc, output)
+        return
+
+    if output == OutputFormat.json:
+        json_success(data)
+        return
+    if output == OutputFormat.quiet:
+        return
+
+    console.print(
+        f"[green]Agent '{data['client_id']}' has been disabled.[/green]"
+    )
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+
+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)
+    except Exception:
+        detail = exc.response.text
+
+    if status == 401:
+        handle_error(
+            "auth_failed",
+            "Authentication failed. Check your admin key.",
+            output,
+            EXIT_AUTH_ERROR,
+        )
+    elif status == 404:
+        handle_error("not_found", str(detail), output, EXIT_CLIENT_ERROR)
+    elif status == 409:
+        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:
+        handle_error("http_error", f"HTTP {status}: {detail}", output, EXIT_CLIENT_ERROR)