cortexdb-cli 0.4.0__tar.gz → 0.4.2__tar.gz

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/.gitignore

@@ -80,3 +80,15 @@ local-instance/
 
 # doc-claims verifier scratch output
 tools/verifier_out*/
+
+# Generated benchmark / runtime data (audit M-10: hundreds of untracked
+# data dirs at the workspace root slow every git status/search and risk
+# being packaged; results JSONs are artifacts, never source)
+benchmarks/data_*/
+benchmarks/**/fast_results/
+data_*/
+*_data/
+cortexdb_data*/
+server_results/
+*.log
+docker_build.log

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-cli
-Version: 0.4.0
+Version: 0.4.2
 Summary: Command-line interface for CortexDB — the long-term memory layer for AI.
 Project-URL: Homepage, https://cortexdb.ai
 Project-URL: Documentation, https://cortexdb.ai/docs

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
-"""CortexDB CLI — command-line interface for the v1 memory API."""
-
-__version__ = "0.4.0"
+"""CortexDB CLI — command-line interface for the v1 memory API."""
+
+__version__ = "0.4.2"

cortexdb_cli-0.4.2/cortexdb_cli/commands/audit.py

@@ -0,0 +1,78 @@
+"""cortexdb audit — GET /v1/audit/chain + POST /v1/audit/chain/verify."""
+
+from __future__ import annotations
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import console, escape, is_json_mode, print_json, spinner
+
+
+@click.group("audit")
+def audit_group() -> None:
+    """Audit log integrity — hash-chain status and verification."""
+
+
+@audit_group.command("chain")
+@click.option("--actor", help="Restrict chain stats to one actor's rows.")
+@click.pass_context
+@handle_errors
+def audit_chain(ctx: click.Context, actor: str | None) -> None:
+    """Show the audit hash-chain head + length (GET /v1/audit/chain).
+
+    Integrity metadata only — hashes and counts, never row content.
+    """
+    cfg = ctx.obj
+    params: dict[str, str] = {}
+    if actor:
+        params["actor"] = actor
+    with get_client(cfg) as client:
+        resp = client.get("/v1/audit/chain", params=params or None)
+        resp.raise_for_status()
+        data = resp.json()
+
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    console.print(f"Chain length: [bold]{data.get('length', 0)}[/bold] row(s)")
+    console.print(f"Head hash:    [dim]{escape(str(data.get('head_hash') or '(empty)'))}[/dim]")
+    legacy = data.get("legacy_rows", 0)
+    if legacy:
+        console.print(f"[dim]{legacy} legacy row(s) predate the chain.[/dim]")
+
+
+@audit_group.command("verify")
+@click.pass_context
+@handle_errors
+def audit_verify(ctx: click.Context) -> None:
+    """Walk the whole audit chain, recomputing every row hash
+    (POST /v1/audit/chain/verify)."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Verifying chain..."):
+                resp = client.post("/v1/audit/chain/verify", json={})
+        else:
+            resp = client.post("/v1/audit/chain/verify", json={})
+        resp.raise_for_status()
+        data = resp.json()
+
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    if data.get("valid"):
+        console.print(
+            f"[success]Chain valid[/success] — {data.get('length', 0)} row(s), "
+            f"head [dim]{escape(str(data.get('head_hash') or '(empty)'))}[/dim]"
+        )
+    else:
+        console.print(
+            f"[error]Chain BROKEN[/error] at row index "
+            f"[bold]{data.get('first_broken_index')}[/bold] "
+            f"of {data.get('length', 0)}."
+        )
+        raise SystemExit(1)
+    legacy = data.get("legacy_rows", 0)
+    if legacy:
+        console.print(f"[dim]{legacy} legacy row(s) predate the chain.[/dim]")

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/commands/beliefs.py

@@ -97,6 +97,76 @@ def beliefs_why(ctx: click.Context, belief_id: str) -> None:
         print_json(resp.json())
 
 
+@beliefs_group.command("create")
+@click.argument("statement")
+@click.option(
+    "--confidence",
+    "-c",
+    type=click.FloatRange(0.0, 1.0),
+    required=True,
+    help="Point estimate in [0, 1].",
+)
+@click.option(
+    "--support",
+    "-e",
+    "supports",
+    multiple=True,
+    help="Evidence ref: an event (evt_...) or fact (fact_...) id. Repeatable.",
+)
+@click.option("--subject", help="Claim subject (entity name); defaults to the statement itself.")
+@click.option("--predicate", help='Claim predicate; server defaults to "asserts".')
+@click.option("--valid-from", help="ISO-8601 valid-time start; defaults to now.")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.pass_context
+@handle_errors
+def beliefs_create(
+    ctx: click.Context,
+    statement: str,
+    confidence: float,
+    supports: tuple[str, ...],
+    subject: str | None,
+    predicate: str | None,
+    valid_from: str | None,
+    scope: str | None,
+) -> None:
+    """Declare a belief directly (POST /v1/beliefs).
+
+    \b
+        cortexdb beliefs create "Acme is on the enterprise plan" \\
+            --confidence 0.9 --support evt_01HX... --subject Acme --predicate plan
+
+    Declaring a newer belief over the same (subject, predicate) closes the
+    previous one.
+    """
+    cfg = ctx.obj
+    s = _scope_or_die(cfg, scope)
+    body: dict = {
+        "scope": s,
+        "statement": statement,
+        "confidence": confidence,
+        "supports": list(supports),
+    }
+    if subject:
+        body["subject"] = subject
+    if predicate:
+        body["predicate"] = predicate
+    if valid_from:
+        body["valid_from"] = valid_from
+    with get_client(cfg) as client:
+        resp = client.post("/v1/beliefs", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+        if is_json_mode(cfg):
+            print_json(data)
+        else:
+            bid = data.get("belief_id") or data.get("id", "")
+            console.print(
+                f"[success]Belief declared[/success] "
+                f"[dim]{escape(str(bid))}[/dim] — {escape(statement)} "
+                f"({confidence:.0%})"
+            )
+
+
 @beliefs_group.command("build")
 @click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
 @click.pass_context

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/commands/experience.py

@@ -145,7 +145,7 @@ def experience_cmd(
     type=click.Choice(["independent", "strict_temporal"]),
     default="independent",
     show_default=True,
-    help="strict_temporal — fail the batch if observed_at is non-monotonic per actor.",
+    help="Ordering hint (informational in v0.8.0 — the server processes items in submit order regardless).",
 )
 @click.pass_context
 @handle_errors
@@ -199,6 +199,19 @@ def experience_bulk(
         else:
             accepted = data.get("accepted") or data.get("count") or len(items)
             console.print(f"[success]Accepted {accepted} envelopes[/success]")
+            # v0.8.0: a 207 Multi-Status / partial bulk response carries
+            # per-item failures. httpx does not raise on 207, so warn loudly
+            # instead of silently reporting success on a partial commit.
+            if resp.status_code == 207 or data.get("partial"):
+                failures = data.get("failures") or []
+                console.print(
+                    f"[warning]Partial commit: {len(failures)} item(s) were NOT written. "
+                    f"Retry only the failed items.[/warning]"
+                )
+                for f in failures[:10]:
+                    console.print(
+                        f"  - index {f.get('index')}: {f.get('error_code')} {f.get('error','')}"
+                    )
 
 
 # Hidden alias — keep `cortexdb remember "..."` working for muscle memory.

cortexdb_cli-0.4.2/cortexdb_cli/commands/forget.py

@@ -0,0 +1,132 @@
+"""cortexdb forget — POST /v1/forget (+ /v1/forget/preview dry runs)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import console, escape, is_json_mode, print_forget, print_json, spinner
+
+
+@click.command("forget")
+@click.option("--memory-id", "-i", multiple=True, help="Event id(s) to forget. Repeatable.")
+@click.option("--query", "-q", help='Free-text predicate, e.g. "test data" or "deal_stage:lost"')
+@click.option("--subject", help="Forget everything where about_subject matches this value.")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option("--reason", "-r", help="Audit trail note — recorded against the forget. Required unless --preview.")
+@click.option(
+    "--cascade",
+    type=click.Choice(["none", "derived_only", "redact_events"]),
+    default="derived_only",
+    show_default=True,
+    help="How aggressively to propagate the forget across derived layers.",
+)
+@click.option(
+    "--preview",
+    is_flag=True,
+    help="Dry run via POST /v1/forget/preview — report per-layer counts, delete nothing.",
+)
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+@click.pass_context
+@handle_errors
+def forget_cmd(
+    ctx: click.Context,
+    memory_id: tuple[str, ...],
+    query: str | None,
+    subject: str | None,
+    scope: str | None,
+    reason: str | None,
+    cascade: str,
+    preview: bool,
+    yes: bool,
+) -> None:
+    """Delete memories with an audit trail.
+
+    \b
+        cortexdb forget --memory-id evt_01HX... --reason "user requested deletion"
+        cortexdb forget --query "test data"      --reason "cleaning up test fixtures"
+        cortexdb forget --subject "user:alice"   --reason "GDPR erasure" --cascade redact_events
+        cortexdb forget --memory-id evt_01HX... --preview
+
+    --preview runs the exact same request through POST /v1/forget/preview:
+    same refusals, per-layer estimated_deleted counts, nothing deleted.
+    """
+    cfg = ctx.obj
+    target_scope = scope or cfg.get("scope") or cfg.get("actor")
+    if not target_scope:
+        raise click.UsageError(
+            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
+        )
+    if not preview and not reason:
+        raise click.UsageError("Missing option '--reason' / '-r' (not needed with --preview).")
+
+    selector: dict[str, Any] = {}
+    if memory_id:
+        selector["memory_ids"] = list(memory_id)
+    if query:
+        # v0.8.0: the server ForgetSelector has no free-text `query` field
+        # (only memory_ids / about_subject / about_entity / predicate).
+        # Sending `query` was silently dropped → empty selector → a
+        # confusing 422 EMPTY_SELECTOR_WITHOUT_CONFIRMATION. Map --query to
+        # the subject selector, the closest supported shape.
+        selector["about_subject"] = query
+    if subject:
+        selector["about_subject"] = subject
+    if not selector:
+        raise click.UsageError("Provide at least one of --memory-id, --query, or --subject.")
+
+    # A preview is non-destructive — never gate it behind a confirmation.
+    if not preview and not yes and not is_json_mode(cfg):
+        target = (
+            f"{len(memory_id)} memory id(s)"
+            if memory_id
+            else (f'query "{query}"' if query else f"subject {subject}")
+        )
+        click.confirm(f"Forget {target} in scope {target_scope}?", abort=True)
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "selector": selector,
+        "cascade": cascade,
+    }
+    if reason:
+        body["audit_note"] = reason
+
+    path = "/v1/forget/preview" if preview else "/v1/forget"
+    label = "Previewing..." if preview else "Forgetting..."
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner(label):
+                resp = client.post(path, json=body)
+        else:
+            resp = client.post(path, json=body)
+        resp.raise_for_status()
+        data = resp.json()
+        if preview:
+            _print_preview(data, cfg)
+        else:
+            print_forget(data, cfg)
+
+
+def _print_preview(data: dict[str, Any], cfg: dict[str, Any]) -> None:
+    """Render the /v1/forget/preview response."""
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    est = data.get("estimated_deleted") or {}
+    total = sum(v for v in est.values() if isinstance(v, int))
+    lines = [f"Would delete [bold]{total}[/bold] record(s) — nothing was deleted."]
+    per_layer = ", ".join(f"{k}: {v}" for k, v in est.items() if isinstance(v, int) and v)
+    if per_layer:
+        lines.append(f"[dim]{escape(per_layer)}[/dim]")
+    pid = data.get("preview_id", "")
+    if pid:
+        lines.append(f"[dim]Preview id: {escape(pid)} (usable as from_preview_id on /v1/erasures)[/dim]")
+    from rich.panel import Panel
+
+    console.print(
+        Panel("\n".join(lines), title="[header]Forget preview[/header]", border_style="yellow")
+    )

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/commands/import_cmd.py

