cerebro-code-memory 0.1.0__tar.gz → 0.2.0__tar.gz

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "cerebro",
       "source": "./plugin",
       "description": "MCP brain for codebases: caches structure + summaries so AI sessions query it instead of re-reading files. Bundles the MCP server, cerebro-first subagents, and session hooks.",
-      "version": "0.1.0"
+      "version": "0.2.0"
     }
   ]
 }

cerebro_code_memory-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via Trusted Publishing (OIDC) whenever a GitHub Release is
+# published. No API token needed — PyPI trusts this repo + workflow directly.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # REQUIRED for PyPI Trusted Publishing (OIDC token exchange)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: cerebro-code-memory
-Version: 0.1.0
+Version: 0.2.0
 Summary: Persistent code-knowledge memory across AI chat sessions (MCP server)
-Project-URL: Homepage, https://github.com/marcodavidd020/cerebro-mcp
-Project-URL: Repository, https://github.com/marcodavidd020/cerebro-mcp
-Project-URL: Issues, https://github.com/marcodavidd020/cerebro-mcp/issues
+Project-URL: Homepage, https://github.com/marcodavidd020/cerebro-code-memory
+Project-URL: Repository, https://github.com/marcodavidd020/cerebro-code-memory
+Project-URL: Issues, https://github.com/marcodavidd020/cerebro-code-memory/issues
 Author-email: Marco Toledo <huancacori@gmail.com>
 License: MIT
 License-File: LICENSE
@@ -72,12 +72,30 @@ Three layers of "traces", cheapest first:
 | `cerebro_callers(name)` | Call sites of a symbol (who calls it, with enclosing fn + line). |
 | `cerebro_calls(path)` | Internal functions a file calls (outgoing call edges). |
 
+## Install
+
+**One command** (published on PyPI) — add the MCP server to Claude Code:
+
+```bash
+claude mcp add cerebro -- uvx cerebro-code-memory
+```
+
+Or install the full **Claude Code plugin** (MCP server + session hooks + cerebro-first subagents):
+
+```
+/plugin marketplace add marcodavidd020/cerebro-code-memory
+/plugin install cerebro@cerebro
+```
+
+Requires Python ≥ 3.10. Point Cerebro at a repo with `CEREBRO_ROOT=/path/to/repo`; it
+also auto-detects the nearest ancestor `.cerebro/` brain (handy in monorepos).
+
 ## Quick start
 
 One command onboards any repo — it indexes and prints the exact registration line:
 
 ```bash
-uv tool install --from . cerebro          # installs the `cerebro` command globally
+uv tool install --from . cerebro          # installs the `cerebro` command globally (dev)
 cd /path/to/your/repo
 cerebro setup --summarize --embed          # index (+ warm summaries / semantic index), then prints next steps
 ```

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/README.md

@@ -50,12 +50,30 @@ Three layers of "traces", cheapest first:
 | `cerebro_callers(name)` | Call sites of a symbol (who calls it, with enclosing fn + line). |
 | `cerebro_calls(path)` | Internal functions a file calls (outgoing call edges). |
 
+## Install
+
+**One command** (published on PyPI) — add the MCP server to Claude Code:
+
+```bash
+claude mcp add cerebro -- uvx cerebro-code-memory
+```
+
+Or install the full **Claude Code plugin** (MCP server + session hooks + cerebro-first subagents):
+
+```
+/plugin marketplace add marcodavidd020/cerebro-code-memory
+/plugin install cerebro@cerebro
+```
+
+Requires Python ≥ 3.10. Point Cerebro at a repo with `CEREBRO_ROOT=/path/to/repo`; it
+also auto-detects the nearest ancestor `.cerebro/` brain (handy in monorepos).
+
 ## Quick start
 
 One command onboards any repo — it indexes and prints the exact registration line:
 
 ```bash
-uv tool install --from . cerebro          # installs the `cerebro` command globally
+uv tool install --from . cerebro          # installs the `cerebro` command globally (dev)
 cd /path/to/your/repo
 cerebro setup --summarize --embed          # index (+ warm summaries / semantic index), then prints next steps
 ```

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/plugin/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "name": "cerebro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Persistent code-knowledge memory: an MCP brain that caches a codebase's structure and summaries so AI sessions query it instead of re-reading files. Bundles the MCP server, cerebro-first subagents, and session hooks.",
-  "author": { "name": "Marco Toledo", "url": "https://github.com/marcodavidd020/cerebro-mcp" },
-  "homepage": "https://github.com/marcodavidd020/cerebro-mcp",
+  "author": { "name": "Marco Toledo", "url": "https://github.com/marcodavidd020/cerebro-code-memory" },
+  "homepage": "https://github.com/marcodavidd020/cerebro-code-memory",
   "license": "MIT",
   "mcpServers": "./.mcp.json",
   "hooks": "./hooks/hooks.json"

