abbacus-cortex 0.2.1__py3-none-any.whl

abbacus_cortex-0.2.1.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.3
+Name: abbacus-cortex
+Version: 0.2.1
+Summary: Cognitive knowledge system with formal ontology, reasoning, and intelligence serving
+Author: Fabrizzio Silveira
+Author-email: Fabrizzio Silveira <74255714+grayisnotacolor@users.noreply.github.com>
+Requires-Dist: pyoxigraph>=0.4
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: typer>=0.15
+Requires-Dist: jinja2>=3.1
+Requires-Dist: python-dotenv>=1.1
+Requires-Dist: bcrypt>=4.2
+Requires-Dist: mcp>=1.6
+Requires-Dist: httpx>=0.28
+Requires-Dist: sentence-transformers>=3.4 ; extra == 'embeddings'
+Requires-Dist: litellm>=1.60 ; extra == 'llm'
+Requires-Python: >=3.12
+Provides-Extra: embeddings
+Provides-Extra: llm
+Description-Content-Type: text/markdown
+
+# Cortex
+
+Cognitive knowledge system with formal ontology, reasoning, and intelligence serving.
+
+Cortex captures knowledge objects (decisions, lessons, fixes, sessions, research, ideas), classifies them with an OWL-RL ontology, discovers relationships, reasons over the graph, and serves intelligence through hybrid retrieval.
+
+## Install
+
+```bash
+# Full install (semantic + keyword search)
+pip install abbacus-cortex[embeddings]
+
+# Lightweight (keyword search only, no PyTorch)
+pip install abbacus-cortex
+
+# From source
+git clone https://github.com/abbacusgroup/Cortex.git
+cd Cortex
+uv sync --extra embeddings
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize — creates ~/.cortex/, loads ontology, warms up embedding model
+cortex init
+
+# 2. Install background services (auto-start on login)
+cortex install
+
+# 3. Register with Claude Code
+cortex register
+
+# 4. Use
+cortex capture "Fix: Neo4j pool exhaustion" --type fix --content "Root cause was..."
+cortex search "Neo4j"
+cortex list
+cortex context "Neo4j"
+cortex dashboard                    # web UI at http://localhost:1315
+```
+
+## Configuration
+
+Set via environment variables (prefix `CORTEX_`) or `.env` file:
+
+```env
+CORTEX_DATA_DIR=~/.cortex
+CORTEX_LLM_MODEL=claude-sonnet-4-20250514
+CORTEX_LLM_API_KEY=sk-...
+CORTEX_DASHBOARD_PASSWORD=           # set via `cortex setup`
+CORTEX_EMBEDDING_MODEL=all-mpnet-base-v2
+```
+
+See `.env.example` for all options.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `cortex init` | Initialize data directory and stores |
+| `cortex setup` | Interactive setup wizard |
+| `cortex install` | Install background services (macOS/Linux) |
+| `cortex uninstall` | Remove background services |
+| `cortex register` | Register MCP server with Claude Code |
+| `cortex capture` | Capture a knowledge object |
+| `cortex search` | Hybrid keyword + semantic search |
+| `cortex read` | Read object in full |
+| `cortex list` | List objects with filters |
+| `cortex status` | Health and counts |
+| `cortex context` | Briefing mode (summaries) |
+| `cortex dossier` | Entity-centric intelligence brief |
+| `cortex graph` | Show object relationships |
+| `cortex synthesize` | Cross-document synthesis |
+| `cortex entities` | List resolved entities |
+| `cortex serve` | Start MCP or HTTP server |
+| `cortex dashboard` | Start web dashboard |
+| `cortex import-v1` | Import from Cortex v1 database |
+| `cortex import-vault` | Import from Obsidian vault |
+
+## MCP Tools
+
+22 tools for AI agent integration. Localhost-bound HTTP exposes all; non-localhost binds expose only the public set.
+
+**Public**: `cortex_search`, `cortex_context`, `cortex_dossier`, `cortex_read`, `cortex_capture`, `cortex_link`, `cortex_feedback`, `cortex_graph`, `cortex_list`, `cortex_classify`, `cortex_pipeline`
+
+**Admin** (localhost only): `cortex_status`, `cortex_synthesize`, `cortex_delete`, `cortex_reason`, `cortex_query_trail`, `cortex_graph_data`, `cortex_list_entities`, `cortex_export`, `cortex_safety_check`, `cortex_debug_sessions`, `cortex_debug_memory`
+
+## Architecture
+
+Cortex runs as a single **MCP HTTP server** that owns the graph store. Claude Code, the dashboard, the CLI, and the REST API are all HTTP clients of that one server.
+
+```
+┌───────────────┐    ┌────────────┐    ┌─────────────┐
+│ Claude Code   │    │  Dashboard │    │     CLI     │
+│ (MCP client)  │    │ (browser)  │    │  (terminal) │
+└───────┬───────┘    └─────┬──────┘    └──────┬──────┘
+        │                  │                  │
+        │ HTTP JSON-RPC    │ HTTP MCP         │ HTTP MCP (default)
+        │                  │                  │ direct (--direct)
+        ▼                  ▼                  ▼
+        ┌──────────────────────────────────────┐
+        │   cortex serve --transport mcp-http  │
+        │   (canonical MCP HTTP server)        │
+        │   PID-locked owner of graph.db       │
+        └──────────────────────────────────────┘
+                          │
+                          ▼
+            ┌─────────────────────────────┐
+            │  ~/.cortex/                 │
+            │    graph.db   (Oxigraph)    │
+            │    cortex.db  (SQLite WAL)  │
+            └─────────────────────────────┘
+```
+
+- **Ontology**: OWL-RL formal ontology with 8 knowledge types and 8 relationship types
+- **Storage**: Oxigraph (RDF/SPARQL) + SQLite (FTS5/BM25) dual-write
+- **Pipeline**: Classify → Extract entities → Link → Enrich → Reason
+- **Retrieval**: Hybrid keyword + semantic + graph-boosted ranking
+- **Serving**: 5 presentation modes (briefing, dossier, document, synthesis, alert)
+- **Transports**: MCP (stdio + HTTP), REST API, Web Dashboard
+
+## Service Management
+
+```bash
+# Install both MCP server and dashboard as background services
+cortex install
+
+# Install only the MCP server
+cortex install --service mcp
+
+# Remove all services
+cortex uninstall
+```
+
+On macOS, this creates LaunchAgent plists (auto-start on login, auto-restart on crash).
+On Linux, this creates systemd user units.
+
+Raw templates are available in `deploy/` for manual setup.
+
+### `--direct` escape hatch
+
+By default, CLI commands route through the running MCP server. If the server is down:
+
+```bash
+cortex --direct list               # bypass MCP, open store directly
+cortex --direct pipeline --batch   # required for bulk SQL operations
+```
+
+Bootstrap commands (`init`, `setup`, `import-v1`, `import-vault`) always run directly.
+
+## Docker
+
+```bash
+docker compose up -d
+# Server at http://localhost:1314
+```
+
+## Troubleshooting
+
+### Crashed MCP server
+
+If the MCP server is killed hard, stale lock files auto-recover on next start. For manual cleanup:
+
+```bash
+cortex doctor unlock              # normal cleanup
+cortex doctor unlock --dry-run    # report only
+cortex doctor unlock --force      # bypass live-holder check
+```
+
+### Log management
+
+```bash
+cortex doctor logs                # show log file sizes and status
+cortex doctor logs --tail 20      # last 20 lines
+cortex doctor logs --rotate       # rotate log files (safe while running)
+```
+
+### Claude Code session staleness
+
+After restarting the MCP server, restart Claude Code to clear its stale session ID. `claude --resume` restores your conversation. The dashboard and CLI do not have this issue.
+
+## Knowledge Types
+
+decision, lesson, fix, session, research, source, synthesis, idea
+
+## Relationship Types
+
+causedBy, contradicts (symmetric), supports, supersedes (transitive), dependsOn, ledTo (inverse of causedBy), implements, mentions
+
+## License
+
+Copyright Abbacus Group.

