cortex-local 2.0.1__tar.gz

cortex_local-2.0.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: cortex-local
+Version: 2.0.1
+Summary: Local semantic search MCP server — notes + code, embedded Qdrant, fastembed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastembed>=0.4.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: qdrant-client>=1.17.0

cortex_local-2.0.1/cortex/cli.py

@@ -0,0 +1,62 @@
+"""cortex CLI — index <path> and serve (stdio MCP)."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+
+@click.group()
+def cli() -> None:
+    """cortex: local semantic search MCP server."""
+
+
+@cli.command()
+@click.argument("path", type=click.Path(exists=True, file_okay=False, resolve_path=True))
+def index(path: str) -> None:
+    """Index PATH (notes and/or code) into ~/.cortex."""
+    from .indexer import index_path
+    index_path(Path(path))
+
+
+@cli.command()
+def serve() -> None:
+    """Run cortex MCP server on stdio."""
+    from .mcp_server import run
+    run()
+
+
+@cli.command()
+def pull_models() -> None:
+    """Pre-download fastembed models."""
+    from .embedder import pull_models as _pull
+    _pull()
+
+
+@cli.command()
+def stats() -> None:
+    """Show cortex efficiency stats."""
+    from .state import _stats
+    from .mcp_server import _fmt_stats
+    from .config import VERSION
+    click.echo(_fmt_stats(VERSION, _stats, current=True))
+
+
+@cli.command("install")
+def install_cmd() -> None:
+    """Download embedding models and register cortex MCP in Claude Code."""
+    from .embedder import pull_models as _pull
+    click.echo("Downloading embedding models...")
+    _pull()
+    click.echo("Registering MCP server in Claude Code...")
+    result = subprocess.run(
+        ["claude", "mcp", "add", "cortex", "--transport", "stdio", "cortex", "serve"],
+        capture_output=True, text=True,
+    )
+    if result.returncode == 0:
+        click.echo("Done. cortex is ready — restart Claude Code to activate.")
+    else:
+        click.echo(f"MCP registration failed:\n{result.stderr}")
+        click.echo("Run manually: claude mcp add cortex --transport stdio cortex serve")
+        sys.exit(1)

cortex_local-2.0.1/cortex/config.py

@@ -0,0 +1,18 @@
+"""Paths and constants for cortex local mode."""
+
+from pathlib import Path
+
+CORTEX_DIR = Path.home() / ".cortex"
+QDRANT_PATH = str(CORTEX_DIR / "qdrant")
+DATA_DIR = CORTEX_DIR
+STATS_FILE = CORTEX_DIR / "stats.json"
+CACHE_FILE = CORTEX_DIR / "embed_cache.json"
+
+EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
+VECTOR_SIZE = 768
+
+try:
+    from importlib.metadata import version
+    VERSION = version("cortex")
+except Exception:
+    VERSION = "dev"

cortex_local-2.0.1/cortex/embedder.py

@@ -0,0 +1,33 @@
+"""fastembed-based dense + sparse embeddings for cortex local mode."""
+
+from .config import EMBED_MODEL
+
+_dense = None
+_sparse = None
+
+
+def embed(text: str) -> list:
+    """Dense embedding via fastembed nomic-embed-text (768 dims)."""
+    global _dense
+    if _dense is None:
+        from fastembed import TextEmbedding
+        _dense = TextEmbedding(EMBED_MODEL)
+    return list(_dense.embed([text[:4000]]))[0].tolist()
+
+
+def sparse_embed(text: str) -> tuple:
+    """BM25 sparse embedding via fastembed (indices, values)."""
+    global _sparse
+    if _sparse is None:
+        from fastembed import SparseTextEmbedding
+        _sparse = SparseTextEmbedding("Qdrant/bm25")
+    e = list(_sparse.embed([text[:4000]]))[0]
+    return e.indices.tolist(), e.values.tolist()
+
+
+def pull_models() -> None:
+    """Pre-download embedding models (run at install time)."""
+    print("Pulling fastembed models...")
+    embed("warmup")
+    sparse_embed("warmup")
+    print("Models ready.")

cortex_local-2.0.1/cortex/indexer.py

@@ -0,0 +1,261 @@
+"""Index notes and code from a local path into embedded Qdrant."""
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+from qdrant_client import QdrantClient
+from qdrant_client.models import (
+    Distance, FieldCondition, Filter, FilterSelector,
+    MatchValue, PointStruct, SparseVector, SparseVectorParams, VectorParams,
+)
+
+from .config import QDRANT_PATH, DATA_DIR, CACHE_FILE, VECTOR_SIZE
+from .embedder import embed, sparse_embed
+
+# Reuse chunking/graph logic from core
+import sys as _sys
+from pathlib import Path as _Path
+_core = _Path(__file__).parent.parent.parent / "core"
+if str(_core) not in _sys.path:
+    _sys.path.insert(0, str(_core))
+
+from chunker import chunk_file, CODE_EXTS, SKIP_DIRS  # noqa: E402
+from cache import load_cache, save_cache  # noqa: E402
+import graph as _graph  # noqa: E402
+
+
+def _qdrant() -> QdrantClient:
+    return QdrantClient(path=QDRANT_PATH)
+
+
+def _ensure_collection(client: QdrantClient, name: str) -> bool:
+    existing = [c.name for c in client.get_collections().collections]
+    if name not in existing:
+        client.create_collection(
+            name,
+            vectors_config=VectorParams(size=VECTOR_SIZE, distance=Distance.COSINE),
+            sparse_vectors_config={"sparse": SparseVectorParams()},
+        )
+        print(f"Created collection '{name}'")
+    return True
+
+
+def _sparse_available() -> bool:
+    try:
+        sparse_embed("warmup")
+        return True
+    except Exception as e:
+        print(f"warn: sparse unavailable: {e}")
+        return False
+
+
+def _make_point(text: str, pid: int, payload: dict, use_sparse: bool) -> PointStruct:
+    dense = embed(text)
+    if use_sparse:
+        idx, vals = sparse_embed(text)
+        vec = {"": dense, "sparse": SparseVector(indices=idx, values=vals)}
+    else:
+        vec = dense
+    return PointStruct(id=pid, vector=vec, payload=payload)
+
+
+# ── Notes ───────────────────────────────────────────────────────────────────
+
+def _parse_frontmatter(text: str) -> tuple:
+    m = re.match(r"^---\n(.*?)\n---\n", text, flags=re.DOTALL)
+    if not m:
+        return text, []
+    fm = m.group(1)
+    tags = []
+    tm = re.search(r"^tags:\s*\[([^\]]+)\]", fm, re.MULTILINE)
+    if tm:
+        tags = [t.strip().strip("\"'") for t in tm.group(1).split(",") if t.strip()]
+    else:
+        tm2 = re.search(r"^tags:\s*\n((?:[ \t]*-[ \t]*.+\n?)+)", fm, re.MULTILINE)
+        if tm2:
+            tags = [re.sub(r"^[ \t]*-[ \t]*", "", l).strip()
+                    for l in tm2.group(1).splitlines() if l.strip()]
+    return text[m.end():], tags
+
+
+def _chunk_markdown(path: Path, notes_dir: Path) -> list:
+    raw = path.read_text(encoding="utf-8")
+    rel = str(path.relative_to(notes_dir))
+    modified_at = int(path.stat().st_mtime)
+    text, tags = _parse_frontmatter(raw)
+
+    chunks, current_heading, current_lines = [], path.stem, []
+    for line in text.splitlines():
+        if re.match(r"^#{1,3} ", line):
+            if current_lines:
+                body = "\n".join(current_lines).strip()
+                if body:
+                    chunks.append({"heading": current_heading, "file": rel, "tags": tags,
+                                   "modified_at": modified_at,
+                                   "text": f"{current_heading}\n\n{body}"})
+            current_heading = line.lstrip("#").strip()
+            current_lines = []
+        else:
+            current_lines.append(line)
+    if current_lines:
+        body = "\n".join(current_lines).strip()
+        if body:
+            chunks.append({"heading": current_heading, "file": rel, "tags": tags,
+                           "modified_at": modified_at, "text": f"{current_heading}\n\n{body}"})
+    if not chunks:
+        body = text.strip()
+        if body:
+            chunks.append({"heading": path.stem, "file": rel, "tags": tags,
+                           "modified_at": modified_at, "text": body})
+    return chunks
+
+
+def _chunk_id(file: str, heading: str) -> int:
+    return int(hashlib.md5(f"{file}:{heading}".encode()).hexdigest()[:8], 16)
+
+
+def index_notes(notes_dir: Path) -> int:
+    """Index all .md files in notes_dir into the 'notes' collection. Returns chunk count."""
+    client = _qdrant()
+    _ensure_collection(client, "notes")
+    use_sparse = _sparse_available()
+
+    md_files = [p for p in notes_dir.rglob("*.md")
+                if ".obsidian" not in p.parts and ".git" not in p.parts]
+
+    cache = load_cache("notes", CACHE_FILE)
+    if client.get_collection("notes").points_count == 0:
+        cache = {}
+    new_cache: dict = {}
+    total = 0
+    cached = 0
+
+    for path in md_files:
+        rel = str(path.relative_to(notes_dir))
+        mtime = path.stat().st_mtime
+        if cache.get(rel) == mtime:
+            new_cache[rel] = mtime
+            cached += 1
+            continue
+        chunks = _chunk_markdown(path, notes_dir)
+        points = [_make_point(c["text"], _chunk_id(c["file"], c["heading"]), c, use_sparse)
+                  for c in chunks]
+        if points:
+            client.upsert("notes", points)
+            total += len(points)
+            print(f"  {rel}: {len(points)} chunk(s)", flush=True)
+        new_cache[rel] = mtime
+
+    save_cache("notes", new_cache, CACHE_FILE)
+    print(f"Done. {total} chunks indexed, {cached}/{len(md_files)} files cached.", flush=True)
+
+    try:
+        G = _graph.build_notes_graph(notes_dir)
+        _graph.persist_notes_graph(G, DATA_DIR)
+    except Exception as e:
+        print(f"  notes graph failed: {e}")
+
+    return total
+
+
+# ── Code ────────────────────────────────────────────────────────────────────
+
+def _code_chunk_id(repo: str, file: str, start: int) -> int:
+    return int(hashlib.md5(f"{repo}:{file}:{start}".encode()).hexdigest()[:8], 16)
+
+
+def index_code(code_dir: Path) -> int:
+    """Index all code files in code_dir into the 'code' collection. Returns chunk count."""
+    repo_name = code_dir.name
+    client = _qdrant()
+    _ensure_collection(client, "code")
+    use_sparse = _sparse_available()
+
+    code_files = [
+        p for p in code_dir.rglob("*")
+        if p.is_file() and p.suffix in CODE_EXTS
+        and not any(s in p.parts for s in SKIP_DIRS)
+    ]
+
+    cache = load_cache("code", CACHE_FILE)
+    if client.get_collection("code").points_count == 0:
+        cache = {}
+    new_cache = dict(cache)
+    total = 0
+    cached = 0
+    file_point_ids: dict = {}
+
+    for i, path in enumerate(code_files):
+        if i % 10 == 0 and i > 0:
+            print(f"  {repo_name}: {i}/{len(code_files)} files, {total} chunks...", flush=True)
+
+        cache_key = f"{repo_name}/{str(path.relative_to(code_dir))}"
+        mtime = path.stat().st_mtime
+        if cache.get(cache_key) == mtime:
+            cached += 1
+            continue
+
+        points = []
+        for chunk in chunk_file(path, repo_name, base_dir=code_dir):
+            pid = _code_chunk_id(repo_name, chunk["file"], chunk["start_line"])
+            points.append(_make_point(chunk["text"], pid, chunk, use_sparse))
+            file_point_ids.setdefault(chunk["file"], []).append(pid)
+        if points:
+            client.upsert("code", points)
+            total += len(points)
+            new_cache[cache_key] = mtime
+
+    save_cache("code", new_cache, CACHE_FILE)
+    print(f"  {repo_name}: {total} chunks from {len(code_files) - cached} files ({cached} cached)", flush=True)
+
+    all_files = {
+        str(p.relative_to(code_dir)) for p in code_files
+    }
+    try:
+        G = _graph.build_code_graph(code_dir, all_files)
+        if G is not None:
+            metadata = _graph.compute_code_metadata(G)
+            _graph.persist_code_graph(G, metadata, repo_name, DATA_DIR)
+            for file_rel, meta in metadata.items():
+                pids = file_point_ids.get(file_rel, [])
+                if pids:
+                    client.set_payload(
+                        collection_name="code",
+                        payload={
+                            "centrality": meta["centrality"],
+                            "community_id": meta["community_id"],
+                            "imports": meta["imports"],
+                            "imported_by": meta["imported_by"],
+                        },
+                        points=pids,
+                    )
+    except Exception as e:
+        print(f"  graph failed: {e}")
+
+    from .state import invalidate_graph_cache
+    invalidate_graph_cache(repo_name)
+    return total
+
+
+def index_path(path: Path) -> None:
+    """Index a path — .md files as notes, code files as code."""
+    path = path.resolve()
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+    md_files = list(path.rglob("*.md"))
+    code_files = [p for p in path.rglob("*")
+                  if p.is_file() and p.suffix in CODE_EXTS
+                  and not any(s in p.parts for s in SKIP_DIRS)]
+
+    if md_files:
+        print(f"\nIndexing notes from {path} ({len(md_files)} .md files)...")
+        index_notes(path)
+
+    if code_files:
+        print(f"\nIndexing code from {path} ({len(code_files)} files)...")
+        index_code(path)
+
+    if not md_files and not code_files:
+        print(f"No indexable files found in {path}")

cortex_local-2.0.1/cortex/mcp_server.py

@@ -0,0 +1,389 @@
+"""Cortex local MCP server — stdio transport, all 8 tools, embedded Qdrant."""
+
+import json
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+from qdrant_client import QdrantClient
+from qdrant_client.models import Prefetch, Fusion, SparseVector
+
+from .config import QDRANT_PATH, DATA_DIR, VERSION, VECTOR_SIZE
+from .embedder import embed, sparse_embed
+from .state import _stats, get_graph_meta, save_stats
+from .indexer import index_path
+
+mcp = FastMCP("cortex")
+
+_reindex_state: dict = {
+    "running": False, "started_at": None, "output": [], "error": None, "done": False,
+}
+_reindex_path: str = ""
+
+
+def _qdrant() -> QdrantClient:
+    return QdrantClient(path=QDRANT_PATH)
+
+
+# ── Reindex ─────────────────────────────────────────────────────────────────
+
+def _run_reindex(path_str: str) -> None:
+    _reindex_state.update(running=True, started_at=time.time(), output=[], error=None, done=False)
+    import io
+    from contextlib import redirect_stdout
+    buf = io.StringIO()
+    try:
+        with redirect_stdout(buf):
+            index_path(Path(path_str))
+        _reindex_state["output"] = buf.getvalue().splitlines()
+        _stats["reindex_count"] += 1
+    except Exception as e:
+        _reindex_state["error"] = str(e)
+    finally:
+        _reindex_state["running"] = False
+        _reindex_state["done"] = True
+        save_stats()
+
+
+# ── PPR helper ───────────────────────────────────────────────────────────────
+
+def _ppr_block(matched_files: list, matched_scores: list) -> str | None:
+    try:
+        from core.notes_graph import ppr_augment
+    except ImportError:
+        try:
+            import sys
+            from pathlib import Path as _P
+            _core = _P(__file__).parent.parent.parent / "core"
+            if str(_core) not in sys.path:
+                sys.path.insert(0, str(_core))
+            from notes_graph import ppr_augment
+        except Exception:
+            return None
+    graph_path = DATA_DIR / "graph_notes.json"
+    extras, reason = ppr_augment(matched_files, matched_scores, graph_path, _return_reason=True)
+    if extras:
+        _stats["ppr_fires"] += 1
+        _stats["ppr_results_added"] += len(extras)
+        lines = ["**Related via wikilinks (PPR):**"]
+        for e in extras:
+            lines.append(f"  -> {e['file']} (ppr: {e['ppr_score']})")
+        return "\n".join(lines)
+    if reason == "exception":
+        _stats["ppr_exception"] += 1
+    else:
+        _stats["ppr_below_threshold"] += 1
+    return None
+
+
+# ── Tools ────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+def search_notes(query: str, limit: int = 5) -> str:
+    """Search the user's personal knowledge base semantically.
+
+    Call this proactively whenever the user asks about:
+    - Their projects, plans, ideas, or roadmap items
+    - Personal context, goals, or decisions they may have documented
+    - How something in their setup works
+    - Anything that sounds like it could be in personal notes
+
+    Returns matching note sections with file path, heading, score, and tags.
+    PPR over wikilinks surfaces related notes beyond direct vector matches.
+    """
+    _stats["search_notes_calls"] += 1
+    client = _qdrant()
+    vector = embed(query)
+    try:
+        idx, vals = sparse_embed(query)
+        results = client.query_points(
+            "notes",
+            prefetch=[
+                Prefetch(query=vector, using=None, limit=limit * 2),
+                Prefetch(query=SparseVector(indices=idx, values=vals), using="sparse", limit=limit * 2),
+            ],
+            query=Fusion.RRF,
+            limit=limit,
+            with_payload=True,
+        ).points
+    except Exception:
+        results = client.query_points("notes", query=vector, limit=limit, with_payload=True).points
+    if not results:
+        return "No results found."
+    _stats["total_results_notes"] += len(results)
+    parts = []
+    matched_files = []
+    matched_scores = []
+    for r in results:
+        p = r.payload
+        tags = p.get("tags", [])
+        tag_str = f" `{'`, `'.join(tags)}`" if tags else ""
+        parts.append(f"**{p['file']} > {p['heading']}** (score: {round(r.score, 3)}){tag_str}\n\n{p['text']}")
+        matched_files.append(p.get("file", ""))
+        matched_scores.append(r.score)
+    ppr = _ppr_block(matched_files, matched_scores)
+    if ppr:
+        parts.append(ppr)
+    out = "\n\n---\n\n".join(parts)
+    _stats["context_tokens_notes"] += len(out) // 4
+    return out
+
+
+@mcp.tool()
+def search_code(query: str, limit: int = 5) -> str:
+    """Search source code across indexed directories semantically.
+
+    Results are re-ranked by centrality (highly-imported files score higher).
+    Returns code chunks with file path, line numbers, language, score, centrality, and community.
+    """
+    _stats["search_code_calls"] += 1
+    client = _qdrant()
+    vector = embed(query)
+    fetch_limit = min(limit * 3, 50)
+    try:
+        idx, vals = sparse_embed(query)
+        results = client.query_points(
+            "code",
+            prefetch=[
+                Prefetch(query=vector, using=None, limit=fetch_limit),
+                Prefetch(query=SparseVector(indices=idx, values=vals), using="sparse", limit=fetch_limit),
+            ],
+            query=Fusion.RRF,
+            limit=fetch_limit,
+            with_payload=True,
+        ).points
+    except Exception:
+        results = client.query_points("code", query=vector, limit=fetch_limit, with_payload=True).points
+    if not results:
+        return "No results found."
+    scored = []
+    for r in results:
+        p = r.payload
+        file_meta = get_graph_meta(p.get("repo", "")).get(p.get("file", ""), {})
+        centrality = file_meta.get("centrality", 0.0)
+        boosted = r.score * (1.0 + 0.2 * centrality)
+        if centrality > 0:
+            _stats["centrality_lift_total"] += round(boosted - r.score, 4)
+            _stats["centrality_lift_count"] += 1
+        scored.append((boosted, r, file_meta))
+    scored.sort(key=lambda x: -x[0])
+    seen: set = set()
+    deduped = []
+    for item in scored:
+        key = f"{item[1].payload.get('repo', '')}/{item[1].payload.get('file', '')}"
+        if key not in seen:
+            seen.add(key)
+            deduped.append(item)
+        if len(deduped) >= limit:
+            break
+    _stats["total_results_code"] += len(deduped)
+    parts = []
+    for boosted_score, r, file_meta in deduped:
+        p = r.payload
+        centrality = file_meta.get("centrality")
+        community = file_meta.get("community_id")
+        header = (
+            f"**{p['repo']}/{p['file']}** "
+            f"lines {p['start_line']}-{p['end_line']} "
+            f"({p.get('language', '')}) — score: {round(boosted_score, 3)}"
+        )
+        if centrality is not None:
+            header += f" · centrality: {centrality}"
+        if community is not None:
+            header += f" · community: {community}"
+        url = p.get("github_url", "")
+        parts.append(f"{header}\n{url}\n\n{p['text']}" if url else f"{header}\n\n{p['text']}")
+    out = "\n\n---\n\n".join(parts)
+    _stats["context_tokens_code"] += len(out) // 4
+    return out
+
+
+@mcp.tool()
+def reindex(path: str = "") -> str:
+    """Re-index a path into the local Qdrant database.
+
+    Runs async — returns immediately. Call reindex_status() to check progress.
+    path: directory to index (defaults to last indexed path).
+    """
+    global _reindex_path
+    target = path or _reindex_path
+    if not target:
+        return "Error: no path specified and no previous path recorded. Pass a path to index."
+    _reindex_path = target
+    if _reindex_state["running"]:
+        return "Reindex already running. Call reindex_status() to check progress."
+    threading.Thread(target=_run_reindex, args=(target,), daemon=True).start()
+    return f"Reindex queued for '{target}'. Use reindex_status() to check progress."
+
+
+@mcp.tool()
+def reindex_status() -> str:
+    """Check whether a reindex is running or finished, and see its output log."""
+    if _reindex_state["started_at"] is None:
+        return "No reindex has been run yet. Call reindex(path='/your/path') to start."
+    elapsed = time.time() - _reindex_state["started_at"]
+    status = "running" if _reindex_state["running"] else "done"
+    lines = [f"Status: {status} ({elapsed:.0f}s elapsed)"]
+    if _reindex_state["output"]:
+        lines.append("\n".join(_reindex_state["output"]))
+    if _reindex_state["error"]:
+        lines.append(f"Error: {_reindex_state['error']}")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_stats(all: bool = False) -> str:
+    """Return cortex efficiency metrics.
+
+    all=False (default): current session stats.
+    all=True: all persisted versions side-by-side.
+    """
+    from .config import STATS_FILE
+    if all:
+        try:
+            versions = json.loads(STATS_FILE.read_text()).get("versions", {}) if STATS_FILE.exists() else {}
+        except Exception:
+            versions = {}
+        if not versions:
+            return "No persisted stats found."
+        blocks = []
+        for v in sorted(versions):
+            s = versions[v]
+            blocks.append(_fmt_stats(v, s, current=(v == VERSION)))
+        return "\n\n".join(blocks)
+    return _fmt_stats(VERSION, _stats, current=True)
+
+
+def _fmt_stats(v: str, s: dict, current: bool = False) -> str:
+    total = s.get("search_code_calls", 0) + s.get("search_notes_calls", 0)
+    ppr_rate = f"{s['ppr_fires'] / s['search_notes_calls'] * 100:.1f}%" if s.get("search_notes_calls") else "—"
+    lift_avg = round(s["centrality_lift_total"] / s["centrality_lift_count"], 4) if s.get("centrality_lift_count") else 0
+    label = f"{v} (current)" if current else v
+    lines = [label]
+    started = s.get("started_at", "")
+    if current and started:
+        try:
+            delta = datetime.now(timezone.utc) - datetime.fromisoformat(started)
+            h, rem = divmod(int(delta.total_seconds()), 3600)
+            m = rem // 60
+            lines.append(f"  uptime: {h}h {m}m")
+        except Exception:
+            pass
+    lines += [
+        f"  searches: code={s.get('search_code_calls', 0)} notes={s.get('search_notes_calls', 0)}  total={total}",
+        f"  centrality lift avg: {lift_avg} (across {s.get('centrality_lift_count', 0)} results)",
+        f"  PPR: {s.get('ppr_fires', 0)} fires ({ppr_rate} of note searches) · +{s.get('ppr_results_added', 0)} results",
+        f"  reindexes: {s.get('reindex_count', 0)}",
+    ]
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_neighbors(file: str, repo: str) -> str:
+    """Show what a code file imports and what imports it (direct graph neighbors).
+
+    Use when you want to explore structural connections around a file.
+    Example: get_neighbors("src/lib/api/sonarr.ts", "arr-client")
+
+    Requires graph data — run reindex first if empty.
+    """
+    meta = get_graph_meta(repo)
+    if not meta:
+        return f"No graph data for '{repo}'. Run reindex() first."
+    file_meta = meta.get(file)
+    if file_meta is None:
+        matches = [f for f in meta if file in f]
+        if not matches:
+            return f"File '{file}' not found in graph for '{repo}'."
+        file = matches[0]
+        file_meta = meta[file]
+    imports = file_meta.get("imports", [])
+    imported_by = file_meta.get("imported_by", [])
+    lines = [
+        f"**{file}**",
+        f"centrality: {file_meta.get('centrality', 0)} · community: {file_meta.get('community_id', '?')}",
+    ]
+    if imports:
+        lines.append(f"\nimports ({len(imports)}):")
+        lines.extend(f"  -> {f}" for f in imports)
+    if imported_by:
+        lines.append(f"\nimported by ({len(imported_by)}):")
+        lines.extend(f"  <- {f}" for f in imported_by)
+    if not imports and not imported_by:
+        lines.append("\nNo connections found (isolated file).")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_community(repo: str, community_id: int) -> str:
+    """List all files in the same structural community/cluster.
+
+    Use when you want to find everything structurally related to a file.
+    Example: get_community("my-project", 0)
+
+    Requires graph data — run reindex first if empty.
+    """
+    meta = get_graph_meta(repo)
+    if not meta:
+        return f"No graph data for '{repo}'. Run reindex() first."
+    members = [
+        (f, m.get("centrality", 0))
+        for f, m in meta.items()
+        if m.get("community_id") == community_id
+    ]
+    if not members:
+        return f"Community {community_id} not found in '{repo}'."
+    members.sort(key=lambda x: -x[1])
+    lines = [f"**Community {community_id}** in '{repo}' — {len(members)} files:"]
+    for f, centrality in members:
+        star = "*" if centrality > 0.1 else " "
+        lines.append(f"  {star} {f} (centrality: {centrality})")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def get_onboarding(existing_content: str = "") -> str:
+    """Get a CLAUDE.md template with Cortex search instructions pre-filled.
+
+    No args: returns full template with placeholder sections.
+    With existing_content: appends Cortex section if not already present.
+    """
+    cortex_section = """## Cortex (semantic search)
+
+cortex is available as an MCP tool. Use it proactively:
+- `search_notes(query)` — search personal knowledge base
+- `search_code(query)` — search indexed code repositories
+- `get_neighbors(file, repo)` — explore import graph for a file
+- `get_community(repo, community_id)` — list files in a structural cluster
+- `reindex(path)` — re-index a directory after changes
+- `reindex_status()` — check reindex progress
+"""
+    if existing_content.strip():
+        if "cortex" in existing_content.lower() or "search_notes" in existing_content:
+            return existing_content
+        return existing_content.rstrip() + "\n\n" + cortex_section
+    return f"""# Project CLAUDE.md
+
+## Stack
+<!-- fill in: language, framework, key dependencies -->
+
+## Commands
+<!-- fill in: build, test, lint, run -->
+
+## Structure
+<!-- fill in: key directories and what they contain -->
+
+## Conventions
+<!-- fill in: naming, patterns, style -->
+
+## Don't
+<!-- fill in: things to avoid -->
+
+{cortex_section}"""
+
+
+def run() -> None:
+    """Entry point for stdio MCP server."""
+    mcp.run(transport="stdio")

cortex_local-2.0.1/cortex/state.py

@@ -0,0 +1,86 @@
+"""Runtime state and graph cache for cortex local mode."""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .config import DATA_DIR, STATS_FILE, VERSION
+
+_graph_cache: dict = {}
+
+_stats: dict = {}
+
+
+def _default_stats() -> dict:
+    return {
+        "search_code_calls": 0,
+        "centrality_lift_total": 0.0,
+        "centrality_lift_count": 0,
+        "search_notes_calls": 0,
+        "ppr_fires": 0,
+        "ppr_results_added": 0,
+        "graph_cache_hits": 0,
+        "graph_cache_misses": 0,
+        "reindex_count": 0,
+        "total_results_code": 0,
+        "total_results_notes": 0,
+        "context_tokens_notes": 0,
+        "context_tokens_code": 0,
+        "ppr_below_threshold": 0,
+        "ppr_exception": 0,
+        "started_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _load_stats() -> dict:
+    defaults = _default_stats()
+    try:
+        if STATS_FILE.exists():
+            data = json.loads(STATS_FILE.read_text())
+            saved = data.get("versions", {}).get(VERSION, {})
+            if saved:
+                return {**defaults, **saved}
+    except Exception:
+        pass
+    return defaults
+
+
+def save_stats() -> None:
+    try:
+        existing: dict = {}
+        if STATS_FILE.exists():
+            existing = json.loads(STATS_FILE.read_text()).get("versions", {})
+        existing[VERSION] = {**_stats, "last_saved": datetime.now(timezone.utc).isoformat()}
+        STATS_FILE.parent.mkdir(parents=True, exist_ok=True)
+        STATS_FILE.write_text(json.dumps({"versions": existing}, indent=2))
+    except Exception:
+        pass
+
+
+def get_graph_meta(repo_name: str) -> dict:
+    if repo_name in _graph_cache:
+        _stats["graph_cache_hits"] += 1
+        return _graph_cache[repo_name]
+    path = DATA_DIR / f"graph_{repo_name}.json"
+    if not path.exists():
+        _stats["graph_cache_misses"] += 1
+        return {}
+    try:
+        data = json.loads(path.read_text())
+        meta = {n["id"]: n for n in data.get("nodes", []) if "id" in n}
+        _graph_cache[repo_name] = meta
+        _stats["graph_cache_misses"] += 1
+        return meta
+    except Exception:
+        _stats["graph_cache_misses"] += 1
+        return {}
+
+
+def invalidate_graph_cache(repo_name: str = "") -> None:
+    if repo_name:
+        _graph_cache.pop(repo_name, None)
+    else:
+        _graph_cache.clear()
+
+
+_stats = _load_stats()

cortex_local-2.0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cortex-local"
+version = "2.0.1"
+description = "Local semantic search MCP server — notes + code, embedded Qdrant, fastembed"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "qdrant-client>=1.17.0",
+    "fastembed>=0.4.0",
+    "click>=8.0.0",
+    "networkx>=3.0",
+]
+
+[project.scripts]
+cortex = "cortex.cli:cli"
+
+[project.entry-points."mcp.servers"]
+cortex = "cortex.mcp_server:run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cortex"]