cerebro_code_memory-0.2.0/plugin/hooks/cerebro-first.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""PreToolUse nudge: enforce 'cerebro-first' the deterministic way.
+
+In a project that HAS a Cerebro brain, if the model reaches for raw code search
+(grep/rg/find, or the native Grep/Glob tools) before consulting Cerebro, block the
+call ONCE per session with a reminder to use cerebro_search / cerebro_get first
+(far cheaper in tokens). Strictly bounded:
+  - only where a `.cerebro/brain.db` exists upward from cwd,
+  - at most ONE nudge per session,
+  - never nudges once Cerebro has been used this session,
+  - the command is never permanently blocked: re-running it passes.
+
+Best-effort: any error → allow silently (a guardrail you trust beats one that
+gets in the way).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+STATE_DIR = Path(tempfile.gettempdir()) / "cerebro-hook-state"
+
+# Raw code-search tools Cerebro can usually answer cheaper. Kept narrow on purpose
+# (no cat/ls/head — too generic) to avoid noisy false nudges.
+_EXPLORE = re.compile(r"\b(grep|rg|find|ack|ag)\b")
+
+
+def find_brain(start: str):
+    try:
+        p = Path(start).resolve()
+    except Exception:
+        return None
+    p = p if p.is_dir() else p.parent
+    for d in (p, *p.parents):
+        if (d / ".cerebro" / "brain.db").exists():
+            return d
+    return None
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    tool = data.get("tool_name", "")
+    ti = data.get("tool_input", {}) or {}
+    sid = data.get("session_id") or "nosession"
+    cwd = data.get("cwd") or os.getcwd()
+
+    # Only act where Cerebro is actually set up.
+    if find_brain(cwd) is None:
+        sys.exit(0)
+
+    # Is this raw exploration?
+    if tool in ("Grep", "Glob"):
+        exploratory = True
+    elif tool == "Bash":
+        exploratory = bool(_EXPLORE.search(ti.get("command", "") or ""))
+    else:
+        exploratory = False
+    if not exploratory:
+        sys.exit(0)
+
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        sys.exit(0)
+    used = STATE_DIR / f"{sid}.cerebro-used"
+    nudged = STATE_DIR / f"{sid}.nudged"
+
+    # Already used Cerebro, or already nudged once → let it through.
+    if used.exists() or nudged.exists():
+        sys.exit(0)
+
+    try:
+        nudged.write_text("1")
+    except Exception:
+        pass
+
+    sys.stderr.write(
+        "💡 This project has a Cerebro brain — querying it is far cheaper than raw "
+        "search.\nBefore grep/find, try:\n"
+        "  • cerebro_search(\"<what you're looking for>\")  → locates code at path:line\n"
+        "  • cerebro_get(\"<path>\")  → a file's summary + symbols + deps, without reading it\n"
+        "One-time reminder. If Cerebro doesn't have what you need, just re-run your command.\n"
+    )
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

