ravmem-cli 0.1.0__py3-none-any.whl

ravmem/cli/kg.py

@@ -0,0 +1,787 @@
+"""ravmem kg — knowledge graph management subcommands."""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from typing import Optional
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+app = typer.Typer(
+    name="kg",
+    help="Knowledge graph management — browse, curate, and query agent memory.",
+    no_args_is_help=True,
+)
+
+_console = Console()
+_err = Console(stderr=True)
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _load_server_cfg(remote: str) -> tuple[str, str | None]:
+    """Return (server_url, api_key) from --remote override or ~/.ravmem/client.json."""
+    if remote:
+        return remote.rstrip("/"), None
+    import os
+    cfg_path = os.path.expanduser("~/.ravmem/client.json")
+    if not os.path.exists(cfg_path):
+        _err.print("[red]No server configured.[/red] Run: ravmem remote config --url <URL>")
+        raise typer.Exit(1)
+    with open(cfg_path) as f:
+        data = _json.load(f)
+    url = data.get("server_url", "").rstrip("/")
+    if not url:
+        _err.print("[red]server_url missing in client.json.[/red] Run: ravmem remote config --url <URL>")
+        raise typer.Exit(1)
+    return url, data.get("api_key") or None
+
+
+def _kg_client(remote: str, team: str, branch: str):
+    """Return an httpx.Client with KG session headers pre-set."""
+    import httpx
+    url, api_key = _load_server_cfg(remote)
+    headers = {
+        "X-KG-Team": team,
+        "X-KG-Branch": branch,
+        "Content-Type": "application/json",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return url, httpx.Client(base_url=url, headers=headers, timeout=15.0)
+
+
+def _kg_get(remote: str, team: str, branch: str, path: str, params: dict | None = None) -> dict | list:
+    url, client = _kg_client(remote, team, branch)
+    with client:
+        resp = client.get(path, params=params or {})
+        if resp.status_code == 404:
+            _err.print(f"[yellow]Not found:[/yellow] {path}")
+            raise typer.Exit(1)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _kg_post(remote: str, team: str, branch: str, path: str, body: dict) -> dict:
+    url, client = _kg_client(remote, team, branch)
+    with client:
+        resp = client.post(path, json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _kg_patch(remote: str, team: str, branch: str, path: str, body: dict) -> dict:
+    url, client = _kg_client(remote, team, branch)
+    with client:
+        resp = client.patch(path, json=body)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _kg_delete(remote: str, team: str, branch: str, path: str) -> dict:
+    url, client = _kg_client(remote, team, branch)
+    with client:
+        resp = client.delete(path)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _trunc(s: str, n: int) -> str:
+    s = str(s or "")
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _print_node_table(nodes: list[dict], title: str = "") -> None:
+    t = Table(box=box.SIMPLE, title=title or None, show_header=True, header_style="bold")
+    t.add_column("ID", style="dim", width=10)
+    t.add_column("Type", width=12)
+    t.add_column("Label", width=55)
+    t.add_column("Conf", width=5, justify="right")
+    t.add_column("Source", width=8)
+    t.add_column("Created", width=19)
+    for n in nodes:
+        conf = n.get("confidence")
+        conf_str = f"{conf:.2f}" if conf is not None else "—"
+        t.add_row(
+            n.get("id", "")[:8],
+            n.get("type", ""),
+            _trunc(n.get("label", ""), 55),
+            conf_str,
+            n.get("source", ""),
+            str(n.get("created_at", ""))[:19],
+        )
+    _console.print(t)
+
+
+def _print_node_detail(node: dict) -> None:
+    lines = []
+    for k in ("id", "type", "label", "scope", "branch", "team_id", "source",
+              "author_id", "active", "confidence", "validated_by_human",
+              "origin_node_id", "created_at", "updated_at"):
+        v = node.get(k)
+        if v is not None:
+            lines.append(f"[bold]{k}[/bold]: {v}")
+    # Extra properties
+    skip = {"id", "type", "label", "scope", "branch", "team_id", "source",
+            "author_id", "active", "confidence", "validated_by_human",
+            "origin_node_id", "created_at", "updated_at"}
+    for k, v in node.items():
+        if k not in skip and v is not None:
+            lines.append(f"[bold]{k}[/bold]: {v}")
+    _console.print(Panel("\n".join(lines), title=f"[cyan]{node.get('type', 'Node')}[/cyan] {node.get('id', '')[:8]}"))
+
+
+# ---------------------------------------------------------------------------
+# Existing commands (init, config) — unchanged
+# ---------------------------------------------------------------------------
+
+@app.command("init")
+def init_cmd(
+    team: str = typer.Option("default", "--team", "-t", help="Team identifier for this KGConfig"),
+    branch: str = typer.Option("global", "--branch", "-b", help="Knowledge branch to configure"),
+    remote: str = typer.Option("", "--remote", "-r", help="Server URL (overrides client.json)"),
+):
+    """Interactive wizard to initialise or reconfigure the knowledge graph."""
+    from ravmem.knowledge.init import run_init
+
+    existing_cfg = None
+    server_url = remote
+
+    if not server_url:
+        try:
+            server_url, _ = _load_server_cfg("")
+        except typer.Exit:
+            server_url = ""
+
+    if server_url:
+        try:
+            import httpx
+            from ravmem.knowledge.config import KGConfig
+            resp = httpx.get(
+                f"{server_url}/api/knowledge/config",
+                params={"team_id": team, "branch": branch},
+                timeout=5,
+            )
+            if resp.status_code == 200:
+                data = resp.json()
+                existing_cfg = KGConfig(
+                    team_id=data.get("team_id", team),
+                    branch=data.get("branch", branch),
+                    mode=data.get("mode", "hitl"),
+                    confidence_enabled=data.get("confidence_enabled", True),
+                    hitl_ai_cap=data.get("hitl_ai_cap", 0.70),
+                    auto_ai_cap=data.get("auto_ai_cap", 1.0),
+                    disabled_node_types=data.get("disabled_node_types", []),
+                )
+        except Exception:
+            pass
+
+    def _save(cfg):
+        if not server_url:
+            typer.echo("Warning: no server configured — config not persisted.", err=True)
+            return
+        try:
+            import httpx
+            resp = httpx.post(f"{server_url}/api/knowledge/config", json=cfg.to_dict(), timeout=5)
+            resp.raise_for_status()
+        except Exception as exc:
+            typer.echo(f"Failed to save config: {exc}", err=True)
+            raise typer.Exit(1)
+
+    run_init(team_id=team, branch=branch, existing_cfg=existing_cfg,
+             save_fn=_save if server_url else None)
+
+
+@app.command("config")
+def config_cmd(
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Show current knowledge graph configuration from the server."""
+    try:
+        data = _kg_get(remote, team, branch, "/api/knowledge/config",
+                       params={"team_id": team, "branch": branch})
+    except typer.Exit:
+        typer.echo("No config found. Run: ravmem kg init")
+        return
+
+    t = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    t.add_column("Setting", style="bold")
+    t.add_column("Value")
+    t.add_row("Team", data.get("team_id", team))
+    t.add_row("Branch", data.get("branch", branch))
+    t.add_row("Mode", data.get("mode", "?").upper())
+    t.add_row("Confidence scoring", "enabled" if data.get("confidence_enabled", True) else "disabled")
+    t.add_row("HITL AI cap", str(data.get("hitl_ai_cap", "?")))
+    t.add_row("Auto AI cap", str(data.get("auto_ai_cap", "?")))
+    disabled = data.get("disabled_node_types", [])
+    if disabled:
+        t.add_row("Disabled node types", ", ".join(disabled))
+    _console.print(t)
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 — Browse and inspect
+# ---------------------------------------------------------------------------
+
+@app.command("list")
+def list_cmd(
+    node_type: Optional[str] = typer.Option(None, "--type", "-T",
+        help="Filter by type: instruction|condition|learning|decision|task|blocker|context|taskpattern"),
+    scope: Optional[str] = typer.Option(None, "--scope", "-s",
+        help="Filter by scope: global | project:<id> | task_type:<pattern>"),
+    all_nodes: bool = typer.Option(False, "--all", "-a",
+        help="Include inactive nodes (default: active only)"),
+    limit: int = typer.Option(50, "--limit", "-n"),
+    output_json: bool = typer.Option(False, "--json", help="Raw JSON output"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """List knowledge graph nodes."""
+    params: dict = {"limit": limit}
+    if node_type:
+        params["node_type"] = node_type
+    if scope:
+        params["scope"] = scope
+    if all_nodes:
+        params["active_only"] = "false"
+
+    data = _kg_get(remote, team, branch, "/api/knowledge/nodes", params=params)
+    nodes = data if isinstance(data, list) else data.get("nodes", [])
+
+    if output_json:
+        typer.echo(_json.dumps(nodes, indent=2, default=str))
+        return
+
+    if not nodes:
+        typer.echo("No nodes found.")
+        return
+
+    label = f"{len(nodes)} node(s)"
+    if node_type:
+        label += f" — type={node_type}"
+    _print_node_table(nodes, title=label)
+
+
+@app.command("get")
+def get_cmd(
+    node_id: str = typer.Argument(..., help="Node ID (full or 8-char prefix)"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Show full details for a single knowledge node."""
+    node = _kg_get(remote, team, branch, f"/api/knowledge/nodes/{node_id}")
+    if output_json:
+        typer.echo(_json.dumps(node, indent=2, default=str))
+        return
+    _print_node_detail(node)
+
+
+@app.command("search")
+def search_cmd(
+    query: str = typer.Argument(..., help="Search query"),
+    limit: int = typer.Option(10, "--limit", "-n"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Search knowledge nodes by keyword."""
+    data = _kg_get(remote, team, branch, "/api/knowledge/search",
+                   params={"q": query, "limit": limit,
+                           "team_id": team, "branch": branch})
+    nodes = data if isinstance(data, list) else data.get("results", [])
+
+    if output_json:
+        typer.echo(_json.dumps(nodes, indent=2, default=str))
+        return
+
+    if not nodes:
+        typer.echo(f"No results for '{query}'.")
+        return
+
+    _print_node_table(nodes, title=f"Results for '{query}'")
+
+
+@app.command("delete")
+def delete_cmd(
+    node_id: str = typer.Argument(..., help="Node ID to soft-delete (deactivate)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Soft-delete (deactivate) a knowledge node."""
+    if not yes:
+        typer.confirm(f"Deactivate node {node_id!r}?", abort=True)
+    _kg_delete(remote, team, branch, f"/api/knowledge/nodes/{node_id}")
+    typer.echo(f"Node {node_id} deactivated.")
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — Human workflow: instructions, conditions, learnings
+# ---------------------------------------------------------------------------
+
+@app.command("set-instruction")
+def set_instruction_cmd(
+    text: str = typer.Argument(..., help="Instruction text"),
+    priority: str = typer.Option("medium", "--priority", "-p",
+        help="Priority: critical | high | medium | low"),
+    scope: str = typer.Option("global", "--scope", "-s",
+        help="Scope: global | project:<id> | task_type:<pattern>"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Create a human-authored instruction rule."""
+    body = {
+        "label": text,
+        "priority": priority,
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+    }
+    result = _kg_post(remote, team, branch, "/api/knowledge/instructions", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    node_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Instruction created: {node_id}")
+    typer.echo(f"  Priority : {priority}")
+    typer.echo(f"  Scope    : {scope}")
+    typer.echo(f"  Text     : {text}")
+
+
+@app.command("set-condition")
+def set_condition_cmd(
+    when: str = typer.Option(..., "--when", "-w", help="Trigger condition (if clause)"),
+    then: str = typer.Option(..., "--then", "-t", help="Action to take (then clause)"),
+    scope: str = typer.Option("global", "--scope", "-s"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Create an if/then condition rule."""
+    body = {
+        "label": f"IF {when} THEN {then}",
+        "when_clause": when,
+        "then_clause": then,
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+    }
+    result = _kg_post(remote, team, branch, "/api/knowledge/conditions", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    node_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Condition created: {node_id}")
+    typer.echo(f"  When : {when}")
+    typer.echo(f"  Then : {then}")
+
+
+@app.command("validate-learning")
+def validate_learning_cmd(
+    learning_id: str = typer.Argument(..., help="Learning node ID"),
+    accept: bool = typer.Option(False, "--accept", "-a", help="Accept the learning"),
+    reject: bool = typer.Option(False, "--reject", "-r", help="Reject the learning"),
+    confidence: Optional[float] = typer.Option(None, "--confidence", "-c",
+        help="Override confidence (0.0–1.0, accept only)"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Accept or reject an AI-generated learning."""
+    if not accept and not reject:
+        _err.print("[red]Specify --accept or --reject.[/red]")
+        raise typer.Exit(1)
+    if accept and reject:
+        _err.print("[red]Specify only one of --accept or --reject.[/red]")
+        raise typer.Exit(1)
+
+    body: dict = {"accepted": accept}
+    if confidence is not None and accept:
+        body["confidence"] = confidence
+
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/learnings/{learning_id}/validate", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    verdict = "accepted" if accept else "rejected"
+    typer.echo(f"Learning {learning_id} {verdict}.")
+    if accept and confidence is not None:
+        typer.echo(f"  Confidence set to {confidence}")
+
+
+@app.command("override-instruction")
+def override_instruction_cmd(
+    instruction_id: str = typer.Argument(..., help="ID of the instruction to replace"),
+    text: str = typer.Argument(..., help="New instruction text"),
+    priority: str = typer.Option("medium", "--priority", "-p"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Replace an instruction (deactivates the original, creates a new one)."""
+    body = {
+        "label": text,
+        "priority": priority,
+        "team_id": team,
+        "branch": branch,
+    }
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/instructions/{instruction_id}/override", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    new_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Instruction {instruction_id} overridden → new ID: {new_id}")
+    typer.echo(f"  Text     : {text}")
+    typer.echo(f"  Priority : {priority}")
+
+
+@app.command("promote")
+def promote_cmd(
+    learning_id: str = typer.Argument(..., help="Learning node ID to promote to Instruction"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Promote a validated learning to an instruction."""
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/learnings/{learning_id}/promote", {})
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    new_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Learning {learning_id} promoted to Instruction: {new_id}")
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 — Task lifecycle
+# ---------------------------------------------------------------------------
+
+@app.command("start-task")
+def start_task_cmd(
+    label: str = typer.Argument(..., help="Task description"),
+    task_type: str = typer.Option("general", "--type", "-T", help="Task type / pattern key"),
+    scope: str = typer.Option("global", "--scope", "-s"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Register a new task and load its context (instructions + conditions)."""
+    body = {
+        "label": label,
+        "task_type": task_type,
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+    }
+    result = _kg_post(remote, team, branch, "/api/knowledge/tasks", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    task_id = result.get("id", result.get("task_id", "?"))
+    typer.echo(f"Task started: {task_id}")
+    typer.echo(f"  Label : {label}")
+    typer.echo(f"  Type  : {task_type}")
+    typer.echo(f"  Scope : {scope}")
+    typer.echo(f"\nLoad context with: ravmem kg load-context {task_id}")
+
+
+@app.command("complete-task")
+def complete_task_cmd(
+    task_id: str = typer.Argument(..., help="Task node ID"),
+    outcome: str = typer.Option("", "--outcome", "-o", help="Outcome description"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Mark a task as complete."""
+    body = {"outcome": outcome, "team_id": team, "branch": branch}
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/tasks/{task_id}/complete", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    typer.echo(f"Task {task_id} completed.")
+    if outcome:
+        typer.echo(f"  Outcome: {outcome}")
+
+
+@app.command("load-context")
+def load_context_cmd(
+    task_id: str = typer.Argument(..., help="Task node ID"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Run 6-step context resolution for a task (instructions, learnings, decisions, similar tasks)."""
+    ctx = _kg_get(remote, team, branch,
+                  f"/api/knowledge/tasks/{task_id}/context",
+                  params={"team_id": team, "branch": branch})
+    if output_json:
+        typer.echo(_json.dumps(ctx, indent=2, default=str))
+        return
+
+    def _section(title: str, nodes: list) -> None:
+        if not nodes:
+            return
+        _console.print(f"\n[bold cyan]{title}[/bold cyan] ({len(nodes)})")
+        for n in nodes:
+            label = n.get("label", n.get("text", ""))
+            nid = n.get("id", "")[:8]
+            conf = n.get("confidence")
+            conf_str = f"  conf={conf:.2f}" if conf is not None else ""
+            _console.print(f"  [dim]{nid}[/dim] {label}{conf_str}")
+
+    _console.rule(f"[bold]Context for task {task_id[:8]}[/bold]")
+    _section("Instructions", ctx.get("instructions", []))
+    _section("Conditions", ctx.get("conditions", []))
+    _section("Learnings", ctx.get("learnings", []))
+    _section("Decisions", ctx.get("decisions", []))
+    _section("Context nodes", ctx.get("context_nodes", []))
+    similar = ctx.get("similar_tasks", [])
+    if similar:
+        _console.print(f"\n[bold cyan]Similar past tasks[/bold cyan] ({len(similar)})")
+        for t in similar:
+            tid = t.get("id", "")[:8]
+            _console.print(f"  [dim]{tid}[/dim] {t.get('label', '')}")
+
+
+@app.command("log-learning")
+def log_learning_cmd(
+    text: str = typer.Argument(..., help="Learning text"),
+    domain: str = typer.Option("", "--domain", "-d", help="Knowledge domain"),
+    task_id: Optional[str] = typer.Option(None, "--task", help="Associated task ID"),
+    confidence: float = typer.Option(0.6, "--confidence", "-c", help="Initial confidence (0.0–1.0)"),
+    scope: str = typer.Option("global", "--scope", "-s"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Record a discovered learning."""
+    body: dict = {
+        "content": text,
+        "domain": domain,
+        "confidence": confidence,
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+        "source": "human",
+        "agent_id": "human",
+        "task_id": task_id or "",
+    }
+    result = _kg_post(remote, team, branch, "/api/knowledge/learnings", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    node_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Learning logged: {node_id}")
+    typer.echo(f"  Text       : {text}")
+    typer.echo(f"  Confidence : {confidence}")
+    if domain:
+        typer.echo(f"  Domain     : {domain}")
+
+
+@app.command("log-decision")
+def log_decision_cmd(
+    text: str = typer.Argument(..., help="Decision summary"),
+    rationale: str = typer.Option("", "--rationale", "-r", help="Why this decision was made"),
+    alternatives: str = typer.Option("", "--alternatives", "-a",
+        help="Comma-separated alternatives that were considered"),
+    task_id: Optional[str] = typer.Option(None, "--task", help="Associated task ID"),
+    scope: str = typer.Option("global", "--scope", "-s"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Record an architectural or implementation decision."""
+    body: dict = {
+        "label": text,
+        "rationale": rationale,
+        "alternatives": [a.strip() for a in alternatives.split(",") if a.strip()],
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+        "source": "human",
+    }
+    if task_id:
+        body["task_id"] = task_id
+    result = _kg_post(remote, team, branch, "/api/knowledge/decisions", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    node_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Decision logged: {node_id}")
+    typer.echo(f"  Decision     : {text}")
+    if rationale:
+        typer.echo(f"  Rationale    : {rationale}")
+    if alternatives:
+        typer.echo(f"  Alternatives : {alternatives}")
+
+
+@app.command("mark-blocked")
+def mark_blocked_cmd(
+    reason: str = typer.Argument(..., help="Description of the blocker"),
+    task_id: Optional[str] = typer.Option(None, "--task", help="Associated task ID"),
+    scope: str = typer.Option("global", "--scope", "-s"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Create a blocker node linked to a task."""
+    body: dict = {
+        "label": reason,
+        "scope": scope,
+        "team_id": team,
+        "branch": branch,
+        "source": "human",
+    }
+    if task_id:
+        body["task_id"] = task_id
+    result = _kg_post(remote, team, branch, "/api/knowledge/blockers", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    node_id = result.get("id", result.get("node_id", "?"))
+    typer.echo(f"Blocker created: {node_id}")
+    typer.echo(f"  Reason : {reason}")
+    typer.echo(f"\nResolve with: ravmem kg resolve-blocker {node_id}")
+
+
+@app.command("resolve-blocker")
+def resolve_blocker_cmd(
+    blocker_id: str = typer.Argument(..., help="Blocker node ID"),
+    decision_id: Optional[str] = typer.Option(None, "--decision", "-d",
+        help="Optional Decision node ID that resolved this blocker"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Mark a blocker as resolved."""
+    body: dict = {"team_id": team, "branch": branch}
+    if decision_id:
+        body["decision_id"] = decision_id
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/blockers/{blocker_id}/resolve", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    typer.echo(f"Blocker {blocker_id} resolved.")
+    if decision_id:
+        typer.echo(f"  Linked decision: {decision_id}")
+
+
+# ---------------------------------------------------------------------------
+# Phase 4 — Advanced / power-user
+# ---------------------------------------------------------------------------
+
+@app.command("update")
+def update_cmd(
+    node_id: str = typer.Argument(..., help="Node ID to update"),
+    label: Optional[str] = typer.Option(None, "--label", "-l", help="New label/text"),
+    priority: Optional[str] = typer.Option(None, "--priority", "-p",
+        help="New priority (instruction nodes only)"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Update a node's properties (creates a CoW copy on the current branch)."""
+    body: dict = {}
+    if label:
+        body["label"] = label
+    if priority:
+        body["priority"] = priority
+    if not body:
+        _err.print("[red]Provide at least --label or --priority.[/red]")
+        raise typer.Exit(1)
+    result = _kg_patch(remote, team, branch, f"/api/knowledge/nodes/{node_id}", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    new_id = result.get("id", node_id)
+    typer.echo(f"Node updated → {new_id}")
+
+
+@app.command("corroborate")
+def corroborate_cmd(
+    learning_id: str = typer.Argument(..., help="Learning node ID"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Increment evidence count and nudge confidence on a learning."""
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/learnings/{learning_id}/corroborate", {})
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    conf = result.get("confidence")
+    ev = result.get("evidence_count")
+    typer.echo(f"Learning {learning_id} corroborated.")
+    if conf is not None:
+        typer.echo(f"  Confidence    : {conf:.2f}")
+    if ev is not None:
+        typer.echo(f"  Evidence count: {ev}")
+
+
+@app.command("link-symbols")
+def link_symbols_cmd(
+    node_id: str = typer.Argument(..., help="KG node ID"),
+    symbol_ids: list[str] = typer.Argument(..., help="One or more code graph Symbol IDs"),
+    output_json: bool = typer.Option(False, "--json"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Link a knowledge node to code graph symbols."""
+    body = {"symbol_ids": symbol_ids}
+    result = _kg_post(remote, team, branch,
+                      f"/api/knowledge/nodes/{node_id}/link-symbols", body)
+    if output_json:
+        typer.echo(_json.dumps(result, indent=2, default=str))
+        return
+    typer.echo(f"Node {node_id} linked to {len(symbol_ids)} symbol(s).")
+
+
+@app.command("set-mode")
+def set_mode_cmd(
+    mode: str = typer.Argument(..., help="Mode: hitl | auto"),
+    team: str = typer.Option("default", "--team", "-t"),
+    branch: str = typer.Option("global", "--branch", "-b"),
+    remote: str = typer.Option("", "--remote", "-r"),
+):
+    """Switch the knowledge graph between HITL and auto confidence modes."""
+    if mode not in ("hitl", "auto"):
+        _err.print("[red]Mode must be 'hitl' or 'auto'.[/red]")
+        raise typer.Exit(1)
+    body = {"mode": mode, "team_id": team, "branch": branch}
+    _kg_post(remote, team, branch, "/api/knowledge/config", body)
+    typer.echo(f"KG mode set to: {mode.upper()}")