droste-memory 1.0.0a0__tar.gz

droste_memory-1.0.0a0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to Droste
+
+Thanks for helping build the causal-memory layer for AI agents. 🌌
+
+## Dev setup
+
+```bash
+git clone <your fork>
+cd droste-memory
+pip install -e ".[dev]"
+pytest                 # should be green before you start
+```
+
+## Ground rules
+
+- **Tests stay green.** `pytest` runs the deterministic regression suite
+  (`tests/`). Add a test for any behaviour change to the engine, ingester, or
+  packer. The suite forces the deterministic hash embedding backend, so it runs
+  offline with no model download.
+- **`eval/` is for benchmarks, `tests/` is for invariants.** Don't mix them.
+- **Keep the zero-config moat.** New required deps are a big deal — prefer
+  optional extras. `fastembed` (no torch) and `tree-sitter-language-pack` are the
+  only heavy runtime deps and both degrade gracefully if missing.
+- **Never commit user data.** `droste_memory_db.json`, `.droste/`,
+  `visualizer/graph.json` and `status.json` are gitignored — they can contain a
+  user's source. Only `visualizer/demo_graph.json` (Droste indexing itself) is
+  public.
+
+## Good first issues
+
+- New language extractor / edge rules in `core/treesitter_extract.py`.
+- More cross-language bridges in `core/droste_ingester.py`
+  (`_build_dependency_links`) — e.g. ORM table refs, GraphQL, gRPC.
+- Visualizer polish in `visualizer/cockpit.html`.
+
+## PRs
+
+Small, focused, with a one-line rationale and a test. CI runs `pytest` on
+Linux across Python 3.10–3.12.

droste_memory-1.0.0a0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Droste-Memory authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

droste_memory-1.0.0a0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md LICENSE CONTRIBUTING.md requirements.txt
+recursive-include visualizer *.html *.py *.json
+prune visualizer/graph.json
+prune visualizer/status.json

droste_memory-1.0.0a0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: droste-memory
+Version: 1.0.0a0
+Summary: Local hybrid structural and semantic graph memory engine.
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: fastembed>=0.8.0
+Requires-Dist: truststore>=0.10.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: tree-sitter-language-pack>=1.9.0
+Provides-Extra: heavy-embed
+Requires-Dist: sentence-transformers>=2.7.0; extra == "heavy-embed"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file

droste_memory-1.0.0a0/README.md

