@reconcrap/people-network-memory 0.1.0

package/src/people_network_memory/cli.py

@@ -0,0 +1,1212 @@
+"""Command line entrypoint for people-memory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+from dataclasses import replace
+from pathlib import Path
+
+from people_network_memory.config import PeopleMemoryConfig
+from people_network_memory.fixtures.eval import (
+    evaluate_dataset,
+    evaluate_retrieval_service,
+    evaluate_services,
+)
+from people_network_memory.fixtures.extractor_eval import evaluate_extractor
+from people_network_memory.fixtures.generator import generate_mock_dataset
+from people_network_memory.fixtures.report import write_eval_markdown_report
+from people_network_memory.harness_adapters.openclaw import (
+    install_openclaw_adapter,
+    openclaw_checks,
+)
+from people_network_memory.harness_adapters.openclaw.integration_eval import (
+    run_harness_memory_integration_eval,
+)
+from people_network_memory.harness_adapters.openclaw.smoke import run_openclaw_adapter_smoke
+from people_network_memory.infrastructure.archive_backup import (
+    create_archive_backup,
+    restore_archive_backup,
+)
+from people_network_memory.infrastructure.diagnostics import graphiti_spike_checks
+from people_network_memory.infrastructure.embeddings import check_embedding_provider
+from people_network_memory.infrastructure.file_store import JsonPeopleStore, local_json_path
+from people_network_memory.infrastructure.graphiti_promotion import run_graphiti_promotion_gate
+from people_network_memory.infrastructure.redaction import redact_sensitive_text
+from people_network_memory.infrastructure.release_check import run_local_release_check
+from people_network_memory.mcp_server.contracts import public_tool_contracts
+from people_network_memory.mcp_server.runtime import build_runtime
+from people_network_memory.ports.errors import PeopleMemoryError
+
+
+def _print_json(payload: object) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _write_json_output(payload: dict[str, object], output: str | None) -> None:
+    if not output:
+        _print_json(payload)
+        return
+    path = Path(output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+    _print_json(
+        {
+            "ok": payload.get("ok", True),
+            "output": str(path),
+            "checked": payload.get("checked"),
+            "passes_v1_thresholds": payload.get("passes_v1_thresholds"),
+        }
+    )
+
+
+def _config_from_args(args: argparse.Namespace, *, default_test_mode: bool = False) -> PeopleMemoryConfig:
+    config = PeopleMemoryConfig.from_env(
+        test_mode=bool(getattr(args, "test_mode", default_test_mode))
+    )
+    updates = {}
+    if getattr(args, "backend", None):
+        updates["backend"] = args.backend
+    if getattr(args, "data_path", None):
+        updates["data_path"] = args.data_path
+    if getattr(args, "graphiti_kuzu_path", None):
+        updates["graphiti_kuzu_path"] = args.graphiti_kuzu_path
+    if getattr(args, "retrieval_judge", None):
+        updates["retrieval_judge"] = args.retrieval_judge
+    if getattr(args, "ingestion_extractor", None):
+        updates["ingestion_extractor"] = args.ingestion_extractor
+    if getattr(args, "identity_advisor", None):
+        updates["identity_advisor"] = args.identity_advisor
+    if updates:
+        config = replace(config, **updates)
+    return config
+
+
+def _build_optional_retrieval_judge(config: PeopleMemoryConfig) -> object | None:
+    if config.retrieval_judge != "llm":
+        return None
+    from people_network_memory.infrastructure.llm_judge import OpenAICompatibleRetrievalJudge
+
+    return OpenAICompatibleRetrievalJudge.from_config(config)
+
+
+def _read_json_file(path: str) -> dict[str, object]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _cmd_start(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    runtime = build_runtime(config)
+    if args.once:
+        _print_json(
+            {
+                "status": "ok",
+                "service": "people-network-memory",
+                "backend": config.backend,
+                "test_mode": config.test_mode,
+                "tools": sorted(runtime.tools.tool_names()),
+            }
+        )
+        return 0
+    runtime.run_stdio()
+    return 0
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    checks = []
+    try:
+        config.validate_runtime()
+        checks.append({"name": "config", "ok": True})
+    except PeopleMemoryError as exc:
+        checks.append({"name": "config", "ok": False, "error": str(exc)})
+    checks.append(
+        {
+            "name": "telemetry",
+            "ok": not config.telemetry_enabled,
+            "detail": "GRAPHITI_TELEMETRY_ENABLED should be false for local personal data.",
+        }
+    )
+    data_path_check = {"name": "data_path", "ok": bool(config.data_path), "path": config.data_path}
+    if config.backend == "local_json":
+        target = local_json_path(config)
+        nearest = target.parent
+        while not nearest.exists() and nearest.parent != nearest:
+            nearest = nearest.parent
+        data_path_check["target"] = str(target)
+        data_path_check["nearest_existing_parent"] = str(nearest)
+        data_path_check["ok"] = bool(config.data_path) and nearest.exists()
+    checks.append(data_path_check)
+    if config.backend == "graphiti":
+        checks.extend(check.to_json() for check in graphiti_spike_checks(config))
+    if getattr(args, "agent", None) == "openclaw":
+        checks.extend(
+            check.to_json()
+            for check in openclaw_checks(
+                getattr(args, "openclaw_home", None) or "~/.openclaw"
+            )
+        )
+    ok = all(check["ok"] for check in checks)
+    _print_json({"ok": ok, "checks": checks})
+    return 0 if ok else 2
+
+
+def _cmd_load_fixtures(args: argparse.Namespace) -> int:
+    dataset = generate_mock_dataset(seed=args.seed)
+    payload = dataset.model_dump(mode="json")
+    if args.summary:
+        _print_json(dataset.summary())
+        return 0
+    if args.output:
+        path = Path(args.output)
+        path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        _print_json({"ok": True, "output": str(path), "summary": dataset.summary()})
+        return 0
+    _print_json(payload)
+    return 0
+
+
+def _cmd_eval_fixtures(args: argparse.Namespace) -> int:
+    dataset = generate_mock_dataset(seed=args.seed)
+    result = evaluate_dataset(
+        dataset,
+        max_interactions=args.max_interactions,
+        max_queries=args.max_queries,
+        only_answerable=not args.all_queries,
+    )
+    payload = result.to_json(
+        include_cases=args.include_cases or args.failures_only,
+        failures_only=args.failures_only,
+    )
+    _write_json_output(payload, args.output)
+    return 0 if payload["passes_v1_thresholds"] else 2
+
+
+def _cmd_spike_graphiti(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    checks = graphiti_spike_checks(config)
+    ok = all(check.ok for check in checks)
+    _print_json(
+        {
+            "ok": ok,
+            "gate": "graphiti_spike",
+            "checks": [check.to_json() for check in checks],
+            "next_step": (
+                "Run live Graphiti integration tests."
+                if ok
+                else "Resolve failed checks before committing to Graphiti as the substrate."
+            ),
+        }
+    )
+    return 0 if ok else 2
+
+
+def _cmd_check_embedding(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    result = check_embedding_provider(config, args.sample)
+    _print_json(result.to_json())
+    return 0 if result.ok else 2
+
+
+def _cmd_smoke_graphiti(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+    if args.isolated:
+        temp_dir = tempfile.TemporaryDirectory()
+        config = replace(
+            config,
+            data_path=temp_dir.name,
+            graphiti_kuzu_path=str(Path(temp_dir.name) / "graphiti.kuzu"),
+        )
+    else:
+        temp_dir = None
+    runtime = None
+    try:
+        runtime = build_runtime(config)
+        record_result = runtime.tools.record_interaction(
+            {
+                "source_text": (
+                    "Met Alice Zhang at Blue Bottle Coffee. We discussed robotics hiring. "
+                    "Alice mentioned Bob Li may be useful for founder intros."
+                ),
+                "interaction_type": "coffee",
+                "place": "Blue Bottle Coffee",
+                "participants": [
+                    {"person": {"label": "Alice Zhang", "person_id": "alice_zhang"}}
+                ],
+                "mentioned_people": [
+                    {
+                        "person": {"label": "Bob Li", "person_id": "bob_li"},
+                        "mentioned_by": {"label": "Alice Zhang", "person_id": "alice_zhang"},
+                        "context": "founder intros",
+                    }
+                ],
+                "topics": ["robotics hiring", "founder intros"],
+                "attributed_claims": [
+                    {
+                        "speaker": {"label": "Alice Zhang", "person_id": "alice_zhang"},
+                        "subject": {"label": "Bob Li", "person_id": "bob_li"},
+                        "claim_text": "Alice Zhang said Bob Li may be useful for founder intros.",
+                    }
+                ],
+            }
+        )
+        search_result = runtime.tools.retrieve_network_context(
+            {"query": "robotics person from Blue Bottle", "limit": 5}
+        )
+        payload = {
+            "ok": bool(search_result.get("results")),
+            "record_interaction": record_result,
+            "search_result_count": len(search_result.get("results", [])),
+            "top_results": search_result.get("results", [])[:3],
+        }
+        _print_json(payload)
+        return 0 if payload["ok"] else 2
+    finally:
+        if runtime is not None:
+            runtime.close()
+        if temp_dir is not None:
+            temp_dir.cleanup()
+
+
+def _cmd_eval_graphiti(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+    if args.isolated:
+        temp_dir = tempfile.TemporaryDirectory()
+        config = replace(
+            config,
+            data_path=temp_dir.name,
+            graphiti_kuzu_path=str(Path(temp_dir.name) / "graphiti.kuzu"),
+        )
+    else:
+        temp_dir = None
+    runtime = None
+    try:
+        dataset = generate_mock_dataset(seed=args.seed)
+        runtime = build_runtime(config)
+        result = evaluate_services(
+            dataset,
+            record_service=runtime.record_service,
+            retrieve_service=runtime.retrieve_service,
+            max_interactions=args.max_interactions,
+            max_queries=args.max_queries,
+            only_answerable=not args.all_queries,
+        )
+        payload = result.to_json(
+            include_cases=not args.no_cases or args.failures_only,
+            failures_only=args.failures_only,
+        )
+        payload.update(
+            {
+                "backend": "graphiti",
+                "isolated": args.isolated,
+                "fixture_summary": dataset.summary(),
+                "enforced_thresholds": args.enforce_thresholds,
+            }
+        )
+        _write_json_output(payload, args.output)
+        return 0 if (not args.enforce_thresholds or payload["passes_v1_thresholds"]) else 2
+    finally:
+        if runtime is not None:
+            runtime.close()
+        if temp_dir is not None:
+            temp_dir.cleanup()
+
+
+def _cmd_eval_graphiti_search(args: argparse.Namespace) -> int:
+    from people_network_memory.application.services import RetrieveContextService
+    from people_network_memory.graphiti_adapter.graphiti_store import GraphitiGraphStore
+
+    config = _config_from_args(args)
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+    graph_store = GraphitiGraphStore.from_config(config)
+    try:
+        dataset = generate_mock_dataset(seed=args.seed)
+        retrieve = RetrieveContextService(
+            graph_search=graph_store,
+            review_queue=graph_store,
+            default_sensitivity_policy=config.sensitivity_policy,
+            retrieval_judge=_build_optional_retrieval_judge(config),
+        )
+        indexed_interactions = (
+            args.indexed_interactions
+            if args.indexed_interactions is not None
+            else len(dataset.interactions)
+        )
+        result = evaluate_retrieval_service(
+            dataset,
+            retrieve_service=retrieve,
+            indexed_interactions=indexed_interactions,
+            max_queries=args.max_queries,
+            only_answerable=not args.all_queries,
+        )
+        payload = result.to_json(
+            include_cases=not args.no_cases or args.failures_only,
+            failures_only=args.failures_only,
+        )
+        payload.update(
+            {
+                "backend": "graphiti",
+                "mode": "search_existing_graph",
+                "seed": args.seed,
+                "graphiti_kuzu_path": config.graphiti_kuzu_path,
+                "indexed_interactions": indexed_interactions,
+                "retrieval_judge": config.retrieval_judge,
+                "enforced_thresholds": args.enforce_thresholds,
+            }
+        )
+        _write_json_output(payload, args.output)
+        if args.report_output:
+            write_eval_markdown_report(
+                payload,
+                args.report_output,
+                title=(
+                    "Graphiti Semantic Hybrid Retrieval Report"
+                    if config.retrieval_judge == "off"
+                    else "Graphiti Semantic Hybrid Retrieval Report With LLM Judge"
+                ),
+                compare_payload=_read_json_file(args.compare_report_input)
+                if args.compare_report_input
+                else None,
+            )
+        return 0 if (not args.enforce_thresholds or payload["passes_v1_thresholds"]) else 2
+    finally:
+        graph_store.close()
+
+
+def _cmd_report_eval(args: argparse.Namespace) -> int:
+    payload = _read_json_file(args.input)
+    compare_payload = _read_json_file(args.compare_input) if args.compare_input else None
+    write_eval_markdown_report(
+        payload,
+        args.output,
+        title=args.title,
+        compare_payload=compare_payload,
+    )
+    _print_json(
+        {
+            "ok": True,
+            "input": args.input,
+            "compare_input": args.compare_input,
+            "output": args.output,
+            "checked": payload.get("checked"),
+        }
+    )
+    return 0
+
+
+def _cmd_graphiti_gate(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    payload = run_graphiti_promotion_gate(
+        config,
+        seed=args.seed,
+        max_interactions=args.max_interactions,
+        max_queries=args.max_queries,
+        isolated=args.isolated,
+        include_cases=args.include_cases,
+        failures_only=args.failures_only,
+        skip_live=args.skip_live,
+        skip_embedding_check=args.skip_embedding_check,
+    )
+    _write_json_output(payload, args.output)
+    return 0 if payload["ok"] else 2
+
+
+def _cmd_index_graphiti(args: argparse.Namespace) -> int:
+    from people_network_memory.graphiti_adapter.indexer import index_local_json_to_graphiti
+
+    config = _config_from_args(args)
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+    payload = index_local_json_to_graphiti(
+        config,
+        source_data_path=args.source_data_path,
+        state_path=args.state_path,
+        limit=args.limit,
+        resume=not args.no_resume,
+        reset_state=args.reset_state,
+        continue_on_error=args.continue_on_error,
+    )
+    _write_json_output(payload, args.output)
+    return 0 if payload["ok"] else 2
+
+
+def _cmd_hydrate_graphiti_cache(args: argparse.Namespace) -> int:
+    from people_network_memory.application.services import RecordInteractionService
+    from people_network_memory.infrastructure.id_generator import SequentialIdGenerator
+
+    config = _config_from_args(args)
+    cache_path = Path(config.data_path).expanduser() / "people-memory.graphiti-cache.json"
+    cache = JsonPeopleStore(cache_path)
+    if args.fixture_seed is not None:
+        interactions = generate_mock_dataset(seed=args.fixture_seed).interactions
+        source = f"fixture-seed-{args.fixture_seed}"
+    elif args.source_data_path:
+        source_path = Path(args.source_data_path).expanduser()
+        interactions = list(JsonPeopleStore(source_path).interactions.values())
+        source = str(source_path)
+    else:
+        _print_json(
+            {
+                "ok": False,
+                "error": "hydrate-graphiti-cache requires --fixture-seed or --source-data-path",
+            }
+        )
+        return 2
+    if args.limit is not None:
+        interactions = interactions[: args.limit]
+    record = RecordInteractionService(
+        memory_store=cache,
+        identity_index=cache,
+        review_queue=cache,
+        id_generator=SequentialIdGenerator(),
+    )
+    cached = 0
+    skipped_existing = 0
+    entries: list[dict[str, object]] = []
+    existing = {
+        (interaction.source_text, interaction.occurred_at)
+        for interaction in cache.interactions.values()
+    }
+    for index, interaction in enumerate(interactions):
+        key = (interaction.source_text, interaction.occurred_at)
+        if key in existing:
+            skipped_existing += 1
+            entries.append(
+                {
+                    "interaction_index": index,
+                    "ok": True,
+                    "cached": False,
+                    "reason": "already_cached",
+                    "source_text": interaction.source_text,
+                }
+            )
+            continue
+        result = record.record(interaction)
+        existing.add(key)
+        cached += 1
+        entries.append(
+            {
+                "interaction_index": index,
+                "ok": True,
+                "cached": True,
+                "source_text": interaction.source_text,
+                "created_people": result.created_people,
+                "updated_people": result.updated_people,
+            }
+        )
+    payload = {
+        "ok": True,
+        "source": source,
+        "target_cache": str(cache_path),
+        "attempted": len(interactions),
+        "cached": cached,
+        "skipped_existing": skipped_existing,
+        "people": len(cache.people),
+        "interactions": len(cache.interactions),
+        "entries": entries,
+    }
+    _write_json_output(payload, args.output)
+    return 0
+
+
+def _cmd_build_semantic_cache(args: argparse.Namespace) -> int:
+    from people_network_memory.graphiti_adapter.graphiti_store import semantic_index_path
+    from people_network_memory.infrastructure.embeddings import (
+        EmbeddingSettings,
+        OpenAICompatibleEmbeddingClient,
+    )
+    from people_network_memory.infrastructure.semantic_index import SemanticProjectionIndex
+
+    config = _config_from_args(args)
+    source_path = (
+        Path(args.source_data_path).expanduser()
+        if args.source_data_path
+        else Path(config.data_path).expanduser() / "people-memory.graphiti-cache.json"
+    )
+    if not source_path.exists():
+        _print_json({"ok": False, "error": f"projection cache does not exist: {source_path}"})
+        return 2
+    source_store = JsonPeopleStore(source_path)
+    interactions = list(source_store.interactions.values())
+    if args.limit is not None:
+        interactions = interactions[: args.limit]
+    settings = EmbeddingSettings.from_config(config)
+    client = OpenAICompatibleEmbeddingClient(settings)
+    index = SemanticProjectionIndex(
+        Path(args.index_path).expanduser() if args.index_path else semantic_index_path(config)
+    )
+    payload = index.build_from_interactions(
+        interactions,
+        embed_texts=client.embed,
+        batch_size=args.batch_size,
+        reset=args.reset,
+    )
+    payload.update(
+        {
+            "source_cache": str(source_path),
+            "provider": settings.provider,
+            "model": settings.model,
+            "dimension": settings.dimension,
+        }
+    )
+    _write_json_output(payload, args.output)
+    return 0
+
+
+def _cmd_graphiti_ladder(args: argparse.Namespace) -> int:
+    from people_network_memory.graphiti_adapter.indexer import index_interactions
+    from people_network_memory.graphiti_adapter.graphiti_store import GraphitiGraphStore
+
+    config = _config_from_args(args)
+    if config.backend != "graphiti":
+        config = replace(config, backend="graphiti")
+    dataset = generate_mock_dataset(seed=args.seed)
+    steps = [int(item) for item in args.steps.split(",") if item.strip()]
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    results: list[dict[str, object]] = []
+    cumulative_config: PeopleMemoryConfig | None = None
+    if args.cumulative:
+        if args.isolated:
+            cumulative_root = output_dir / "cumulative-store"
+            cumulative_config = replace(
+                config,
+                data_path=str(cumulative_root / "projection"),
+                graphiti_kuzu_path=str(cumulative_root / "graphiti.kuzu"),
+            )
+        else:
+            cumulative_config = config
+    for step in steps:
+        if args.cumulative:
+            run_config = cumulative_config or config
+            temp_dir = None
+        elif args.isolated:
+            temp_dir = tempfile.TemporaryDirectory()
+            run_config = replace(
+                config,
+                data_path=temp_dir.name,
+                graphiti_kuzu_path=str(Path(temp_dir.name) / "graphiti.kuzu"),
+            )
+        else:
+            temp_dir = None
+            run_config = config
+        graph_store = None
+        try:
+            graph_store = GraphitiGraphStore.from_config(run_config)
+            interactions = (
+                dataset.interactions[:step] if args.cumulative else dataset.interactions
+            )
+            step_payload = index_interactions(
+                interactions,
+                state_path=(
+                    output_dir / "ladder-cumulative-state.json"
+                    if args.cumulative
+                    else output_dir / f"ladder-{step:03d}-state.json"
+                ),
+                source_path=Path(f"fixture-seed-{args.seed}.json"),
+                graphiti_kuzu_path=Path(run_config.graphiti_kuzu_path).expanduser(),
+                limit=None if args.cumulative else step,
+                resume=args.cumulative,
+                reset_state=args.cumulative
+                and step == steps[0]
+                and not args.resume_cumulative,
+                continue_on_error=args.continue_on_error,
+                index_one=graph_store.index_interaction_episode,
+                cache_one=graph_store.cache_interaction_projection,
+            )
+            if args.cumulative:
+                step_payload["target_interactions"] = step
+        except Exception as exc:  # pragma: no cover - live provider defensive path
+            step_payload = {
+                "ok": False,
+                "step": step,
+                "error": str(exc),
+            }
+        finally:
+            if graph_store is not None:
+                graph_store.close()
+            if temp_dir is not None:
+                temp_dir.cleanup()
+        step_payload["step"] = step
+        step_file = output_dir / f"ladder-{step:03d}.json"
+        step_file.write_text(
+            json.dumps(step_payload, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+        results.append({**step_payload, "artifact": str(step_file)})
+        if not step_payload.get("ok") and not args.continue_ladder:
+            break
+    summary: dict[str, object] = {
+        "ok": all(bool(result.get("ok")) for result in results),
+        "gate": "graphiti_ingestion_ladder",
+        "seed": args.seed,
+        "steps_requested": steps,
+        "steps_completed": len(results),
+        "output_dir": str(output_dir),
+        "cumulative": args.cumulative,
+        "resume_cumulative": args.resume_cumulative,
+        "results": results,
+    }
+    summary_file = output_dir / "ladder-summary.json"
+    summary_file.write_text(
+        json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+    _print_json(summary)
+    return 0 if summary["ok"] else 2
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    config = _config_from_args(args, default_test_mode=True)
+    runtime = build_runtime(config)
+    payload = runtime.store.export_data()
+    if args.output:
+        Path(args.output).write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        _print_json({"ok": True, "output": args.output})
+        return 0
+    _print_json(payload)
+    return 0
+
+
+def _cmd_list_reviews(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    runtime = build_runtime(config)
+    reviews = runtime.review_workflow.list_reviews(status=args.status)
+    _print_json(
+        {
+            "ok": True,
+            "count": len(reviews),
+            "reviews": [item.model_dump(mode="json") for item in reviews],
+        }
+    )
+    return 0
+
+
+def _cmd_resolve_review(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    runtime = build_runtime(config)
+    item = runtime.review_workflow.resolve_identity_review(
+        review_id=args.review_id,
+        source_person_id=args.source_person_id,
+        target_person_id=args.target_person_id,
+        note=args.note,
+    )
+    _print_json({"ok": True, "review": item.model_dump(mode="json")})
+    return 0
+
+
+def _cmd_dismiss_review(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    runtime = build_runtime(config)
+    item = runtime.review_workflow.dismiss_review(review_id=args.review_id, note=args.note)
+    _print_json({"ok": True, "review": item.model_dump(mode="json")})
+    return 0
+
+
+def _cmd_backup(args: argparse.Namespace) -> int:
+    if not args.output:
+        _print_json({"ok": False, "error": "backup requires --output"})
+        return 2
+    config = _config_from_args(args)
+    runtime = build_runtime(config)
+    payload = runtime.store.export_data()
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    _print_json({"ok": True, "output": str(output), "people": len(payload.get("people", []))})
+    return 0
+
+
+def _cmd_backup_archive(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    if config.backend == "inmemory":
+        config = replace(config, backend="local_json")
+    payload = create_archive_backup(config, args.output)
+    _print_json(payload)
+    return 0
+
+
+def _cmd_restore_archive(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    if config.backend == "inmemory":
+        config = replace(config, backend="local_json")
+    payload = restore_archive_backup(config, args.input, confirm=args.confirm)
+    _print_json(payload)
+    return 0
+
+
+def _cmd_restore(args: argparse.Namespace) -> int:
+    config = _config_from_args(args)
+    if config.backend != "local_json":
+        _print_json({"ok": False, "error": "restore currently supports backend=local_json only"})
+        return 2
+    source = Path(args.input)
+    if not source.exists():
+        _print_json({"ok": False, "error": f"restore input does not exist: {source}"})
+        return 2
+    payload = json.loads(source.read_text(encoding="utf-8"))
+    target = local_json_path(config)
+    JsonPeopleStore.restore_to_path(target, payload)
+    _print_json({"ok": True, "restored_to": str(target), "people": len(payload.get("people", []))})
+    return 0
+
+
+def _cmd_reset(args: argparse.Namespace) -> int:
+    if args.confirm != "DELETE":
+        _print_json(
+            {
+                "ok": False,
+                "error": "reset requires --confirm DELETE; no user data was deleted",
+            }
+        )
+        return 2
+    config = _config_from_args(args)
+    if config.backend == "local_json":
+        target = local_json_path(config)
+        if target.exists():
+            target.unlink()
+            detail = f"deleted {target}"
+        else:
+            detail = f"no local data file existed at {target}"
+        _print_json({"ok": True, "detail": detail})
+        return 0
+    _print_json({"ok": True, "detail": f"reset completed for backend={config.backend}"})
+    return 0
+
+
+def _cmd_redact(args: argparse.Namespace) -> int:
+    _print_json({"redacted": redact_sensitive_text(args.text)})
+    return 0
+
+
+def _cmd_install_openclaw(args: argparse.Namespace) -> int:
+    result = install_openclaw_adapter(
+        home=args.home,
+        command=args.command,
+        command_args=args.command_arg,
+        backend=args.backend,
+        ingestion_extractor=args.ingestion_extractor,
+        identity_advisor=args.identity_advisor,
+        managed_bootstrap=args.managed_bootstrap,
+        auto_update=args.auto_update,
+        dry_run=args.dry_run,
+    )
+    _print_json(result.to_json())
+    return 0
+
+
+def _cmd_smoke_openclaw(args: argparse.Namespace) -> int:
+    payload = run_openclaw_adapter_smoke(
+        home=args.home,
+        install=not args.no_install,
+        backend=args.backend,
+    )
+    _print_json(payload)
+    return 0 if payload["ok"] else 2
+
+
+def _cmd_eval_harness_integration(args: argparse.Namespace) -> int:
+    payload = run_harness_memory_integration_eval()
+    _write_json_output(payload, args.output)
+    return 0 if payload["ok"] else 2
+
+
+def _cmd_eval_extractor(args: argparse.Namespace) -> int:
+    from people_network_memory.infrastructure.llm_extractor import (
+        OpenAICompatibleInteractionExtractor,
+    )
+
+    config = _config_from_args(args)
+    extractor = OpenAICompatibleInteractionExtractor.from_config(config)
+    payload = evaluate_extractor(extractor, max_cases=args.max_cases)
+    payload["min_pass_rate"] = args.min_pass_rate
+    payload["ok"] = bool(payload["pass_rate"] >= args.min_pass_rate)
+    _write_json_output(payload, args.output)
+    return 0 if payload["ok"] else 2
+
+
+def _cmd_tool_schemas(args: argparse.Namespace) -> int:
+    _print_json(
+        {
+            "ok": True,
+            "contract_version": "v1",
+            "tools": public_tool_contracts(),
+        }
+    )
+    return 0
+
+
+def _cmd_release_check(args: argparse.Namespace) -> int:
+    payload = run_local_release_check()
+    _write_json_output(payload, args.output)
+    return 0 if payload["ok"] else 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="people-memory")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    start = sub.add_parser("start")
+    start.add_argument("--test-mode", action="store_true")
+    start.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    start.add_argument("--data-path")
+    start.add_argument("--ingestion-extractor", choices=["off", "llm"])
+    start.add_argument("--identity-advisor", choices=["off", "llm"])
+    start.add_argument("--once", action="store_true")
+    start.set_defaults(func=_cmd_start)
+
+    doctor = sub.add_parser("doctor")
+    doctor.add_argument("--test-mode", action="store_true")
+    doctor.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    doctor.add_argument("--data-path")
+    doctor.add_argument("--ingestion-extractor", choices=["off", "llm"])
+    doctor.add_argument("--identity-advisor", choices=["off", "llm"])
+    doctor.add_argument("--agent", choices=["openclaw"])
+    doctor.add_argument("--openclaw-home", default="~/.openclaw")
+    doctor.set_defaults(func=_cmd_doctor)
+
+    fixtures = sub.add_parser("load-fixtures")
+    fixtures.add_argument("--seed", type=int, default=42)
+    fixtures.add_argument("--summary", action="store_true")
+    fixtures.add_argument("--output")
+    fixtures.set_defaults(func=_cmd_load_fixtures)
+
+    eval_fixtures = sub.add_parser("eval-fixtures")
+    eval_fixtures.add_argument("--seed", type=int, default=42)
+    eval_fixtures.add_argument("--max-interactions", type=int)
+    eval_fixtures.add_argument("--max-queries", type=int)
+    eval_fixtures.add_argument("--include-cases", action="store_true")
+    eval_fixtures.add_argument("--failures-only", action="store_true")
+    eval_fixtures.add_argument(
+        "--all-queries",
+        action="store_true",
+        help="Evaluate selected queries even if max-interactions makes some targets unanswerable.",
+    )
+    eval_fixtures.add_argument("--output")
+    eval_fixtures.set_defaults(func=_cmd_eval_fixtures)
+
+    graphiti = sub.add_parser("spike-graphiti")
+    graphiti.add_argument("--test-mode", action="store_true")
+    graphiti.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    graphiti.add_argument("--data-path")
+    graphiti.set_defaults(func=_cmd_spike_graphiti)
+
+    embedding = sub.add_parser("check-embedding")
+    embedding.add_argument("--test-mode", action="store_true")
+    embedding.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    embedding.add_argument("--data-path")
+    embedding.add_argument("--sample", default="Alice likes robotics and coffee.")
+    embedding.set_defaults(func=_cmd_check_embedding)
+
+    smoke_graphiti = sub.add_parser("smoke-graphiti")
+    smoke_graphiti.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    smoke_graphiti.add_argument("--data-path")
+    smoke_graphiti.add_argument("--isolated", action="store_true")
+    smoke_graphiti.set_defaults(func=_cmd_smoke_graphiti)
+
+    eval_graphiti = sub.add_parser("eval-graphiti")
+    eval_graphiti.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    eval_graphiti.add_argument("--data-path")
+    eval_graphiti.add_argument("--isolated", action="store_true")
+    eval_graphiti.add_argument("--seed", type=int, default=42)
+    eval_graphiti.add_argument("--max-interactions", type=int)
+    eval_graphiti.add_argument("--max-queries", type=int)
+    eval_graphiti.add_argument("--no-cases", action="store_true")
+    eval_graphiti.add_argument("--failures-only", action="store_true")
+    eval_graphiti.add_argument(
+        "--all-queries",
+        action="store_true",
+        help="Evaluate selected queries even if max-interactions makes some targets unanswerable.",
+    )
+    eval_graphiti.add_argument("--output")
+    eval_graphiti.add_argument("--enforce-thresholds", action="store_true")
+    eval_graphiti.set_defaults(func=_cmd_eval_graphiti)
+
+    eval_graphiti_search = sub.add_parser("eval-graphiti-search")
+    eval_graphiti_search.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    eval_graphiti_search.add_argument("--data-path")
+    eval_graphiti_search.add_argument("--graphiti-kuzu-path")
+    eval_graphiti_search.add_argument("--retrieval-judge", choices=["off", "llm"])
+    eval_graphiti_search.add_argument("--seed", type=int, default=42)
+    eval_graphiti_search.add_argument("--indexed-interactions", type=int)
+    eval_graphiti_search.add_argument("--max-queries", type=int)
+    eval_graphiti_search.add_argument("--no-cases", action="store_true")
+    eval_graphiti_search.add_argument("--failures-only", action="store_true")
+    eval_graphiti_search.add_argument(
+        "--all-queries",
+        action="store_true",
+        help="Evaluate selected queries even if indexed-interactions makes some targets unanswerable.",
+    )
+    eval_graphiti_search.add_argument("--output")
+    eval_graphiti_search.add_argument("--report-output")
+    eval_graphiti_search.add_argument(
+        "--compare-report-input",
+        help="Optional baseline eval JSON to compare in the generated Markdown report.",
+    )
+    eval_graphiti_search.add_argument("--enforce-thresholds", action="store_true")
+    eval_graphiti_search.set_defaults(func=_cmd_eval_graphiti_search)
+
+    report_eval = sub.add_parser("report-eval")
+    report_eval.add_argument("--input", required=True)
+    report_eval.add_argument("--output", required=True)
+    report_eval.add_argument("--compare-input")
+    report_eval.add_argument(
+        "--title",
+        default="Personal Network Memory Retrieval Test Report",
+    )
+    report_eval.set_defaults(func=_cmd_report_eval)
+
+    graphiti_gate = sub.add_parser("graphiti-gate")
+    graphiti_gate.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    graphiti_gate.add_argument("--data-path")
+    graphiti_gate.add_argument("--isolated", action="store_true", default=True)
+    graphiti_gate.add_argument(
+        "--no-isolated",
+        action="store_false",
+        dest="isolated",
+        help="Use the configured Graphiti/Kuzu paths instead of a temporary isolated database.",
+    )
+    graphiti_gate.add_argument("--seed", type=int, default=42)
+    graphiti_gate.add_argument("--max-interactions", type=int)
+    graphiti_gate.add_argument("--max-queries", type=int)
+    graphiti_gate.add_argument("--include-cases", action="store_true")
+    graphiti_gate.add_argument("--failures-only", action="store_true", default=True)
+    graphiti_gate.add_argument(
+        "--all-cases",
+        action="store_false",
+        dest="failures_only",
+        help="When cases are included, write every case instead of failures only.",
+    )
+    graphiti_gate.add_argument(
+        "--skip-live",
+        action="store_true",
+        help="Only render static gate structure; promotion will remain blocked.",
+    )
+    graphiti_gate.add_argument(
+        "--skip-embedding-check",
+        action="store_true",
+        help="Skip the live embedding ping; promotion will remain blocked.",
+    )
+    graphiti_gate.add_argument("--output")
+    graphiti_gate.set_defaults(func=_cmd_graphiti_gate)
+
+    index_graphiti = sub.add_parser("index-graphiti")
+    index_graphiti.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    index_graphiti.add_argument("--data-path")
+    index_graphiti.add_argument("--source-data-path")
+    index_graphiti.add_argument("--state-path")
+    index_graphiti.add_argument("--limit", type=int)
+    index_graphiti.add_argument("--output")
+    index_graphiti.add_argument("--no-resume", action="store_true")
+    index_graphiti.add_argument("--reset-state", action="store_true")
+    index_graphiti.add_argument("--continue-on-error", action="store_true")
+    index_graphiti.set_defaults(func=_cmd_index_graphiti)
+
+    hydrate_graphiti_cache = sub.add_parser("hydrate-graphiti-cache")
+    hydrate_graphiti_cache.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    hydrate_graphiti_cache.add_argument("--data-path", required=True)
+    hydrate_graphiti_cache.add_argument("--source-data-path")
+    hydrate_graphiti_cache.add_argument("--fixture-seed", type=int)
+    hydrate_graphiti_cache.add_argument("--limit", type=int)
+    hydrate_graphiti_cache.add_argument("--output")
+    hydrate_graphiti_cache.set_defaults(func=_cmd_hydrate_graphiti_cache)
+
+    build_semantic_cache = sub.add_parser("build-semantic-cache")
+    build_semantic_cache.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    build_semantic_cache.add_argument("--data-path", required=True)
+    build_semantic_cache.add_argument("--source-data-path")
+    build_semantic_cache.add_argument("--index-path")
+    build_semantic_cache.add_argument("--limit", type=int)
+    build_semantic_cache.add_argument("--batch-size", type=int, default=16)
+    build_semantic_cache.add_argument("--reset", action="store_true")
+    build_semantic_cache.add_argument("--output")
+    build_semantic_cache.set_defaults(func=_cmd_build_semantic_cache)
+
+    graphiti_ladder = sub.add_parser("graphiti-ladder")
+    graphiti_ladder.add_argument("--backend", choices=["graphiti"], default="graphiti")
+    graphiti_ladder.add_argument("--data-path")
+    graphiti_ladder.add_argument("--seed", type=int, default=42)
+    graphiti_ladder.add_argument("--steps", default="1,3,10,20,40,90")
+    graphiti_ladder.add_argument(
+        "--output-dir",
+        default=".people-network-memory/test-artifacts/graphiti-ladder",
+    )
+    graphiti_ladder.add_argument("--isolated", action="store_true", default=True)
+    graphiti_ladder.add_argument(
+        "--no-isolated",
+        action="store_false",
+        dest="isolated",
+        help="Reuse configured Graphiti/Kuzu paths instead of one isolated database per step.",
+    )
+    graphiti_ladder.add_argument("--continue-on-error", action="store_true")
+    graphiti_ladder.add_argument("--continue-ladder", action="store_true")
+    graphiti_ladder.add_argument(
+        "--cumulative",
+        action="store_true",
+        help=(
+            "Reuse one artifact-local Graphiti/Kuzu store and state file across steps, "
+            "so larger rungs only index the additional fixture interactions."
+        ),
+    )
+    graphiti_ladder.add_argument(
+        "--resume-cumulative",
+        action="store_true",
+        help="With --cumulative, preserve an existing ladder-cumulative-state.json.",
+    )
+    graphiti_ladder.set_defaults(func=_cmd_graphiti_ladder)
+
+    export = sub.add_parser("export")
+    export.add_argument("--test-mode", action="store_true")
+    export.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    export.add_argument("--data-path")
+    export.add_argument("--output")
+    export.set_defaults(func=_cmd_export)
+
+    list_reviews = sub.add_parser("list-reviews")
+    list_reviews.add_argument("--test-mode", action="store_true")
+    list_reviews.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    list_reviews.add_argument("--data-path")
+    list_reviews.add_argument(
+        "--status", choices=["open", "resolved", "dismissed", "all"], default="open"
+    )
+    list_reviews.set_defaults(func=_cmd_list_reviews)
+
+    resolve_review = sub.add_parser("resolve-review")
+    resolve_review.add_argument("--test-mode", action="store_true")
+    resolve_review.add_argument("--backend", choices=["local_json", "graphiti"])
+    resolve_review.add_argument("--data-path")
+    resolve_review.add_argument("--review-id", required=True)
+    resolve_review.add_argument("--source-person-id", required=True)
+    resolve_review.add_argument("--target-person-id", required=True)
+    resolve_review.add_argument("--note")
+    resolve_review.set_defaults(func=_cmd_resolve_review)
+
+    dismiss_review = sub.add_parser("dismiss-review")
+    dismiss_review.add_argument("--test-mode", action="store_true")
+    dismiss_review.add_argument("--backend", choices=["local_json", "graphiti"])
+    dismiss_review.add_argument("--data-path")
+    dismiss_review.add_argument("--review-id", required=True)
+    dismiss_review.add_argument("--note")
+    dismiss_review.set_defaults(func=_cmd_dismiss_review)
+
+    backup = sub.add_parser("backup")
+    backup.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    backup.add_argument("--data-path")
+    backup.add_argument("--output", required=True)
+    backup.set_defaults(func=_cmd_backup)
+
+    backup_archive = sub.add_parser("backup-archive")
+    backup_archive.add_argument("--test-mode", action="store_true")
+    backup_archive.add_argument("--backend", choices=["local_json", "graphiti"], default="local_json")
+    backup_archive.add_argument("--data-path")
+    backup_archive.add_argument("--output", required=True)
+    backup_archive.set_defaults(func=_cmd_backup_archive)
+
+    restore_archive = sub.add_parser("restore-archive")
+    restore_archive.add_argument("--test-mode", action="store_true")
+    restore_archive.add_argument("--backend", choices=["local_json", "graphiti"], default="local_json")
+    restore_archive.add_argument("--data-path")
+    restore_archive.add_argument("--input", required=True)
+    restore_archive.add_argument("--confirm", default="")
+    restore_archive.set_defaults(func=_cmd_restore_archive)
+
+    restore = sub.add_parser("restore")
+    restore.add_argument("--backend", choices=["local_json"], default="local_json")
+    restore.add_argument("--data-path")
+    restore.add_argument("--input", required=True)
+    restore.set_defaults(func=_cmd_restore)
+
+    reset = sub.add_parser("reset")
+    reset.add_argument("--backend", choices=["inmemory", "local_json", "graphiti"])
+    reset.add_argument("--data-path")
+    reset.add_argument("--confirm", default="")
+    reset.set_defaults(func=_cmd_reset)
+
+    redact = sub.add_parser("redact")
+    redact.add_argument("text")
+    redact.set_defaults(func=_cmd_redact)
+
+    install_openclaw = sub.add_parser("install-openclaw")
+    install_openclaw.add_argument("--home", default="~/.openclaw")
+    install_openclaw.add_argument(
+        "--command",
+        help=(
+            "Command to run. Defaults to the active Python executable and "
+            "`-m people_network_memory.cli start`."
+        ),
+    )
+    install_openclaw.add_argument(
+        "--command-arg",
+        action="append",
+        help="Override MCP command args. Repeat for each arg.",
+    )
+    install_openclaw.add_argument(
+        "--backend", choices=["local_json", "inmemory", "graphiti"], default="local_json"
+    )
+    install_openclaw.add_argument("--ingestion-extractor", choices=["off", "llm"], default="llm")
+    install_openclaw.add_argument("--identity-advisor", choices=["off", "llm"], default="llm")
+    install_openclaw.add_argument(
+        "--managed-bootstrap",
+        action="store_true",
+        help=(
+            "Install a self-healing MCP command that creates/updates the local "
+            "venv before launching the server."
+        ),
+    )
+    install_openclaw.add_argument(
+        "--auto-update",
+        action="store_true",
+        help="With --managed-bootstrap, run git pull --ff-only before dependency checks.",
+    )
+    install_openclaw.add_argument("--dry-run", action="store_true")
+    install_openclaw.set_defaults(func=_cmd_install_openclaw)
+
+    smoke_openclaw = sub.add_parser("smoke-openclaw")
+    smoke_openclaw.add_argument("--home")
+    smoke_openclaw.add_argument(
+        "--backend", choices=["local_json", "inmemory", "graphiti"], default="local_json"
+    )
+    smoke_openclaw.add_argument("--no-install", action="store_true")
+    smoke_openclaw.set_defaults(func=_cmd_smoke_openclaw)
+
+    eval_harness = sub.add_parser("eval-harness-integration")
+    eval_harness.add_argument("--output")
+    eval_harness.set_defaults(func=_cmd_eval_harness_integration)
+
+    eval_extractor = sub.add_parser("eval-extractor")
+    eval_extractor.add_argument("--ingestion-extractor", choices=["llm"], default="llm")
+    eval_extractor.add_argument("--max-cases", type=int)
+    eval_extractor.add_argument("--min-pass-rate", type=float, default=0.8)
+    eval_extractor.add_argument("--output")
+    eval_extractor.set_defaults(func=_cmd_eval_extractor)
+
+    release_check = sub.add_parser("release-check")
+    release_check.add_argument("--output")
+    release_check.set_defaults(func=_cmd_release_check)
+
+    tool_schemas = sub.add_parser("tool-schemas")
+    tool_schemas.set_defaults(func=_cmd_tool_schemas)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except PeopleMemoryError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())