robo-cortex 0.4.0__py3-none-any.whl

robo_cortex/cli/commands/init.py

@@ -0,0 +1,76 @@
+"""Command: roco init"""
+
+import json
+import sys
+
+from robo_cortex.core.init import init_repo
+from robo_cortex.core.errors import RoboCortexError
+from robo_cortex.core.store import open_global_store
+from robo_cortex.cli._common import _get_cmd_name, cli_command
+
+
+@cli_command("init")
+def run(args) -> int:
+    if args.use_global:
+        return _run_global(args)
+
+    result = init_repo(args.repo)
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"Initialized robo-cortex in {result['db_path']}")
+        if result["gitignore_updated"]:
+            print(f"Added .cortex/ to {result['repo_root']}/.gitignore")
+        if "warning" in result:
+            print(f"warning: {result['warning']}", file=sys.stderr)
+    return 0
+
+
+def _run_global(args) -> int:
+    """`roco init --global`: explicitly create/open the scope-B store
+    (~/.cortex/global.db, ARCHITECTURE.md §2), instead of leaving it to be
+    created implicitly by the first `record --scope global` call. No git
+    repository is needed or resolved -- the global store lives outside any
+    single repo by construction.
+    """
+    conn = open_global_store()
+    if conn is None:
+        print(
+            f"{_get_cmd_name()} init --global: global store is disabled "
+            "(ROBO_CORTEX_NO_GLOBAL is set)",
+            file=sys.stderr,
+        )
+        return 1
+    db_path = conn.execute("PRAGMA database_list").fetchone()[2]
+    conn.close()
+
+    if args.json:
+        print(json.dumps({"db_path": db_path}))
+    else:
+        print(f"Initialized robo-cortex global store in {db_path}")
+        print(
+            "Global memories (--scope global) require --assumptions: "
+            "conditions that must match the task text verbatim before the "
+            "memory is retrieved (ARCHITECTURE.md §5.4)."
+        )
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "init", help="Initialize robo-cortex in a git repository"
+    )
+    p.add_argument(
+        "--repo",
+        default=None,
+        help="Path inside the target repository (default: current directory)",
+    )
+    p.add_argument(
+        "--global", dest="use_global", action="store_true",
+        help="Initialize the global (scope=global) store instead (~/.cortex/global.db); no git repository needed",
+    )
+    p.add_argument(
+        "--json", action="store_true", help="Machine-readable JSON output"
+    )
+    p.set_defaults(func=run)

robo_cortex/cli/commands/link.py