cerebro_code_memory-0.2.0/plugin/hooks/cerebro-mark-used.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""PostToolUse: record that Cerebro was used this session, so the cerebro-first
+nudge (cerebro-first.py) stays quiet for the rest of the session. Best-effort."""
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+STATE_DIR = Path(tempfile.gettempdir()) / "cerebro-hook-state"
+
+try:
+    data = json.load(sys.stdin)
+    sid = data.get("session_id") or "nosession"
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    (STATE_DIR / f"{sid}.cerebro-used").write_text("1")
+except Exception:
+    pass
+sys.exit(0)

cerebro_code_memory-0.2.0/plugin/hooks/cerebro-session-end.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""SessionEnd hook: auto-record.
+
+When CEREBRO_AUTORECORD=N (a positive int) is set, re-summarize up to N files whose
+cached summary went STALE during the session — so the NEXT session reuses fresh
+traces instead of re-reading the files you changed. Detached (never blocks exit)
+and OFF by default (it spends a little via `claude -p`; set the env var to opt in).
+Mirrors the spawn pattern of session_start.py's autosummarize.
+"""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def find_brain_root(start: str):
+    p = Path(start).resolve()
+    p = p if p.is_dir() else p.parent
+    for d in (p, *p.parents):
+        if (d / ".cerebro" / "brain.db").exists():
+            return d
+    return None
+
+
+def main() -> None:
+    n = os.environ.get("CEREBRO_AUTORECORD", "").strip()
+    if not (n.isdigit() and int(n) > 0):
+        return  # opt-in: set CEREBRO_AUTORECORD=N to enable
+
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        data = {}
+    cwd = data.get("cwd") or os.getcwd()
+    root = find_brain_root(cwd)
+    if root is None:
+        return  # not a Cerebro project
+
+    env = {**os.environ, "CEREBRO_ROOT": str(root)}
+    home = os.environ.get("CEREBRO_HOME")
+    uv = os.environ.get("CEREBRO_UV", "uv")
+    cmd = (
+        [uv, "run", "--directory", home, "cerebro", "summarize", "--stale", "--limit", n]
+        if home
+        else ["cerebro", "summarize", "--stale", "--limit", n]
+    )
+    try:
+        subprocess.Popen(
+            cmd, env=env,
+            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except Exception:
+        pass  # best-effort; never block session exit
+
+
+if __name__ == "__main__":
+    main()

cerebro_code_memory-0.2.0/plugin/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/cerebro-session-end.py"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/cerebro-first.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_edit.py"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/verify-edit.py"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__cerebro__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/cerebro-mark-used.py"
+          }
+        ]
+      }
+    ]
+  }
+}