abbacus_cortex-0.2.1.dist-info/RECORD

@@ -0,0 +1,65 @@
+cortex/__init__.py,sha256=fdX8yf2PkG6RQGMsP2Gwx05VVMKtujgAlPLwH03rNAw,68
+cortex/__main__.py,sha256=omWWYPYr4nDk8T7ZVLk6rXJ0TzRtZtwPIAEpRKd-Ey4,92
+cortex/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/cli/backup.py,sha256=xMTs-gi1r1p2pl4QYaIfvZxHqWmyNRFBMMSxTfHKfAM,10551
+cortex/cli/install.py,sha256=jBSyBrJ1CmokynUstyJo2cxaOMcgjFvWeJAEq3YLjBs,11570
+cortex/cli/main.py,sha256=b4alF6o6kwW5gI-OINOdh6Nmq55GekgWTZmdfMSljik,73473
+cortex/core/__init__.py,sha256=VZjPX_XAfgfdxKUuWVCLjOSP679uDExusMe9eHjjwzA,334
+cortex/core/config.py,sha256=7M1dpI_RHb673G6jTaH_3xYONt7o2Lx5dpKDxA3bThI,5591
+cortex/core/constants.py,sha256=YsVUmFYqmnrCMxLjuzX0JS6kB6gDmF7OEMKG3xrCtsM,1198
+cortex/core/errors.py,sha256=nXvHAlzf-hTZS2Ywi2ICO8ehSHQxnlJPhmwrPMlqqlc,8188
+cortex/core/logging.py,sha256=Em3CKkeCWxw4wtLoJytRv1kV0bdTi5PhArfJUO4KA08,7153
+cortex/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/dashboard/server.py,sha256=uyaWZDhS7XopvPzKBgoojPjnlR29aEtxBQyaI2uBzZc,12255
+cortex/dashboard/static/css/style.css,sha256=qTqAhgOlaNLWGRccmDjb6u8nwiF6Fi-gnfMv3oB-AUQ,6578
+cortex/dashboard/static/js/graph.js,sha256=JmVZSy6WaicYWslFXMqoc5ywxrex8wCWETOtTibvWs0,5677
+cortex/dashboard/templates/base.html,sha256=bcI3NVyyTw4hsNq-M-Q1L4OY1KW2B_UpVi10XqZmp4c,1385
+cortex/dashboard/templates/create.html,sha256=OQ4ZMi_erDLac0_IqVsT24r3_jy3TpUOmxxFqH9ZCWQ,1600
+cortex/dashboard/templates/detail.html,sha256=AalREYMa8XRQGp-3Y-88_Ok47aedaPTbX6JeuLGmnQo,1845
+cortex/dashboard/templates/documents.html,sha256=KK6RgmchRgT-qKNSVhbR3mgOBRiUbaxgj3Vl2MNtSfM,1929
+cortex/dashboard/templates/entities.html,sha256=9nadwZYdP9vCk5kYpmPiBN75Lat-VmqbTEVPLdsogp8,1482
+cortex/dashboard/templates/error.html,sha256=Wj3OBN9o0LJmbIcP1obiOrCS96Q4T_Dangxqcub0KYc,665
+cortex/dashboard/templates/graph.html,sha256=OQad4DAuVhDnPz1jb6TzfxAcDtiw-1RtkC95Bo-FrT0,1608
+cortex/dashboard/templates/home.html,sha256=K1ewFV5ke0_k9cceVD4cOdBv-nPEBiGkPO1fgFxde9U,1749
+cortex/dashboard/templates/login.html,sha256=2rJGZVXpKhlBtA0YJBYTErouCQFUEEkilvW7Le1PrEY,846
+cortex/dashboard/templates/settings.html,sha256=sROZ3UJWcZgth5zb0axCZHt_8GiMfyBQAulkOZ59IsQ,1465
+cortex/dashboard/templates/trail.html,sha256=QyNsMA4x6pQ21gIqY9l6_OKRfcBd2OIrovftCZVwFrQ,1004
+cortex/db/__init__.py,sha256=CPsig_A8yUNJnilkptnT5H_KiQ5R1aDm83VB6q7499k,136
+cortex/db/content_store.py,sha256=3QA4fJ73DiWW6N3eRF1TWa1gmnpIIF5CnJukJYAZItg,15102
+cortex/db/graph_store.py,sha256=UrYHBdsfqt64Nnc7e9PJ6Exut4Wj3og05oPBFizRbMQ,36340
+cortex/db/store.py,sha256=xLJCKPdwbLJFpz6aqlB1vm1G9z05pBNADUQvRD1g5Rg,8531
+cortex/ontology/__init__.py,sha256=iQyQB_GTmQR_uICI7PAB2Qn5tHhTCqBe6yNfy8KlwSQ,158
+cortex/ontology/cortex.ttl,sha256=xP2-m9vQUvz7j8jntVuERlAn80vTeDD7dFpxA53WqvE,13662
+cortex/ontology/namespaces.py,sha256=A7bHHMvJ69nIJQhd7078kWvmHSjoUmaeBW_ylzuIC8Y,2205
+cortex/ontology/resolver.py,sha256=ujYOGhTO-nwjpKjdQ_i8ysE9IXdYteW9G5otVbyDDUg,989
+cortex/pipeline/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/pipeline/advanced_reason.py,sha256=b2_tvn5HoxZtoGbFOQKv5ZlBHwAxpkuKq6yXwTMQM-s,12059
+cortex/pipeline/enrich.py,sha256=OTKUxubU7QZLNzQeO5fsKvm3IJ5yu2kChCeGALx7vag,3790
+cortex/pipeline/importer.py,sha256=yCl3SP1R1efMyMO2gIo4bCr2gWXnB1mhsgkhZqZ-Es8,20983
+cortex/pipeline/link.py,sha256=JT5upsowG3jCo-qfjroI6K2UzksSZm5A8Dfg_q7EbEw,4764
+cortex/pipeline/normalize.py,sha256=CqDjj1kHAD-U-nQi7gNfCIswxVNViW_pDY8-3HXD3j0,4958
+cortex/pipeline/orchestrator.py,sha256=VGTn3hnptR7FCeIEffrp5LDevcgN_oMrNbWMijlTfgs,6779
+cortex/pipeline/reason.py,sha256=dIw3B_5YnBX9Ic0UN-v2sCfZp-nVVv_c7FT74kwv47I,6462
+cortex/pipeline/templates.py,sha256=_nMChnXMuARX-uyfSZrPlaJeyLlRv0AO9_eaUf7u3HA,2884
+cortex/pipeline/temporal.py,sha256=zJiY3GW2joyJI_rsVmdHkIhvsBGeUwqLMAU9M_35K50,4642
+cortex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/retrieval/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/retrieval/engine.py,sha256=TZbrHR3p1gpMVT-7RCoFr655QjocPAOqeDVaJ_dZMjQ,8464
+cortex/retrieval/graph.py,sha256=7NIDpWnFH5ocsKG75RLmLH5N1yl1j9dmuhmggjPl_Fg,9442
+cortex/retrieval/learner.py,sha256=l-B00mZppIxVcM_mZQxwNk8WMqw4oQ8e2_-4E2wlUFk,4857
+cortex/retrieval/presenters.py,sha256=izqsXxd3KlBKtMfMhm-ZDn75H6U7eACfhnQlhrEss3Q,13903
+cortex/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/services/embeddings.py,sha256=e4s6Fc1XGzU85fuOdLUuLBILON6hS539SkskMEyA5IE,6388
+cortex/services/llm.py,sha256=5ituqPM7eKRMwWnuqkfjTW-yoSR_AW8w8p0phqw7Zpk,8738
+cortex/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/transport/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/transport/api/server.py,sha256=fteAYnF9lHYB6lsKa3l96O_hUqCRDQM8pkRSnbZMcAs,15647
+cortex/transport/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortex/transport/mcp/__main__.py,sha256=SDv0uFPqsHIntBumxIZYkXOLOtCV-xP1YClO6EBHVMw,151
+cortex/transport/mcp/client.py,sha256=bav28U68umFBOANh878WsgPxH0DgsA9YhRuxwPFqB9E,17381
+cortex/transport/mcp/server.py,sha256=tInX88m0Q8Kd_2R0tflcNCU87vMJqlUYQ4aKczGhpE8,26972
+abbacus_cortex-0.2.1.dist-info/WHEEL,sha256=s_zqWxHFEH8b58BCtf46hFCqPaISurdB9R1XJ8za6XI,80
+abbacus_cortex-0.2.1.dist-info/entry_points.txt,sha256=Cf_p26EHtXKEoKpjBCHUfjXku9cC2-S5Qpb_issRlGM,48
+abbacus_cortex-0.2.1.dist-info/METADATA,sha256=Yg5PdYHNSb9IKj0ICyFw4EqN-R-K7-sy1EGrDYdAaVI,7844
+abbacus_cortex-0.2.1.dist-info/RECORD,,