@@ -0,0 +1,47 @@
+"""Command: roco link"""
+
+import json
+import sys
+
+from robo_cortex.core.lifecycle import create_link
+from robo_cortex.core.memory import find_memory_store
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, LINK_TYPE_ARGS, cli_command
+
+
+@cli_command("link")
+def run(args) -> int:
+    link_type = LINK_TYPE_ARGS[args.link_type]
+    with _store(args.repo) as (_repo_root, conn), _global_store() as global_conn:
+        store1 = find_memory_store(conn, global_conn, args.id1, scope=args.scope)
+        store2 = find_memory_store(conn, global_conn, args.id2, scope=args.scope)
+        if store1 is not store2:
+            print(
+                "robo-cortex link: cannot link memories across the repo "
+                "and global stores (memory_link is a same-store reference)",
+                file=sys.stderr,
+            )
+            return 1
+        result = create_link(store1, args.id1, args.id2, link_type)
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"Linked {result['from_id']} --{result['link_type']}--> {result['to_id']}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("link", help="Link two memories as contradicting or duplicate")
+    p.add_argument("id1", type=int)
+    p.add_argument("link_type", choices=sorted(LINK_TYPE_ARGS))
+    p.add_argument("id2", type=int)
+    p.add_argument("--repo", default=None)
+    p.add_argument(
+        "--scope",
+        choices=["repo", "global"],
+        default=None,
+        help="Disambiguate ids that collide between the repo and global stores "
+             "(both id1 and id2 must be in the same store to link)",
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/list_cmd.py

@@ -0,0 +1,57 @@
+"""Command: roco list"""
+
+import json
+import sys
+
+from robo_cortex.core.memory import list_memories
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+from robo_cortex.cli._output import format_status
+
+
+@cli_command("list")
+def run(args) -> int:
+    with _store(args.repo) as (_repo_root, conn), _global_store() as global_conn:
+        results = []
+        if args.scope in (None, "repo"):
+            results += list_memories(
+                conn,
+                status=args.status,
+                scope=args.scope,
+                type=args.type,
+                needs_consolidation=args.needs_consolidation,
+                abandoned_without_lesson=args.abandoned_without_lesson,
+            )
+        if args.scope in (None, "global"):
+            results += list_memories(
+                global_conn,
+                status=args.status,
+                scope=args.scope,
+                type=args.type,
+                needs_consolidation=args.needs_consolidation,
+                abandoned_without_lesson=args.abandoned_without_lesson,
+            )
+        results.sort(key=lambda m: m["id"])
+
+    if args.json:
+        print(json.dumps(results))
+    else:
+        if not results:
+            print("No memories found.")
+        for memory in results:
+            print(
+                f"[{memory['id']}] {memory['type']:12s} {memory['scope']:6s} "
+                f"{format_status(memory['status'], width=13)} {memory['statement']}"
+            )
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("list", help="List memories")
+    p.add_argument("--repo", default=None)
+    p.add_argument("--status", default=None)
+    p.add_argument("--scope", choices=["repo", "global"], default=None)
+    p.add_argument("--type", default=None)
+    p.add_argument("--needs-consolidation", action="store_true")
+    p.add_argument("--abandoned-without-lesson", action="store_true")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/mcp.py

@@ -0,0 +1,37 @@
+"""Command: roco mcp"""
+
+import sys
+
+from robo_cortex.core.errors import RoboCortexError
+from robo_cortex.cli._common import _get_cmd_name, cli_command
+
+
+@cli_command("mcp")
+def run(args) -> int:
+    # Lazy import: the mcp SDK is only needed for this one subcommand, not
+    # for every CLI invocation -- keeps `robo-cortex record`/`show`/etc.
+    # fast and independent of an mcp package version, matching the mission's
+    # "every third-party dependency must be justified" posture (justified
+    # exactly here, nowhere else).
+    try:
+        from robo_cortex.mcp_server import run as run_mcp_server
+    except ImportError:
+        print(
+            f"{_get_cmd_name()} mcp: the 'mcp' package is not installed. "
+            f"Install it with: pip install 'robo-cortex[mcp]'",
+            file=sys.stderr,
+        )
+        return 1
+
+    run_mcp_server(args.repo)
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("mcp", help="Run the MCP server (stdio)")
+    p.add_argument(
+        "--repo",
+        default=None,
+        help="Path inside the target repository (default: current directory)",
+    )
+    p.set_defaults(func=run)

robo_cortex/cli/commands/record.py

@@ -0,0 +1,156 @@
+"""Command: roco record"""
+
+import json
+import sys
+
+from robo_cortex.core.memory import (
+    CONFIDENCES,
+    SCOPES,
+    TYPES,
+    record_batch,
+    record_memory,
+)
+from robo_cortex.core.invalidate import add_path, update_path
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+
+
+@cli_command("record")
+def run(args) -> int:
+    with _store(args.repo) as (repo_root, conn):
+        if args.update_path:
+            if not (args.id and args.old_path and args.new_path):
+                print(
+                    "robo-cortex record --update-path: ID, --old-path, "
+                    "and --new-path are all required",
+                    file=sys.stderr,
+                )
+                return 2
+            result = update_path(conn, repo_root, args.id, args.old_path, args.new_path)
+            if args.json:
+                print(json.dumps(result))
+            else:
+                print(f"Updated memory {result['id']}: {args.old_path} -> {args.new_path}")
+            return 0
+
+        if args.add_path:
+            if not args.id:
+                print(
+                    "robo-cortex record --add-path: ID is required",
+                    file=sys.stderr,
+                )
+                return 2
+            result = add_path(conn, repo_root, args.id, args.add_path)
+            if args.json:
+                print(json.dumps(result))
+            else:
+                print(f"Added path to memory {result['id']}: {args.add_path}")
+            return 0
+
+        if args.batch:
+            lines = sys.stdin.read().splitlines()
+            result = record_batch(conn, repo_root, lines)
+            if args.json:
+                print(json.dumps(result))
+            else:
+                print(f"Created {result['created']} memories.")
+                for failure in result["failed"]:
+                    print(
+                        f"  line {failure['line']}: {failure['error']}",
+                        file=sys.stderr,
+                    )
+            return 0
+
+        if not (args.type and args.scope and args.statement and args.confidence):
+            print(
+                "robo-cortex record: --type, --scope, --statement, and "
+                "--confidence are required (or use --batch to read JSON "
+                "Lines from stdin, --update-path to relink an existing "
+                "memory, or --add-path to attach a path to one)",
+                file=sys.stderr,
+            )
+            return 2
+
+        if args.scope == "global":
+            # scope='global' memories live in ~/.cortex/global.db, not
+            # the local repo store -- ARCHITECTURE.md §2: scope B "cannot
+            # live in one repository's .cortex/".
+            with _global_store() as global_conn:
+                result = record_memory(
+                    global_conn,
+                    repo_root,
+                    type=args.type,
+                    scope=args.scope,
+                    statement=args.statement,
+                    confidence=args.confidence,
+                    why_it_matters=args.why_it_matters,
+                    assumptions=args.assumptions,
+                    paths=args.paths,
+                    lesson_from=args.lesson_from,
+                )
+        else:
+            result = record_memory(
+                conn,
+                repo_root,
+                type=args.type,
+                scope=args.scope,
+                statement=args.statement,
+                confidence=args.confidence,
+                why_it_matters=args.why_it_matters,
+                assumptions=args.assumptions,
+                paths=args.paths,
+                lesson_from=args.lesson_from,
+            )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"Recorded memory {result['id']} (status: {result['status']})")
+        for path in result["paths"]:
+            print(f"  path: {path['path']}  blob_hash: {path['blob_hash']}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "record",
+        help="Record a new memory",
+        description="Record a new memory in this repository or globally.\n"
+        "New memories start in 'provisional' status. Use 'roco status <id> activate' to promote to 'active', "
+        "or attach evidence which auto-promotes provisional→active on the first evidence.",
+    )
+    p.add_argument("id", nargs="?", type=int, default=None, help="Used with --update-path or --add-path")
+    p.add_argument("--repo", default=None)
+    p.add_argument("--type", choices=sorted(TYPES), default=None, help="Memory type: decision, lesson, fact, etc.")
+    p.add_argument("--scope", choices=sorted(SCOPES), default=None, help="Memory scope: 'repo' (this project) or 'global' (reusable)")
+    p.add_argument("--statement", default=None)
+    p.add_argument(
+        "--confidence", choices=sorted(CONFIDENCES), default=None,
+        help="Confidence level: low, medium, or high"
+    )
+    p.add_argument("--why", dest="why_it_matters", default=None)
+    p.add_argument("--assumptions", default=None, help="Comma-separated preconditions (for global memories, all must match the task text verbatim)")
+    p.add_argument(
+        "--path", dest="paths", action="append", default=[]
+    )
+    p.add_argument(
+        "--lesson-from", dest="lesson_from", type=int, default=None,
+        help="Link a new type=lesson memory back to the abandoned memory it compresses",
+    )
+    p.add_argument(
+        "--batch",
+        action="store_true",
+        help="Read JSON Lines from stdin instead of the flags above",
+    )
+    p.add_argument(
+        "--update-path", action="store_true",
+        help="Relink an existing memory's path (needs ID, --old-path, --new-path)",
+    )
+    p.add_argument("--old-path", default=None)
+    p.add_argument("--new-path", default=None)
+    p.add_argument(
+        "--add-path", dest="add_path", default=None,
+        help="Attach a new path to an existing memory (needs ID and --add-path); "
+        "useful for a file that didn't exist at HEAD when the memory was first recorded",
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/retrieve.py

@@ -0,0 +1,88 @@
+"""Command: roco retrieve"""
+
+import json
+import sys
+
+from robo_cortex.core.retrieve import (
+    DEFAULT_BUDGET_ITEMS,
+    DEFAULT_BUDGET_TOKENS,
+    retrieve_context,
+)
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+from robo_cortex.cli._output import _format_score_breakdown, format_status
+
+
+@cli_command("retrieve")
+def run(args) -> int:
+    if not args.task:
+        print("robo-cortex retrieve: --task is required", file=sys.stderr)
+        return 2
+
+    with _store(args.repo) as (repo_root, conn), _global_store() as global_conn:
+        result = retrieve_context(
+            conn,
+            repo_root,
+            task=args.task,
+            paths=args.paths,
+            budget_items=args.budget_items,
+            budget_tokens=args.budget_tokens,
+            explain=args.explain,
+            global_conn=global_conn,
+        )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        meta = result["meta"]
+        print(
+            f"matched={meta['matched']} returned={meta['returned']} "
+            f"needs_review={meta['needs_review']} contradicted={meta['contradicted']}"
+        )
+        if meta["matched"] == 0:
+            print(
+                "  hint: no memory passed candidacy (global-scope items must pass"
+            )
+            print(
+                "        the assumptions gate — see ARCHITECTURE.md §5.4). Try:"
+            )
+            print(f"        roco search --query \"{args.task}\"")
+            print(
+                "        roco show <id> --explain-against \"<task>\" (see why candidates didn't match)"
+            )
+        for omission in meta["omitted"]:
+            print(f"  omitted: {omission['count']} ({omission['reason']})")
+        if args.explain and "omitted_details" in meta:
+            for detail in meta["omitted_details"]:
+                print(f"    - id={detail['id']} scope={detail['scope']} omitted due to {detail['reason']}")
+        for item in result["data"]:
+            # Status is only surfaced when it's not the common case (active):
+            # a needs_review item buried in a ranked result list is worth
+            # flagging inline, not just visible via the aggregate count above.
+            status_marker = (
+                f"{format_status(item['status'])} " if item["status"] != "active" else ""
+            )
+            print(
+                f"[{item['id']}] score={item['score']:.3f} "
+                f"{item['scope']:6s} {item['type']:12s} {status_marker}{item['statement']}"
+            )
+            if args.explain:
+                print(f"    {_format_score_breakdown(item['score_breakdown'])}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "retrieve", help="Retrieve a ranked, budgeted context pack for a task"
+    )
+    p.add_argument("--repo", default=None)
+    p.add_argument("--task", default=None)
+    p.add_argument("--path", dest="paths", action="append", default=[])
+    p.add_argument(
+        "--budget-items", type=int, default=DEFAULT_BUDGET_ITEMS
+    )
+    p.add_argument(
+        "--budget-tokens", type=int, default=DEFAULT_BUDGET_TOKENS
+    )
+    p.add_argument("--explain", action="store_true")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/search.py

@@ -0,0 +1,48 @@
+"""Command: roco search"""
+
+import json
+import sys
+
+from robo_cortex.core.retrieve import DEFAULT_SEARCH_LIMIT, search_memory
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+
+
+@cli_command("search")
+def run(args) -> int:
+    if not args.query:
+        print("robo-cortex search: --query is required", file=sys.stderr)
+        return 2
+
+    with _store(args.repo) as (repo_root, conn), _global_store() as global_conn:
+        result = search_memory(
+            conn,
+            repo_root,
+            query=args.query,
+            scope=args.scope,
+            type=args.type,
+            status=args.status,
+            limit=args.limit,
+            global_conn=global_conn,
+        )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"matched={result['matched']} returned={result['returned']}")
+        for item in result["data"]:
+            print(f"[{item['id']}] {item['type']:12s} {item['status']:13s} {item['statement']}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "search", help="Search memories by area, task, or concept (exploration, not budgeted)"
+    )
+    p.add_argument("--repo", default=None)
+    p.add_argument("--query", default=None)
+    p.add_argument("--scope", default=None)
+    p.add_argument("--type", default=None)
+    p.add_argument("--status", default=None)
+    p.add_argument("--limit", type=int, default=DEFAULT_SEARCH_LIMIT)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/show.py