cerebro_code_memory-0.2.0/plugin/hooks/verify-edit.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Hook determinista anti-alucinación.
+
+Tras cada Edit/Write/MultiEdit, verifica el archivo editado con las herramientas
+REALES disponibles (sintaxis + análisis). No puede alucinar: o el archivo pasa, o
+no. Si encuentra errores reales, escribe el detalle en stderr y sale con código 2,
+así Claude recibe el error y lo corrige (la edición YA se aplicó; esto no la borra).
+
+Filosofía: NUNCA bloquear por falta de tooling. Si una herramienta no está
+instalada o falla por motivos de entorno (no por el código), se salta en silencio.
+Un guardarraíl en el que se confía y queda encendido vale más que uno potente que
+se termina apagando por ruidoso.
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+import sys
+
+# Ubicaciones comunes de herramientas que el PATH con que Claude Code lanza los
+# hooks puede NO incluir (p.ej. ~/flutter/bin lo agrega .zshrc; node vive en nvm).
+# Sin esto, el hook se saltaría en silencio dart/node/ruff = falsa seguridad.
+_EXTRA_PATHS = [
+    os.path.expanduser("~/flutter/bin"),
+    os.path.expanduser("~/fvm/default/bin"),
+    os.path.expanduser("~/.pub-cache/bin"),
+    os.path.expanduser("~/.local/bin"),  # uv / uvx
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+] + sorted(glob.glob(os.path.expanduser("~/.nvm/versions/node/*/bin")), reverse=True)
+
+
+def _enriched_path():
+    extra = [p for p in _EXTRA_PATHS if os.path.isdir(p)]
+    return os.pathsep.join(extra + [os.environ.get("PATH", "")])
+
+
+def run(cmd, cwd=None, timeout=90):
+    """Devuelve (returncode, salida). returncode None = herramienta ausente/timeout.
+    Resuelve cmd[0] a ruta absoluta vía un PATH enriquecido para no depender del
+    PATH heredado (que al ejecutar hooks suele venir mínimo)."""
+    path = _enriched_path()
+    exe = shutil.which(cmd[0], path=path)
+    if exe is None:
+        return None, ""  # herramienta ausente -> saltar (nunca bloquear por tooling)
+    env = dict(os.environ)
+    env["PATH"] = path
+    try:
+        p = subprocess.run([exe] + cmd[1:], cwd=cwd, capture_output=True,
+                           text=True, timeout=timeout, env=env)
+        return p.returncode, (p.stdout + p.stderr).strip()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None, ""
+
+
+def find_up(start, name):
+    d = os.path.abspath(start)
+    while True:
+        if os.path.exists(os.path.join(d, name)):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+
+def check(path):
+    """Devuelve lista de mensajes de error (vacía = ok)."""
+    ext = os.path.splitext(path)[1].lower()
+    d = os.path.dirname(path)
+    errors = []
+
+    if ext in (".py", ".pyi"):
+        # 1) Sintaxis — stdlib, siempre disponible, cero falsos positivos.
+        rc, out = run([sys.executable, "-m", "py_compile", path])
+        if rc not in (0, None):
+            errors.append("SyntaxError (py_compile):\n" + out)
+        else:
+            # 2) Nombres indefinidos / imports rotos (lo que delata alucinaciones).
+            #    ruff vía uvx: rc==1 => hallazgos; rc None/2 => uv ausente o problema
+            #    de entorno (run() resuelve uvx por PATH enriquecido; si falta, salta).
+            rc, out = run([
+                "uvx", "ruff", "check", "--quiet", "--output-format", "concise",
+                "--select", "F821,F811,F823", path,
+            ], timeout=120)
+            if rc == 1 and ".py:" in out:
+                errors.append("ruff (nombres indefinidos / imports):\n" + out)
+
+    elif ext in (".js", ".jsx", ".mjs", ".cjs"):
+        rc, out = run(["node", "--check", path])
+        if rc not in (0, None):
+            errors.append("SyntaxError (node --check):\n" + out)
+
+    elif ext in (".ts", ".tsx"):
+        root = find_up(d, "node_modules")
+        eslint = os.path.join(root, "node_modules", ".bin", "eslint") if root else None
+        if eslint and os.path.exists(eslint):
+            rc, out = run([eslint, "--no-error-on-unmatched-pattern", path], cwd=root, timeout=120)
+            if rc == 1 and out:
+                errors.append("eslint:\n" + out)
+
+    elif ext == ".dart":
+        # --no-fatal-warnings: rc!=0 solo ante ERRORES reales (infos/warnings no bloquean;
+        # los infos ya son no-fatales por defecto). "Usage:" => error de CLI, no de código: saltar.
+        rc, out = run(["dart", "analyze", "--no-fatal-warnings", path], timeout=150)
+        if rc not in (0, None) and out and "Usage:" not in out:
+            errors.append("dart analyze:\n" + out)
+
+    return errors
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    ti = data.get("tool_input", {}) or {}
+    path = ti.get("file_path") or ti.get("path")
+    if not path or not os.path.isfile(path):
+        sys.exit(0)
+
+    errors = check(path)
+    if errors:
+        sys.stderr.write(
+            "⛔ Verificación determinista falló en " + path + ":\n\n"
+            + "\n\n".join(errors)
+            + "\n\nEstos son errores reales del código recién escrito. "
+            "Corrígelos antes de continuar.\n"
+        )
+        sys.exit(2)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cerebro-code-memory"
-version = "0.1.0"
+version = "0.2.0"
 description = "Persistent code-knowledge memory across AI chat sessions (MCP server)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,9 +28,9 @@ cerebro-graph = "cerebro.viz:graph_main"
 cerebro-export-obsidian = "cerebro.viz:obsidian_main"
 
 [project.urls]
-Homepage = "https://github.com/marcodavidd020/cerebro-mcp"
-Repository = "https://github.com/marcodavidd020/cerebro-mcp"
-Issues = "https://github.com/marcodavidd020/cerebro-mcp/issues"
+Homepage = "https://github.com/marcodavidd020/cerebro-code-memory"
+Repository = "https://github.com/marcodavidd020/cerebro-code-memory"
+Issues = "https://github.com/marcodavidd020/cerebro-code-memory/issues"
 
 [project.optional-dependencies]
 semantic = ["model2vec>=0.3", "numpy>=1.26"]

cerebro_code_memory-0.2.0/src/cerebro/apiroutes.py

