cortex-kg 0.2.2__tar.gz → 0.3.1__tar.gz

{cortex_kg-0.2.2/src/cortex_kg.egg-info → cortex_kg-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-kg
-Version: 0.2.2
+Version: 0.3.1
 Summary: Cortex: a persistent, workspace-level Engineering Knowledge Graph.
 Author-email: Roshan Gamage <roshangamage01@users.noreply.github.com>
 License: MIT

cortex_kg-0.3.1/docs/benchmarks/graphify-vs-cortex-2026-07-25-post.json

@@ -0,0 +1,99 @@
+{
+  "date": "2026-07-25",
+  "post_optimization": true,
+  "ingest": {
+    "sample_repo": {
+      "full": {
+        "wall_sec": 0.928,
+        "files_extracted": 7,
+        "candidates": 74,
+        "nodes_created": 38,
+        "edges_created": 30,
+        "extract_ms": 3.1,
+        "resolve_ms": 581.8,
+        "link_ms": 337.4
+      },
+      "fast": {
+        "wall_sec": 0.089,
+        "files_extracted": 2,
+        "candidates": 8,
+        "nodes_created": 7,
+        "edges_created": 1,
+        "extract_ms": 0.5,
+        "resolve_ms": 72.5,
+        "link_ms": 9.7
+      }
+    },
+    "web/src": {
+      "full": {
+        "wall_sec": 1.676,
+        "files_extracted": 25,
+        "candidates": 124,
+        "nodes_created": 80,
+        "edges_created": 29,
+        "extract_ms": 32.3,
+        "resolve_ms": 916.9,
+        "link_ms": 709.2
+      },
+      "fast": {
+        "wall_sec": 0.691,
+        "files_extracted": 25,
+        "candidates": 66,
+        "nodes_created": 66,
+        "edges_created": 0,
+        "extract_ms": 24.5,
+        "resolve_ms": 635.6,
+        "link_ms": 12.7
+      }
+    },
+    "src/cortex": {
+      "full": {
+        "wall_sec": 22.433,
+        "files_extracted": 78,
+        "candidates": 2060,
+        "nodes_created": 1160,
+        "edges_created": 436,
+        "extract_ms": 213.3,
+        "resolve_ms": 13026.6,
+        "link_ms": 9145.7
+      },
+      "fast": {
+        "wall_sec": 9.507,
+        "files_extracted": 78,
+        "candidates": 1260,
+        "nodes_created": 1077,
+        "edges_created": 36,
+        "extract_ms": 219.2,
+        "resolve_ms": 9231.9,
+        "link_ms": 10.9
+      }
+    }
+  },
+  "concurrency": {
+    "errors_per_burst": [
+      0,
+      0,
+      0,
+      0,
+      0
+    ],
+    "wall_ms_per_burst": [
+      8.1,
+      6.3,
+      6.0,
+      6.8,
+      6.6
+    ],
+    "total_errors": 0
+  },
+  "query": {
+    "search_ms_median": 11.54,
+    "token_estimate": 886,
+    "naive_baseline_tokens": 4051,
+    "reduction_factor": 4.57
+  },
+  "soak_30s": {
+    "ok": 35840,
+    "errors": 0
+  }
+}

cortex_kg-0.3.1/docs/benchmarks/graphify-vs-cortex-2026-07-25-rerun.json

@@ -0,0 +1,112 @@
+{
+  "date": "2026-07-25",
+  "label": "fresh-rerun",
+  "ingest": {
+    "sample_repo": {
+      "full": {
+        "wall_sec": 1.01,
+        "files_extracted": 7,
+        "candidates": 74,
+        "nodes_created": 38,
+        "edges_created": 30,
+        "extract_ms": 4.7,
+        "resolve_ms": 632.4,
+        "link_ms": 363.1
+      },
+      "fast": {
+        "wall_sec": 0.091,
+        "files_extracted": 2,
+        "candidates": 8,
+        "nodes_created": 7,
+        "edges_created": 1,
+        "extract_ms": 0.8,
+        "resolve_ms": 72.7,
+        "link_ms": 11.1
+      }
+    },
+    "web/src": {
+      "full": {
+        "wall_sec": 1.849,
+        "files_extracted": 25,
+        "candidates": 124,
+        "nodes_created": 80,
+        "edges_created": 29,
+        "extract_ms": 44.8,
+        "resolve_ms": 1009.3,
+        "link_ms": 772.6
+      },
+      "fast": {
+        "wall_sec": 0.65,
+        "files_extracted": 25,
+        "candidates": 66,
+        "nodes_created": 66,
+        "edges_created": 0,
+        "extract_ms": 26.5,
+        "resolve_ms": 596.1,
+        "link_ms": 9.3
+      }
+    },
+    "src/cortex": {
+      "full": {
+        "wall_sec": 23.641,
+        "files_extracted": 78,
+        "candidates": 2060,
+        "nodes_created": 1160,
+        "edges_created": 436,
+        "extract_ms": 209.8,
+        "resolve_ms": 13503.8,
+        "link_ms": 9870.7
+      },
+      "fast": {
+        "wall_sec": 9.464,
+        "files_extracted": 78,
+        "candidates": 1260,
+        "nodes_created": 1077,
+        "edges_created": 36,
+        "extract_ms": 233.6,
+        "resolve_ms": 9167.0,
+        "link_ms": 9.5
+      }
+    }
+  },
+  "concurrency": {
+    "errors_per_burst": [
+      0,
+      0,
+      0,
+      0,
+      0
+    ],
+    "wall_ms_per_burst": [
+      7.3,
+      5.7,
+      6.9,
+      6.4,
+      7.0
+    ],
+    "total_errors": 0
+  },
+  "query": {
+    "search_ms_median": 0.8,
+    "context_ms": 20.9,
+    "token_estimate": 895,
+    "naive_baseline_tokens": 4051,
+    "reduction_factor": 4.53
+  },
+  "graphify": {
+    "sample_repo": {
+      "wall_sec": 0.344,
+      "exit": 1,
+      "stderr_tail": "error: detected non-code corpus files that require semantic extraction; provide --semantic <path>, pass --backend <provider>, or use the graphify assistant skill/runtime pipeline.\n"
+    },
+    "web/src": {
+      "wall_sec": 0.386,
+      "exit": 0,
+      "stderr_tail": "eal description. A ~0%-description graph almost always means the description pass never ran. Run `graphify describe .` (no API key needed \u2014 assistant mode) before exporting for non-null descriptions.\n"
+    }
+  },
+  "soak_30s": {
+    "ok": 35384,
+    "errors": 0
+  }
+}

cortex_kg-0.3.1/docs/benchmarks/graphify-vs-cortex-2026-07-25.json

@@ -0,0 +1,179 @@
+{
+  "meta": {
+    "graphify_version": "0.16.0",
+    "cortex_install": "/Users/roshan/Projects/Cortex/.venv/bin/cortex",
+    "cortex_api": "http://127.0.0.1:8420",
+    "notes": [
+      "Graphify headless extract is AST/code-only here (--no-description/--no-label; no LLM).",
+      "Mixed corpus (md/docs) requires Graphify semantic backend; Cortex ingests mixed corpus natively.",
+      "Fair cold builds: sample code-only, web/src, Cortex src/ vs prior Cortex ingest benches."
+    ]
+  },
+  "build_ingest": {
+    "graphify_cold_sample_code_only": {
+      "wall_s": 0.23,
+      "nodes": 15,
+      "links": 17,
+      "files": 2
+    },
+    "graphify_cold_web_src": {
+      "wall_s": 0.37,
+      "nodes": 157,
+      "links": 323,
+      "files": 25
+    },
+    "graphify_cold_cortex_src": {
+      "wall_s": 0.64,
+      "nodes": 643,
+      "links": 1264,
+      "files": 70,
+      "communities": 62
+    },
+    "graphify_full_repo_auto_scope": {
+      "ok": false,
+      "error": "requires semantic extraction for non-code corpus"
+    },
+    "cortex_cold_sample": {
+      "wall_s": 1.31,
+      "server_s": 1.17,
+      "nodes_created": 38,
+      "edges_created": 30,
+      "files_extracted": 7
+    },
+    "cortex_cold_web_src": {
+      "wall_s": 2.43,
+      "server_s": 2.34,
+      "nodes_created": 79,
+      "edges_created": 29,
+      "files_extracted": 25
+    },
+    "cortex_incremental_full_repo": {
+      "wall_s": 27.34,
+      "server_s": 27.27,
+      "files_extracted": 22,
+      "files_skipped": 144,
+      "nodes_created": 59,
+      "edges_created": 192
+    },
+    "cortex_graph_after": {
+      "nodes": 1492,
+      "edges": 2234
+    }
+  },
+  "query_latency_ms": {
+    "graphify_query_AuthService_sample": {
+      "median_ms": 95.8,
+      "mean_ms": 95.69,
+      "out_bytes": 1837,
+      "ok": true,
+      "preview": "NODE AuthService [src=src/auth_service.py loc=L9 community=2] | NODE BillingService [src=src/billing_service.py loc=L7 community=0] | NODE auth_service.py [src=src/auth_service.py loc="
+    },
+    "graphify_query_daemon_src": {
+      "median_ms": 101.84,
+      "mean_ms": 102.12,
+      "out_bytes": 2438,
+      "ok": true,
+      "preview": "NODE Node [src=cortex/models.py loc=L90 community=0] | NODE Edge [src=cortex/models.py loc=L137 community=0] | NODE Provenance [src=cortex/models.py loc=L62 community=22] | NODE CortexDa"
+    },
+    "graphify_explain": {
+      "median_ms": 99.99,
+      "mean_ms": 100.62,
+      "out_bytes": 380,
+      "ok": true,
+      "preview": "Node: get_daemon() |   ID:        daemon_get_daemon |   Source:    cortex/daemon.py L129 |   Type:      code |   Community: 28 |   Degree:    4 |  | Connections (4): |   --> CortexDaemon [calls] ["
+    },
+    "graphify_summary": {
+      "median_ms": 101.47,
+      "mean_ms": 101.17,
+      "out_bytes": 1237,
+      "ok": true,
+      "preview": "Graphify First-Hop Summary | Graph: 643 nodes, 1264 edges, 62 communities, density 0.0061, average degree 3.9316, undirected |  | Top hubs: |   1. Node (degree 77, community 0 Community 0,"
+    },
+    "cortex_search_AuthService": {
+      "median_ms": 0.71,
+      "mean_ms": 9.8,
+      "min_ms": 0.62,
+      "max_ms": 46.24
+    },
+    "cortex_context_ingest": {
+      "median_ms": 28.96,
+      "mean_ms": 45.69,
+      "min_ms": 28.73,
+      "max_ms": 79.36
+    },
+    "cortex_impact": {
+      "median_ms": 17.35,
+      "mean_ms": 17.67,
+      "min_ms": 17.22,
+      "max_ms": 18.44
+    },
+    "cortex_path": {
+      "median_ms": 9.15,
+      "mean_ms": 9.19,
+      "min_ms": 8.97,
+      "max_ms": 9.44
+    },
+    "cortex_snapshot_500": {
+      "median_ms": 15.42,
+      "mean_ms": 15.55,
+      "min_ms": 15.18,
+      "max_ms": 16.06
+    },
+    "cortex_mcp_initialize": {
+      "median_ms": 1.34,
+      "mean_ms": 2.83,
+      "min_ms": 1.29,
+      "max_ms": 5.87
+    },
+    "cortex_cli_search": {
+      "median_ms": 53.65,
+      "mean_ms": 54.54,
+      "min_ms": 52.12,
+      "max_ms": 57.86
+    }
+  },
+  "concurrency": {
+    "graphify_8_query_wall_ms": {
+      "median": 208.56,
+      "max": 245.33
+    },
+    "graphify_8_json_load_ms": {
+      "median": 6.72
+    },
+    "cortex_8_search_wall_ms": {
+      "median": 78.08,
+      "max": 258.7,
+      "errors_per_burst": [
+        2,
+        0,
+        0
+      ]
+    },
+    "cortex_simultaneous_ingest_search_mcp": {
+      "lock_conflicts": 0,
+      "ok": true
+    }
+  },
+  "architecture": {
+    "graphify": {
+      "storage": ".graphify/graph.json (file)",
+      "multi_process": "yes (multi-reader JSON)",
+      "mcp": "stdio graphify serve",
+      "ui": "static Ontology Studio (export)",
+      "workspaces": "per-folder .graphify (path-local)",
+      "extraction": "AST + optional LLM semantic",
+      "edge_audit": "EXTRACTED / INFERRED / AMBIGUOUS",
+      "agent_tools": "query, path, explain, review-*, minimal-context, wiki"
+    },
+    "cortex": {
+      "storage": "Kuzu + SQLite FTS + Lance vectors (~/.cortex/<workspace>)",
+      "multi_process": "single writer; share via serve-api",
+      "mcp": "HTTP /mcp + stdio proxy",
+      "ui": "live WebGL Brain + REST",
+      "workspaces": "named registry, federated views",
+      "extraction": "multi-extractor pipeline (code, docs, git, \u2026) no LLM required",
+      "edge_audit": "provenance + confidence + feedback confirm/reject",
+      "agent_tools": "search_knowledge, get_context, explain_impact, add_note, link, \u2026"
+    }
+  }
+}

cortex_kg-0.3.1/docs/benchmarks/graphify-vs-cortex-2026-07-25.md

@@ -0,0 +1,127 @@
+# Graphify vs Cortex — local benchmark report
+
+**Date:** 2026-07-25  
+**Machines/installs:**
+- Graphify `0.16.0` at `/Users/roshan/.local/bin/graphify`
+- Cortex local venv `.venv/bin/cortex` + `serve-api` on `http://127.0.0.1:8420`
+**Raw JSON:** [graphify-vs-cortex-2026-07-25.json](./graphify-vs-cortex-2026-07-25.json)  
+**Post-optimization JSON:** [graphify-vs-cortex-2026-07-25-post.json](./graphify-vs-cortex-2026-07-25-post.json)
+
+### Method notes (fairness)
+
+- Graphify headless runs used **AST/code-only** (`--no-description --no-label`, no LLM). Mixed docs/markdown **failed** without a semantic backend.
+- Cortex numbers reuse the earlier write-path suite on the same machine (cold `sample_repo`, cold `web/src`, incremental full-repo ingest) plus fresh matched query timings against `default` (1,492 nodes / 2,234 edges after ingest).
+- “Query” is not identical: Graphify CLI BFS over `graph.json` vs Cortex hybrid search/context over Kuzu+FTS+vectors.
+
+---
+
+## 1. Executive summary
+
+| Dimension | Winner | Why |
+|---|---|---|
+| Cold **code** graph build speed | **Graphify** | ~3–6× faster on same trees (file AST → JSON) |
+| Mixed corpus (code+docs+git) without LLM | **Cortex** | Graphify headless blocks; Cortex extractors run |
+| Hot query / search latency | **Cortex** | ~0.7 ms search vs ~100 ms Graphify CLI query |
+| Concurrent multi-tool use (Brain+MCP+CLI+ingest) | **Cortex** (post shared-daemon) | 0 lock conflicts in suite; Graphify wins multi-process *reads* of JSON |
+| Agent review tooling (PR blast radius, wiki, studio) | **Graphify** | Richer out-of-box review/wiki/studio CLI |
+| Live interactive UI | **Cortex** | WebGL Brain + REST; Graphify is static studio export |
+| Multi-workspace federation | **Cortex** | Named workspaces + federated views |
+| Honest edge typology (EXTRACTED/INFERRED/AMBIGUOUS) | **Graphify** | First-class; Cortex uses provenance/confidence instead |
+| Zero-setup “drop folder → graph” feel | **Graphify** | Path-local `.graphify/`; no long-lived server |
+
+**Bottom line:** Graphify still feels smoother for *one-folder code graphs and agent review packs*. Cortex is stronger as a *persistent engineering KG service* (hybrid retrieval, live UI, multi-client via `serve-api`), but remains slower to build and less “instant CLI” than Graphify’s JSON pipeline.
+
+---
+
+## 2. Build / ingest
+
+| Corpus | Graphify cold | Cortex (baseline) | Cortex **post-opt `--fast`** |
+|---|---|---|---|
+| `examples/sample_repo` (code-only for GFY) | **0.23 s** → 15 nodes / 17 links (2 files) | **1.31 s** → +38 nodes / +30 edges | **0.09 s** → 7 nodes (code-only) |
+| `web/src` | **0.37 s** → 157 nodes / 323 links (25 files) | **2.43 s** → +79 nodes / +29 edges | **0.69 s** → 66 nodes (FTS/project link deferred) |
+| `src/cortex` (Python) | **0.64 s** (whole `src/`) | ~22–34 s full resolve+link | **9.5 s** fast / **22.4 s** full |
+| Full Cortex repo (`scope auto`) | **FAIL** — needs semantic backend for non-code | **27.3 s** incremental | (not re-run; warm hash skip unchanged) |
+
+**Post-opt notes:** Stage profiling showed extract was only ~1–5% of wall time; wins came from batched Kuzu/FTS/provenance writes, deferred project linking + keyword index in `--fast`, and suppressing import-stub candidates. Graphify still wins raw AST→JSON on large trees; Cortex `--fast` now beats Graphify on `sample_repo`.
+
+---
+
+## 3. Query / agent-path latency (median)
+
+| Operation | Graphify | Cortex |
+|---|---:|---:|
+| Question → answer (`query` / `search`) | ~96–102 ms (CLI+JSON) | **0.7 ms** HTTP search |
+| Rich context | ~100 ms `summary` / query text | **29 ms** `/context` |
+| Impact / blast | n/a as first-class (use review-*) | **17 ms** `/impact` |
+| Shortest path | ~103 ms CLI | **9 ms** HTTP |
+| Graph slice for UI | load JSON (~7 ms×8 concurrent) | **15 ms** snapshot(500) |
+| MCP initialize | stdio process (not timed here) | **1.3 ms** HTTP `/mcp` |
+| CLI process wrapper | ~(same ~100 ms floor) | **54 ms** `cortex search` (process start) |
+
+Graphify’s built-in **token reduction benchmark** on the `src/` graph: **2.4×** fewer tokens vs naive corpus (avg query ~17.5k tokens vs ~43k naive).
+
+---
+
+## 4. Concurrency & locking
+
+| Scenario | Graphify | Cortex baseline | Cortex **post-opt** |
+|---|---|---|---|
+| 8 parallel reads | OK — JSON multi-reader; 8× query wall ~**209 ms** | 8× search wall ~**78 ms** (intermittent 500s) | **0 errors** across 5 bursts; wall ~**6–8 ms**/burst |
+| 30s soak (8-way `/search`) | n/a | n/a | **35,840 OK / 0 errors** |
+| Ingest + search + MCP + Brain same workspace | N/A (rebuild replaces JSON; readers can race stale file) | **0 lock conflicts** in write-path suite | unchanged (shared `serve-api`) |
+| Two OS processes opening DB | Fine for reads | Historically locked; mitigated by shared `serve-api` | `cortex up` keeps one owner |
+
+---
+
+## 5. Product surface comparison
+
+| Aspect | Graphify | Cortex |
+|---|---|---|
+| Storage | `.graphify/graph.json` (+ studio, analysis) | `~/.cortex/<workspace>/` (Kuzu, FTS, vectors, meta) |
+| Workspaces | Folder-local | Named registry + dropdown UI + federation modes |
+| UI | Static Ontology Studio | Live Cortex Brain (WebGL) |
+| MCP | `graphify serve` stdio | `/mcp` on `serve-api` (+ stdio proxy) |
+| Extraction | AST + optional LLM semantic / describe / label | Deterministic extractors (code, markdown, git, …) |
+| Agent extras | `review-*`, `minimal-context`, wiki, flows, commit advice | `get_context`, `explain_impact`, `add_note`, `link`, feedback |
+| Edge honesty | EXTRACTED / INFERRED / AMBIGUOUS | Provenance records + confidence + confirm/reject |
+| Hybrid retrieval | Graph traversal (+ optional LLM) | Keyword + vector + graph |
+| Requires daemon | No | Yes for smooth multi-client (`serve-api`) |
+
+---
+
+## 6. Quality spot check (`AuthService`)
+
+- **Graphify** (sample graph): returns structural neighborhood — `AuthService`, methods, `BillingService`, EXTRACTED edges, file/line communities. Excellent for “what is connected in code.”
+- **Cortex** (default workspace): returns typed entities — `Service` AuthService, related `ArchitectureDecision`, `Concept`, with **keyword+vector** channels. Better for “what decisions/docs relate,” because docs/ADRs were ingested without an LLM.
+
+---
+
+## 7. Improvements list for Cortex — status after optimization pass
+
+| # | Item | Status |
+|---|---|---|
+| 1 | Fast code-only ingest (`--fast` / `--scope code`) | **Done** — sample 0.09s; `web/src` 0.69s; `src/cortex` 9.5s (link+FTS deferred) |
+| 2 | Always-on `serve-api` DX | **Done** — `cortex up` / `down` / `status` + TopBar health/queue chip |
+| 3 | Fix concurrent HTTP 500s | **Done** — store locks + cache lock + embed single-flight; 0/35840 soak errors |
+| 4 | Review pack tools | **Done** — `review_delta` / `minimal_context` REST + MCP |
+| 5 | Edge honesty labels | **Done** — `EXTRACTED`/`INFERRED`/`AMBIGUOUS` in graph payloads + Brain filter |
+| 6 | Token-budget report | **Done** — `naive_baseline_tokens` + `reduction_factor` (measured **4.57×** on sample) |
+| 7 | Static studio export | **Done** — `cortex export studio` |
+| 8 | Path-local `.cortex/project.json` | **Done** — written by `setup project` / `workspaces use` |
+| 9 | Watch by default | **Done** — `cortex up --watch` |
+| 10 | Community overlay | **Done** — “Color by community” toggle on Brain |
+| 11 | CLI workspaces + completion | **Done** — `cortex workspaces list\|use` + `docs/completions/cortex.zsh` |
+| 12 | CLI process tax | **Done** — `cortex shell` REPL |
+| 13 | Docs happy path | **Done** — `cortex up` documented in install/brain/cursor |
+| 14 | Hybrid channel badges | **Done** — SearchBox `kw`/`vec`/`graph` badges |
+| 15 | Federation first-run wizard | **Done** — Workspaces rail onboarding panel |
+
+**Remaining headroom:** large-tree `--fast` is still dominated by per-node Kuzu MERGE (~9s for ~1k nodes). Further gains need true bulk Cypher / COPY ingest, not more extractor skips.
+
+---
+
+## 8. Suggested next measurement
+
+1. Graphify **with** semantic backend (if API keys available) on full Cortex repo vs Cortex full ingest — quality + time.
+2. Agent task eval: same 10 architecture questions scored for answer usefulness (not just latency).
+3. ~~Soak test: 5-minute parallel Brain + MCP + ingest watch~~ — **30s 8-way `/search` soak done: 0 errors**; extend to full 5 min + watch in a follow-up.

{cortex_kg-0.2.2 → cortex_kg-0.3.1}/docs/cortex-brain.md

@@ -3,24 +3,32 @@
 Cortex Brain is the WebGL visualization of your Engineering Knowledge Graph.
 After install, you open it in a browser — **no separate frontend server**.
 
-## One-time setup (3 commands)
+## One-time setup (happy path)
 
 ```bash
 # 1. Install
 pipx install cortex-kg
 # or: pip install cortex-kg
 
-# 2. Index a project (creates knowledge in a workspace)
-cortex --workspace default ingest /path/to/your/repo --project MyApp
+# 2. Start the shared daemon (Brain + MCP + CLI share one Kuzu process)
+cortex up
+# optional: also watch for file changes
+# cortex up --watch /path/to/your/repo --project MyApp
 
-# 3. Start the API + UI
-cortex --workspace default serve-api
+# 3. Index a project (CLI auto-detects serve-api)
+cortex ingest /path/to/your/repo --project MyApp
+# fast code-only path (Graphify-class speed):
+# cortex ingest /path/to/your/repo --project MyApp --fast
 ```
 
 Open **http://localhost:8420** in your browser.
 
-In the top bar, set **Workspace** to the same name you used above
-(`default`, `demo`, `work`, …). If it doesn’t match, the canvas looks empty.
+`cortex up` writes a pidfile under `~/.cortex/`, prints Brain + `/mcp` URLs,
+and is safe to re-run (idempotent if already healthy). Use `cortex status`
+/ `cortex down` to inspect or stop.
+
+In the top bar, pick **Workspace** from the dropdown (same name you used
+above: `default`, `demo`, `work`, …). If it doesn’t match, the canvas looks empty.
 
 That’s the whole setup.
 
@@ -131,29 +139,38 @@ Open http://localhost:8420 and set **Workspace** to `demo`.
 - **Custom port:** `cortex serve-api --port 9000`
 - **Custom UI folder** (advanced): `export CORTEX_WEB_DIST=/path/to/dist`
 - Data lives in `~/.cortex/<workspace>/` (override with `CORTEX_HOME`)
-- The **Workspace** field in the top bar commits on blur/Enter, not every
-  keystroke — typing a workspace id auto-creates it on first use, so
-  committing on every keystroke used to create (and lock-probe) a phantom
-  workspace per partial string typed.
+- The **Workspace** control in the top bar is a dropdown of known workspaces
+  (from `GET /workspaces`), with a create path for new ids.
+
+## Recommended layout: one `serve-api`
+
+Run a single long-lived API process so Brain, Cursor MCP, and the CLI share
+one Kuzu connection:
+
+```bash
+cortex --workspace default serve-api
+```
+
+- Brain UI: http://localhost:8420
+- MCP (streamable HTTP): http://127.0.0.1:8420/mcp
+- CLI (`ingest`, `search`, `info`, …) auto-detects the API and calls it over
+  HTTP when reachable (override with `CORTEX_API_URL`)
+
+`cortex setup cursor` / `setup project` write an MCP config that points at
+that `/mcp` URL. Stdio `serve-mcp` also proxies to the API when it is up.
 
 ## Troubleshooting: "Workspace 'X' is locked by another Cortex process"
 
 The embedded graph DB (Kuzu) only allows **one read-write process per
-workspace** at a time. If you see this error (a `503` in the graph
-canvas, or in `serve-api`'s logs), something else already has that
-workspace open — most commonly:
-
-- **Cursor's Cortex MCP integration** (`cortex --workspace <ws> serve-mcp`),
-  started automatically whenever Cursor uses `search_knowledge`,
-  `get_context`, etc. against that workspace.
-- **Another `serve-api` / CLI command** (`cortex ingest`, `cortex info`, …)
-  still running against the same workspace.
-
-Fix: either stop the other process, or point Brain at a workspace that
-isn't in use elsewhere (switch **Workspace** in the top bar). Ingesting
-into a workspace that Cursor's MCP server is actively using will hit the
-same conflict — pick a workspace Cursor doesn't reference, or briefly stop
-the MCP server, ingest, then restart it.
+workspace** at a time. A lock usually means a second process tried to open
+the same DB directory (for example an old stdio MCP that opened Kuzu
+locally while `serve-api` was already running).
+
+Fix: keep **one** `cortex serve-api` running for that workspace, point MCP at
+`http://127.0.0.1:8420/mcp` (or use stdio `serve-mcp`, which proxies when
+the API is healthy), and run CLI commands while the API is up so they do
+not open Kuzu themselves. If you still see a lock, stop the stray process
+that holds the file lock, then restart `serve-api`.
 
 ## Developing the UI itself