abbacus_cortex-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.6
+Root-Is-Purelib: true
+Tag: py3-none-any

abbacus_cortex-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+cortex = cortex.cli.main:app
+

cortex/__init__.py

@@ -0,0 +1,3 @@
+"""Cortex — Cognitive knowledge system."""
+
+__version__ = "0.2.1"

cortex/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running Cortex as ``python -m cortex``."""
+
+from cortex.cli.main import app
+
+app()

cortex/cli/backup.py

@@ -0,0 +1,317 @@
+"""Backup and restore for Cortex data stores.
+
+Creates timestamped tar.gz archives of cortex.db and graph.db/, and
+restores them with safety rollback via a .pre-restore/ staging area.
+"""
+
+from __future__ import annotations
+
+import shutil
+import sqlite3
+import tarfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from cortex.core.config import CortexConfig
+
+# ---------------------------------------------------------------------------
+# Exclusion rules
+# ---------------------------------------------------------------------------
+
+# Relative paths (from data_dir) to exclude from backup archives.
+_EXCLUDE_EXACT = frozenset({
+    "graph.db.lock",
+    "graph.db/LOCK",
+    ".env",
+    "cortex.db-wal",
+    "cortex.db-shm",
+})
+
+_EXCLUDE_SUFFIXES = (".log", ".err", ".log.old", ".err.old")
+
+
+def _should_exclude(rel: str) -> bool:
+    """Return True if *rel* (relative to data_dir) should be skipped."""
+    if rel in _EXCLUDE_EXACT:
+        return True
+    # Top-level server logs
+    parts = rel.split("/")
+    if len(parts) == 1 and rel.endswith(_EXCLUDE_SUFFIXES):
+        return True
+    # RocksDB diagnostic log archives inside graph.db/
+    if parts[0] == "graph.db" and len(parts) == 2:
+        name = parts[1]
+        if name.startswith("LOG.old"):
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Server-running check
+# ---------------------------------------------------------------------------
+
+
+def _check_server_running(config: CortexConfig) -> tuple[bool, int | None, str | None]:
+    """Check if a Cortex server is holding the graph.db lock.
+
+    Returns (is_running, pid_or_none, cmdline_or_none).
+    """
+    from cortex.db.graph_store import _marker_path_for, _pid_alive, _read_marker
+
+    marker_path = _marker_path_for(config.graph_db_path)
+    if not marker_path.exists():
+        return (False, None, None)
+
+    marker = _read_marker(marker_path)
+    if marker is None or marker.get("_unreadable"):
+        return (False, None, None)
+
+    raw_pid = marker.get("pid")
+    if not isinstance(raw_pid, int):
+        return (False, None, None)
+
+    cmdline = marker.get("cmdline")
+    if _pid_alive(raw_pid):
+        return (True, raw_pid, cmdline)
+    return (False, raw_pid, cmdline)
+
+
+# ---------------------------------------------------------------------------
+# SQLite WAL checkpoint
+# ---------------------------------------------------------------------------
+
+
+def _checkpoint_sqlite(db_path: Path) -> None:
+    """Flush the SQLite WAL into the main database file.
+
+    Uses a short-lived direct connection (not ContentStore) to avoid
+    acquiring schema locks or interfering with a running server.
+    """
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Human-readable file size
+# ---------------------------------------------------------------------------
+
+
+def _human_size(nbytes: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if nbytes < 1024:
+            return f"{nbytes:.1f} {unit}" if unit != "B" else f"{nbytes} {unit}"
+        nbytes /= 1024
+    return f"{nbytes:.1f} TB"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def do_backup(config: CortexConfig, output: Path | None = None) -> Path:
+    """Create a tar.gz backup of cortex.db and graph.db/.
+
+    Returns the path to the created archive.
+    """
+    # 1. Verify stores exist
+    if not config.sqlite_db_path.exists():
+        typer.secho(
+            f"Cortex not initialized — {config.sqlite_db_path} not found.\n"
+            "Run `cortex init` first.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if not config.graph_db_path.exists() or not config.graph_db_path.is_dir():
+        typer.secho(
+            f"Graph store not found at {config.graph_db_path}.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # 2. Warn if server is running (safe to proceed)
+    running, pid, _cmdline = _check_server_running(config)
+    if running:
+        typer.secho(
+            f"  Cortex server is running (PID {pid}). "
+            "Backup will proceed — stores support concurrent reads.",
+            fg=typer.colors.YELLOW,
+        )
+
+    # 3. Checkpoint SQLite WAL
+    typer.echo("  Checkpointing SQLite WAL...")
+    _checkpoint_sqlite(config.sqlite_db_path)
+
+    # 4. Build archive
+    stamp = datetime.now(UTC).strftime("%Y-%m-%dT%H%M%S")
+    filename = f"cortex-backup-{stamp}.tar.gz"
+    out_dir = output if output else Path.cwd()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = out_dir / filename
+
+    typer.echo(f"  Archiving to {archive_path}...")
+    data_dir = config.data_dir
+    with tarfile.open(archive_path, "w:gz") as tar:
+        for path in sorted(data_dir.rglob("*")):
+            if not path.is_file():
+                continue
+            rel = str(path.relative_to(data_dir))
+            if _should_exclude(rel):
+                continue
+            tar.add(str(path), arcname=rel)
+
+    # 5. Report
+    size = archive_path.stat().st_size
+    doc_count = _quick_doc_count(config.sqlite_db_path)
+    typer.secho(f"\nBackup complete: {archive_path}", fg=typer.colors.GREEN)
+    typer.echo(f"  Size: {_human_size(size)}")
+    if doc_count is not None:
+        typer.echo(f"  Documents: {doc_count}")
+
+    return archive_path
+
+
+def do_restore(config: CortexConfig, archive: Path) -> None:
+    """Restore Cortex data from a tar.gz backup archive."""
+    # 1. Verify archive exists
+    if not archive.exists():
+        typer.secho(f"Archive not found: {archive}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    # 2. Validate archive
+    try:
+        with tarfile.open(archive, "r:gz") as tar:
+            names = tar.getnames()
+    except tarfile.TarError as e:
+        typer.secho(
+            f"Invalid archive: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1) from None
+
+    # 3. Validate contents
+    has_db = "cortex.db" in names
+    has_graph = any(n.startswith("graph.db/") for n in names)
+    if not has_db or not has_graph:
+        missing = []
+        if not has_db:
+            missing.append("cortex.db")
+        if not has_graph:
+            missing.append("graph.db/")
+        typer.secho(
+            f"Archive is missing required files: {', '.join(missing)}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    # 4. Path traversal check
+    for name in names:
+        if name.startswith("/") or ".." in name.split("/"):
+            typer.secho(
+                f"Archive contains unsafe path: {name!r}. Refusing to extract.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(1)
+
+    # 5. Refuse if server is running
+    running, pid, _cmdline = _check_server_running(config)
+    if running:
+        typer.secho(
+            f"Cortex server is running (PID {pid}). "
+            f"Stop it first:\n  cortex uninstall\n  # or: kill {pid}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    data_dir = config.data_dir
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    # 6. Safety: move current stores to .pre-restore/
+    pre_restore = data_dir / ".pre-restore"
+    if pre_restore.exists():
+        shutil.rmtree(pre_restore)
+    pre_restore.mkdir()
+
+    moved_db = False
+    moved_graph = False
+    try:
+        if config.sqlite_db_path.exists():
+            shutil.move(str(config.sqlite_db_path), str(pre_restore / "cortex.db"))
+            moved_db = True
+            # Also move WAL/SHM if present
+            for suffix in ("-wal", "-shm"):
+                wal = config.data_dir / f"cortex.db{suffix}"
+                if wal.exists():
+                    shutil.move(str(wal), str(pre_restore / f"cortex.db{suffix}"))
+
+        if config.graph_db_path.exists():
+            shutil.move(str(config.graph_db_path), str(pre_restore / "graph.db"))
+            moved_graph = True
+
+        # 7. Extract
+        typer.echo(f"  Extracting {archive.name} to {data_dir}...")
+        with tarfile.open(archive, "r:gz") as tar:
+            tar.extractall(path=str(data_dir), filter="data")
+
+        # 8. Clean lock files from extraction
+        lock_marker = data_dir / "graph.db.lock"
+        if lock_marker.exists():
+            lock_marker.unlink()
+        rocksdb_lock = config.graph_db_path / "LOCK"
+        if rocksdb_lock.exists():
+            rocksdb_lock.unlink()
+
+    except Exception:
+        # Attempt rollback
+        typer.secho(
+            "\nExtraction failed — rolling back from .pre-restore/",
+            fg=typer.colors.YELLOW,
+            err=True,
+        )
+        if moved_db and (pre_restore / "cortex.db").exists():
+            shutil.move(str(pre_restore / "cortex.db"), str(config.sqlite_db_path))
+            for suffix in ("-wal", "-shm"):
+                backed = pre_restore / f"cortex.db{suffix}"
+                if backed.exists():
+                    shutil.move(str(backed), str(config.data_dir / f"cortex.db{suffix}"))
+        if moved_graph and (pre_restore / "graph.db").exists():
+            shutil.move(str(pre_restore / "graph.db"), str(config.graph_db_path))
+        raise
+
+    # 9. Report
+    doc_count = _quick_doc_count(config.sqlite_db_path)
+    typer.secho(f"\nRestore complete: {data_dir}", fg=typer.colors.GREEN)
+    if doc_count is not None:
+        typer.echo(f"  Documents: {doc_count}")
+    typer.echo("  Old data saved to .pre-restore/ (safe to delete after verifying).")
+    typer.echo("  Run `cortex status` to verify.")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _quick_doc_count(db_path: Path) -> int | None:
+    """Quick readonly document count from SQLite. Returns None on any error."""
+    try:
+        conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+        try:
+            row = conn.execute("SELECT COUNT(*) FROM documents").fetchone()
+            return row[0] if row else None
+        finally:
+            conn.close()
+    except Exception:
+        return None