@@ -0,0 +1,88 @@
+"""Backend HTTP endpoint extraction — slice 1 of API-call tracing (front↔back).
+
+Cerebro's import/call graphs miss the network boundary: a storefront calling a
+backend endpoint over HTTP is a real dependency invisible to `import` edges. This
+extracts the BACKEND side — the routes a server exposes — so a session can answer
+"where is POST /carts/lines handled?" cheaply, and so a later slice can match
+frontend HTTP calls to these routes (the actual HTTP_CALLS edges).
+
+v1 targets NestJS controllers (the Fenix backend): `@Controller('base')` plus the
+method decorators `@Get/@Post/@Put/@Patch/@Delete/@All`. Best-effort line scan —
+robust for the conventional one-controller-per-file layout. Read-only; computed on
+demand from `*.controller.ts` files (a small subset), so no schema change.
+"""
+from __future__ import annotations
+
+import re
+
+_CONTROLLER = re.compile(r"@Controller\(\s*['\"`]([^'\"`]*)['\"`]")
+_CONTROLLER_BARE = re.compile(r"@Controller\(\s*\)")
+_METHOD = re.compile(r"@(Get|Post|Put|Patch|Delete|All)\(\s*(?:['\"`]([^'\"`]*)['\"`])?")
+# A method declaration line: optional modifiers then `name(`. Used to attach a
+# handler name to the decorator above it.
+_HANDLER = re.compile(r"^\s*(?:public\s+|private\s+|protected\s+|async\s+|static\s+)*"
+                      r"([A-Za-z_]\w*)\s*\(")
+
+_HTTP = ("GET", "POST", "PUT", "PATCH", "DELETE", "ALL")
+
+
+def _join(base: str | None, path: str | None) -> str:
+    parts = [p.strip("/") for p in (base or "", path or "") if p and p.strip("/")]
+    return "/" + "/".join(parts)
+
+
+def extract_file(rel: str, text: str) -> list[dict]:
+    """Endpoints declared in one controller source. Each: method, path, file,
+    line, handler."""
+    base: str | None = None
+    out: list[dict] = []
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        mc = _CONTROLLER.search(line)
+        if mc:
+            base = mc.group(1)
+            continue
+        if _CONTROLLER_BARE.search(line):
+            base = ""
+            continue
+        mm = _METHOD.search(line)
+        if not mm:
+            continue
+        method = mm.group(1).upper()
+        path = mm.group(2) or ""
+        handler = None
+        for j in range(i + 1, min(i + 6, len(lines))):
+            stripped = lines[j].lstrip()
+            if stripped.startswith("@"):
+                continue  # another decorator (e.g. @UseGuards) — keep looking
+            mh = _HANDLER.match(lines[j])
+            if mh:
+                handler = mh.group(1)
+            break
+        out.append({"method": method, "path": _join(base, path),
+                    "file": rel, "line": i + 1, "handler": handler})
+    return out
+
+
+def find(config, conn, query: str = "") -> list[dict]:
+    """All backend endpoints (optionally filtered by `query`), across the indexed
+    NestJS controllers. Sorted by path then method."""
+    rows = conn.execute(
+        "SELECT path FROM files WHERE path LIKE '%.controller.ts' ORDER BY path"
+    ).fetchall()
+    eps: list[dict] = []
+    for r in rows:
+        rel = r["path"]
+        try:
+            text = (config.root / rel).read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        eps.extend(extract_file(rel, text))
+    if query:
+        q = query.lower()
+        eps = [
+            e for e in eps
+            if q in f"{e['method']} {e['path']} {e['handler'] or ''} {e['file']}".lower()
+        ]
+    eps.sort(key=lambda e: (e["path"], e["method"]))
+    return eps

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/src/cerebro/cli.py

@@ -93,6 +93,11 @@ def cmd_calls(args):
     print(_bind_server(config, conn).cerebro_calls(args.path))
 
 
+def cmd_endpoints(args):
+    config, conn = _ctx()
+    print(_bind_server(config, conn).cerebro_endpoints(" ".join(args.query)))
+
+
 def cmd_recall(args):
     from . import views
     config, conn = _ctx()
@@ -153,7 +158,13 @@ def cmd_obsidian(args):
 def cmd_summarize(args):
     from . import summarizer
     config, conn = _ctx()
-    rels = summarizer.select_central_missing(conn, args.limit, args.prefix)
+    if getattr(args, "stale", False):
+        rels = summarizer.select_stale(conn, args.limit, args.prefix)
+        seen = set(rels)
+        rels += [r for r in summarizer.select_central_missing(conn, args.limit - len(rels), args.prefix)
+                 if r not in seen]
+    else:
+        rels = summarizer.select_central_missing(conn, args.limit, args.prefix)
     print(json.dumps(summarizer.run(config, conn, rels, workers=args.workers)))
 
 