@@ -0,0 +1,148 @@
+<div align="center">
+
+# 🌌 Droste
+
+### See your codebase as a living galaxy — and give your AI agent causal memory of it.
+
+Droste indexes any repo into a **fractal, zoomable map of its symbols**, wires them
+together with their **real call / import / DB edges across languages**, and serves
+an AI agent the *causal* slice of code it actually needs — not just keyword matches.
+
+**Local-first · zero-config · polyglot · MCP-native**
+
+<!-- ░░░ HERO ░░░  replace with a 10s GIF: galaxy → zoom into a folder → click a
+     symbol → a cross-language wormhole lights up. See docs/assets/README.md. -->
+![Droste fractal code galaxy](docs/assets/hero.gif)
+
+[Quickstart](#-quickstart) · [Why it's different](#-why-its-different) · [How it works](#-how-it-works) · [MCP](#-use-it-from-claude--cursor-mcp) · [Benchmarks](#-benchmarks)
+
+</div>
+
+---
+
+## ⚡ Quickstart
+
+```bash
+pip install -e .          # or: pip install droste-memory   (once on PyPI)
+droste index .            # index the current repo
+droste view               # open the fractal galaxy in your browser  ✨
+```
+
+Three commands. `droste view` opens a full-screen, 60fps zoomable map of your
+code — scroll to dive from the project star into folder orbits, down to the
+individual functions, with the causal edges glowing between them.
+
+Need it for an agent instead of your eyes?
+
+```bash
+droste context "checkout flow" --budget 1500   # causal context slice for an LLM
+```
+
+---
+
+## ✨ Why it's different
+
+Most "code context" tools rank by **keyword** (ctags / ripgrep / repo-maps) or by
+**embedding cosine** (vector-RAG). Both can only return what *resembles* your query.
+A caller that shares no tokens — or a database function in a different language — is
+invisible to them, yet it's exactly what you need to understand or change the code.
+
+Droste's edge is the **causal graph**:
+
+- 🧭 **Causal wormholes.** Real `syntax_dependency` edges (calls, imports,
+  inheritance) in both directions — Droste hands the agent the *callers and
+  callees*, ordered, within a token budget.
+- 🌍 **Cross-language bridges.** This is the part nobody else does well: Droste
+  links **across languages** — app code → **SQL** functions/tables (`.rpc('x')`,
+  `.from('table')`), → **edge functions**, and same-name handlers between any two
+  languages. Your Dart/TS/Python frontend and your database stop being two
+  separate worlds on the map.
+- 🪐 **A map you actually want to look at.** The fractal galaxy isn't a gimmick —
+  it's how you *see* coupling, risk hotspots, and the blast radius of a change.
+- 🔌 **Zero-config & local.** No cloud, no account, no API key. `fastembed` (ONNX,
+  no torch) gives real semantics; a deterministic fallback keeps it runnable
+  anywhere.
+
+**Polyglot:** Python (AST) + tree-sitter for **Dart, TypeScript/JavaScript, Go,
+Rust, Java, C#, C/C++, Kotlin, Swift, Ruby, PHP, SQL** — symbols *and* edges.
+
+> **Honest scope:** Droste's measured advantage is **structural / causal**
+> retrieval. On pure semantic "concept" queries it's competitive with a vector
+> baseline, not a leap. Cross-language bridges are strongest where the target is
+> actually defined in the indexed repo (e.g. SQL schema in your migrations).
+
+---
+
+## 📊 Benchmarks
+
+Self-supervised eval (gold = the true caller/callee set from the AST), equal
+retrieval breadth *k*, **real** embeddings, across Python + Dart repos
+(`eval/comparative_eval.py`):
+
+| structural retrieval | **Droste** | vector-RAG core | lexical core |
+| --- | --- | --- | --- |
+| neighbour-recall | **0.94** | 0.18 | 0.42 |
+| nDCG@k | **0.65** | 0.10 | 0.29 |
+
+…plus hundreds of true causal neighbours that **both** baselines structurally miss.
+This is a *retrieval-method* comparison (the cores of vector-RAG and lexical search),
+not a head-to-head against the finished products that wrap them.
+
+---
+
+## 🔍 How it works
+
+- **Causal graph.** Each definition is parsed (Python `ast`; tree-sitter for the
+  rest) into the names it calls / imports / inherits → first-class
+  `syntax_dependency` edges. Cross-language edges add DB calls (`.rpc`, `.from`,
+  `.functions.invoke`) and string-literal name matches across languages.
+- **Hybrid seed.** A query is matched by a normalized blend of lexical score and
+  semantic cosine (fastembed `bge-small-en-v1.5`, 384-dim), then the graph expands
+  the seed bidirectionally (callees *and* callers).
+- **Token packer.** Results fit a budget with LOD-demotion (full → contract →
+  skeleton) and a hard guardrail that never cuts a line of code mid-token.
+- **Sharded persistence.** One shard per file under `.droste/`, blake2b
+  dirty-tracking so a re-index rewrites only what changed; atomic writes + meta
+  written last → crash-safe (it self-heals on the next run).
+
+---
+
+## 🔌 Use it from Claude / Cursor (MCP)
+
+Droste is a drop-in **MCP server** — your agent calls it as primary code memory
+instead of blind file reads.
+
+```jsonc
+{
+  "mcpServers": {
+    "droste": { "command": "python", "args": ["/abs/path/to/droste-memory/server.py"] }
+  }
+}
+```
+
+Key tools: `droste_index_project`, `droste_get_context`, `droste_status`.
+
+---
+
+## 🧪 Development
+
+```bash
+pip install -e ".[dev]"
+pytest                            # deterministic regression suite (tests/)
+python eval/comparative_eval.py   # retrieval benchmark vs lexical & vector cores
+```
+
+`tests/` = invariants + concurrency (round-trip, dirty-oracle, packer guardrail,
+cross-process shard race). `eval/` = performance/quality benchmarks.
+
+---
+
+## 🗺️ Status
+
+**v1.0.0a0 (alpha).** Engine, polyglot + cross-language graph, CLI, fractal
+visualizer and MCP server are working and tested. Packaging/distribution are
+maturing — issues and PRs welcome (`CONTRIBUTING.md`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

droste_memory-1.0.0a0/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core package for Droste-Memory."""
+
+from .droste_engine import DrosteConceptEngine, DrosteNode
+from .droste_ingester import DrosteProjectIngester
+
+__all__ = ["DrosteConceptEngine", "DrosteNode", "DrosteProjectIngester"]

droste_memory-1.0.0a0/core/droste_cli.py

@@ -0,0 +1,409 @@
+"""Command line interface for Droste-Memory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+from urllib import error, request
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+LOCAL_PACKAGES = ROOT / ".python-packages"
+if LOCAL_PACKAGES.exists():
+    sys.path.insert(0, str(LOCAL_PACKAGES))
+
+from core.droste_engine import DEFAULT_DB_PATH, DrosteConceptEngine
+from core.droste_ingester import DrosteProjectIngester, droste_zoom_query
+
+
+VERSION = "v1.0-Alpha-Sharded"
+VISUALIZER_CAMERA_URL = "http://127.0.0.1:5000/api/camera"
+
+RESET = "\033[0m"
+GREEN = "\033[92m"
+CYAN = "\033[96m"
+WHITE = "\033[97m"
+DIM = "\033[2m"
+
+
+RADIAL_ART = r"""
+                  .-----------------------.
+             .----'           |           '----.
+         .---'          .-----+-----.          '---.
+       .'          .----'     |     '----.          '.
+      /        .---'      .---+---.      '---.        \
+     /      .-'        .-'    |    '-.        '-.      \
+    |     .'        .-'   .---+---.   '-.        '.     |
+    |    /        .'    .'    |    '.    '.        \    |
+    |   |        |     |   .--+--.   |     |        |   |
+    | --+--------+-----+---+  @  +---+-----+--------+-- |
+    |   |        |     |   '--+--'   |     |        |   |
+    |    \        '.    '.    |    .'    .'        /    |
+    |     '.        '-.   '---+---'   .-'        .'     |
+     \      '-.        '-.    |    .-'        .-'      /
+      \        '---.      '---+---'      .---'        /
+       '.          '----.     |     .----'          .'
+         '---.          '-----+-----'          .---'
+             '----.           |           .----'
+                  '-----------------------'
+"""
+
+
+def _wants_color(enabled: bool | None = None) -> bool:
+    if enabled is not None:
+        return enabled
+    if os.environ.get("NO_COLOR"):
+        return False
+    return sys.stdout.isatty()
+
+
+def _paint(text: str, color: str, enabled: bool) -> str:
+    return f"{color}{text}{RESET}" if enabled else text
+
+
+def print_splash(color: bool | None = None) -> None:
+    enabled = _wants_color(color)
+    art_lines = RADIAL_ART.strip("\n").splitlines()
+    for index, line in enumerate(art_lines):
+        print(_paint(line, CYAN if index % 2 == 0 else GREEN, enabled))
+    print()
+    print(_paint("DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT", WHITE, enabled))
+    print(_paint(f"Local Graph Engine {VERSION}", WHITE, enabled))
+    print()
+    print(_paint("Commands", CYAN, enabled))
+    print("  droste index <path> [--reset]")
+    print("  droste status")
+    print("  droste zoom <symbol_name>")
+    print("  droste context [query] --budget 1500")
+    print()
+    print(_paint("Fast path: droste context hub_core --budget 1000 | clip", DIM, enabled))
+
+
+def print_compact_header(color: bool | None = None) -> None:
+    enabled = _wants_color(color)
+    print(_paint(f"DROSTE-MEMORY {VERSION}", WHITE, enabled))
+    print(_paint("Rigid Fractal Radial Layout", CYAN, enabled))
+
+
+def _human_bytes(size: int) -> str:
+    units = ("B", "KB", "MB", "GB", "TB")
+    value = float(size)
+    for unit in units:
+        if value < 1024 or unit == units[-1]:
+            if unit == "B":
+                return f"{int(value)} {unit}"
+            return f"{value:.2f} {unit}"
+        value /= 1024
+    return f"{size} B"
+
+
+def _load_meta(db_path: Path) -> dict[str, Any]:
+    if not db_path.exists():
+        return {"storage": "missing", "error": None}
+    try:
+        return json.loads(db_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        return {"storage": "corrupt", "error": str(exc)}
+    except OSError as exc:
+        return {"storage": "unreadable", "error": str(exc)}
+
+
+def _storage_label(db_path: Path) -> str:
+    meta = _load_meta(db_path)
+    storage = meta.get("storage")
+    if storage == "sharded":
+        return "Sharded"
+    if storage in {"missing", "corrupt", "unreadable"}:
+        return str(storage).title()
+    if isinstance(meta.get("nodes"), list) and meta.get("nodes"):
+        return "Legacy inline (migrates on next graph save)"
+    return "Inline empty"
+
+
+def _shard_stats(db_path: Path) -> dict[str, Any]:
+    shard_dir = db_path.parent / ".droste" / "nodes"
+    if not shard_dir.exists():
+        return {"path": str(shard_dir), "count": 0, "bytes": 0}
+    files = [path for path in shard_dir.glob("*.json") if path.is_file()]
+    return {
+        "path": str(shard_dir),
+        "count": len(files),
+        "bytes": sum(path.stat().st_size for path in files),
+    }
+
+
+def _engine(db_path: Path | None = None) -> DrosteConceptEngine:
+    return DrosteConceptEngine(db_path=db_path or DEFAULT_DB_PATH)
+
+
+def command_status(args: argparse.Namespace) -> int:
+    engine = _engine(args.db)
+    migration = engine.ensure_sharded_storage()
+    nodes = engine.all_nodes()
+    links = engine.all_links()
+    symbol_count = sum(1 for node in nodes if node.node_type == "symbol")
+    syntax_link_count = sum(1 for link in links if link.type == "syntax_dependency")
+    shard_stats = _shard_stats(engine.db_path)
+
+    payload = {
+        "storage": _storage_label(engine.db_path),
+        "database": str(engine.db_path),
+        "node_count": len(nodes),
+        "symbol_count": symbol_count,
+        "link_count": len(links),
+        "syntax_link_count": syntax_link_count,
+        "shard_dir": shard_stats["path"],
+        "shard_count": shard_stats["count"],
+        "shard_bytes": shard_stats["bytes"],
+        "migration": migration,
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0
+
+    print_compact_header()
+    print("status")
+    print(f"  migration:     {migration['status']}")
+    print(f"  storage:       {payload['storage']}")
+    print(f"  database:      {payload['database']}")
+    print(f"  live nodes:    {payload['node_count']}")
+    print(f"  symbols:       {payload['symbol_count']}")
+    print(f"  links:         {payload['link_count']}")
+    print(f"  syntax links:  {payload['syntax_link_count']}")
+    print(f"  shard dir:     {payload['shard_dir']}")
+    print(f"  shard files:   {payload['shard_count']}")
+    print(f"  shard cache:   {_human_bytes(int(payload['shard_bytes']))}")
+    return 0
+
+
+def _post_visualizer_camera(camera: dict[str, Any], url: str) -> tuple[bool, str]:
+    payload = {
+        "x": camera.get("x", 0.0),
+        "y": camera.get("y", 0.0),
+        "zoom_level": camera.get("zoom", 1.0),
+    }
+    body = json.dumps(payload).encode("utf-8")
+    req = request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with request.urlopen(req, timeout=1.5) as response:
+            return True, f"HTTP {response.status}"
+    except (OSError, error.URLError, error.HTTPError) as exc:
+        return False, str(exc)
+
+
+def _open_editor(source_path: str | None, line_start: int | None) -> tuple[bool, str]:
+    if not source_path:
+        return False, "no source_path on focused node"
+    line = max(1, int(line_start or 1))
+    target = f"{source_path}:{line}"
+    code = shutil.which("code")
+    if code:
+        subprocess.Popen([code, "--goto", target])
+        return True, f"code --goto {target}"
+    return False, target
+
+
+def command_zoom(args: argparse.Namespace) -> int:
+    engine = _engine(args.db)
+    result = droste_zoom_query(args.symbol_name, engine=engine)
+    if result.get("status") != "focused":
+        print(f"not found: {args.symbol_name}", file=sys.stderr)
+        return 2
+
+    node = result["focused_node"]
+    camera = result["camera"]
+    print(f"focused: {node['title']}")
+    print(f"  node:   {node['id']}")
+    print(f"  type:   {node['node_type']}")
+    print(f"  source: {node.get('source_path') or '(none)'}")
+    print(f"  line:   {node.get('line_start') or '(none)'}")
+    print(f"  camera: x={camera['x']:.4f} y={camera['y']:.4f} zoom={camera['zoom']:.2f}")
+
+    if not args.no_visualizer:
+        ok, message = _post_visualizer_camera(camera, args.visualizer_url)
+        status = "sent" if ok else "not sent"
+        print(f"  visualizer: {status} ({message})")
+
+    if not args.no_open:
+        opened, message = _open_editor(node.get("source_path"), node.get("line_start"))
+        status = "opened" if opened else "fallback"
+        print(f"  editor: {status} ({message})")
+    return 0
+
+
+def command_context(args: argparse.Namespace) -> int:
+    engine = _engine(args.db)
+    ingester = DrosteProjectIngester(engine)
+    result = ingester.get_context(args.query, budget=args.budget)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+    print(result.get("compiled_context", ""))
+    return 0
+
+
+def command_index(args: argparse.Namespace) -> int:
+    from core import treesitter_extract
+
+    path = Path(args.path).expanduser()
+    if not path.is_dir():
+        print(f"not a directory: {path}", file=sys.stderr)
+        return 2
+
+    engine = _engine(args.db)
+    ingester = DrosteProjectIngester(engine)
+    result = ingester.index_project(
+        str(path),
+        reset=args.reset,
+        max_files=args.max_files,
+        max_symbols=args.max_symbols,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+
+    stats = result["stats"]
+    ts_on = result.get("treesitter_available", treesitter_extract.available())
+    print_compact_header()
+    print(f"indexed {path}")
+    print(f"  files:         {stats['file_count']}")
+    print(f"  symbols:       {stats['symbol_count']}")
+    print(f"  links:         {stats['link_count']}")
+    print(f"  syntax edges:  {result.get('syntax_dependency_links', 0)}")
+    print(f"  reused files:  {result.get('reused_files', 0)}")
+    print(f"  embeddings:    {engine.projector.backend}")
+    if ts_on:
+        print("  tree-sitter:   on (polyglot call-graph active)")
+    else:
+        print("  tree-sitter:   OFF — non-Python files degrade to symbols "
+              "without causal edges")
+        print("                 fix: pip install tree-sitter-language-pack",
+              file=sys.stderr)
+    return 0
+
+
+def command_view(args: argparse.Namespace) -> int:
+    """Export the live graph for the chosen root and open the fractal cockpit —
+    the one-command 'wow': index, then `droste view`."""
+    import http.server
+    import importlib.util
+    import socketserver
+    import threading
+    import webbrowser
+
+    vis_dir = ROOT / "visualizer"
+    spec = importlib.util.spec_from_file_location(
+        "droste_export_graph", str(vis_dir / "export_graph.py"))
+    exporter = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(exporter)
+    try:
+        counts = exporter.export(args.root, vis_dir / "graph.json")
+    except SystemExit as exc:
+        print(exc, file=sys.stderr)
+        return 2
+
+    engine = _engine(args.db)
+    nodes = engine.all_nodes()
+    links = engine.all_links()
+    (vis_dir / "status.json").write_text(json.dumps({
+        "node_count": len(nodes),
+        "symbol_count": sum(1 for n in nodes if n.node_type == "symbol"),
+        "link_count": len(links),
+        "syntax_link_count": sum(1 for l in links if l.type == "syntax_dependency"),
+        "counts": counts,
+    }, ensure_ascii=False), encoding="utf-8")
+
+    def handler(*a, **k):
+        return http.server.SimpleHTTPRequestHandler(*a, directory=str(vis_dir), **k)
+
+    socketserver.TCPServer.allow_reuse_address = True
+    httpd = socketserver.TCPServer(("127.0.0.1", args.port), handler)
+    url = f"http://127.0.0.1:{args.port}/cockpit.html"
+    print_compact_header()
+    print(f"view  ->  {url}")
+    print(f"  project: {counts['symbol']} symbols / {counts['edge']} causal edges "
+          f"across {counts['file']} files")
+    print("  Ctrl+C to stop")
+    if not args.no_open:
+        threading.Timer(0.6, lambda: webbrowser.open(url)).start()
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nstopped")
+    finally:
+        httpd.server_close()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="droste",
+        description="Droste-Memory cyberpunk graph CLI.",
+    )
+    parser.add_argument("--db", type=Path, default=DEFAULT_DB_PATH, help=argparse.SUPPRESS)
+    parser.add_argument("--version", action="version", version=f"droste {VERSION}")
+    sub = parser.add_subparsers(dest="command")
+
+    index = sub.add_parser("index", help="Index a project into the local graph.")
+    index.add_argument("path", help="Project root directory to index.")
+    index.add_argument("--reset", action="store_true",
+                       help="Wipe this root's prior nodes before indexing.")
+    index.add_argument("--max-files", type=int, default=2000)
+    index.add_argument("--max-symbols", type=int, default=20000)
+    index.add_argument("--json", action="store_true", help="Emit the full index result JSON.")
+    index.set_defaults(func=command_index)
+
+    status = sub.add_parser("status", help="Show local graph health.")
+    status.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    status.set_defaults(func=command_status)
+
+    zoom = sub.add_parser("zoom", help="Focus a symbol in editor and visualizer.")
+    zoom.add_argument("symbol_name")
+    zoom.add_argument("--no-open", action="store_true", help="Do not launch the editor.")
+    zoom.add_argument(
+        "--no-visualizer",
+        action="store_true",
+        help="Do not POST camera coordinates to the local visualizer.",
+    )
+    zoom.add_argument("--visualizer-url", default=VISUALIZER_CAMERA_URL)
+    zoom.set_defaults(func=command_zoom)
+
+    context = sub.add_parser("context", help="Emit compressed LLM context.")
+    context.add_argument("query", nargs="?", default="project")
+    context.add_argument("--budget", type=int, default=1500)
+    context.add_argument("--json", action="store_true", help="Emit full context payload JSON.")
+    context.set_defaults(func=command_context)
+
+    view = sub.add_parser("view", help="Open the fractal visualizer on the live graph.")
+    view.add_argument("--root", default=None, help="Indexed root to view (default: most recent).")
+    view.add_argument("--port", type=int, default=7878)
+    view.add_argument("--no-open", action="store_true", help="Serve without opening a browser.")
+    view.set_defaults(func=command_view)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        print_splash()
+        return 0
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())