cortex-local 2.1.16__tar.gz → 2.2.1__tar.gz

{cortex_local-2.1.16 → cortex_local-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-local
-Version: 2.1.16
+Version: 2.2.1
 Summary: Local semantic search MCP server — notes + code, embedded Qdrant, fastembed
 Requires-Python: >=3.11
 Requires-Dist: click>=8.0.0
@@ -8,8 +8,8 @@ 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
-Provides-Extra: legacy
-Requires-Dist: numpy==1.26.4; extra == 'legacy'
+Requires-Dist: tqdm>=4.0
+Requires-Dist: watchdog>=3.0
 Description-Content-Type: text/markdown
 
 # cortex-local

{cortex_local-2.1.16 → cortex_local-2.2.1}/cortex/cli.py

@@ -1,14 +1,17 @@
 """cortex CLI — index <path> and serve (stdio MCP)."""
 
+import json
 import shutil
 import subprocess
 import sys
+from collections import Counter
 from pathlib import Path
 
 import click
 
 from .config import (
     WORKSPACES_DIR, get_active_workspace, set_active_workspace, get_workspace_dir,
+    data_dir, save_last_indexed_path,
 )
 
 
@@ -19,10 +22,12 @@ def cli() -> None:
 
 @cli.command()
 @click.argument("path", type=click.Path(exists=True, file_okay=False, resolve_path=True))
-def index(path: str) -> None:
+@click.option("--progress/--no-progress", default=True, help="Show tqdm progress bar.")
+def index(path: str, progress: bool) -> None:
     """Index PATH (notes and/or code) into ~/.cortex."""
     from .indexer import index_path
-    index_path(Path(path))
+    index_path(Path(path), show_progress=progress)
+    save_last_indexed_path(path)
 
 
 @cli.command()
@@ -117,6 +122,44 @@ def workspace_current() -> None:
     click.echo(get_active_workspace())
 
 
+@cli.command("search-log")
+@click.option("--top", default=10, show_default=True, help="Number of top queries to show.")
+def search_log_cmd(top: int) -> None:
+    """Show search query analytics from the search log."""
+    log_file = data_dir() / "search_log.jsonl"
+    if not log_file.exists():
+        click.echo("No search log found. Run some searches first.")
+        return
+    queries = []
+    zero_result_queries = []
+    tool_counts: Counter = Counter()
+    with open(log_file) as f:
+        for line in f:
+            try:
+                entry = json.loads(line)
+            except Exception:
+                continue
+            q = entry.get("query", "")
+            queries.append(q)
+            tool_counts[entry.get("tool", "unknown")] += 1
+            if not entry.get("top"):
+                zero_result_queries.append(q)
+    if not queries:
+        click.echo("Search log is empty.")
+        return
+    click.echo(f"Total searches: {len(queries)}")
+    for tool, count in sorted(tool_counts.items()):
+        click.echo(f"  {tool}: {count}")
+    click.echo(f"\nTop {top} queries:")
+    for q, n in Counter(queries).most_common(top):
+        click.echo(f"  {n:3d}x  {q}")
+    if zero_result_queries:
+        unique_zero = sorted(set(zero_result_queries))
+        click.echo(f"\nZero-result queries ({len(unique_zero)} unique):")
+        for q in unique_zero[:20]:
+            click.echo(f"  {q}")
+
+
 @cli.command("install")
 def install_cmd() -> None:
     """Download embedding models and register cortex MCP in Claude Code."""

{cortex_local-2.1.16 → cortex_local-2.2.1}/cortex/config.py

@@ -2,11 +2,19 @@
 
 import os
 import shutil
+import tomllib
 from pathlib import Path
 
 CORTEX_DIR = Path.home() / ".cortex"
 WORKSPACES_DIR = CORTEX_DIR / "workspaces"
 ACTIVE_WORKSPACE_FILE = CORTEX_DIR / "active_workspace"
+CONFIG_FILE = CORTEX_DIR / "config.toml"
+
+_CONFIG_DEFAULTS: dict = {
+    "watch": {"enabled": True, "debounce_seconds": 2.0},
+    "index": {"last_path": "", "exclude_patterns": []},
+}
+_config_cache: dict | None = None
 
 EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5"
 VECTOR_SIZE = 768
@@ -50,6 +58,41 @@ def stats_file(ws: str | None = None) -> Path:
     return get_workspace_dir(ws) / "stats.json"
 
 
+def get_config() -> dict:
+    global _config_cache
+    if _config_cache is not None:
+        return _config_cache
+    cfg: dict = {k: dict(v) for k, v in _CONFIG_DEFAULTS.items()}
+    if CONFIG_FILE.exists():
+        try:
+            loaded = tomllib.loads(CONFIG_FILE.read_text())
+            for section, vals in loaded.items():
+                if section in cfg and isinstance(vals, dict):
+                    cfg[section].update(vals)
+        except Exception:
+            pass
+    _config_cache = cfg
+    return cfg
+
+
+def save_last_indexed_path(path: str) -> None:
+    global _config_cache
+    CORTEX_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        if CONFIG_FILE.exists():
+            text = CONFIG_FILE.read_text()
+            import re
+            text = re.sub(r'^last_path\s*=.*$', f'last_path = "{path}"', text, flags=re.MULTILINE)
+            if 'last_path' not in text:
+                text += f'\n[index]\nlast_path = "{path}"\n'
+        else:
+            text = f'[watch]\nenabled = true\ndebounce_seconds = 2.0\n\n[index]\nlast_path = "{path}"\nexclude_patterns = []\n'
+        CONFIG_FILE.write_text(text)
+    except Exception:
+        pass
+    _config_cache = None  # invalidate cache
+
+
 def migrate_legacy() -> None:
     """Move old flat ~/.cortex/ layout into ~/.cortex/workspaces/default/ on first run."""
     old_qdrant = CORTEX_DIR / "qdrant"

cortex_local-2.2.1/cortex/core/cache.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Mtime-based embedding cache — skip re-embedding unchanged files on full reindex."""
+
+import json
+import os
+from pathlib import Path
+
+
+def _default_cache_file() -> Path:
+    repos_config = os.environ.get("REPOS_CONFIG", "/app/data/repos.json")
+    return Path(repos_config).parent / "embed_cache.json"
+
+
+def load_cache(section: str, cache_file: Path | None = None) -> dict:
+    """Load {rel_path: {"mtime": float, "hash": str}} for given section ('notes' or 'code')."""
+    if cache_file is None:
+        cache_file = _default_cache_file()
+    try:
+        if cache_file.exists():
+            raw = json.loads(cache_file.read_text()).get(section, {})
+            return {k: v if isinstance(v, dict) else {"mtime": v, "hash": ""} for k, v in raw.items()}
+    except Exception:
+        pass
+    return {}
+
+
+def save_cache(section: str, data: dict, cache_file: Path | None = None) -> None:
+    """Persist updated cache section without touching other sections."""
+    if cache_file is None:
+        cache_file = _default_cache_file()
+    try:
+        existing = json.loads(cache_file.read_text()) if cache_file.exists() else {}
+        existing[section] = data
+        cache_file.write_text(json.dumps(existing))
+    except Exception as e:
+        print(f"warn: cache save failed: {e}", flush=True)

{cortex_local-2.1.16 → cortex_local-2.2.1}/cortex/core/chunker.py

@@ -1,8 +1,12 @@
 #!/usr/bin/env python3
 """Source code chunking — tree-sitter semantic parsing with sliding-window fallback."""
 
+import fnmatch
+import os
 from pathlib import Path
 
+REPOS_DIR = Path(os.environ.get("REPOS_DIR", "/tmp/repos"))
+
 CODE_EXTS = {".js", ".ts", ".tsx", ".jsx", ".svelte", ".py", ".java", ".go", ".rs", ".css", ".html", ".kt", ".kts", ".gd", ".yml", ".yaml"}
 SKIP_DIRS = {"node_modules", ".git", "dist", "build", ".next", ".svelte-kit", "__pycache__", ".gradle", "target"}
 LANG_MAP = {
@@ -13,11 +17,16 @@ LANG_MAP = {
     ".yml": "yaml", ".yaml": "yaml",
 }
 
+def _is_excluded(rel: str, patterns: list) -> bool:
+    return any(fnmatch.fnmatch(rel, p) for p in patterns)
+
+
 CHUNK_LINES = 30
 OVERLAP_LINES = 5
 MAX_CHUNK_LINES = 80
 
 _FRAMEWORK_FILENAMES = {
+    # SvelteKit route/hook conventions
     "hooks.server":    "sveltekit server hooks handle",
     "hooks.client":    "sveltekit client hooks",
     "+page":           "sveltekit page component",
@@ -26,16 +35,19 @@ _FRAMEWORK_FILENAMES = {
     "+page.server":    "sveltekit page server load action",
     "+layout.server":  "sveltekit layout server load",
     "+error":          "sveltekit error page",
+    # Framework config files (unambiguous)
     "svelte.config":   "sveltekit",
     "next.config":     "nextjs",
     "nuxt.config":     "nuxt",
     "astro.config":    "astro",
     "remix.config":    "remix",
+    # Next.js pages router conventions
     "_app":            "nextjs",
     "_document":       "nextjs",
 }
 
 _FRAMEWORK_IMPORTS = [
+    # JS/TS frameworks
     ("@sveltejs/kit",          "sveltekit"),
     ("from 'react'",           "react"),
     ('from "react"',           "react"),
@@ -53,6 +65,7 @@ _FRAMEWORK_IMPORTS = [
     ("@remix-run/",            "remix"),
     ("from 'astro'",           "astro"),
     ('from "astro"',           "astro"),
+    # Python frameworks
     ("from fastapi",           "fastapi"),
     ("import fastapi",         "fastapi"),
     ("from django",            "django"),
@@ -62,6 +75,7 @@ _FRAMEWORK_IMPORTS = [
     ("from starlette",         "starlette"),
     ("from pydantic",          "pydantic"),
     ("from sqlalchemy",        "sqlalchemy"),
+    # Python ML/data
     ("import torch",           "pytorch"),
     ("from torch",             "pytorch"),
     ("import tensorflow",      "tensorflow"),
@@ -72,31 +86,19 @@ _FRAMEWORK_IMPORTS = [
     ("from transformers",      "huggingface"),
     ("from qdrant_client",     "qdrant"),
     ("from fastembed",         "fastembed"),
+    # Kotlin/Java
     ("import io.ktor",         "ktor"),
     ("import org.springframework", "spring"),
     ("import androidx",        "android"),
+    # Go
     ("gin-gonic/gin",          "gin"),
     ("gofiber/fiber",          "fiber"),
+    # Rust
     ("use actix",              "actix"),
     ("use axum",               "axum"),
     ("use tokio",              "tokio"),
 ]
 
-
-def _extra_tokens(rel: str, lines: list) -> str:
-    stem = Path(rel).stem
-    parts = []
-    if stem in _FRAMEWORK_FILENAMES:
-        parts.append(_FRAMEWORK_FILENAMES[stem])
-    header = "\n".join(lines[:50])
-    seen = set(parts)
-    for pattern, framework in _FRAMEWORK_IMPORTS:
-        if pattern in header and framework not in seen:
-            parts.append(framework)
-            seen.add(framework)
-    return " ".join(parts)
-
-
 try:
     from tree_sitter import Language, Parser as _TSParser
     import tree_sitter_python as _tspy
@@ -129,6 +131,29 @@ except Exception:
     _TS_SEMANTIC = {}
 
 
+def _path_tokens(repo_name: str, rel: str) -> str:
+    parts = [repo_name.replace("-", " ").replace("_", " ")]
+    for p in Path(rel).parts[:-1]:
+        parts.append(p.replace("-", " ").replace("_", " "))
+    stem = Path(rel).stem.replace("-", " ").replace("_", " ").replace(".", " ")
+    parts.append(stem)
+    return " ".join(parts)
+
+
+def _extra_tokens(rel: str, lines: list) -> str:
+    stem = Path(rel).stem
+    parts = []
+    if stem in _FRAMEWORK_FILENAMES:
+        parts.append(_FRAMEWORK_FILENAMES[stem])
+    header = "\n".join(lines[:50])
+    seen = set(parts)
+    for pattern, framework in _FRAMEWORK_IMPORTS:
+        if pattern in header and framework not in seen:
+            parts.append(framework)
+            seen.add(framework)
+    return " ".join(parts)
+
+
 def _sliding_window(lines: list, start: int, end: int, repo_name: str, rel: str, language: str, github_url_base: str = "", extra_tokens: str = "") -> list:
     step = CHUNK_LINES - OVERLAP_LINES
     chunks = []
@@ -138,7 +163,8 @@ def _sliding_window(lines: list, start: int, end: int, repo_name: str, rel: str,
         body = "\n".join(lines[i:j]).strip()
         if body:
             url = f"{github_url_base}/{rel}#L{i+1}-L{j}" if github_url_base else ""
-            header = f"# {repo_name}/{rel} (lines {i+1}-{j})"
+            tokens = _path_tokens(repo_name, rel)
+            header = f"# {repo_name}/{rel} (lines {i+1}-{j})\n# {tokens}"
             if extra_tokens:
                 header += f"\n# {extra_tokens}"
             chunks.append({
@@ -195,6 +221,24 @@ def chunk_file(path: Path, repo_name: str, base_dir: Path | None = None, github_
     language = LANG_MAP.get(ext, ext.lstrip("."))
     extra = _extra_tokens(rel, lines)
 
+    def _header(rel: str, s: int, e: int, tokens: str) -> str:
+        h = f"# {repo_name}/{rel} (lines {s}-{e})\n# {tokens}"
+        return h + f"\n# {extra}" if extra else h
+
+    # Small files: keep as single chunk to avoid diluting path/filename signal
+    if len(lines) <= MAX_CHUNK_LINES:
+        body = "\n".join(lines).strip()
+        if body:
+            url = f"{github_url_base}/{rel}#L1-L{len(lines)}" if github_url_base else ""
+            tokens = _path_tokens(repo_name, rel)
+            return [{
+                "repo": repo_name, "file": rel, "language": language,
+                "start_line": 1, "end_line": len(lines),
+                "text": f"{_header(rel, 1, len(lines), tokens)}\n\n{body}",
+                "github_url": url,
+            }]
+        return []
+
     if _TS_AVAILABLE and ext in _TS_LANGUAGES:
         try:
             parser = _TSParser(_TS_LANGUAGES[ext])
@@ -212,13 +256,11 @@ def chunk_file(path: Path, repo_name: str, base_dir: Path | None = None, github_
                         body = "\n".join(lines[s:e]).strip()
                         if body:
                             url = f"{github_url_base}/{rel}#L{s+1}-L{e}" if github_url_base else ""
-                            header = f"# {repo_name}/{rel} (lines {s+1}-{e})"
-                            if extra:
-                                header += f"\n# {extra}"
+                            tokens = _path_tokens(repo_name, rel)
                             chunks.append({
                                 "repo": repo_name, "file": rel, "language": language,
                                 "start_line": s + 1, "end_line": e,
-                                "text": f"{header}\n\n{body}",
+                                "text": f"{_header(rel, s+1, e, tokens)}\n\n{body}",
                                 "github_url": url,
                             })
                 return chunks

cortex_local-2.2.1/cortex/core/formatters.py

@@ -0,0 +1,114 @@
+"""Shared result formatters for MCP search tools — used by server and local modes."""
+
+from datetime import datetime, timezone
+
+
+def format_notes_parts(results) -> tuple:
+    """Build parts list from note search results.
+
+    Returns (parts, matched_files, matched_scores). Caller is responsible for:
+    - computing ppr_block from matched_files/matched_scores and appending to parts
+    - joining parts with '\\n\\n---\\n\\n'
+    - updating stats['context_tokens_notes']
+    """
+    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)
+    return parts, matched_files, matched_scores
+
+
+def format_code_results(deduped) -> str:
+    """Build formatted string from scored/deduped code search results.
+
+    Input: list of (boosted_score, qdrant_point, file_meta) tuples.
+    Caller is responsible for updating stats['context_tokens_code'].
+    """
+    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']}")
+    return "\n\n---\n\n".join(parts)
+
+
+def fmt_stats(v: str, stats: dict, current: bool = False) -> str:
+    """Format stats block for one version. Safe for both server and local stats dicts."""
+    total_searches = stats.get("search_code_calls", 0) + stats.get("search_notes_calls", 0)
+    ppr_rate = (
+        f"{stats['ppr_fires'] / stats['search_notes_calls'] * 100:.1f}%"
+        if stats.get("search_notes_calls", 0) > 0 else "—"
+    )
+    avg_ppr = round(stats["ppr_results_added"] / stats["ppr_fires"], 1) if stats.get("ppr_fires", 0) > 0 else "—"
+    total_cache = stats.get("graph_cache_hits", 0) + stats.get("graph_cache_misses", 0)
+    cache_rate = f"{stats['graph_cache_hits'] / total_cache * 100:.1f}%" if total_cache > 0 else "—"
+    avg_lift = round(stats["centrality_lift_total"] / stats["centrality_lift_count"], 4) if stats.get("centrality_lift_count", 0) > 0 else 0
+    total_results = stats.get("total_results_code", 0) + stats.get("total_results_notes", 0)
+    avg_results = round(total_results / total_searches, 1) if total_searches > 0 else "—"
+    notes_pct = f"{stats['search_notes_calls'] / total_searches * 100:.0f}%" if total_searches > 0 else "—"
+
+    label = f"{v} (current)" if current else v
+    lines = [label]
+
+    started = stats.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
+    elif started:
+        last = stats.get("last_saved", "")
+        period = started[:10]
+        if last:
+            period += f" -> {last[:10]}"
+        lines.append(f"  period: {period}")
+
+    lines += [
+        f"  searches: code={stats.get('search_code_calls', 0)} notes={stats.get('search_notes_calls', 0)}  total={total_searches}  (notes {notes_pct})",
+        f"  results: code={stats.get('total_results_code', 0)} notes={stats.get('total_results_notes', 0)}  avg/search={avg_results}",
+        f"  centrality lift avg: {avg_lift} (across {stats.get('centrality_lift_count', 0)} results)",
+        f"  PPR: {stats.get('ppr_fires', 0)} fires ({ppr_rate} of note searches) · +{stats.get('ppr_results_added', 0)} results · avg {avg_ppr}/fire",
+    ]
+    _ppr_diag = {k: stats.get(k, 0) for k in ("ppr_nx_missing", "ppr_graph_missing", "ppr_no_matches", "ppr_below_threshold", "ppr_exception")}
+    if any(_ppr_diag.values()):
+        lines.append(
+            f"  PPR misses: nx={_ppr_diag['ppr_nx_missing']} graph={_ppr_diag['ppr_graph_missing']}"
+            f" no_match={_ppr_diag['ppr_no_matches']} below_threshold={_ppr_diag['ppr_below_threshold']}"
+            f" exception={_ppr_diag['ppr_exception']}"
+        )
+    ctx_notes = stats.get("context_tokens_notes", 0)
+    ctx_code = stats.get("context_tokens_code", 0)
+    ctx_total = ctx_notes + ctx_code
+
+    def _k(n):
+        return f"{n // 1000}k" if n >= 1000 else str(n)
+
+    lines += [
+        f"  context injected: notes={_k(ctx_notes)} code={_k(ctx_code)}  total={_k(ctx_total)} tokens (~chars/4 est.)",
+        f"  graph cache: {cache_rate} ({stats.get('graph_cache_hits', 0)}/{total_cache})",
+        f"  embed cache skipped: notes={stats.get('embed_cache_notes', 0)} code={stats.get('embed_cache_code', 0)}",
+        f"  reindexes: {stats.get('reindex_count', 0)}",
+    ]
+    return "\n".join(lines)

cortex_local-2.2.1/cortex/core/graph.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+"""Graph module facade — re-exports all graph building and PPR utilities."""
+
+try:
+    from .code_graph import build_code_graph, compute_code_metadata, persist_code_graph  # noqa: F401
+    from .notes_graph import build_notes_graph, persist_notes_graph, ppr_augment  # noqa: F401
+    from .global_graph import build_global_graph  # noqa: F401
+except ImportError:
+    from code_graph import build_code_graph, compute_code_metadata, persist_code_graph  # noqa: F401
+    from notes_graph import build_notes_graph, persist_notes_graph, ppr_augment  # noqa: F401
+    from global_graph import build_global_graph  # noqa: F401

{cortex_local-2.1.16 → cortex_local-2.2.1}/cortex/indexer.py

@@ -4,6 +4,8 @@ import hashlib
 import re
 from pathlib import Path
 
+from tqdm import tqdm
+
 from qdrant_client import QdrantClient
 from qdrant_client.models import (
     Distance, FieldCondition, Filter, FilterSelector,
@@ -12,7 +14,7 @@ from qdrant_client.models import (
 
 from .config import qdrant_path, data_dir, cache_file, VECTOR_SIZE, migrate_legacy
 from .embedder import embed, sparse_embed
-from .core.chunker import chunk_file, CODE_EXTS, SKIP_DIRS
+from .core.chunker import chunk_file, CODE_EXTS, SKIP_DIRS, _is_excluded
 from .core.cache import load_cache, save_cache
 from .core import graph as _graph
 
@@ -110,8 +112,11 @@ 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:
+def index_notes(notes_dir: Path, show_progress: bool = False) -> int:
     """Index all .md files in notes_dir into the 'notes' collection. Returns chunk count."""
+    from .config import get_config
+    exclude_patterns = get_config()["index"]["exclude_patterns"]
+
     client = _qdrant()
     _ensure_collection(client, "notes")
     use_sparse = _sparse_available()
@@ -126,11 +131,19 @@ def index_notes(notes_dir: Path) -> int:
     total = 0
     cached = 0
 
-    for path in md_files:
+    for path in tqdm(md_files, desc="notes", disable=not show_progress):
         rel = str(path.relative_to(notes_dir))
+        if _is_excluded(rel, exclude_patterns):
+            continue
         mtime = path.stat().st_mtime
-        if cache.get(rel) == mtime:
-            new_cache[rel] = mtime
+        entry = cache.get(rel, {})
+        if entry.get("mtime") == mtime:
+            new_cache[rel] = entry
+            cached += 1
+            continue
+        content_hash = hashlib.sha1(path.read_bytes()).hexdigest()[:16]
+        if entry.get("hash") == content_hash:
+            new_cache[rel] = {"mtime": mtime, "hash": content_hash}
             cached += 1
             continue
         chunks = _chunk_markdown(path, notes_dir)
@@ -139,8 +152,9 @@ def index_notes(notes_dir: Path) -> int:
         if points:
             client.upsert("notes", points)
             total += len(points)
-            print(f"  {rel}: {len(points)} chunk(s)", flush=True)
-        new_cache[rel] = mtime
+            if not show_progress:
+                print(f"  {rel}: {len(points)} chunk(s)", flush=True)
+        new_cache[rel] = {"mtime": mtime, "hash": content_hash}
 
     save_cache("notes", new_cache, cache_file())
     print(f"Done. {total} chunks indexed, {cached}/{len(md_files)} files cached.", flush=True)
@@ -160,8 +174,11 @@ 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:
+def index_code(code_dir: Path, show_progress: bool = False) -> int:
     """Index all code files in code_dir into the 'code' collection. Returns chunk count."""
+    from .config import get_config
+    exclude_patterns = get_config()["index"]["exclude_patterns"]
+
     repo_name = code_dir.name
     client = _qdrant()
     _ensure_collection(client, "code")
@@ -171,6 +188,7 @@ def index_code(code_dir: Path) -> int:
         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)
+        and not _is_excluded(str(p.relative_to(code_dir)), exclude_patterns)
     ]
 
     cache = load_cache("code", cache_file())
@@ -181,13 +199,16 @@ def index_code(code_dir: Path) -> int:
     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)
-
+    for path in tqdm(code_files, desc=repo_name, disable=not show_progress):
         cache_key = f"{repo_name}/{str(path.relative_to(code_dir))}"
         mtime = path.stat().st_mtime
-        if cache.get(cache_key) == mtime:
+        entry = cache.get(cache_key, {})
+        if entry.get("mtime") == mtime:
+            cached += 1
+            continue
+        content_hash = hashlib.sha1(path.read_bytes()).hexdigest()[:16]
+        if entry.get("hash") == content_hash:
+            new_cache[cache_key] = {"mtime": mtime, "hash": content_hash}
             cached += 1
             continue
 
@@ -199,7 +220,7 @@ def index_code(code_dir: Path) -> int:
         if points:
             client.upsert("code", points)
             total += len(points)
-            new_cache[cache_key] = mtime
+            new_cache[cache_key] = {"mtime": mtime, "hash": content_hash}
 
     save_cache("code", new_cache, cache_file())
     print(f"  {repo_name}: {total} chunks from {len(code_files) - cached} files ({cached} cached)", flush=True)
@@ -233,7 +254,7 @@ def index_code(code_dir: Path) -> int:
     return total
 
 
-def index_path(path: Path) -> None:
+def index_path(path: Path, show_progress: bool = False) -> None:
     """Index a path — .md files as notes, code files as code."""
     path = path.resolve()
     data_dir().mkdir(parents=True, exist_ok=True)
@@ -245,11 +266,11 @@ def index_path(path: Path) -> None:
 
     if md_files:
         print(f"\nIndexing notes from {path} ({len(md_files)} .md files)...")
-        index_notes(path)
+        index_notes(path, show_progress=show_progress)
 
     if code_files:
         print(f"\nIndexing code from {path} ({len(code_files)} files)...")
-        index_code(path)
+        index_code(path, show_progress=show_progress)
 
     if not md_files and not code_files:
         print(f"No indexable files found in {path}")

{cortex_local-2.1.16 → cortex_local-2.2.1}/cortex/mcp_server.py

@@ -3,21 +3,22 @@
 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,
+    qdrant_path, data_dir, stats_file, VERSION, VECTOR_SIZE,
     WORKSPACES_DIR, get_active_workspace, set_active_workspace,
-    get_workspace_dir, PPR_THRESHOLD,
+    get_workspace_dir, PPR_THRESHOLD, get_config,
 )
 from .embedder import embed, sparse_embed
 from .state import _stats, get_graph_meta, save_stats, invalidate_graph_cache
 from .indexer import index_path
+from .core.formatters import format_notes_parts, format_code_results, fmt_stats
 
 mcp = FastMCP("cortex")
 
@@ -86,20 +87,7 @@ def _ppr_block(matched_files: list, matched_scores: list) -> str | 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
+def _search_notes(query: str, limit: int = 5):
     client = _qdrant()
     vector = embed(query)
     try:
@@ -117,37 +105,18 @@ def search_notes(query: str, limit: int = 5) -> str:
     except Exception:
         results = client.query_points("notes", query=vector, limit=limit, with_payload=True).points
     if not results:
-        return "No results found."
+        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)
-    _log_search("search_notes", query, [
-        {"file": f, "score": round(s, 3)} for f, s in zip(matched_files, matched_scores)
-    ])
+    parts, matched_files, matched_scores = format_notes_parts(results)
     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
-
+    return out, matched_files, matched_scores
 
-@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
+def _search_code(query: str, limit: int = 5):
     client = _qdrant()
     vector = embed(query)
     fetch_limit = min(limit * 3, 50)
@@ -166,7 +135,7 @@ def search_code(query: str, limit: int = 5) -> str:
     except Exception:
         results = client.query_points("code", query=vector, limit=fetch_limit, with_payload=True).points
     if not results:
-        return "No results found."
+        return "No results found.", []
     scored = []
     for r in results:
         p = r.payload
@@ -188,31 +157,64 @@ def search_code(query: str, limit: int = 5) -> str:
         if len(deduped) >= limit:
             break
     _stats["total_results_code"] += len(deduped)
-    _log_search("search_code", query, [
+    log_entries = [
         {"repo": r.payload.get("repo", ""), "file": r.payload.get("file", ""), "score": round(bs, 3)}
         for bs, r, _ in 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)
+    ]
+    out = format_code_results(deduped)
     _stats["context_tokens_code"] += len(out) // 4
+    return out, log_entries
+
+
+@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
+    out, matched_files, matched_scores = _search_notes(query, limit)
+    _log_search("search_notes", query, [
+        {"file": f, "score": round(s, 3)} for f, s in zip(matched_files, matched_scores)
+    ])
+    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
+    out, log_entries = _search_code(query, limit)
+    _log_search("search_code", query, log_entries)
     return out
 
 
+@mcp.tool()
+def search_all(query: str, limit: int = 5) -> str:
+    """Search both notes and code simultaneously.
+
+    Use when unsure whether the answer is in notes or code,
+    or when you want a combined view across both collections.
+    """
+    _stats["search_notes_calls"] += 1
+    _stats["search_code_calls"] += 1
+    notes_out, matched_files, matched_scores = _search_notes(query, limit)
+    code_out, log_entries = _search_code(query, limit)
+    _log_search("search_all", query, log_entries)
+    return f"## Notes\n\n{notes_out}\n\n## Code\n\n{code_out}"
+
+
 @mcp.tool()
 def reindex(path: str = "") -> str:
     """Re-index a path into the local Qdrant database.
@@ -253,44 +255,19 @@ def get_stats(all: bool = False) -> str:
     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 {}
+            sf = stats_file()
+            versions = json.loads(sf.read_text()).get("versions", {}) if sf.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)))
+            blocks.append(fmt_stats(v, versions[v], 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)
+    return fmt_stats(VERSION, _stats, current=True)
 
 
 @mcp.tool()
@@ -438,4 +415,10 @@ def list_workspaces() -> str:
 
 def run() -> None:
     """Entry point for stdio MCP server."""
+    cfg = get_config()
+    if cfg["watch"]["enabled"]:
+        last = cfg["index"].get("last_path", "")
+        if last and Path(last).exists():
+            from .watcher import CortexWatcher
+            CortexWatcher(Path(last), cfg["watch"]["debounce_seconds"]).start()
     mcp.run(transport="stdio")

cortex_local-2.2.1/cortex/watcher.py

@@ -0,0 +1,60 @@
+"""Debounced filesystem watcher for automatic reindex on file changes."""
+
+import threading
+from pathlib import Path
+
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler as _Handler
+
+    class CortexWatcher:
+        def __init__(self, path: Path, debounce: float = 2.0):
+            self._path = path
+            self._debounce = debounce
+            self._timer: threading.Timer | None = None
+            self._lock = threading.Lock()
+            self._observer = Observer()
+
+        def _schedule(self):
+            with self._lock:
+                if self._timer:
+                    self._timer.cancel()
+                self._timer = threading.Timer(self._debounce, self._fire)
+                self._timer.daemon = True
+                self._timer.start()
+
+        def _fire(self):
+            with self._lock:
+                self._timer = None
+            try:
+                from .indexer import index_path
+                index_path(self._path)
+            except Exception as e:
+                print(f"[watcher] reindex failed: {e}", flush=True)
+
+        def start(self):
+            handler = type("_H", (_Handler,), {
+                "on_any_event": lambda s, e: (
+                    None if e.is_directory or not str(e.src_path).endswith(".md")
+                    else self._schedule()
+                ),
+            })()
+            self._observer.schedule(handler, str(self._path), recursive=True)
+            self._observer.daemon = True
+            self._observer.start()
+            print(f"[cortex] watching {self._path} (debounce {self._debounce}s)", flush=True)
+
+        def stop(self):
+            self._observer.stop()
+            self._observer.join()
+
+except ImportError:
+    class CortexWatcher:  # type: ignore[no-redef]
+        def __init__(self, *args, **kwargs):
+            pass
+
+        def start(self):
+            print("[cortex] watchdog not installed — auto-reindex disabled", flush=True)
+
+        def stop(self):
+            pass

{cortex_local-2.1.16 → cortex_local-2.2.1}/pyproject.toml

@@ -14,11 +14,10 @@ dependencies = [
     "fastembed>=0.4.0",
     "click>=8.0.0",
     "networkx>=3.0",
+    "watchdog>=3.0",
+    "tqdm>=4.0",
 ]
 
-[project.optional-dependencies]
-legacy = ["numpy==1.26.4"]
-
 [project.scripts]
 cortex = "cortex.cli:cli"
 

cortex_local-2.1.16/cortex/core/cache.py

@@ -1,25 +0,0 @@
-#!/usr/bin/env python3
-"""Mtime-based embedding cache — skip re-embedding unchanged files on full reindex."""
-
-import json
-from pathlib import Path
-
-
-def load_cache(section: str, cache_file: Path) -> dict:
-    """Load {rel_path: mtime} for given section ('notes' or 'code')."""
-    try:
-        if cache_file.exists():
-            return json.loads(cache_file.read_text()).get(section, {})
-    except Exception:
-        pass
-    return {}
-
-
-def save_cache(section: str, data: dict, cache_file: Path) -> None:
-    """Persist updated cache section without touching other sections."""
-    try:
-        existing = json.loads(cache_file.read_text()) if cache_file.exists() else {}
-        existing[section] = data
-        cache_file.write_text(json.dumps(existing))
-    except Exception as e:
-        print(f"warn: cache save failed: {e}", flush=True)

cortex_local-2.1.16/cortex/core/graph.py

@@ -1,6 +0,0 @@
-#!/usr/bin/env python3
-"""Graph module facade — re-exports all graph building and PPR utilities."""
-
-from .code_graph import build_code_graph, compute_code_metadata, persist_code_graph  # noqa: F401
-from .notes_graph import build_notes_graph, persist_notes_graph, ppr_augment  # noqa: F401
-from .global_graph import build_global_graph  # noqa: F401