@@ -288,6 +299,7 @@ _COMMANDS = {
     "embed": cmd_embed, "impact": cmd_impact, "cycles": cmd_cycles, "orphans": cmd_orphans,
     "dead-symbols": cmd_orphans_symbols,
     "callers": cmd_callers, "calls": cmd_calls, "recall": cmd_recall,
+    "endpoints": cmd_endpoints,
 }
 
 
@@ -320,6 +332,7 @@ def _build_parser() -> argparse.ArgumentParser:
     s = sub.add_parser("obsidian", help="export an Obsidian vault"); s.add_argument("-o", "--out")
     s = sub.add_parser("summarize", help="warm summaries via claude -p")
     s.add_argument("--limit", type=int, default=20); s.add_argument("--prefix"); s.add_argument("--workers", type=int, default=4)
+    s.add_argument("--stale", action="store_true", help="also re-summarize stale summaries (edited files)")
     sub.add_parser("embed", help="build the semantic index (needs --extra semantic)")
     s = sub.add_parser("impact", help="transitive blast radius of a file"); s.add_argument("path")
     sub.add_parser("cycles", help="circular-import groups")
@@ -328,6 +341,7 @@ def _build_parser() -> argparse.ArgumentParser:
     s.add_argument("--prefix", default="")
     s = sub.add_parser("callers", help="call sites of a symbol"); s.add_argument("name")
     s = sub.add_parser("calls", help="internal calls a file makes"); s.add_argument("path")
+    s = sub.add_parser("endpoints", help="backend HTTP endpoints (NestJS routes)"); s.add_argument("query", nargs="*")
     s = sub.add_parser("recall", help="recall recorded decisions"); s.add_argument("query", nargs="*")
     return p
 

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/src/cerebro/server.py

@@ -13,7 +13,7 @@ from pathlib import Path
 from mcp.server.fastmcp import FastMCP
 
 from . import config as cfg
-from . import callgraph, db, embeddings, gitsync, graph, indexer, insights, notes, summaries, views
+from . import apiroutes, callgraph, db, embeddings, gitsync, graph, indexer, insights, notes, summaries, views
 
 mcp = FastMCP("cerebro")
 
@@ -357,6 +357,27 @@ def cerebro_dead_symbols(prefix: str = "") -> str:
     return "\n".join(out)
 
 
+@mcp.tool()
+def cerebro_endpoints(query: str = "") -> str:
+    """Backend HTTP endpoints (NestJS routes) the project exposes — the front↔back
+    boundary that `import` edges miss. Search by path / method / handler (e.g.
+    'POST carts', 'promotions', 'findActive') to answer 'where is this endpoint
+    handled?' without grepping decorators."""
+    config, conn = _ctx()
+    eps = apiroutes.find(config, conn, query)
+    if not eps:
+        scope = f" matching '{query}'" if query else ""
+        return f"No backend endpoints{scope} found (scans *.controller.ts NestJS routes)."
+    cap = 60
+    out = [f"{len(eps)} endpoint(s)" + (f" matching '{query}'" if query else "") + ":"]
+    for e in eps[:cap]:
+        h = f"  ({e['handler']})" if e["handler"] else ""
+        out.append(f"  {e['method']:6} {e['path']}  → {e['file']}:{e['line']}{h}")
+    if len(eps) > cap:
+        out.append(f"  … (+{len(eps) - cap} more)")
+    return "\n".join(out)
+
+
 def map_main():
     """`cerebro-map` entry point: print the project map (read-only). Used by the
     Claude Code session-start hook to inject the overview into a new session."""

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/src/cerebro/summarizer.py

