cortex-kg 0.1.0__py3-none-any.whl

cortex/__init__.py

@@ -0,0 +1,8 @@
+"""Cortex: a persistent, workspace-level Engineering Knowledge Graph.
+
+Cortex models relationships between engineering knowledge (concepts, APIs,
+services, decisions, people, documents, ...) rather than files. Knowledge is
+owned by the workspace and outlives any single project.
+"""
+
+__version__ = "0.1.0"

cortex/agents/hooks.py

@@ -0,0 +1,55 @@
+"""Future AI agent integration (roadmap section 26): agents subscribe to
+the change feed and react to new knowledge instead of polling.
+
+`AgentHookRegistry` lets multiple independent agents/automations register
+interest in specific event types (e.g. "run static analysis whenever a new
+Service node appears") without any of them needing to know about each
+other -- the same decoupling MCP gives you for *querying* the graph, but
+for *reacting* to it.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Callable
+
+from cortex.sync.change_feed import ChangeFeed
+
+HookCallback = Callable[[dict], None]
+
+
+class AgentHookRegistry:
+    def __init__(self, daemon):
+        self._daemon = daemon
+        self._hooks: dict[str, list[HookCallback]] = {}
+        self._stop_event: threading.Event | None = None
+        self._thread: threading.Thread | None = None
+
+    def on(self, event_type: str, callback: HookCallback) -> None:
+        """Register `callback` for a specific change-feed event type, or
+        pass `"*"` to receive every event."""
+        self._hooks.setdefault(event_type, []).append(callback)
+
+    def dispatch(self, event: dict) -> None:
+        for callback in self._hooks.get(event.get("type", ""), []):
+            callback(event)
+        for callback in self._hooks.get("*", []):
+            callback(event)
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop_event = threading.Event()
+        feed = ChangeFeed.instance(self._daemon)
+
+        def _run():
+            feed.watch(self.dispatch, self._stop_event)
+
+        self._thread = threading.Thread(target=_run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        if self._stop_event:
+            self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=2)

cortex/agents/writeback.py

@@ -0,0 +1,58 @@
+"""Agent write-back API (roadmap section 26): "Agents both consume context
+and contribute knowledge (write API with provenance = agent X)."
+
+This is a typed convenience wrapper over the same primitives the MCP
+`add_note`/`link` tools and the REST `/nodes`/`/edges` endpoints use --
+every write is tagged with `actor` as provenance and audited, so an
+agent's contributions are exactly as traceable as a human's or an
+extractor's.
+"""
+
+from __future__ import annotations
+
+from cortex.models import Edge, Node, Provenance
+
+
+class AgentWriteback:
+    def __init__(self, daemon, agent_id: str):
+        self._daemon = daemon
+        self.agent_id = agent_id
+
+    def record_observation(self, node_type: str, canonical_name: str, properties: dict | None = None,
+                            confidence: float = 0.8) -> Node:
+        """An agent contributing a new fact it derived/observed (e.g. "this
+        function is a hot path" from a profiling run)."""
+        self._daemon.ontology.ensure_node_type(node_type, registered_by=f"agent:{self.agent_id}")
+        existing = self._daemon.graph.find_by_natural_key(node_type, canonical_name, self._daemon.workspace_id)
+        node = existing or Node(type=node_type, canonical_name=canonical_name, workspace_id=self._daemon.workspace_id)
+        if properties:
+            node.properties.update(properties)
+        node.confidence = max(node.confidence, confidence) if existing else confidence
+        self._daemon.graph.upsert_node(node)
+        self._daemon.keyword.upsert(node.id, node.type, node.workspace_id, node.canonical_name,
+                                     ",".join(node.aliases), str(node.properties))
+        self._daemon.provenance.record(node.id, "node", Provenance(
+            source_id=f"agent:{self.agent_id}", source_type="agent_writeback", extractor="agent.record_observation",
+            extractor_version="1", confidence=confidence,
+        ))
+        self._daemon.provenance.audit(self.agent_id, "record_observation", node.id, node_type)
+        self._publish("node_added", node_id=node.id)
+        return node
+
+    def link(self, edge_type: str, from_id: str, to_id: str, properties: dict | None = None,
+              confidence: float = 0.75) -> Edge:
+        self._daemon.ontology.ensure_edge_type(edge_type, registered_by=f"agent:{self.agent_id}")
+        edge = Edge(type=edge_type, from_id=from_id, to_id=to_id, properties=properties or {},
+                    confidence=confidence)
+        self._daemon.graph.upsert_edge(edge)
+        self._daemon.provenance.record(edge.id, "edge", Provenance(
+            source_id=f"agent:{self.agent_id}", source_type="agent_writeback", extractor="agent.link",
+            extractor_version="1", confidence=confidence,
+        ))
+        self._daemon.provenance.audit(self.agent_id, "link", edge.id, edge_type)
+        self._publish("edge_added", edge_id=edge.id)
+        return edge
+
+    def _publish(self, event_type: str, **fields) -> None:
+        from cortex.sync.change_feed import ChangeFeed
+        ChangeFeed.instance(self._daemon).publish({"type": event_type, "actor": self.agent_id, **fields})

cortex/api/rest.py

@@ -0,0 +1,239 @@
+"""Public REST API (roadmap sections 1, 4, 17).
+
+This is the same capability surface exposed over MCP
+(`cortex.mcp_server.server`), but as a versioned HTTP API so any tool that
+isn't MCP-aware -- browsers, CI bots, custom scripts -- can still read from
+and write to the graph. Node/edge IDs are the stable public contract
+(section 17): they never change across re-extraction.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import asyncio
+import json
+
+from fastapi import Depends, FastAPI, HTTPException, Query
+from pydantic import BaseModel
+from sse_starlette.sse import EventSourceResponse
+
+from cortex.config import DEFAULT_WORKSPACE
+from cortex.daemon import CortexDaemon, get_daemon
+from cortex.models import Edge, Node, Provenance
+from cortex.sync.change_feed import ChangeFeed
+
+app = FastAPI(
+    title="Cortex Engineering Knowledge Graph API",
+    version="v1",
+    description="Workspace-level knowledge graph API. See /docs for the full contract.",
+)
+
+
+def daemon_dep(workspace: str = Query(default=DEFAULT_WORKSPACE)) -> CortexDaemon:
+    return get_daemon(workspace)
+
+
+class NodeIn(BaseModel):
+    type: str
+    canonical_name: str
+    properties: dict[str, Any] = {}
+    aliases: list[str] = []
+    confidence: float = 1.0
+    source_id: str = "api"
+    source_type: str = "manual"
+    actor: str = "api-client"
+
+
+class EdgeIn(BaseModel):
+    type: str
+    from_id: str
+    to_id: str
+    properties: dict[str, Any] = {}
+    confidence: float = 1.0
+    directional: bool = True
+    source_id: str = "api"
+    source_type: str = "manual"
+    actor: str = "api-client"
+
+
+class NodeOut(BaseModel):
+    id: str
+    type: str
+    canonical_name: str
+    aliases: list[str]
+    properties: dict[str, Any]
+    confidence: float
+    workspace_id: str
+    created_at: str
+    valid_from: str
+    valid_to: Optional[str] = None
+
+
+def _node_out(n: Node) -> NodeOut:
+    return NodeOut(
+        id=n.id, type=n.type, canonical_name=n.canonical_name, aliases=n.aliases,
+        properties=n.properties, confidence=n.confidence, workspace_id=n.workspace_id,
+        created_at=n.created_at, valid_from=n.valid_from, valid_to=n.valid_to,
+    )
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.get("/info")
+def info(daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    return daemon.info()
+
+
+@app.post("/nodes", response_model=NodeOut)
+def create_node(body: NodeIn, daemon: CortexDaemon = Depends(daemon_dep)) -> NodeOut:
+    daemon.ontology.ensure_node_type(body.type, registered_by=f"api:{body.actor}")
+    existing = daemon.graph.find_by_natural_key(body.type, body.canonical_name, daemon.workspace_id)
+    node = existing or Node(
+        type=body.type, canonical_name=body.canonical_name, workspace_id=daemon.workspace_id,
+    )
+    node.properties.update(body.properties)
+    node.aliases = sorted(set(node.aliases) | set(body.aliases))
+    node.confidence = max(node.confidence, body.confidence)
+    daemon.graph.upsert_node(node)
+    daemon.provenance.record(node.id, "node", Provenance(
+        source_id=body.source_id, source_type=body.source_type, extractor="api",
+        extractor_version="1", confidence=body.confidence,
+    ))
+    daemon.keyword.upsert(node.id, node.type, node.workspace_id, node.canonical_name,
+                           ",".join(node.aliases), str(node.properties))
+    daemon.provenance.audit(body.actor, "create_node", node.id, body.type)
+    return _node_out(node)
+
+
+@app.get("/nodes/{node_id}", response_model=NodeOut)
+def get_node(node_id: str, daemon: CortexDaemon = Depends(daemon_dep)) -> NodeOut:
+    node = daemon.graph.get_node(node_id)
+    if not node:
+        raise HTTPException(status_code=404, detail="node not found")
+    return _node_out(node)
+
+
+@app.get("/nodes", response_model=list[NodeOut])
+def list_nodes(type: Optional[str] = None, limit: int = 100,
+                daemon: CortexDaemon = Depends(daemon_dep)) -> list[NodeOut]:
+    nodes = daemon.graph.list_nodes(type_=type, workspace_id=daemon.workspace_id, limit=limit)
+    return [_node_out(n) for n in nodes]
+
+
+@app.get("/nodes/{node_id}/provenance")
+def node_provenance(node_id: str, daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    return [p.to_json() for p in daemon.provenance.for_entity(node_id)]
+
+
+@app.post("/edges")
+def create_edge(body: EdgeIn, daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    daemon.ontology.ensure_edge_type(body.type, registered_by=f"api:{body.actor}")
+    edge = Edge(type=body.type, from_id=body.from_id, to_id=body.to_id,
+                properties=body.properties, confidence=body.confidence, directional=body.directional)
+    daemon.graph.upsert_edge(edge)
+    daemon.provenance.record(edge.id, "edge", Provenance(
+        source_id=body.source_id, source_type=body.source_type, extractor="api",
+        extractor_version="1", confidence=body.confidence,
+    ))
+    daemon.provenance.audit(body.actor, "create_edge", edge.id, body.type)
+    return {"id": edge.id, "type": edge.type, "from_id": edge.from_id, "to_id": edge.to_id}
+
+
+@app.get("/nodes/{node_id}/neighbors")
+def neighbors(node_id: str, direction: str = "both", edge_type: Optional[str] = None,
+              daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    edge_types = [edge_type] if edge_type else None
+    pairs = daemon.graph.neighbors(node_id, edge_types=edge_types, direction=direction)
+    return [{"edge_type": e.type, "edge_id": e.id, "node": _node_out(n).model_dump()} for e, n in pairs]
+
+
+@app.get("/nodes/{node_id}/traverse")
+def traverse(node_id: str, direction: str = "out", max_depth: int = 2,
+             edge_type: Optional[str] = None, daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    edge_types = [edge_type] if edge_type else None
+    nodes, edges = daemon.graph.traverse(node_id, edge_types=edge_types, direction=direction,
+                                          max_depth=max_depth)
+    return {
+        "nodes": [_node_out(n).model_dump() for n in nodes],
+        "edges": [{"id": e.id, "type": e.type, "from_id": e.from_id, "to_id": e.to_id} for e in edges],
+    }
+
+
+@app.get("/nodes/{from_id}/path/{to_id}")
+def shortest_path(from_id: str, to_id: str, max_depth: int = 6,
+                   daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    path = daemon.graph.shortest_path(from_id, to_id, max_depth=max_depth)
+    return {"path": path}
+
+
+@app.get("/search")
+def search(q: str, k: int = 10, daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    results = daemon.query_engine.search(q, k=k)
+    return results
+
+
+@app.get("/context")
+def context(q: str, max_tokens: int = 2000, format: str = "markdown",
+            daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    return daemon.context_generator.generate(q, max_tokens=max_tokens, fmt=format)
+
+
+@app.get("/nodes/{node_id}/impact")
+def impact(node_id: str, max_depth: int = 3, daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    result = daemon.query_engine._traversal.explain_impact(node_id, max_depth=max_depth)
+    return {"root_id": result.root_id, "affected": [_node_out(n).model_dump() for n in result.affected_nodes]}
+
+
+class FeedbackIn(BaseModel):
+    actor: str = "api-client"
+    verdict: str  # "confirm" | "reject"
+
+
+@app.post("/edges/{edge_id}/feedback")
+def edge_feedback(edge_id: str, body: FeedbackIn, daemon: CortexDaemon = Depends(daemon_dep)) -> dict:
+    if body.verdict not in ("confirm", "reject"):
+        raise HTTPException(status_code=400, detail="verdict must be 'confirm' or 'reject'")
+    daemon.provenance.record_feedback(edge_id, body.actor, body.verdict)
+    return {"edge_id": edge_id, "verdict": body.verdict}
+
+
+@app.get("/ontology/node-types")
+def node_types(daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    return daemon.ontology.list_node_types()
+
+
+@app.get("/ontology/edge-types")
+def edge_types(daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    return daemon.ontology.list_edge_types()
+
+
+@app.get("/change-feed/recent")
+def change_feed_recent(daemon: CortexDaemon = Depends(daemon_dep)) -> list[dict]:
+    return ChangeFeed.instance(daemon).history()
+
+
+@app.get("/change-feed/stream")
+async def change_feed_stream(workspace: str = Query(default=DEFAULT_WORKSPACE)):
+    """Server-sent events: live subscription to graph changes (roadmap
+    section 10) -- any tool can react to new knowledge instead of polling.
+    """
+    daemon = get_daemon(workspace)
+    feed = ChangeFeed.instance(daemon)
+    q = feed.subscribe()
+
+    async def event_generator():
+        try:
+            while True:
+                try:
+                    event = await asyncio.get_event_loop().run_in_executor(None, q.get, True, 1.0)
+                    yield {"event": "change", "data": json.dumps(event, default=str)}
+                except Exception:
+                    yield {"event": "heartbeat", "data": ""}
+        finally:
+            feed.unsubscribe(q)
+
+    return EventSourceResponse(event_generator())

cortex/cli.py

@@ -0,0 +1,238 @@
+"""`cortex` command-line entrypoint.
+
+    cortex init                          create/initialize a workspace
+    cortex info                          show graph/vector/job stats
+    cortex ingest <path> [--workspace]   run the full ingestion pipeline over a directory
+    cortex watch <path> [--project]      keep graph updated as files change
+    cortex search "<query>"              hybrid search
+    cortex context "<query>"             generate LLM-ready context
+    cortex setup cursor|claude|project   print or write MCP / project integration files
+    cortex serve-api [--port]            run the REST API (uvicorn)
+    cortex serve-mcp                     run the MCP server over stdio
+    cortex node get <id>                 fetch a single node
+    cortex node traverse <id>            traverse from a node
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from cortex.config import DEFAULT_WORKSPACE
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    from cortex.daemon import CortexDaemon
+
+    daemon = CortexDaemon(args.workspace)
+    print(json.dumps(daemon.info(), indent=2))
+
+
+def cmd_info(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+
+    daemon = get_daemon(args.workspace)
+    print(json.dumps(daemon.info(), indent=2))
+
+
+def cmd_ingest(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+    from cortex.ingestion.pipeline import IngestionPipeline
+
+    daemon = get_daemon(args.workspace)
+    pipeline = IngestionPipeline(daemon)
+    report = pipeline.run(args.path, project_name=args.project)
+    print(json.dumps(report, indent=2))
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+
+    daemon = get_daemon(args.workspace)
+    results = daemon.query_engine.search(args.query, k=args.k)
+    print(json.dumps(results, indent=2, default=str))
+
+
+def cmd_context(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+
+    daemon = get_daemon(args.workspace)
+    ctx = daemon.context_generator.generate(args.query, max_tokens=args.max_tokens, fmt=args.format)
+    if args.format == "markdown":
+        print(ctx["content"])
+    else:
+        print(json.dumps(ctx, indent=2, default=str))
+
+
+def cmd_watch(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+    from cortex.sync.watcher import Watcher
+
+    daemon = get_daemon(args.workspace)
+    watcher = Watcher(daemon, args.path, project_name=args.project)
+    print(json.dumps({
+        "status": "watching",
+        "path": str(args.path),
+        "workspace": args.workspace,
+        "project": args.project,
+    }, indent=2))
+    watcher.start()
+    try:
+        import time
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        watcher.stop()
+        print("\nStopped watching.", file=sys.stderr)
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    from cortex.setup.generators import (
+        claude_desktop_config,
+        cursor_mcp_config,
+        vscode_mcp_config,
+        write_project_setup,
+    )
+
+    project_path = args.path or "."
+    if args.target == "cursor":
+        config = cursor_mcp_config(args.workspace, project_path)
+    elif args.target == "claude":
+        config = claude_desktop_config(args.workspace, project_path)
+    elif args.target == "vscode":
+        config = vscode_mcp_config(args.workspace, project_path)
+    elif args.target == "project":
+        if args.write:
+            written = write_project_setup(
+                Path(project_path),
+                workspace=args.workspace,
+                project_name=args.project or Path(project_path).resolve().name,
+            )
+            print(json.dumps({"written": written}, indent=2))
+        else:
+            print(json.dumps({
+                "mcp": cursor_mcp_config(args.workspace, project_path),
+                "rule_hint": "Run with --write to create .cursor/mcp.json and .cursor/rules/cortex.mdc",
+            }, indent=2))
+        return
+    else:
+        print(f"unknown setup target: {args.target}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.write and args.target in ("cursor", "claude", "vscode"):
+        if args.target == "claude":
+            dest = Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+        else:
+            dest = Path(project_path).resolve() / ".cursor" / "mcp.json"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        existing: dict = {}
+        if dest.exists():
+            existing = json.loads(dest.read_text(encoding="utf-8"))
+        existing.setdefault("mcpServers", {}).update(config["mcpServers"])
+        dest.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps({"written": str(dest), "config": existing}, indent=2))
+    else:
+        print(json.dumps(config, indent=2))
+
+
+def cmd_serve_api(args: argparse.Namespace) -> None:
+    import uvicorn
+
+    uvicorn.run("cortex.api.rest:app", host="0.0.0.0", port=args.port, reload=False)
+
+
+def cmd_serve_mcp(args: argparse.Namespace) -> None:
+    from cortex.mcp_server.server import run_stdio
+
+    run_stdio(workspace=args.workspace)
+
+
+def cmd_node_get(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+
+    daemon = get_daemon(args.workspace)
+    node = daemon.graph.get_node(args.id)
+    if not node:
+        print("not found", file=sys.stderr)
+        sys.exit(1)
+    print(json.dumps(node.to_row(), indent=2))
+
+
+def cmd_node_traverse(args: argparse.Namespace) -> None:
+    from cortex.daemon import get_daemon
+
+    daemon = get_daemon(args.workspace)
+    nodes, edges = daemon.graph.traverse(args.id, max_depth=args.depth, direction=args.direction)
+    print(json.dumps({
+        "nodes": [n.to_row() for n in nodes],
+        "edges": [{"type": e.type, "from": e.from_id, "to": e.to_id} for e in edges],
+    }, indent=2))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cortex", description="Engineering Knowledge Graph CLI")
+    parser.add_argument("--workspace", default=DEFAULT_WORKSPACE)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("init").set_defaults(func=cmd_init)
+
+    sub.add_parser("info").set_defaults(func=cmd_info)
+
+    p_ingest = sub.add_parser("ingest")
+    p_ingest.add_argument("path")
+    p_ingest.add_argument("--project", default=None)
+    p_ingest.set_defaults(func=cmd_ingest)
+
+    p_watch = sub.add_parser("watch", help="Watch a directory and re-ingest changed files")
+    p_watch.add_argument("path")
+    p_watch.add_argument("--project", default=None)
+    p_watch.set_defaults(func=cmd_watch)
+
+    p_search = sub.add_parser("search")
+    p_search.add_argument("query")
+    p_search.add_argument("--k", type=int, default=10)
+    p_search.set_defaults(func=cmd_search)
+
+    p_context = sub.add_parser("context")
+    p_context.add_argument("query")
+    p_context.add_argument("--max-tokens", type=int, default=2000, dest="max_tokens")
+    p_context.add_argument("--format", default="markdown", choices=["markdown", "json", "facts", "citations"])
+    p_context.set_defaults(func=cmd_context)
+
+    p_api = sub.add_parser("serve-api")
+    p_api.add_argument("--port", type=int, default=8420)
+    p_api.set_defaults(func=cmd_serve_api)
+
+    sub.add_parser("serve-mcp").set_defaults(func=cmd_serve_mcp)
+
+    p_setup = sub.add_parser("setup", help="Generate MCP configs or project integration files")
+    p_setup.add_argument("target", choices=["cursor", "claude", "vscode", "project"])
+    p_setup.add_argument("--path", default=".", help="Project directory (default: current dir)")
+    p_setup.add_argument("--project", default=None, help="Project name for rules / ingest")
+    p_setup.add_argument("--write", action="store_true", help="Write config files instead of printing JSON")
+    p_setup.set_defaults(func=cmd_setup)
+
+    p_node = sub.add_parser("node")
+    node_sub = p_node.add_subparsers(dest="node_command", required=True)
+    p_node_get = node_sub.add_parser("get")
+    p_node_get.add_argument("id")
+    p_node_get.set_defaults(func=cmd_node_get)
+    p_node_traverse = node_sub.add_parser("traverse")
+    p_node_traverse.add_argument("id")
+    p_node_traverse.add_argument("--depth", type=int, default=2)
+    p_node_traverse.add_argument("--direction", default="out", choices=["out", "in", "both"])
+    p_node_traverse.set_defaults(func=cmd_node_traverse)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

cortex/config.py

@@ -0,0 +1,80 @@
+"""Workspace-level configuration and the on-disk data layout.
+
+Layout (see roadmap section 5 - Storage Architecture)::
+
+    ~/.cortex/<workspace_id>/
+        graph/        Kuzu embedded graph database
+        vectors/      LanceDB embedded vector database
+        index/        Keyword (FTS) index (SQLite FTS5)
+        meta/         Provenance, job queue, schema registry, ACLs (SQLite)
+        blobs/        Content-addressed cache of raw extracted chunks
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CORTEX_HOME_ENV = "CORTEX_HOME"
+DEFAULT_WORKSPACE = "default"
+
+
+def cortex_home() -> Path:
+    """Root directory for all Cortex data, across all workspaces."""
+    override = os.environ.get(CORTEX_HOME_ENV)
+    base = Path(override) if override else Path.home() / ".cortex"
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+@dataclass(frozen=True)
+class WorkspacePaths:
+    workspace_id: str
+    root: Path
+
+    @property
+    def graph_dir(self) -> Path:
+        """Kuzu wants to create the database file itself at this exact
+        path, so this is the *parent* directory that must pre-exist, not
+        the database path itself. See `graph_db_path`.
+        """
+        return self.root / "graph"
+
+    @property
+    def graph_db_path(self) -> Path:
+        return self.graph_dir / "db.kuzu"
+
+    @property
+    def vectors_dir(self) -> Path:
+        return self.root / "vectors"
+
+    @property
+    def index_dir(self) -> Path:
+        return self.root / "index"
+
+    @property
+    def meta_dir(self) -> Path:
+        return self.root / "meta"
+
+    @property
+    def blobs_dir(self) -> Path:
+        return self.root / "blobs"
+
+    @property
+    def meta_db_path(self) -> Path:
+        return self.meta_dir / "meta.sqlite3"
+
+    @property
+    def keyword_db_path(self) -> Path:
+        return self.index_dir / "keyword.sqlite3"
+
+    def ensure(self) -> "WorkspacePaths":
+        for d in (self.graph_dir, self.vectors_dir, self.index_dir, self.meta_dir, self.blobs_dir):
+            d.mkdir(parents=True, exist_ok=True)
+        return self
+
+
+def workspace_paths(workspace_id: str = DEFAULT_WORKSPACE) -> WorkspacePaths:
+    root = cortex_home() / workspace_id
+    return WorkspacePaths(workspace_id=workspace_id, root=root).ensure()