memoryhub-cli 0.1.1__py3-none-any.whl

memoryhub_cli/__init__.py

@@ -0,0 +1,3 @@
+"""MemoryHub CLI client."""
+
+__version__ = "0.1.1"

memoryhub_cli/config.py

@@ -0,0 +1,41 @@
+"""Configuration management for MemoryHub CLI."""
+
+import json
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "memoryhub"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def load_config() -> dict:
+    """Load config from disk. Returns empty dict if not found."""
+    if not CONFIG_FILE.exists():
+        return {}
+    return json.loads(CONFIG_FILE.read_text())
+
+
+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_connection_params() -> dict:
+    """Get 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", "")),
+        "auth_url": os.environ.get("MEMORYHUB_AUTH_URL", config.get("auth_url", "")),
+        "client_id": os.environ.get("MEMORYHUB_CLIENT_ID", config.get("client_id", "")),
+        "client_secret": os.environ.get(
+            "MEMORYHUB_CLIENT_SECRET", config.get("client_secret", "")
+        ),
+    }

memoryhub_cli/main.py

@@ -0,0 +1,479 @@
+"""MemoryHub CLI — terminal interface for centralized agent memory."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+
+import typer
+from memoryhub import CONFIG_FILENAME, ConfigError, load_project_config
+from rich.console import Console
+from rich.table import Table
+
+from memoryhub_cli.config import get_connection_params, save_config
+from memoryhub_cli.project_config import (
+    InitChoices,
+    LoadingPattern,
+    SessionShape,
+    build_project_config,
+    rewrite_rule_file,
+    suggest_pattern,
+    write_init_files,
+)
+
+app = typer.Typer(
+    name="memoryhub",
+    help="CLI client for MemoryHub — centralized, governed memory for AI agents.",
+    no_args_is_help=True,
+)
+config_app = typer.Typer(
+    name="config",
+    help="Manage project-level MemoryHub configuration (.memoryhub.yaml).",
+    no_args_is_help=True,
+)
+app.add_typer(config_app, name="config")
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _get_client():
+    """Create a MemoryHubClient from config/env."""
+    from memoryhub import MemoryHubClient
+
+    params = get_connection_params()
+    missing = [k for k, v in params.items() if not v]
+    if missing:
+        err_console.print(
+            f"[red]Missing configuration: {', '.join(missing)}[/red]\n"
+            "Run [bold]memoryhub login[/bold] or set environment variables."
+        )
+        raise typer.Exit(1)
+
+    return MemoryHubClient(
+        url=params["url"],
+        auth_url=params["auth_url"],
+        client_id=params["client_id"],
+        client_secret=params["client_secret"],
+    )
+
+
+def _run(coro):
+    """Run an async coroutine."""
+    return asyncio.run(coro)
+
+
+@app.command()
+def login(
+    url: str = typer.Option(..., prompt="MemoryHub MCP URL", help="MCP server URL"),
+    auth_url: str = typer.Option(..., prompt="Auth service URL", help="OAuth 2.1 auth URL"),
+    client_id: str = typer.Option(..., prompt="Client ID", help="OAuth client ID"),
+    client_secret: str = typer.Option(
+        ..., prompt="Client secret", hide_input=True, help="OAuth client secret"
+    ),
+):
+    """Configure connection to a MemoryHub instance.
+
+    Credentials are stored in ~/.config/memoryhub/config.json (mode 600).
+    Environment variables (MEMORYHUB_URL, etc.) take precedence over stored config.
+    """
+    save_config({
+        "url": url,
+        "auth_url": auth_url,
+        "client_id": client_id,
+        "client_secret": client_secret,
+    })
+    console.print("[green]Configuration saved.[/green]")
+
+    # Test connectivity
+    async def _test():
+        from memoryhub import MemoryHubClient
+
+        client = MemoryHubClient(
+            url=url, auth_url=auth_url,
+            client_id=client_id, client_secret=client_secret,
+        )
+        async with client:
+            result = await client.search("test", max_results=1)
+            return result
+
+    try:
+        _run(_test())
+        console.print("[green]Connection verified.[/green]")
+    except Exception as exc:
+        err_console.print(f"[yellow]Warning: connection test failed: {exc}[/yellow]")
+        err_console.print("Credentials saved anyway. Check URL and credentials.")
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    scope: str | None = typer.Option(None, "--scope", "-s", help="Filter by scope"),
+    max_results: int = typer.Option(10, "--max", "-n", help="Maximum results"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Search memories using semantic similarity."""
+    client = _get_client()
+
+    async def _do():
+        async with client:
+            return await client.search(
+                query, scope=scope, max_results=max_results,
+            )
+
+    result = _run(_do())
+
+    if json_output:
+        console.print_json(result.model_dump_json())
+        return
+
+    if not result.results:
+        console.print("[dim]No results found.[/dim]")
+        return
+
+    table = Table(title=f"Search: {query}")
+    table.add_column("ID", style="dim", max_width=12)
+    table.add_column("Scope", style="cyan")
+    table.add_column("Weight", justify="right")
+    table.add_column("Score", justify="right")
+    table.add_column("Stub", max_width=60)
+
+    for mem in result.results:
+        score = f"{mem.relevance_score:.3f}" if mem.relevance_score else "-"
+        table.add_row(
+            str(mem.id)[:12],
+            mem.scope,
+            f"{mem.weight:.2f}",
+            score,
+            (mem.stub or mem.content)[:60],
+        )
+
+    console.print(table)
+    more = " (more available)" if result.has_more else ""
+    console.print(
+        f"[dim]{len(result.results)} of {result.total_matching} matching{more}[/dim]"
+    )
+
+
+@app.command()
+def read(
+    memory_id: str = typer.Argument(..., help="Memory UUID"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Read a memory by ID."""
+    client = _get_client()
+
+    async def _do():
+        async with client:
+            return await client.read(memory_id)
+
+    memory = _run(_do())
+
+    if json_output:
+        console.print_json(memory.model_dump_json())
+        return
+
+    console.print(f"[bold]{memory.scope}[/bold] | v{memory.version} | weight {memory.weight:.2f}")
+    console.print(f"[dim]ID: {memory.id}[/dim]")
+    console.print(f"[dim]Owner: {memory.owner_id}[/dim]")
+    console.print()
+    console.print(memory.content)
+
+    if memory.branch_count:
+        console.print(
+            f"\n[dim]{memory.branch_count} branch(es). "
+            f"Search or read by ID to inspect them.[/dim]"
+        )
+
+
+@app.command()
+def write(
+    content: str = typer.Argument(None, help="Memory content (reads from stdin if omitted)"),
+    scope: str = typer.Option("user", "--scope", "-s", help="Memory scope"),
+    weight: float = typer.Option(0.7, "--weight", "-w", help="Priority weight 0.0-1.0"),
+    parent_id: str | None = typer.Option(None, "--parent", help="Parent memory ID"),
+    branch_type: str | None = typer.Option(None, "--branch-type", help="Branch type"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Write a new memory.
+
+    Content can be passed as an argument or piped via stdin.
+    """
+    if content is None:
+        if sys.stdin.isatty():
+            err_console.print("[red]Provide content as argument or pipe via stdin.[/red]")
+            raise typer.Exit(1)
+        content = sys.stdin.read().strip()
+
+    if not content:
+        err_console.print("[red]Content cannot be empty.[/red]")
+        raise typer.Exit(1)
+
+    client = _get_client()
+
+    async def _do():
+        async with client:
+            return await client.write(
+                content, scope=scope, weight=weight,
+                parent_id=parent_id, branch_type=branch_type,
+            )
+
+    result = _run(_do())
+
+    if json_output:
+        console.print_json(result.model_dump_json())
+        return
+
+    mem = result.memory
+    console.print(f"[green]Memory created:[/green] {mem.id}")
+    console.print(f"  Scope: {mem.scope} | Weight: {mem.weight:.2f} | Version: {mem.version}")
+    if result.curation.blocked:
+        console.print("[yellow]Note: curation pipeline blocked this write.[/yellow]")
+    elif result.curation.similar_count > 0:
+        console.print(
+            f"[dim]Curation: {result.curation.similar_count} similar memories found"
+            f" (nearest score: {result.curation.nearest_score:.3f})[/dim]"
+        )
+
+
+@app.command()
+def delete(
+    memory_id: str = typer.Argument(..., help="Memory UUID to delete"),
+    force: bool = typer.Option(False, "--force", "-f", help="Skip confirmation"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Soft-delete a memory and its version chain."""
+    if not force:
+        confirm = typer.confirm(f"Delete memory {memory_id} and all versions?")
+        if not confirm:
+            raise typer.Abort()
+
+    client = _get_client()
+
+    async def _do():
+        async with client:
+            return await client.delete(memory_id)
+
+    result = _run(_do())
+
+    if json_output:
+        console.print_json(result.model_dump_json())
+        return
+
+    console.print(
+        f"[green]Deleted:[/green] {result.total_deleted} nodes "
+        f"({result.versions_deleted} versions, {result.branches_deleted} branches)"
+    )
+
+
+@app.command()
+def history(
+    memory_id: str = typer.Argument(..., help="Memory UUID"),
+    max_versions: int = typer.Option(20, "--max", "-n", help="Maximum versions to show"),
+    json_output: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
+):
+    """Show version history for a memory."""
+    client = _get_client()
+
+    async def _do():
+        async with client:
+            return await client.get_history(memory_id, max_versions=max_versions)
+
+    result = _run(_do())
+
+    if json_output:
+        console.print_json(result.model_dump_json())
+        return
+
+    if not result.versions:
+        console.print("[dim]No version history found.[/dim]")
+        return
+
+    table = Table(title=f"History: {memory_id[:12]}...")
+    table.add_column("Version", justify="right")
+    table.add_column("Current", justify="center")
+    table.add_column("Created", style="dim")
+    table.add_column("Stub", max_width=60)
+
+    for v in result.versions:
+        current = "[green]Yes[/green]" if v.is_current else ""
+        created = str(v.created_at)[:19] if v.created_at else "-"
+        table.add_row(
+            f"v{v.version}",
+            current,
+            created,
+            (v.stub or v.content)[:60],
+        )
+
+    console.print(table)
+    if result.has_more:
+        console.print(
+            f"[dim]Showing {len(result.versions)} of {result.total_versions} versions[/dim]"
+        )
+
+
+# ── memoryhub config init / regenerate ───────────────────────────────────────
+
+
+_SHAPE_PROMPT = """\
+What's this project's typical session shape?
+  1) One topic per session, narrow scope (focused)
+  2) Multiple topics per session, broad context needed (broad)
+  3) Sessions evolve — start narrow, may pivot (adaptive)\
+"""
+
+_PATTERN_PROMPT = """\
+How should memories load?
+  1) Eager — load at session start (best for broad)
+  2) Lazy — load after first user turn (best for focused)
+  3) Lazy + rebias on pivot (best for adaptive)
+  4) Just-in-time — never preload, search on demand\
+"""
+
+_FOCUS_PROMPT = """\
+How should session focus be inferred?
+  1) Declared — agent will ask
+  2) Inferred from working directory
+  3) Inferred from first user turn
+  4) Auto (try inference, fall back to ask)\
+"""
+
+_CONTRADICTION_BLURB = """\
+Cross-domain contradiction detection:
+  Focused mode loads only memories matching session topic. If you make
+  a decision in this session that contradicts a memory from a different
+  topic, the agent won't catch it. You can value this coverage over
+  token efficiency by switching to broad mode.\
+"""
+
+
+_SHAPE_BY_INDEX: dict[int, SessionShape] = {1: "focused", 2: "broad", 3: "adaptive"}
+_PATTERN_BY_INDEX: dict[int, LoadingPattern] = {
+    1: "eager",
+    2: "lazy",
+    3: "lazy_with_rebias",
+    4: "jit",
+}
+_FOCUS_BY_INDEX = {1: "declared", 2: "directory", 3: "first_turn", 4: "auto"}
+
+
+def _prompt_choice(prompt_text: str, choices: dict, default: int) -> int:
+    """Prompt for an integer in `choices`, defaulting to `default`."""
+    while True:
+        console.print(prompt_text)
+        raw = typer.prompt(f"Choice [{default}]", default=str(default))
+        try:
+            value = int(raw)
+        except ValueError:
+            err_console.print(f"[red]Not a number: {raw}[/red]")
+            continue
+        if value in choices:
+            return value
+        err_console.print(
+            f"[red]Pick one of: {', '.join(str(k) for k in choices)}[/red]"
+        )
+
+
+@config_app.command("init")
+def config_init(
+    project_dir: Path = typer.Option(
+        Path("."),
+        "--dir",
+        "-d",
+        help="Project directory (defaults to cwd).",
+        file_okay=False,
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing .memoryhub.yaml or generated rule file.",
+    ),
+):
+    """Walk through project setup and write `.memoryhub.yaml` + the
+    generated `.claude/rules/memoryhub-loading.md` rule file."""
+    project_dir = project_dir.resolve()
+    console.print(f"[bold]Configuring MemoryHub for[/bold] {project_dir}\n")
+
+    shape_idx = _prompt_choice(_SHAPE_PROMPT, _SHAPE_BY_INDEX, default=1)
+    shape = _SHAPE_BY_INDEX[shape_idx]
+
+    suggested_pattern = suggest_pattern(shape)
+    pattern_default = next(
+        i for i, p in _PATTERN_BY_INDEX.items() if p == suggested_pattern
+    )
+    pattern_idx = _prompt_choice(_PATTERN_PROMPT, _PATTERN_BY_INDEX, default=pattern_default)
+    pattern = _PATTERN_BY_INDEX[pattern_idx]
+
+    focus_idx = _prompt_choice(_FOCUS_PROMPT, _FOCUS_BY_INDEX, default=4)
+    focus_source = _FOCUS_BY_INDEX[focus_idx]
+
+    console.print(f"\n{_CONTRADICTION_BLURB}\n")
+    keep_contradictions = typer.confirm(
+        "Keep contradiction detection across all domains?",
+        default=False,
+    )
+
+    choices = InitChoices(
+        session_shape=shape,
+        pattern=pattern,
+        focus_source=focus_source,
+        cross_domain_contradiction_detection=keep_contradictions,
+    )
+    config = build_project_config(choices)
+
+    try:
+        result = write_init_files(config, project_dir, overwrite=force)
+    except FileExistsError as exc:
+        err_console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    console.print(f"\n[green]Wrote {result.yaml_path}[/green]")
+    console.print(f"[green]Wrote {result.rule_path}[/green]")
+    if result.legacy_backup is not None:
+        console.print(
+            f"[yellow]Backed up legacy rule to {result.legacy_backup}.[/yellow]\n"
+            f"Review and delete the .bak when you're satisfied with the new rule."
+        )
+
+
+@config_app.command("regenerate")
+def config_regenerate(
+    project_dir: Path = typer.Option(
+        Path("."),
+        "--dir",
+        "-d",
+        help="Project directory (defaults to cwd).",
+        file_okay=False,
+    ),
+):
+    """Re-render `.claude/rules/memoryhub-loading.md` from `.memoryhub.yaml`.
+
+    Use this after editing the YAML by hand to refresh the rule file
+    without running the interactive prompt again.
+    """
+    project_dir = project_dir.resolve()
+    yaml_path = project_dir / CONFIG_FILENAME
+    if not yaml_path.is_file():
+        err_console.print(
+            f"[red]No {CONFIG_FILENAME} in {project_dir}.[/red]\n"
+            "Run [bold]memoryhub config init[/bold] first."
+        )
+        raise typer.Exit(1)
+
+    try:
+        config = load_project_config(yaml_path)
+    except ConfigError as exc:
+        err_console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    result = rewrite_rule_file(config, project_dir)
+    console.print(f"[green]Regenerated {result.rule_path}[/green]")
+    if result.legacy_backup is not None:
+        console.print(
+            f"[yellow]Backed up legacy rule to {result.legacy_backup}.[/yellow]"
+        )
+
+
+if __name__ == "__main__":
+    app()

memoryhub_cli/project_config.py

@@ -0,0 +1,417 @@
+"""Project-config scaffolding for `memoryhub config init`.
+
+Pure functions that build a :class:`memoryhub.ProjectConfig` from a set
+of choices and render the corresponding `.memoryhub.yaml` and
+`.claude/rules/memoryhub-loading.md` files.
+
+The interactive prompting lives in :mod:`memoryhub_cli.main`; everything
+in this module is testable without I/O of its own.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from memoryhub import (
+    CONFIG_FILENAME,
+    MemoryLoadingConfig,
+    ProjectConfig,
+    RetrievalDefaults,
+)
+
+# ── Choices captured from the interactive prompt ─────────────────────────────
+
+
+SessionShape = Literal["focused", "broad", "adaptive"]
+LoadingPattern = Literal["eager", "lazy", "lazy_with_rebias", "jit"]
+FocusSource = Literal["declared", "directory", "first_turn", "auto"]
+
+
+@dataclass(frozen=True)
+class InitChoices:
+    """Answers collected from the interactive prompt.
+
+    Decoupled from :class:`ProjectConfig` so the prompt and the schema
+    can evolve independently. ``session_shape`` is captured for the
+    rule-file template (it shapes the introductory prose) but maps onto
+    the ``memory_loading.mode`` field.
+    """
+
+    session_shape: SessionShape
+    pattern: LoadingPattern
+    focus_source: FocusSource
+    cross_domain_contradiction_detection: bool
+
+
+# ── Defaults that the prompt suggests based on session shape ─────────────────
+
+
+_PATTERN_FOR_SHAPE: dict[SessionShape, LoadingPattern] = {
+    "focused": "lazy",
+    "broad": "eager",
+    "adaptive": "lazy_with_rebias",
+}
+
+_MODE_FOR_SHAPE: dict[SessionShape, Literal["focused", "broad"]] = {
+    "focused": "focused",
+    "broad": "broad",
+    "adaptive": "focused",
+}
+
+
+def suggest_pattern(shape: SessionShape) -> LoadingPattern:
+    """Return the recommended pattern for a given session shape."""
+    return _PATTERN_FOR_SHAPE[shape]
+
+
+# ── Schema construction ──────────────────────────────────────────────────────
+
+
+def build_project_config(choices: InitChoices) -> ProjectConfig:
+    """Translate user choices into a :class:`ProjectConfig`.
+
+    The ``session_focus_weight`` and Pattern E knobs use schema defaults;
+    the prompt does not surface them in v1 to keep the interaction
+    short. Users can edit ``.memoryhub.yaml`` directly to tune them and
+    re-run ``memoryhub config regenerate``.
+    """
+    return ProjectConfig(
+        memory_loading=MemoryLoadingConfig(
+            mode=_MODE_FOR_SHAPE[choices.session_shape],
+            pattern=choices.pattern,
+            focus_source=choices.focus_source,
+            cross_domain_contradiction_detection=(
+                choices.cross_domain_contradiction_detection
+            ),
+        ),
+        retrieval_defaults=RetrievalDefaults(),
+    )
+
+
+# ── YAML serialization ───────────────────────────────────────────────────────
+
+
+_YAML_HEADER = (
+    "# MemoryHub project configuration\n"
+    "#\n"
+    "# Generated by `memoryhub config init`. Edit by hand and run\n"
+    "# `memoryhub config regenerate` to refresh the rule file.\n"
+    "#\n"
+    "# Schema reference: docs/agent-memory-ergonomics/design.md\n"
+    "\n"
+)
+
+
+def render_yaml(config: ProjectConfig) -> str:
+    """Serialize a ProjectConfig to YAML with a generator banner."""
+    body = yaml.safe_dump(
+        config.model_dump(),
+        sort_keys=False,
+        default_flow_style=False,
+    )
+    return _YAML_HEADER + body
+
+
+# ── Rule-file templates ──────────────────────────────────────────────────────
+#
+# The wording of these templates matters more than the YAML config — they are
+# the actual instructions the consuming agent reads. Each template is fully
+# self-contained: session start, during-session, memory hygiene, and
+# contradiction handling. The pattern-specific session-start and
+# during-session sections are the only parts that vary; hygiene and
+# contradiction handling are shared.
+
+
+_RULE_HEADER = """\
+# MemoryHub Loading: {pattern_title}
+
+This project uses MemoryHub for persistent, centralized agent memory across
+conversations. You MUST use it.
+
+This rule was generated by `memoryhub config init` from `.memoryhub.yaml`.
+Re-run `memoryhub config regenerate` after editing the YAML to refresh this
+file. Do not hand-edit this file directly — your changes will be overwritten.
+"""
+
+
+_PATTERN_BLOCKS: dict[LoadingPattern, str] = {
+    "eager": """\
+## At session start
+
+1. Call `register_session(api_key="<your-api-key>")` to authenticate.
+2. Immediately call `search_memory(query="", mode="index", max_results=50)`
+   to load the full working set as lightweight stubs. The empty query plus
+   `mode="index"` returns headers for everything visible to your user.
+3. Hold the returned working set in context for the entire session.
+
+## During the session
+
+- When a stub looks load-bearing for the current task, call `read_memory`
+  to expand it into full content.
+- New writes (your own or another agent's) are NOT pushed automatically.
+  If a decision depends on the latest state, call `search_memory` again
+  rather than trusting the working set you loaded at session start.
+""",
+    "lazy": """\
+## At session start
+
+Call `register_session(api_key="<your-api-key>")` to authenticate. Do NOT
+call `search_memory` yet — your working set is empty until the first user
+turn arrives.
+
+## After the first user turn
+
+Derive a 1-2 sentence summary of the user's intent from the opening
+message. Call `search_memory(query=<summary>)`. Use the returned memories
+as your working set for the session.
+
+## During the session
+
+- Trust your working set. Re-search only when the user explicitly
+  references a concept you don't have loaded.
+- If the opening turn was vague ("can you take a look at this?"), your
+  working set may miss relevant memories. Watch for it and re-search with
+  a more specific query as soon as the topic firms up.
+""",
+    "lazy_with_rebias": """\
+## At session start
+
+Call `register_session(api_key="<your-api-key>")` to authenticate. Do NOT
+call `search_memory` yet.
+
+## After the first user turn
+
+Derive a 1-2 sentence summary of the user's intent from the opening
+message. Call `search_memory(query=<summary>)`. Use the returned memories
+as your working set for the session.
+
+## During the session — watch for pivots
+
+A pivot is any of:
+
+1. **Subsystem change** — the user changes topic to a different area of
+   the project (e.g., from "deployment" to "UI", or from "MCP server" to
+   "SDK").
+2. **Unknown concept** — the user references a project-specific term that
+   isn't in your working set.
+3. **Explicit switch** — the user says "let's switch to...", "now let's
+   talk about...", or similar phrasing.
+
+When you detect a pivot, call `search_memory` with a query for the new
+topic. **ADD the results to your working set; do not replace it.** The
+prior topic may come back later in the same session, and the agent should
+not have to re-search for memories it already saw.
+""",
+    "jit": """\
+## At session start
+
+Call `register_session(api_key="<your-api-key>")` to authenticate. Do NOT
+call `search_memory`. There is no working set in this pattern.
+
+## During the session
+
+- Call `search_memory` only when you encounter a question whose answer
+  might be in memory. Each search is one-shot.
+- Triggers that warrant a search: the user asks "what did we decide
+  about X?", references a project-specific term you don't recognize, or
+  asks for a recommendation that should reflect prior decisions.
+- After acting on a search result, let it drop from context once the
+  immediate question is answered. Do not accumulate a working set.
+
+This pattern minimizes startup token cost at the price of missing
+implicit context. Use it for narrow one-shot tooling sessions.
+""",
+}
+
+
+_HYGIENE_BLOCK = """\
+## Memory hygiene
+
+- Keep memories concise and self-contained. Another agent should
+  understand them without re-loading the conversation that produced them.
+- DO write preferences, decisions, architectural choices, tool
+  configuration, and workflow patterns. Skip ephemeral things like "user
+  asked me to read a file."
+- Use `update_memory` (not `write_memory`) to revise an existing entry —
+  this preserves version history. Use `write_memory` only for new facts.
+- Set weights deliberately: `1.0` for critical policies, `0.8-0.9` for
+  strong preferences, `0.5-0.7` for nice-to-know context.
+- Add rationale branches via `parent_id` + `branch_type="rationale"` when
+  the "why" behind a preference is load-bearing.
+- Use the right scope: `user` for personal preferences, `project` for
+  project-specific context, `organizational` for team/org patterns,
+  `enterprise` for mandated policies.
+"""
+
+
+_CONTRADICTION_ENABLED = """\
+## Contradiction handling
+
+When you notice the user's behavior contradicting a memory you have
+loaded, call `report_contradiction` with the memory_id and a one-sentence
+description of the observed behavior. The server tracks contradiction
+counts and surfaces stale memories for review.
+"""
+
+
+_CONTRADICTION_DISABLED = """\
+## Contradiction handling
+
+This project runs with `cross_domain_contradiction_detection: false` in
+`.memoryhub.yaml`, which means you only catch contradictions for memories
+inside your current working set. Memories from other domains will not be
+checked — that's a deliberate tradeoff for token efficiency over coverage.
+
+When you DO notice a contradiction with a loaded memory, call
+`report_contradiction` with the memory_id and a one-sentence description.
+"""
+
+
+_PATTERN_TITLES: dict[LoadingPattern, str] = {
+    "eager": "Eager",
+    "lazy": "Lazy",
+    "lazy_with_rebias": "Lazy + Rebias on Pivot",
+    "jit": "Just-in-Time",
+}
+
+
+def render_rule_file(config: ProjectConfig) -> str:
+    """Render the full `.claude/rules/memoryhub-loading.md` for a config."""
+    pattern = config.memory_loading.pattern
+    pattern_block = _PATTERN_BLOCKS[pattern]
+    contradiction_block = (
+        _CONTRADICTION_ENABLED
+        if config.memory_loading.cross_domain_contradiction_detection
+        else _CONTRADICTION_DISABLED
+    )
+    return "\n".join(
+        [
+            _RULE_HEADER.format(pattern_title=_PATTERN_TITLES[pattern]),
+            pattern_block,
+            _HYGIENE_BLOCK,
+            contradiction_block,
+        ]
+    )
+
+
+# ── Filesystem helpers ───────────────────────────────────────────────────────
+
+
+@dataclass
+class WriteResult:
+    """Outcome of writing the project config + rule file to disk."""
+
+    yaml_path: Path
+    rule_path: Path
+    legacy_backup: Path | None  # set when an old memoryhub-integration.md was moved
+
+
+LEGACY_RULE_NAME = "memoryhub-integration.md"
+GENERATED_RULE_NAME = "memoryhub-loading.md"
+
+
+def _backup_legacy_rule(rules_dir: Path) -> Path | None:
+    """Move any existing memoryhub-integration.md aside to a .bak file.
+
+    Returns the backup path, or None if no legacy file existed. Preserves
+    multiple backups by appending a numeric suffix when a .bak already
+    exists from an earlier run.
+    """
+    legacy = rules_dir / LEGACY_RULE_NAME
+    if not legacy.exists():
+        return None
+    backup = legacy.with_suffix(legacy.suffix + ".bak")
+    n = 1
+    while backup.exists():
+        backup = legacy.with_suffix(f"{legacy.suffix}.bak.{n}")
+        n += 1
+    legacy.rename(backup)
+    return backup
+
+
+def write_init_files(
+    config: ProjectConfig,
+    project_dir: Path,
+    *,
+    overwrite: bool = False,
+) -> WriteResult:
+    """Write both `.memoryhub.yaml` and the generated rule file.
+
+    Used by `memoryhub config init`. The regenerate flow uses
+    :func:`rewrite_rule_file` instead so it does not clobber the
+    user-edited YAML.
+
+    Raises:
+        FileExistsError: If either generated file already exists and
+            ``overwrite`` is False. The legacy rule file is always
+            backed up (never silently overwritten).
+    """
+    project_dir = Path(project_dir)
+    yaml_path = project_dir / CONFIG_FILENAME
+    rules_dir = project_dir / ".claude" / "rules"
+    rule_path = rules_dir / GENERATED_RULE_NAME
+
+    if not overwrite:
+        for existing in (yaml_path, rule_path):
+            if existing.exists():
+                raise FileExistsError(
+                    f"{existing} already exists. Re-run with --force to overwrite."
+                )
+
+    rules_dir.mkdir(parents=True, exist_ok=True)
+    legacy_backup = _backup_legacy_rule(rules_dir)
+
+    yaml_path.write_text(render_yaml(config))
+    rule_path.write_text(render_rule_file(config))
+
+    return WriteResult(
+        yaml_path=yaml_path,
+        rule_path=rule_path,
+        legacy_backup=legacy_backup,
+    )
+
+
+def rewrite_rule_file(
+    config: ProjectConfig,
+    project_dir: Path,
+) -> WriteResult:
+    """Rewrite only the rule file from a config; leave .memoryhub.yaml alone.
+
+    Used by `memoryhub config regenerate` after the user edits the YAML
+    by hand. The legacy rule file is still backed up if present.
+    """
+    project_dir = Path(project_dir)
+    yaml_path = project_dir / CONFIG_FILENAME
+    rules_dir = project_dir / ".claude" / "rules"
+    rule_path = rules_dir / GENERATED_RULE_NAME
+
+    rules_dir.mkdir(parents=True, exist_ok=True)
+    legacy_backup = _backup_legacy_rule(rules_dir)
+
+    rule_path.write_text(render_rule_file(config))
+
+    return WriteResult(
+        yaml_path=yaml_path,
+        rule_path=rule_path,
+        legacy_backup=legacy_backup,
+    )
+
+
+__all__ = [
+    "InitChoices",
+    "SessionShape",
+    "LoadingPattern",
+    "FocusSource",
+    "WriteResult",
+    "GENERATED_RULE_NAME",
+    "LEGACY_RULE_NAME",
+    "build_project_config",
+    "render_yaml",
+    "render_rule_file",
+    "rewrite_rule_file",
+    "suggest_pattern",
+    "write_init_files",
+]

memoryhub_cli-0.1.1.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: memoryhub-cli
+Version: 0.1.1
+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: memoryhub>=0.1.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
+```
+
+## Usage
+
+```bash
+# Authenticate to a MemoryHub instance
+memoryhub login
+
+# Search for memories
+memoryhub search "deployment patterns"
+
+# Read a specific memory
+memoryhub read <memory-id>
+
+# Write a new memory
+memoryhub write "Use Podman, not Docker" --scope user --weight 0.9
+
+# Set up project-level memory loading
+memoryhub config init
+memoryhub config regenerate
+```
+
+## 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)**

memoryhub_cli-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+memoryhub_cli/__init__.py,sha256=qpv8--Pq9bszQpeJomDelIVQkg-cHIabTJ4fPq7m_O8,51
+memoryhub_cli/config.py,sha256=fvAJilz5OaknpbPQ8ZXCGTF96XzbwxTMNCmT4QlwD7Y,1342
+memoryhub_cli/main.py,sha256=ZZn2bVC0qODznmIimbg7PBoSilbO9YAKHw1K-VaLsqs,15292
+memoryhub_cli/project_config.py,sha256=QAgiL29Xb78ahak7YdszAu3Br9B0SHoOrWgSzcROnDE,14239
+memoryhub_cli-0.1.1.dist-info/METADATA,sha256=cs9Fl_zll4QUvXmp9PjU25t4i3PY2r-fm1et72xbyTM,3737
+memoryhub_cli-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+memoryhub_cli-0.1.1.dist-info/entry_points.txt,sha256=eXwBBQKrI_bBPPBxLrwGIlJr7wb3lTO9IrtmtA1c_ns,53
+memoryhub_cli-0.1.1.dist-info/RECORD,,

memoryhub_cli-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

memoryhub_cli-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memoryhub = memoryhub_cli.main:app