@@ -0,0 +1,62 @@
+"""Command: roco show"""
+
+import json
+import sys
+
+from robo_cortex.core.memory import find_memory_store, get_memory
+from robo_cortex.core.retrieve import explain_memory_score
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+from robo_cortex.cli._output import _format_score_breakdown, format_status
+
+
+@cli_command("show")
+def run(args) -> int:
+    with _store(args.repo) as (_repo_root, conn), _global_store() as global_conn:
+        store = find_memory_store(conn, global_conn, args.id, scope=args.scope)
+        result = get_memory(store, args.id)
+        if args.explain_against:
+            result["score_breakdown"] = explain_memory_score(
+                conn, args.id, args.explain_against,
+                global_conn=global_conn, scope=args.scope,
+            )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(
+            f"[{result['id']}] {result['type']} "
+            f"({result['scope']}, {format_status(result['status'])}, "
+            f"confidence={result['confidence']})"
+        )
+        print(result["statement"])
+        if result["status_reason"]:
+            print(f"status reason: {result['status_reason']}")
+        if result["why_it_matters"]:
+            print(f"why it matters: {result['why_it_matters']}")
+        if result["assumptions"]:
+            print(f"assumptions: {result['assumptions']}")
+        for path in result["paths"]:
+            print(f"  path: {path['path']}  blob_hash: {path['blob_hash']}")
+        for item in result["evidence"]:
+            print(f"  evidence [{item['id']}] {item['kind']} ({item['status']}): {item['description']}")
+        for link in result["links"]:
+            print(f"  link: {link['direction']} {link['link_type']} <-> memory {link['memory_id']}")
+        if "score_breakdown" in result:
+            print(f"  explain: {_format_score_breakdown(result['score_breakdown'])}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("show", help="Show one memory in full")
+    p.add_argument("id", type=int)
+    p.add_argument("--repo", default=None)
+    p.add_argument(
+        "--scope", choices=["repo", "global"], default=None,
+        help="Disambiguate an id that collides between the repo and global stores",
+    )
+    p.add_argument(
+        "--explain-against", dest="explain_against", default=None,
+        help="Print this memory's score components against a hypothetical task",
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/status.py

@@ -0,0 +1,83 @@
+"""Command: roco status"""
+
+import json
+import sys
+
+from robo_cortex.core.lifecycle import STATUS_ACTIONS, change_status, status_batch
+from robo_cortex.core.memory import find_memory_store
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+
+
+@cli_command("status")
+def run(args) -> int:
+    with _store(args.repo) as (repo_root, conn), _global_store() as global_conn:
+        if args.batch:
+            lines = sys.stdin.read().splitlines()
+            result = status_batch(conn, global_conn, repo_root, lines)
+            if args.json:
+                print(json.dumps(result))
+            else:
+                print(f"Updated {result['updated']} memories.")
+                for failure in result["failed"]:
+                    print(
+                        f"  line {failure['line']}: {failure['error']}",
+                        file=sys.stderr,
+                    )
+            return 0
+
+        if not args.id or not args.action:
+            print(
+                "robo-cortex status: ID and ACTION are required "
+                "(or use --batch to read JSON Lines from stdin)",
+                file=sys.stderr,
+            )
+            return 2
+
+        if not args.reason:
+            print("robo-cortex status: --reason is required", file=sys.stderr)
+            return 2
+
+        new_status = STATUS_ACTIONS[args.action]
+        store = find_memory_store(conn, global_conn, args.id, scope=args.scope)
+        result = change_status(
+            store, repo_root, args.id, new_status, args.reason,
+            supersedes_link_to=args.supersedes,
+        )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"Memory {result['id']} -> {result['status']}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser("status", help="Change a memory's status")
+    p.add_argument("id", type=int, nargs="?", default=None)
+    p.add_argument(
+        "action",
+        nargs="?",
+        choices=sorted(STATUS_ACTIONS),
+        default=None,
+        help="Verb: activate, supersede, invalidate, abandon, or archive (state transitions—ARCHITECTURE.md §4)",
+    )
+    p.add_argument(
+        "--reason",
+        default=None,
+        help="Required: explain why this status change (permanent audit trail, not just current state)",
+    )
+    p.add_argument("--supersedes", type=int, default=None)
+    p.add_argument("--repo", default=None)
+    p.add_argument(
+        "--scope",
+        choices=["repo", "global"],
+        default=None,
+        help="Disambiguate an id that collides between the repo and global stores",
+    )
+    p.add_argument(
+        "--batch",
+        action="store_true",
+        help="Read JSON Lines (id, action, reason, ...) from stdin instead of single id/action",
+    )
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)