@@ -67,6 +67,23 @@ def select_central_missing(conn, limit: int, prefix: str | None = None) -> list[
     return out
 
 
+def select_stale(conn, limit: int, prefix: str | None = None) -> list[str]:
+    """Files whose cached summary went STALE (source changed since it was written).
+    Re-warming these is the 'auto-record' path: edits during a session leave their
+    summaries outdated, and select_central_missing skips them (they HAVE a summary).
+    Bounded by `limit`."""
+    out = []
+    for path in summaries.stale_summaries(conn):
+        if cfg.Config.lang_for(path) is None:
+            continue
+        if prefix and not path.startswith(prefix):
+            continue
+        out.append(path)
+        if len(out) >= limit:
+            break
+    return out
+
+
 def run(config, conn, rels: list[str], model: str = DEFAULT_MODEL, workers: int = 4) -> dict:
     """Summarize files in parallel (claude -p subprocesses), then record serially
     (one sqlite writer). Returns a count of what was produced."""
@@ -91,11 +108,19 @@ def main():  # `cerebro-summarize` entry point
     ap.add_argument("--model", default=DEFAULT_MODEL)
     ap.add_argument("--prefix", default=None, help="only files under this path prefix")
     ap.add_argument("--workers", type=int, default=4)
+    ap.add_argument("--stale", action="store_true",
+                    help="re-summarize summaries gone stale (file changed), then fill with missing")
     args = ap.parse_args()
 
     config = cfg.Config.load()
     conn = db.connect(config.db_path)
-    rels = select_central_missing(conn, args.limit, args.prefix)
+    if args.stale:
+        rels = select_stale(conn, args.limit, args.prefix)
+        seen = set(rels)
+        rels += [r for r in select_central_missing(conn, args.limit - len(rels), args.prefix)
+                 if r not in seen]
+    else:
+        rels = select_central_missing(conn, args.limit, args.prefix)
     if not rels:
         print(json.dumps({"summarized": 0, "note": "nothing missing in scope"}))
         return

cerebro_code_memory-0.2.0/tests/test_apiroutes.py

@@ -0,0 +1,42 @@
+from cerebro import apiroutes
+
+SAMPLE = """
+@Controller('carts')
+export class CartController {
+  @Get()
+  findAll() {}
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {}
+
+  @Post('lines')
+  @UseGuards(AuthGuard)
+  async addLine(@Body() dto: Dto) {}
+
+  @Delete(':id')
+  remove(@Param('id') id: string) {}
+}
+"""
+
+
+def test_extract_nestjs_routes():
+    eps = apiroutes.extract_file("cart.controller.ts", SAMPLE)
+    by = {(e["method"], e["path"]): e for e in eps}
+    assert ("GET", "/carts") in by
+    assert ("GET", "/carts/:id") in by
+    assert ("POST", "/carts/lines") in by
+    assert ("DELETE", "/carts/:id") in by
+    # handler attaches to the method even past an intervening decorator
+    assert by[("POST", "/carts/lines")]["handler"] == "addLine"
+    assert by[("GET", "/carts")]["handler"] == "findAll"
+
+
+def test_bare_controller_and_empty_path():
+    eps = apiroutes.extract_file("x.controller.ts", "@Controller()\nclass X {\n  @Get()\n  ping() {}\n}\n")
+    assert eps == [
+        {"method": "GET", "path": "/", "file": "x.controller.ts", "line": 3, "handler": "ping"}
+    ]
+
+
+def test_no_controller_no_routes():
+    assert apiroutes.extract_file("plain.ts", "export const x = 1;\n") == []

{cerebro_code_memory-0.1.0 → cerebro_code_memory-0.2.0}/tests/test_summarizer.py

@@ -39,3 +39,27 @@ def test_run_records_generated_summaries(tmp_path, project, monkeypatch):
     res = summarizer.run(config, conn, ["a.py"], workers=1)
     assert res["summarized"] == 1
     assert summaries.get(conn, "a.py")["summary_en"] == "summary of a.py"
+
+
+def test_select_stale_finds_changed_summaries(tmp_path, project):
+    """A summary whose source file changed (edit + reindex) surfaces as a stale
+    candidate, so the SessionEnd auto-record can re-warm it."""
+    config, conn = project
+    write(tmp_path, "x.py", "def a():\n    return 1\n")
+    indexer.reindex(config, conn)
+    summaries.record(conn, "x.py", "does a")
+    assert summarizer.select_stale(conn, 10) == []  # fresh — not stale
+
+    write(tmp_path, "x.py", "def a():\n    return 2  # changed\n")
+    indexer.reindex(config, conn)
+    assert summarizer.select_stale(conn, 10) == ["x.py"]  # now stale
+
+
+def test_select_stale_skips_non_source(tmp_path, project):
+    config, conn = project
+    write(tmp_path, "README.md", "# hi\n")
+    indexer.reindex(config, conn)
+    summaries.record(conn, "README.md", "readme")
+    write(tmp_path, "README.md", "# hi changed\n")
+    indexer.reindex(config, conn)
+    assert summarizer.select_stale(conn, 10) == []  # .md has no language -> skipped

cerebro_code_memory-0.1.0/plugin/hooks/hooks.json

@@ -1,25 +0,0 @@
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post_edit.py"
-          }
-        ]
-      }
-    ]
-  }
-}