@@ -15,7 +15,7 @@ import click
 
 from cortexdb_cli.client import get_client
 from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import console, is_json_mode, print_json
+from cortexdb_cli.output import console, is_json_mode, print_json, spinner
 
 
 def _now_iso() -> str:
@@ -49,6 +49,36 @@ def _envelope(content: str, scope: str, idem: str, extra_meta: dict[str, Any]) -
     return body
 
 
+def _server_import(cfg: dict[str, Any], scope: str, raw: str) -> None:
+    """POST /v1/import — one-shot server-side JSONL import (202)."""
+    body = {"scope": scope, "data": raw}
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Importing..."):
+                resp = client.post("/v1/import", json=body)
+        else:
+            resp = client.post("/v1/import", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+    accepted = data.get("accepted", 0)
+    failed = data.get("failed", 0)
+    console.print(f"[success]Imported {accepted} row(s)[/success]", end="")
+    if failed:
+        console.print(f" [warning]({failed} failed)[/warning]")
+        first = data.get("first_error")
+        if first:
+            console.print(f"[warning]First error: {first}[/warning]")
+    else:
+        console.print()
+    status_url = data.get("status_url")
+    if status_url:
+        console.print(f"[dim]Job: {data.get('import_id', '')} — status at {status_url}[/dim]")
+
+
 @click.command("import")
 @click.argument("file", type=click.Path(exists=True), required=False)
 @click.option(
@@ -63,6 +93,16 @@ def _envelope(content: str, scope: str, idem: str, extra_meta: dict[str, Any]) -
     is_flag=True,
     help="Treat a .txt input as one memory rather than one-per-line.",
 )
+@click.option(
+    "--server",
+    "server_side",
+    is_flag=True,
+    help=(
+        "Send the input in one request to POST /v1/import (server-side JSONL "
+        "import; canonical envelopes or /v1/export lines) instead of one "
+        "POST /v1/experience per row."
+    ),
+)
 @click.pass_context
 @handle_errors
 def import_cmd(
@@ -71,6 +111,7 @@ def import_cmd(
     fmt: str | None,
     scope: str | None,
     single: bool,
+    server_side: bool,
 ) -> None:
     """Import memories from a file.
 
@@ -79,6 +120,7 @@ def import_cmd(
         cortexdb import data.jsonl
         cortexdb import notes.csv
         cortexdb import notes.txt --single
+        cortexdb import backup.jsonl --server
         cat data.json | cortexdb import -
     """
     cfg = ctx.obj
@@ -109,6 +151,18 @@ def import_cmd(
     else:
         raise click.UsageError("Provide a file path or pipe from stdin.")
 
+    # Server-side path: hand the raw JSONL to POST /v1/import in one request
+    # and let the server's import engine do the row work.
+    if server_side:
+        if fmt != "jsonl":
+            raise click.UsageError(
+                "--server requires JSONL input (canonical envelopes or "
+                "/v1/export lines); pass --format jsonl for stdin or "
+                "non-.jsonl files."
+            )
+        _server_import(cfg, target_scope, raw)
+        return
+
     # Parse
     memories: list[dict[str, Any]] = []
     if fmt == "json":

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/commands/init.py

@@ -11,12 +11,38 @@ from cortexdb_cli.output import console
 from cortexdb_cli.state import save_state, state_path
 
 
+def _inherit_group_flag(
+    ctx: click.Context,
+    name: str,
+    own_value: str | None,
+) -> str | None:
+    """Fall back to a flag given at the GROUP level (`cortexdb --endpoint …
+    init`) when init's own flag wasn't supplied.
+
+    Users reasonably write global flags before the subcommand; Click parses
+    them into the group's params and, before 0.4.1, init silently ignored
+    them — `cortexdb --endpoint X --api-key Y init` performed an anonymous
+    signup against the DEFAULT endpoint. Only the parent's RAW params are
+    consulted (never merged config), so a stale config.toml can't leak into
+    a fresh init. If both levels are set and disagree, init's own flag wins
+    with a warning.
+    """
+    parent = ctx.parent
+    group_value = parent.params.get(name) if parent is not None else None
+    if own_value is not None and group_value is not None and own_value != group_value:
+        console.print(
+            f"[warning]--{name.replace('_', '-')} given both before and after "
+            f"`init` with different values; using {own_value!r}.[/warning]"
+        )
+        return own_value
+    return own_value if own_value is not None else group_value
+
+
 @click.command("init")
 @click.option(
     "--endpoint",
-    default=DEFAULT_ENDPOINT,
-    show_default=True,
-    help="CortexDB v1 API base URL.",
+    default=None,
+    help=f"CortexDB v1 API base URL.  [default: {DEFAULT_ENDPOINT}]",
 )
 @click.option(
     "--api-key",
@@ -33,8 +59,10 @@ from cortexdb_cli.state import save_state, state_path
     default=None,
     help="Default scope path. Defaults to the actor.",
 )
+@click.pass_context
 def init_cmd(
-    endpoint: str,
+    ctx: click.Context,
+    endpoint: str | None,
     api_key: str | None,
     actor: str | None,
     scope: str | None,
@@ -45,6 +73,12 @@ def init_cmd(
     Without flags:      anonymous signup (free tier, 7-day token TTL).
     With --api-key:     register an existing token + actor (e.g. from your IdP).
     """
+    # Global-flag inheritance: `cortexdb --endpoint X init` == `cortexdb init --endpoint X`.
+    endpoint = _inherit_group_flag(ctx, "endpoint", endpoint) or DEFAULT_ENDPOINT
+    api_key = _inherit_group_flag(ctx, "api_key", api_key)
+    actor = _inherit_group_flag(ctx, "actor", actor)
+    scope = _inherit_group_flag(ctx, "scope", scope)
+
     console.print("\n[header]CortexDB CLI setup[/header]\n")
 
     if api_key:

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/commands/recall.py

@@ -1,121 +1,121 @@
-"""cortexdb recall — POST /v1/recall."""
-
-from __future__ import annotations
-
-from typing import Any
-
-import click
-
-from cortexdb_cli.client import get_client
-from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import is_json_mode, print_recall, spinner
-
-
-@click.command("recall")
-@click.argument("query")
-@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
-@click.option(
-    "--view",
-    type=click.Choice(["raw", "granular", "structured", "holistic", "descend"]),
-    default=None,
-    help="Pack shape. Defaults to your configured view (CORTEXDB_VIEW env or "
-    "`cortexdb config set view ...`), else 'holistic'. 'descend' = the scope + all "
-    "child scopes; 'holistic' = the scope + its parents; 'granular' = exact scope only.",
-)
-@click.option(
-    "--include",
-    multiple=True,
-    type=click.Choice(["events", "episodes", "facts", "beliefs", "understanding"]),
-    help="Layers to fill (repeatable). Default: facts + beliefs + episodes.",
-)
-@click.option(
-    "--temporal",
-    default=None,
-    help='Natural-language time window, e.g. "last 30 days".',
-)
-@click.option(
-    "--max-tokens",
-    type=int,
-    default=None,
-    help="Budget for the returned context_block (string).",
-)
-@click.option(
-    "--diagnostics",
-    type=click.Choice(["none", "summary", "full"]),
-    default="none",
-    show_default=True,
-    help='"none" works on every tier. "summary"/"full" need the diagnostics.read capability.',
-)
-@click.option(
-    "--filter",
-    "filters",
-    multiple=True,
-    metavar="KEY=VALUE",
-    help="Hard attribute filter, repeatable (AND across keys, any-of when a "
-    "key repeats). Keys: labels, intent, modality, caller, observed_actor. "
-    "Example: --filter labels=primary_inbox",
-)
-@click.pass_context
-@handle_errors
-def recall_cmd(
-    ctx: click.Context,
-    query: str,
-    scope: str | None,
-    view: str,
-    include: tuple[str, ...],
-    temporal: str | None,
-    max_tokens: int | None,
-    diagnostics: str,
-    filters: tuple[str, ...],
-) -> None:
-    """Recall context from memory.
-
-    \b
-        cortexdb recall "what did we decide about Acme?"
-        cortexdb recall "renewal status" --temporal "last 30 days"
-    """
-    cfg = ctx.obj
-    view = view or cfg.get("view") or "holistic"
-    if view not in ("raw", "granular", "structured", "holistic", "descend"):
-        raise click.UsageError(
-            f"Invalid view {view!r}. Choose: raw, granular, structured, holistic, descend."
-        )
-    target_scope = scope or cfg.get("scope") or cfg.get("actor")
-    if not target_scope:
-        raise click.UsageError(
-            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
-        )
-
-    body: dict[str, Any] = {
-        "scope": target_scope,
-        "view": view,
-        "query": query,
-        "diagnostics": diagnostics,
-    }
-    if include:
-        body["include"] = list(include)
-    if temporal:
-        body["temporal"] = {"natural": temporal}
-    if max_tokens is not None:
-        body["budgets"] = {"max_tokens": max_tokens}
-    if filters:
-        fmap: dict[str, Any] = {}
-        for f in filters:
-            if "=" not in f:
-                raise click.UsageError(f"--filter must be KEY=VALUE, got {f!r}")
-            k, v = f.split("=", 1)
-            if k in fmap:
-                prev = fmap[k] if isinstance(fmap[k], list) else [fmap[k]]
-                fmap[k] = prev + [v]
-            else:
-                fmap[k] = v
-        body["filters"] = {"metadata": fmap}
-
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Recalling..."):
-                resp = client.post("/v1/recall", json=body)
-        else:
-            resp = client.post("/v1/recall", json=body)
-        resp.raise_for_status()
-        print_recall(resp.json(), cfg)
+"""cortexdb recall — POST /v1/recall."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from cortexdb_cli.client import get_client
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import is_json_mode, print_recall, spinner
+
+
+@click.command("recall")
+@click.argument("query")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option(
+    "--view",
+    type=click.Choice(["raw", "granular", "structured", "holistic", "descend"]),
+    default=None,
+    help="Pack shape. Defaults to your configured view (CORTEXDB_VIEW env or "
+    "`cortexdb config set view ...`), else 'holistic'. 'descend' = the scope + all "
+    "child scopes; 'holistic' = the scope + its parents; 'granular' = exact scope only.",
+)
+@click.option(
+    "--include",
+    multiple=True,
+    type=click.Choice(["events", "episodes", "facts", "beliefs", "understanding"]),
+    help="Layers to fill (repeatable). Default: facts + beliefs + episodes.",
+)
+@click.option(
+    "--temporal",
+    default=None,
+    help='Natural-language time window, e.g. "last 30 days".',
+)
+@click.option(
+    "--max-tokens",
+    type=int,
+    default=None,
+    help="Budget for the returned context_block (string).",
+)
+@click.option(
+    "--diagnostics",
+    type=click.Choice(["none", "summary", "full"]),
+    default="none",
+    show_default=True,
+    help='"none" works on every tier. "summary"/"full" need the diagnostics.read capability.',
+)
+@click.option(
+    "--filter",
+    "filters",
+    multiple=True,
+    metavar="KEY=VALUE",
+    help="Hard attribute filter, repeatable (AND across keys, any-of when a "
+    "key repeats). Keys: labels, intent, modality, caller, observed_actor. "
+    "Example: --filter labels=primary_inbox",
+)
+@click.pass_context
+@handle_errors
+def recall_cmd(
+    ctx: click.Context,
+    query: str,
+    scope: str | None,
+    view: str,
+    include: tuple[str, ...],
+    temporal: str | None,
+    max_tokens: int | None,
+    diagnostics: str,
+    filters: tuple[str, ...],
+) -> None:
+    """Recall context from memory.
+
+    \b
+        cortexdb recall "what did we decide about Acme?"
+        cortexdb recall "renewal status" --temporal "last 30 days"
+    """
+    cfg = ctx.obj
+    view = view or cfg.get("view") or "holistic"
+    if view not in ("raw", "granular", "structured", "holistic", "descend"):
+        raise click.UsageError(
+            f"Invalid view {view!r}. Choose: raw, granular, structured, holistic, descend."
+        )
+    target_scope = scope or cfg.get("scope") or cfg.get("actor")
+    if not target_scope:
+        raise click.UsageError(
+            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
+        )
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "view": view,
+        "query": query,
+        "diagnostics": diagnostics,
+    }
+    if include:
+        body["include"] = list(include)
+    if temporal:
+        body["temporal"] = {"natural": temporal}
+    if max_tokens is not None:
+        body["budgets"] = {"max_tokens": max_tokens}
+    if filters:
+        fmap: dict[str, Any] = {}
+        for f in filters:
+            if "=" not in f:
+                raise click.UsageError(f"--filter must be KEY=VALUE, got {f!r}")
+            k, v = f.split("=", 1)
+            if k in fmap:
+                prev = fmap[k] if isinstance(fmap[k], list) else [fmap[k]]
+                fmap[k] = prev + [v]
+            else:
+                fmap[k] = v
+        body["filters"] = {"metadata": fmap}
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Recalling..."):
+                resp = client.post("/v1/recall", json=body)
+        else:
+            resp = client.post("/v1/recall", json=body)
+        resp.raise_for_status()
+        print_recall(resp.json(), cfg)

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/cortexdb_cli/main.py

@@ -9,10 +9,11 @@ Usage:
     cortexdb answer   "..."                  recall + LLM answer  (POST /v1/answer)
     cortexdb compose  "..."                  markdown document from memory (POST /v1/compose)
     cortexdb forget   --memory-id ...        delete with audit    (POST /v1/forget)
+    cortexdb forget   --preview ...          dry run              (POST /v1/forget/preview)
     cortexdb episodes {list,get,delete}
     cortexdb entities {list,get,link}
     cortexdb facts    {list,timeline}
-    cortexdb beliefs  {list,why,build}
+    cortexdb beliefs  {list,why,build,create}
     cortexdb conflicts {list,show,resolve}
     cortexdb claims   {history}
     cortexdb concepts {list,coverage,synthesize}
@@ -20,7 +21,9 @@ Usage:
     cortexdb auth     {whoami,signup,tokens,revoke}
     cortexdb policy   {effective,deployment}
     cortexdb admin    {health,usage,layers}
+    cortexdb audit    {chain,verify}
     cortexdb import   data.json
+    cortexdb import   backup.jsonl --server  server-side import   (POST /v1/import)
     cortexdb export   -o backup.json
     cortexdb config   {show,set}
     cortexdb                                 interactive REPL
@@ -98,6 +101,7 @@ def cli(
 
 from cortexdb_cli.commands.admin import admin_group
 from cortexdb_cli.commands.answer import answer_cmd
+from cortexdb_cli.commands.audit import audit_group
 from cortexdb_cli.commands.compose import compose_cmd
 from cortexdb_cli.commands.auth import auth_group
 from cortexdb_cli.commands.beliefs import beliefs_group
@@ -146,6 +150,7 @@ cli.add_command(scopes_group)
 cli.add_command(auth_group)
 cli.add_command(policy_group)
 cli.add_command(admin_group)
+cli.add_command(audit_group)
 cli.add_command(import_cmd)
 cli.add_command(export_cmd)
 cli.add_command(config_group)

{cortexdb_cli-0.4.0 → cortexdb_cli-0.4.2}/pyproject.toml

@@ -1,56 +1,56 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "cortexdb-cli"
-version = "0.4.0"
-description = "Command-line interface for CortexDB — the long-term memory layer for AI."
-readme = "README.md"
-license = "Apache-2.0"
-requires-python = ">=3.10"
-authors = [
-    { name = "CortexDB Team", email = "team@cortexdb.ai" },
-]
-keywords = ["ai", "memory", "cli", "cortexdb", "agents", "llm"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Environment :: Console",
-    "Intended Audience :: Developers",
-    "License :: OSI Approved :: Apache Software License",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-    "Topic :: Scientific/Engineering :: Artificial Intelligence",
-    "Topic :: Database",
-]
-dependencies = [
-    "click>=8.1",
-    "rich>=13.0",
-    "rich-click>=1.7",
-    "httpx>=0.27",
-    "prompt-toolkit>=3.0",
-    "tomli>=2.0; python_version < '3.11'",
-    "tomli-w>=1.0",
-]
-
-[project.scripts]
-cortexdb = "cortexdb_cli.main:cli"
-
-[project.urls]
-Homepage = "https://cortexdb.ai"
-Documentation = "https://cortexdb.ai/docs"
-Repository = "https://github.com/cortexdb/cortexdb"
-Issues = "https://github.com/cortexdb/cortexdb/issues"
-
-[tool.hatch.build.targets.wheel]
-packages = ["cortexdb_cli"]
-
-[tool.hatch.build.targets.sdist]
-include = ["cortexdb_cli", "README.md", "LICENSE"]
-
-[tool.ruff]
-target-version = "py310"
-line-length = 100
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortexdb-cli"
+version = "0.4.2"
+description = "Command-line interface for CortexDB — the long-term memory layer for AI."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "CortexDB Team", email = "team@cortexdb.ai" },
+]
+keywords = ["ai", "memory", "cli", "cortexdb", "agents", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Database",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "rich-click>=1.7",
+    "httpx>=0.27",
+    "prompt-toolkit>=3.0",
+    "tomli>=2.0; python_version < '3.11'",
+    "tomli-w>=1.0",
+]
+
+[project.scripts]
+cortexdb = "cortexdb_cli.main:cli"
+
+[project.urls]
+Homepage = "https://cortexdb.ai"
+Documentation = "https://cortexdb.ai/docs"
+Repository = "https://github.com/cortexdb/cortexdb"
+Issues = "https://github.com/cortexdb/cortexdb/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cortexdb_cli"]
+
+[tool.hatch.build.targets.sdist]
+include = ["cortexdb_cli", "README.md", "LICENSE"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

cortexdb_cli-0.4.0/cortexdb_cli/commands/forget.py

@@ -1,86 +0,0 @@
-"""cortexdb forget — POST /v1/forget."""
-
-from __future__ import annotations
-
-from typing import Any
-
-import click
-
-from cortexdb_cli.client import get_client
-from cortexdb_cli.errors import handle_errors
-from cortexdb_cli.output import is_json_mode, print_forget, spinner
-
-
-@click.command("forget")
-@click.option("--memory-id", "-i", multiple=True, help="Event id(s) to forget. Repeatable.")
-@click.option("--query", "-q", help='Free-text predicate, e.g. "test data" or "deal_stage:lost"')
-@click.option("--subject", help="Forget everything where about_subject matches this value.")
-@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
-@click.option("--reason", "-r", required=True, help="Audit trail note — recorded against the forget.")
-@click.option(
-    "--cascade",
-    type=click.Choice(["none", "derived_only", "redact_events"]),
-    default="derived_only",
-    show_default=True,
-    help="How aggressively to propagate the forget across derived layers.",
-)
-@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
-@click.pass_context
-@handle_errors
-def forget_cmd(
-    ctx: click.Context,
-    memory_id: tuple[str, ...],
-    query: str | None,
-    subject: str | None,
-    scope: str | None,
-    reason: str,
-    cascade: str,
-    yes: bool,
-) -> None:
-    """Delete memories with an audit trail.
-
-    \b
-        cortexdb forget --memory-id evt_01HX... --reason "user requested deletion"
-        cortexdb forget --query "test data"      --reason "cleaning up test fixtures"
-        cortexdb forget --subject "user:alice"   --reason "GDPR erasure" --cascade redact_events
-    """
-    cfg = ctx.obj
-    target_scope = scope or cfg.get("scope") or cfg.get("actor")
-    if not target_scope:
-        raise click.UsageError(
-            "No scope configured. Run `cortexdb init` first, or pass --scope explicitly."
-        )
-
-    selector: dict[str, Any] = {}
-    if memory_id:
-        selector["memory_ids"] = list(memory_id)
-    if query:
-        selector["query"] = query
-    if subject:
-        selector["about_subject"] = subject
-    if not selector:
-        raise click.UsageError("Provide at least one of --memory-id, --query, or --subject.")
-
-    if not yes and not is_json_mode(cfg):
-        target = (
-            f"{len(memory_id)} memory id(s)"
-            if memory_id
-            else (f'query "{query}"' if query else f"subject {subject}")
-        )
-        click.confirm(f"Forget {target} in scope {target_scope}?", abort=True)
-
-    body = {
-        "scope": target_scope,
-        "selector": selector,
-        "cascade": cascade,
-        "audit_note": reason,
-    }
-
-    with get_client(cfg) as client:
-        if not is_json_mode(cfg):
-            with spinner("Forgetting..."):
-                resp = client.post("/v1/forget", json=body)
-        else:
-            resp = client.post("/v1/forget", json=body)
-        resp.raise_for_status()
-        print_forget(resp.json(), cfg)