cortexdb-cli 0.2.0__tar.gz

cortexdb_cli-0.2.0/.gitignore

@@ -0,0 +1,71 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log

cortexdb_cli-0.2.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: cortexdb-cli
+Version: 0.2.0
+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
+Project-URL: Repository, https://github.com/cortexdb/cortexdb
+Project-URL: Issues, https://github.com/cortexdb/cortexdb/issues
+Author-email: CortexDB Team <team@cortexdb.ai>
+License-Expression: Apache-2.0
+Keywords: agents,ai,cli,cortexdb,llm,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich-click>=1.7
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# cortexdb-cli
+
+Command-line interface for [CortexDB](https://cortexdb.ai) — the long-term memory layer for AI systems.
+
+Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup
+in one command, no email or card; works against the public SaaS or any
+self-hosted CortexDB deployment.
+
+## Install
+
+```bash
+pip install cortexdb-cli
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+# 1. One-time setup — anonymous signup, writes ~/.cortexdb/state.json
+cortexdb init
+
+# 2. Store a memory
+cortexdb remember "Q3 revenue: $2.4M. We're on track for $10M ARR by year-end."
+
+# 3. Recall it
+cortexdb recall "Q3 revenue?"
+
+# 4. Or just type — drops into a REPL
+cortexdb
+```
+
+The signup token has a 7-day TTL on the free tier. Re-run `cortexdb init`
+to refresh, or pass `--api-key` + `--actor` to use a token from your IdP.
+
+## Commands
+
+```
+cortexdb init                                 anonymous signup; persist token + actor
+cortexdb remember "..."                       store a memory (POST /v1/experience)
+cortexdb recall   "..."                       recall a stratified context pack
+cortexdb search   "..."                       granular event-level search
+cortexdb forget   --memory-id ...             delete with audit
+cortexdb episodes {list,get,delete}           episode CRUD
+cortexdb entities {list,get,link}             entity rollups over the Facts layer
+cortexdb admin    {health,usage,layers}       diagnostics
+cortexdb import   data.json                   bulk-load (JSON / JSONL / CSV / TXT)
+cortexdb export   -o backup.json              export memories
+cortexdb config   {show,set}                  view / edit ~/.cortexdb/config.toml
+cortexdb                                      interactive REPL
+```
+
+## Configuration
+
+Three layers, in precedence order:
+
+1. **CLI flags** — `--api-key`, `--endpoint`, `--actor`, `--scope`, `--profile`
+2. **Environment** — `CORTEXDB_API_KEY`, `CORTEXDB_URL`, `CORTEXDB_ACTOR`, `CORTEXDB_SCOPE`
+3. **Persisted state**:
+   - `~/.cortexdb/config.toml` — endpoint, profile names (human-editable)
+   - `~/.cortexdb/state.json` — token, actor, scope, expiry (managed by `init`, 0600 on POSIX)
+
+The state.json format matches the cortexdb-mcp 0.3.0 server's, so you can
+copy state across to use both tools from the same anonymous identity.
+
+## Pipe-friendly
+
+Auto-detects when stdout isn't a TTY and emits JSON:
+
+```bash
+cortexdb recall "Q3 revenue" | jq .context_block
+cortexdb entities list      | jq '.[].subject'
+echo "remember this"        | cortexdb remember -
+```
+
+Force JSON mode any time with `--json`.
+
+## Auth notes
+
+- The v1 API requires both `Authorization: Bearer <PASETO>` and `X-Cortex-Actor`.
+  The CLI stamps both on every request — you never need to pass them by hand.
+- 401s show the specific error code (`TOKEN_EXPIRED`, `actor_mismatch`, …)
+  and the remediation: usually `cortexdb init`.
+- 403s cite the missing capability and the policy tier that denied. If a
+  recall returns `diagnostics.read denied`, pass `--diagnostics none` —
+  free-tier tokens don't carry the `diagnostics.read` capability.
+
+## License
+
+Apache-2.0

cortexdb_cli-0.2.0/README.md

@@ -0,0 +1,90 @@
+# cortexdb-cli
+
+Command-line interface for [CortexDB](https://cortexdb.ai) — the long-term memory layer for AI systems.
+
+Wraps the v1 HTTP API in a small, fast Click + Rich CLI. Anonymous signup
+in one command, no email or card; works against the public SaaS or any
+self-hosted CortexDB deployment.
+
+## Install
+
+```bash
+pip install cortexdb-cli
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```bash
+# 1. One-time setup — anonymous signup, writes ~/.cortexdb/state.json
+cortexdb init
+
+# 2. Store a memory
+cortexdb remember "Q3 revenue: $2.4M. We're on track for $10M ARR by year-end."
+
+# 3. Recall it
+cortexdb recall "Q3 revenue?"
+
+# 4. Or just type — drops into a REPL
+cortexdb
+```
+
+The signup token has a 7-day TTL on the free tier. Re-run `cortexdb init`
+to refresh, or pass `--api-key` + `--actor` to use a token from your IdP.
+
+## Commands
+
+```
+cortexdb init                                 anonymous signup; persist token + actor
+cortexdb remember "..."                       store a memory (POST /v1/experience)
+cortexdb recall   "..."                       recall a stratified context pack
+cortexdb search   "..."                       granular event-level search
+cortexdb forget   --memory-id ...             delete with audit
+cortexdb episodes {list,get,delete}           episode CRUD
+cortexdb entities {list,get,link}             entity rollups over the Facts layer
+cortexdb admin    {health,usage,layers}       diagnostics
+cortexdb import   data.json                   bulk-load (JSON / JSONL / CSV / TXT)
+cortexdb export   -o backup.json              export memories
+cortexdb config   {show,set}                  view / edit ~/.cortexdb/config.toml
+cortexdb                                      interactive REPL
+```
+
+## Configuration
+
+Three layers, in precedence order:
+
+1. **CLI flags** — `--api-key`, `--endpoint`, `--actor`, `--scope`, `--profile`
+2. **Environment** — `CORTEXDB_API_KEY`, `CORTEXDB_URL`, `CORTEXDB_ACTOR`, `CORTEXDB_SCOPE`
+3. **Persisted state**:
+   - `~/.cortexdb/config.toml` — endpoint, profile names (human-editable)
+   - `~/.cortexdb/state.json` — token, actor, scope, expiry (managed by `init`, 0600 on POSIX)
+
+The state.json format matches the cortexdb-mcp 0.3.0 server's, so you can
+copy state across to use both tools from the same anonymous identity.
+
+## Pipe-friendly
+
+Auto-detects when stdout isn't a TTY and emits JSON:
+
+```bash
+cortexdb recall "Q3 revenue" | jq .context_block
+cortexdb entities list      | jq '.[].subject'
+echo "remember this"        | cortexdb remember -
+```
+
+Force JSON mode any time with `--json`.
+
+## Auth notes
+
+- The v1 API requires both `Authorization: Bearer <PASETO>` and `X-Cortex-Actor`.
+  The CLI stamps both on every request — you never need to pass them by hand.
+- 401s show the specific error code (`TOKEN_EXPIRED`, `actor_mismatch`, …)
+  and the remediation: usually `cortexdb init`.
+- 403s cite the missing capability and the policy tier that denied. If a
+  recall returns `diagnostics.read denied`, pass `--diagnostics none` —
+  free-tier tokens don't carry the `diagnostics.read` capability.
+
+## License
+
+Apache-2.0

cortexdb_cli-0.2.0/cortexdb_cli/__init__.py

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

cortexdb_cli-0.2.0/cortexdb_cli/client.py

@@ -0,0 +1,92 @@
+"""HTTP client for the CortexDB v1 API.
+
+Thin wrapper around httpx that reads credentials + endpoint from the CLI
+context and stamps every request with both `Authorization: Bearer …` and
+`X-Cortex-Actor: …`. The actor header is mandatory on v1 — missing it
+returns 401 ACTOR_MISMATCH no matter how valid the token is.
+
+We deliberately don't depend on the cortexdbai SDK: keeping the CLI a
+straight HTTP client makes the install fast and lets us pin httpx
+independently from the SDK's release cadence.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Generator
+
+import httpx
+
+from cortexdb_cli import __version__
+
+DEFAULT_ENDPOINT = "https://api-v1.cortexdb.ai"
+
+
+class CortexClient:
+    """Synchronous HTTP client for the CortexDB v1 API."""
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        actor: str = "",
+        timeout: float = 30.0,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+        self.actor = actor
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "User-Agent": f"cortexdb-cli/{__version__}",
+        }
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        if actor:
+            headers["X-Cortex-Actor"] = actor
+        self._http = httpx.Client(
+            base_url=self.endpoint,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        return self._http.get(path, params=params)
+
+    def post(
+        self,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        return self._http.post(path, json=json, params=params)
+
+    def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
+        return self._http.delete(path, params=params)
+
+
+def signup(endpoint: str = DEFAULT_ENDPOINT, timeout: float = 30.0) -> dict[str, Any]:
+    """Call POST /v1/auth/signup and return {token, user_id, scope, expires_at, tier}.
+
+    The endpoint is public — no auth required. Free tier; 7-day TTL.
+    """
+    with httpx.Client(timeout=timeout) as http:
+        resp = http.post(f"{endpoint.rstrip('/')}/v1/auth/signup", json={})
+        resp.raise_for_status()
+        return resp.json()
+
+
+@contextmanager
+def get_client(ctx: dict[str, Any]) -> Generator[CortexClient, None, None]:
+    """Create a CortexClient from CLI context."""
+    client = CortexClient(
+        endpoint=ctx.get("endpoint", DEFAULT_ENDPOINT),
+        api_key=ctx.get("api_key", ""),
+        actor=ctx.get("actor", ""),
+    )
+    try:
+        yield client
+    finally:
+        client.close()

cortexdb_cli-0.2.0/cortexdb_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CortexDB CLI command modules."""

cortexdb_cli-0.2.0/cortexdb_cli/commands/admin.py

@@ -0,0 +1,83 @@
+"""cortexdb admin — health, usage, layer stats."""
+
+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 (
+    is_json_mode,
+    print_health,
+    print_ontology,
+    print_usage,
+    spinner,
+)
+
+
+@click.group("admin")
+def admin_group() -> None:
+    """Diagnostics — reachability, identity, rate-limit, layer status."""
+
+
+@admin_group.command("health")
+@click.pass_context
+@handle_errors
+def admin_health(ctx: click.Context) -> None:
+    """Auth + reachability check (GET /v1/auth/whoami)."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Normalise into the shape print_health expects.
+        body.setdefault("status", "ok")
+        print_health(body, cfg)
+
+
+@admin_group.command("usage")
+@click.pass_context
+@handle_errors
+def admin_usage(ctx: click.Context) -> None:
+    """Tier, capabilities, rate-limit headroom, token expiry."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading usage..."):
+                resp = client.get("/v1/auth/whoami")
+        else:
+            resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        # Fold rate-limit + expiry response headers into the body so the
+        # output formatter can render them in one block.
+        for k in (
+            "X-RateLimit-Limit",
+            "X-RateLimit-Reset",
+            "X-RateLimit-Remaining",
+            "X-Cortex-Token-Expires-In",
+            "X-Cortex-Token-Expires-At",
+        ):
+            if k in resp.headers:
+                body[k] = resp.headers[k]
+        print_usage(body, cfg)
+
+
+@admin_group.command("layers")
+@click.pass_context
+@handle_errors
+def admin_layers(ctx: click.Context) -> None:
+    """Per-layer counts and synthesis lag (GET /v1/admin/layers/stats).
+
+    Stability: experimental — the endpoint is gated by the
+    `admin.layers.stats` capability and may not be present on the free tier.
+    """
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Loading layer stats..."):
+                resp = client.get("/v1/admin/layers/stats")
+        else:
+            resp = client.get("/v1/admin/layers/stats")
+        resp.raise_for_status()
+        print_ontology(resp.json(), cfg)

cortexdb_cli-0.2.0/cortexdb_cli/commands/answer.py

@@ -0,0 +1,98 @@
+"""cortexdb answer — POST /v1/answer (recall + LLM answer)."""
+
+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, is_json_mode, print_json, spinner
+
+
+@click.command("answer")
+@click.argument("question")
+@click.option("--scope", "-S", help="Scope path (defaults to your default scope)")
+@click.option(
+    "--view",
+    type=click.Choice(["raw", "granular", "structured", "holistic", "descend"]),
+    default="holistic",
+    show_default=True,
+)
+@click.option("--temporal", help='Natural-language time window, e.g. "last 30 days"')
+@click.option("--answer-model", help="Override the answer model (paid tier only).")
+@click.option(
+    "--diagnostics",
+    type=click.Choice(["none", "summary", "full"]),
+    default="none",
+    show_default=True,
+)
+@click.pass_context
+@handle_errors
+def answer_cmd(
+    ctx: click.Context,
+    question: str,
+    scope: str | None,
+    view: str,
+    temporal: str | None,
+    answer_model: str | None,
+    diagnostics: str,
+) -> None:
+    """Ask a question — server recalls context and an LLM answers it.
+
+    Counts against the tenant's LLM quota. Requires the `llm.invoke`
+    capability (granted by default on every tier including Free).
+
+        cortexdb answer "Did Acme renew?" --temporal "last 30 days"
+    """
+    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."
+        )
+
+    body: dict[str, Any] = {
+        "scope": target_scope,
+        "question": question,
+        "view": view,
+        "diagnostics": diagnostics,
+    }
+    if temporal:
+        body["temporal"] = {"natural": temporal}
+    if answer_model:
+        body["answer_model"] = answer_model
+
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Answering..."):
+                resp = client.post("/v1/answer", json=body)
+        else:
+            resp = client.post("/v1/answer", json=body)
+        resp.raise_for_status()
+        data = resp.json()
+
+    if is_json_mode(cfg):
+        print_json(data)
+        return
+
+    from rich.markup import escape
+    from rich.panel import Panel
+
+    text = data.get("answer") or data.get("text") or "(no answer returned)"
+    cites = data.get("citations") or []
+
+    console.print(
+        Panel(
+            escape(str(text)),
+            title="[header]Answer[/header]",
+            border_style="cyan",
+            padding=(1, 2),
+        )
+    )
+    if cites:
+        console.print(f"\n[dim]{len(cites)} citation(s):[/dim]")
+        for c in cites[:10]:
+            eid = c.get("event_id") or c.get("id") or ""
+            console.print(f"  [dim]· {escape(eid)}[/dim]")

cortexdb_cli-0.2.0/cortexdb_cli/commands/auth.py

@@ -0,0 +1,128 @@
+"""cortexdb auth — /v1/auth/{whoami,signup,tokens,revoke}."""
+
+from __future__ import annotations
+
+import click
+
+from cortexdb_cli.client import DEFAULT_ENDPOINT, get_client, signup as signup_call
+from cortexdb_cli.config import config_path, save_config
+from cortexdb_cli.errors import handle_errors
+from cortexdb_cli.output import console, is_json_mode, print_json, print_health, spinner
+from cortexdb_cli.state import save_state, state_path
+
+
+@click.group("auth")
+def auth_group() -> None:
+    """Identity, token mint, revoke, anonymous signup."""
+
+
+@auth_group.command("whoami")
+@click.pass_context
+@handle_errors
+def auth_whoami(ctx: click.Context) -> None:
+    """GET /v1/auth/whoami — caller, tenant, effective capabilities."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.get("/v1/auth/whoami")
+        resp.raise_for_status()
+        body = resp.json()
+        body.setdefault("status", "ok")
+        print_health(body, cfg)
+
+
+@auth_group.command("signup")
+@click.option(
+    "--endpoint",
+    default=DEFAULT_ENDPOINT,
+    show_default=True,
+    help="CortexDB v1 API base URL.",
+)
+@click.option("--save", "save_state_flag", is_flag=True, help="Persist to ~/.cortexdb/state.json")
+@click.pass_context
+@handle_errors
+def auth_signup(ctx: click.Context, endpoint: str, save_state_flag: bool) -> None:
+    """POST /v1/auth/signup — anonymous free-tier token.
+
+    Without --save, prints the response and exits — useful when you want
+    to feed the token into a CI env var. With --save, behaves like
+    `cortexdb init` and writes ~/.cortexdb/state.json.
+    """
+    resp = signup_call(endpoint)
+    if save_state_flag:
+        save_state(
+            {
+                "token": resp["token"],
+                "user_id": resp["user_id"],
+                "scope": resp.get("scope") or resp["user_id"],
+                "expires_at": resp.get("expires_at"),
+                "tier": resp.get("tier", "free"),
+                "source": "signup",
+            }
+        )
+        save_config("default", {"endpoint": endpoint})
+        if is_json_mode(ctx.obj):
+            print_json(resp)
+        else:
+            console.print(
+                f"[success]Saved state[/success] to {state_path()}\n"
+                f"  Actor: {resp['user_id']}\n"
+                f"  Scope: {resp.get('scope') or resp['user_id']}\n"
+                f"  Expires: {resp.get('expires_at', '?')}"
+            )
+    else:
+        print_json(resp)
+
+
+@auth_group.command("tokens")
+@click.option("--subject", required=True, help="`sub` claim on the minted token, e.g. user:alice")
+@click.option(
+    "--ttl",
+    "ttl_seconds",
+    type=int,
+    default=3600,
+    show_default=True,
+    help="Token lifetime in seconds (server enforces a tenant ceiling).",
+)
+@click.option("--scope", "scopes", multiple=True, help="`scopes` claim — repeat for multiple.")
+@click.pass_context
+@handle_errors
+def auth_tokens(
+    ctx: click.Context, subject: str, ttl_seconds: int, scopes: tuple[str, ...]
+) -> None:
+    """POST /v1/auth/tokens — mint a service-account token.
+
+    Requires the `auth.mint` capability. Free-tier anonymous tokens do not
+    have it — you must hold an IdP-issued token (or a token previously
+    minted by an account that does).
+
+        cortexdb auth tokens --subject user:alice --ttl 3600 --scope org:acme/user:alice
+    """
+    cfg = ctx.obj
+    body: dict[str, object] = {"subject": subject, "ttl_seconds": ttl_seconds}
+    if scopes:
+        body["scopes"] = list(scopes)
+    with get_client(cfg) as client:
+        if not is_json_mode(cfg):
+            with spinner("Minting..."):
+                resp = client.post("/v1/auth/tokens", json=body)
+        else:
+            resp = client.post("/v1/auth/tokens", json=body)
+        resp.raise_for_status()
+        print_json(resp.json())
+
+
+@auth_group.command("revoke")
+@click.option("--jti", required=True, help="Token jti claim to add to the revocation list.")
+@click.option("--reason", required=True, help="Audit reason (e.g. 'token leaked').")
+@click.pass_context
+@handle_errors
+def auth_revoke(ctx: click.Context, jti: str, reason: str) -> None:
+    """POST /v1/auth/revoke — invalidate a token by jti."""
+    cfg = ctx.obj
+    with get_client(cfg) as client:
+        resp = client.post("/v1/auth/revoke", json={"jti": jti, "reason": reason})
+        resp.raise_for_status()
+        if is_json_mode(cfg):
+            print_json({"revoked": jti})
+        else:
+            console.print(f"[success]Revoked[/success] jti={jti}")