cerebro-code-memory 0.1.0__tar.gz

cerebro_code_memory-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "cerebro",
+  "owner": {
+    "name": "Marco Toledo",
+    "url": "https://github.com/marcodavidd020"
+  },
+  "plugins": [
+    {
+      "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"
+    }
+  ]
+}

cerebro_code_memory-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Cerebro brain (generated, per-repo)
+.cerebro/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# uv
+.python-version
+uv.lock

cerebro_code_memory-0.1.0/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md — Cerebro
+
+Estándares reales de este proyecto. Cárgalos antes de proponer o escribir código.
+Si algo aquí contradice al código actual, **gana el código**: verifícalo y actualiza este archivo.
+
+## Qué es
+MCP server en Python que cachea el *entendimiento* de un codebase en un SQLite ("brain")
+para que sesiones de chat lo **consulten** en vez de re-leer carpetas. La consigna de todo
+el proyecto: **salida token-barata**.
+
+## Stack (verificado en `pyproject.toml`)
+- Python **>=3.10**. Server con `FastMCP` (paquete `mcp>=1.2.0`).
+- Deps núcleo: `tree-sitter` + `tree-sitter-language-pack`, `networkx`, `pathspec`.
+- Semántica **opcional** detrás del extra `semantic`: `model2vec`, `numpy`. **Sin torch, sin API keys, nada sale de la máquina** — invariante de privacidad.
+- Tests: `pytest` (en `.venv`). Build: `hatchling`, paquete en `src/cerebro`.
+
+## Arquitectura (una responsabilidad por módulo, en `src/cerebro/`)
+- `server.py` — superficie de tools MCP (`@mcp.tool()`). Delgada: arma texto compacto y delega la lógica.
+- `cli.py` — entrypoint CLI unificado (`cerebro <subcomando>`).
+- `config.py` — `Config.load()`; resuelve raíz (`CEREBRO_ROOT` o git) y `db_path`.
+- `db.py` — conexión SQLite + queries de bajo nivel (módulo más central; casi todo depende de él).
+- `indexer.py` — parseo tree-sitter: símbolos, edges, hashes; `reindex`/`diff`.
+- `graph.py` — grafo de dependencias (`dependencies`/`dependents`) sobre networkx.
+- `insights.py` — `impact`, `cycles`, `orphans`, `dead_symbols`.
+- `callgraph.py` — `callers`/`calls` (resueltos por nombre).
+- `summaries.py` / `summarizer.py` — guardar/leer resúmenes; warming batch vía `claude -p` headless.
+- `embeddings.py` — búsqueda semántica model2vec (opcional).
+- `notes.py` — log de decisiones. `gitsync.py` — frescura git-aware. `tsconfig.py` — alias tsconfig/jsconfig.
+- `views.py` — render de texto (`map_text`, `recall_text`). `viz.py` — HTML del grafo + export Obsidian. `docaudit.py` — living docs.
+
+## Convenciones (observadas en el código, respétalas)
+- `from __future__ import annotations`; type hints modernos (`X | None`, no `Optional`).
+- Toda tool MCP devuelve **string compacto**. Acota listas con helpers tipo `_join_capped` y caps (`_DEP_CAP`, `_SYM_CAP`). No vuelques datos sin límite: el ahorro de tokens es el producto.
+- Docstrings explican el **porqué** (economía de tokens, invariantes), no lo obvio.
+- Rutas: **siempre** normaliza a clave repo-relativa con `_resolve_path` antes de tocar la DB. Saltarse esto rompe la persistencia entre sesiones.
+- Resúmenes y notas del brain se escriben **en inglés** (tokeniza más barato), densos, 1-3 frases.
+- Scripts CLI: cada uno expone un `main()` a nivel módulo (ver `[project.scripts]`).
+- Tests: fixtures de DB en memoria construyendo edges a mano (ver `tests/`).
+
+## Cómo agregar una tool MCP nueva (patrón completo)
+1. Lógica en el módulo de dominio que corresponda (no en `server.py`).
+2. `@mcp.tool()` en `server.py` que llama a esa lógica y arma el texto compacto.
+3. Subcomando equivalente en `cli.py`.
+4. Test en `tests/` con fixture en memoria.
+
+## Comandos
+- Tests: `uv run pytest`  (o `.venv/bin/pytest`).
+- Reindexar este propio repo: `uv run cerebro index`.
+- Lint: **no hay ruff/mypy configurados**. Si quieres lint puntual: `uvx ruff check src/`.
+
+## Qué NO hacer (guardarraíles anti-alucinación)
+- No inventes nombres de tools: el set canónico vive en `server.py` (`cerebro_*`).
+- No agregues dependencias a la ligera; lo pesado/opcional va detrás de un extra.
+- No engordes la salida de las tools ni te saltes los caps.
+- No escribas resúmenes/notas en español dentro del brain.
+- No accedas a la DB con una ruta cruda: pasa por `_resolve_path`.
+- No introduzcas torch, llamadas a APIs externas, ni nada que saque datos de la máquina.

cerebro_code_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Toledo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cerebro_code_memory-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: cerebro-code-memory
+Version: 0.1.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
+Author-email: Marco Toledo <huancacori@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: claude,code-intelligence,mcp,semantic-search,sqlite,tree-sitter
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: networkx>=3.2
+Requires-Dist: pathspec>=0.12
+Requires-Dist: tree-sitter-language-pack>=0.7
+Requires-Dist: tree-sitter>=0.23
+Provides-Extra: semantic
+Requires-Dist: model2vec>=0.3; extra == 'semantic'
+Requires-Dist: numpy>=1.26; extra == 'semantic'
+Description-Content-Type: text/markdown
+
+# Cerebro 🧠
+
+**Persistent code-knowledge memory across AI chat sessions.**
+
+Every new chat re-analyzes your project's folders from scratch to understand it,
+burning tokens re-discovering what a previous chat already learned. Cerebro caches
+the *understanding* — not just the files — in a small SQLite "brain" that lives
+**outside** the chat. New sessions **query** it instead of re-reading folders.
+
+Instead of reading 50 files (~100k tokens) to understand a project, the model makes
+one `cerebro_map()` call (~2-3k tokens) plus a few targeted lookups.
+
+## How it works
+
+Three layers of "traces", cheapest first:
+
+1. **Structural map** (free, no LLM) — `tree-sitter` extracts symbols + imports and
+   builds a dependency graph. Imports resolve both relative paths and **tsconfig /
+   jsconfig path aliases** (`@/...`), so Next.js / NestJS monorepos get real edges.
+   **PageRank** ranks the most important modules. Each file is hashed so changes
+   are detectable. Languages: Python, JavaScript / TypeScript (incl. JSX/TSX)
+   and Dart / Flutter.
+2. **Cached summaries** (the big saver) — as a chat understands a file, it calls
+   `cerebro_record(path, summary)` to store a 1-3 sentence **English** summary
+   (English tokenizes ~15-30% cheaper than Spanish). Future sessions reuse it.
+3. **Freshness** — each summary is tied to the file's hash. If the file changed,
+   the trace is flagged **stale** so only that file gets re-read.
+
+> Why not Dijkstra? Code knowledge is a *relevance* problem, not a shortest-path one.
+> The useful algorithms are graph traversal (BFS/DFS, for impact) and centrality
+> (PageRank, for ranking) — not weighted routing.
+
+## MCP tools
+
+| Tool | Purpose |
+|------|---------|
+| `cerebro_map(top=30)` | Cheap project overview, modules ranked by centrality. **Call first.** |
+| `cerebro_get(path)` | Summary + symbols + dependencies of a file, without reading it. |
+| `cerebro_search(query)` | Hybrid semantic + keyword search; semantic hits resolve to the exact symbol (`path:line`), not just the file. |
+| `cerebro_record(path, summary)` | Leave a trace: store your understanding of a file. |
+| `cerebro_note(content, topic?)` | Record a decision / domain rule / gotcha (the *why*). |
+| `cerebro_recall(query?)` | Recall decisions recorded by past sessions. |
+| `cerebro_stale()` | Files changed since last index + stale summaries. |
+| `cerebro_sync()` | Catch branch switch / git pull / external edits and reindex them. |
+| `cerebro_reindex(paths?)` | Refresh the structural index (only changed files). |
+| `cerebro_impact(path)` | Transitive blast radius: everything that (in)directly imports a file. |
+| `cerebro_cycles()` | Circular-import groups (architecture smell). |
+| `cerebro_orphans(prefix?)` | Code files nothing imports — dead-code candidates (file-level). |
+| `cerebro_dead_symbols(prefix?)` | Unused-export candidates: functions/classes/methods referenced nowhere *in their own project*, inside files that *are* imported (symbol-level dead code). |
+| `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). |
+
+## 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
+cd /path/to/your/repo
+cerebro setup --summarize --embed          # index (+ warm summaries / semantic index), then prints next steps
+```
+
+`cerebro setup` is idempotent. Then run the `claude mcp add …` line it prints, reload
+your editor, and the `cerebro_*` tools are available in chat.
+
+## Unified CLI
+
+```
+cerebro                 # no args -> MCP server (stdio); this is what the registration runs
+cerebro setup           # index this repo + print MCP registration
+cerebro index [--force] # build/refresh the index
+cerebro search <query>  # hybrid semantic + keyword search
+cerebro map             # project overview
+cerebro graph           # interactive dependency-graph HTML
+cerebro obsidian        # export an Obsidian vault
+cerebro summarize / embed
+cerebro impact / cycles / orphans / callers / calls / recall
+cerebro doc-audit <vault>   # living docs: flag knowledge notes whose referenced code changed
+```
+
+### Living documentation (`doc-audit`)
+
+`cerebro doc-audit <markdown-vault>` cross-checks a curated knowledge vault against
+the code index: it parses each note's code references (`path:line`, backticked
+symbols) and the note's `ultima_verificacion`/`fecha`, then flags notes whose
+referenced files **changed after** they were verified, **moved/were deleted**, or
+mention a **symbol that no longer exists**. `--aliases` maps wiki app names to repo
+dirs (`backend_app=fenix-store-backend,…`); `--fix` patches stale notes' frontmatter
+to `estado: revisar`. This is the bridge between an auto-fresh code index and a
+human-curated wiki — documentation that can't silently rot.
+
+`cerebro doc-refresh <note>` closes the loop: it re-audits one stale note against
+the *live* code and prints a briefing — current symbols, summary and dependents for
+each reference, plus the new location of any moved file — exactly the context an
+agent needs to propose the update (self-healing docs, human-reviewed).
+
+Without a global install, prefix any command with `uv run` (e.g. `uv run cerebro setup`).
+
+Point Cerebro at a specific repo with `CEREBRO_ROOT=/path/to/repo`. It honors
+`.gitignore` plus an optional **`.cerebroignore`** (same syntax) for excluding
+heavy non-source dirs (`backup/`, `**/uploads/`, …) without touching your VCS
+config. `node_modules/`, `.next/`, `dist/`, `build/` are ignored by default.
+
+Works on monorepos: index the whole thing at once (a single brain at the root,
+with cross-package alias resolution) or per sub-app (`CEREBRO_ROOT` per package).
+
+### Register with Claude Code
+
+```bash
+claude mcp add cerebro -- uv --directory /path/to/cerebro run cerebro
+```
+
+Set `CEREBRO_ROOT` to the project you want the brain to cover. See `plugin/` for the
+optional Claude Code plugin that auto-injects the map at session start and flags
+edited files as stale.
+
+## Scope (MVP) 
+
+In: structural map, cached summaries, freshness, keyword search, tsconfig/jsconfig
+alias resolution, `.cerebroignore`, batch summary warming (`cerebro-summarize`, via
+headless `claude -p` — no API key), a decision log (`cerebro_note` /
+`cerebro_recall`, surfaced at session start), and git-aware freshness
+(`cerebro_sync` catches branch switch / pull / external edits across nested repos),
+and optional local semantic search (`cerebro-embed` + `--extra semantic`: model2vec
+embeddings — one vector per symbol — no torch, no API key, nothing leaves the
+machine — `cerebro_search` becomes hybrid semantic + keyword and lands on the exact
+symbol (`path:line`), not just the file), and visualizations (`cerebro-graph` →
+self-contained interactive HTML dependency graph; `cerebro-export-obsidian` → an
+Obsidian vault where imports are `[[links]]`), and architecture insights
+(`cerebro_impact` transitive blast radius, `cerebro_cycles` circular imports,
+`cerebro_orphans` dead-code candidates), and a symbol-level call graph
+(`cerebro_callers` / `cerebro_calls`, tree-sitter name-resolved).
+Deferred to v2: a live file watcher, and LSP-backed call graph for type-precise
+resolution (the current call graph resolves by name).
+
+## License
+
+MIT © 2026 Marco Toledo — see [LICENSE](LICENSE).

cerebro_code_memory-0.1.0/README.md

@@ -0,0 +1,138 @@
+# Cerebro 🧠
+
+**Persistent code-knowledge memory across AI chat sessions.**
+
+Every new chat re-analyzes your project's folders from scratch to understand it,
+burning tokens re-discovering what a previous chat already learned. Cerebro caches
+the *understanding* — not just the files — in a small SQLite "brain" that lives
+**outside** the chat. New sessions **query** it instead of re-reading folders.
+
+Instead of reading 50 files (~100k tokens) to understand a project, the model makes
+one `cerebro_map()` call (~2-3k tokens) plus a few targeted lookups.
+
+## How it works
+
+Three layers of "traces", cheapest first:
+
+1. **Structural map** (free, no LLM) — `tree-sitter` extracts symbols + imports and
+   builds a dependency graph. Imports resolve both relative paths and **tsconfig /
+   jsconfig path aliases** (`@/...`), so Next.js / NestJS monorepos get real edges.
+   **PageRank** ranks the most important modules. Each file is hashed so changes
+   are detectable. Languages: Python, JavaScript / TypeScript (incl. JSX/TSX)
+   and Dart / Flutter.
+2. **Cached summaries** (the big saver) — as a chat understands a file, it calls
+   `cerebro_record(path, summary)` to store a 1-3 sentence **English** summary
+   (English tokenizes ~15-30% cheaper than Spanish). Future sessions reuse it.
+3. **Freshness** — each summary is tied to the file's hash. If the file changed,
+   the trace is flagged **stale** so only that file gets re-read.
+
+> Why not Dijkstra? Code knowledge is a *relevance* problem, not a shortest-path one.
+> The useful algorithms are graph traversal (BFS/DFS, for impact) and centrality
+> (PageRank, for ranking) — not weighted routing.
+
+## MCP tools
+
+| Tool | Purpose |
+|------|---------|
+| `cerebro_map(top=30)` | Cheap project overview, modules ranked by centrality. **Call first.** |
+| `cerebro_get(path)` | Summary + symbols + dependencies of a file, without reading it. |
+| `cerebro_search(query)` | Hybrid semantic + keyword search; semantic hits resolve to the exact symbol (`path:line`), not just the file. |
+| `cerebro_record(path, summary)` | Leave a trace: store your understanding of a file. |
+| `cerebro_note(content, topic?)` | Record a decision / domain rule / gotcha (the *why*). |
+| `cerebro_recall(query?)` | Recall decisions recorded by past sessions. |
+| `cerebro_stale()` | Files changed since last index + stale summaries. |
+| `cerebro_sync()` | Catch branch switch / git pull / external edits and reindex them. |
+| `cerebro_reindex(paths?)` | Refresh the structural index (only changed files). |
+| `cerebro_impact(path)` | Transitive blast radius: everything that (in)directly imports a file. |
+| `cerebro_cycles()` | Circular-import groups (architecture smell). |
+| `cerebro_orphans(prefix?)` | Code files nothing imports — dead-code candidates (file-level). |
+| `cerebro_dead_symbols(prefix?)` | Unused-export candidates: functions/classes/methods referenced nowhere *in their own project*, inside files that *are* imported (symbol-level dead code). |
+| `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). |
+
+## 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
+cd /path/to/your/repo
+cerebro setup --summarize --embed          # index (+ warm summaries / semantic index), then prints next steps
+```
+
+`cerebro setup` is idempotent. Then run the `claude mcp add …` line it prints, reload
+your editor, and the `cerebro_*` tools are available in chat.
+
+## Unified CLI
+
+```
+cerebro                 # no args -> MCP server (stdio); this is what the registration runs
+cerebro setup           # index this repo + print MCP registration
+cerebro index [--force] # build/refresh the index
+cerebro search <query>  # hybrid semantic + keyword search
+cerebro map             # project overview
+cerebro graph           # interactive dependency-graph HTML
+cerebro obsidian        # export an Obsidian vault
+cerebro summarize / embed
+cerebro impact / cycles / orphans / callers / calls / recall
+cerebro doc-audit <vault>   # living docs: flag knowledge notes whose referenced code changed
+```
+
+### Living documentation (`doc-audit`)
+
+`cerebro doc-audit <markdown-vault>` cross-checks a curated knowledge vault against
+the code index: it parses each note's code references (`path:line`, backticked
+symbols) and the note's `ultima_verificacion`/`fecha`, then flags notes whose
+referenced files **changed after** they were verified, **moved/were deleted**, or
+mention a **symbol that no longer exists**. `--aliases` maps wiki app names to repo
+dirs (`backend_app=fenix-store-backend,…`); `--fix` patches stale notes' frontmatter
+to `estado: revisar`. This is the bridge between an auto-fresh code index and a
+human-curated wiki — documentation that can't silently rot.
+
+`cerebro doc-refresh <note>` closes the loop: it re-audits one stale note against
+the *live* code and prints a briefing — current symbols, summary and dependents for
+each reference, plus the new location of any moved file — exactly the context an
+agent needs to propose the update (self-healing docs, human-reviewed).
+
+Without a global install, prefix any command with `uv run` (e.g. `uv run cerebro setup`).
+
+Point Cerebro at a specific repo with `CEREBRO_ROOT=/path/to/repo`. It honors
+`.gitignore` plus an optional **`.cerebroignore`** (same syntax) for excluding
+heavy non-source dirs (`backup/`, `**/uploads/`, …) without touching your VCS
+config. `node_modules/`, `.next/`, `dist/`, `build/` are ignored by default.
+
+Works on monorepos: index the whole thing at once (a single brain at the root,
+with cross-package alias resolution) or per sub-app (`CEREBRO_ROOT` per package).
+
+### Register with Claude Code
+
+```bash
+claude mcp add cerebro -- uv --directory /path/to/cerebro run cerebro
+```
+
+Set `CEREBRO_ROOT` to the project you want the brain to cover. See `plugin/` for the
+optional Claude Code plugin that auto-injects the map at session start and flags
+edited files as stale.
+
+## Scope (MVP) 
+
+In: structural map, cached summaries, freshness, keyword search, tsconfig/jsconfig
+alias resolution, `.cerebroignore`, batch summary warming (`cerebro-summarize`, via
+headless `claude -p` — no API key), a decision log (`cerebro_note` /
+`cerebro_recall`, surfaced at session start), and git-aware freshness
+(`cerebro_sync` catches branch switch / pull / external edits across nested repos),
+and optional local semantic search (`cerebro-embed` + `--extra semantic`: model2vec
+embeddings — one vector per symbol — no torch, no API key, nothing leaves the
+machine — `cerebro_search` becomes hybrid semantic + keyword and lands on the exact
+symbol (`path:line`), not just the file), and visualizations (`cerebro-graph` →
+self-contained interactive HTML dependency graph; `cerebro-export-obsidian` → an
+Obsidian vault where imports are `[[links]]`), and architecture insights
+(`cerebro_impact` transitive blast radius, `cerebro_cycles` circular imports,
+`cerebro_orphans` dead-code candidates), and a symbol-level call graph
+(`cerebro_callers` / `cerebro_calls`, tree-sitter name-resolved).
+Deferred to v2: a live file watcher, and LSP-backed call graph for type-precise
+resolution (the current call graph resolves by name).
+
+## License
+
+MIT © 2026 Marco Toledo — see [LICENSE](LICENSE).

cerebro_code_memory-0.1.0/USAGE.md

@@ -0,0 +1,58 @@
+# Cerebro — daily driver
+
+How to actually use it day to day. Set up once, then it mostly runs itself.
+
+## Once per repo
+
+```bash
+uv tool install --from ~/Proyectos/cerebro cerebro     # one time, global `cerebro`
+cd /your/repo
+cerebro setup --summarize --embed                       # index + warm summaries + semantic index
+# then run the `claude mcp add …` line it prints, and reload your editor
+```
+
+Hooks live in `~/.claude/settings.json` (SessionStart injects the map; PostToolUse keeps
+the index fresh). The skill in `~/.claude/skills/cerebro/` tells the model to use it.
+
+## Day to day (mostly automatic)
+
+- **New chat** → the map + recorded decisions are injected automatically. Just work.
+- **You edit a file** → it reindexes that file (~0.3s). Nothing to do.
+- **The model** queries `cerebro_*` instead of grepping; it records summaries/decisions as it learns.
+
+You only reach for commands when you want something specific:
+
+| Want | Command (or just ask the model) |
+|---|---|
+| Find code by intent | `cerebro search "where do we validate stock at checkout?"` |
+| Understand a file w/o reading it | `cerebro_get <path>` (in chat) |
+| Blast radius before a change | `cerebro impact <path>` |
+| Who calls this | `cerebro callers <name>` |
+| Architecture smells | `cerebro cycles` · `cerebro orphans` (dead files) · `cerebro dead-symbols` (unused exports) |
+| See the whole project | `cerebro graph` → one HTML graph; `cerebro graph-all` regenerates the scoped graphs declared in `.cerebro/graphs.toml` |
+| Browse as a wiki | `cerebro obsidian` → open the vault in Obsidian |
+
+## Keep it warm (on demand, not scheduled)
+
+```bash
+cerebro index --force          # re-extract everything (after an extractor upgrade)
+cerebro summarize --limit 50   # more cached summaries (uses claude -p, no API key)
+cerebro embed                  # refresh the semantic index after summaries change
+```
+
+Optional: set `CEREBRO_AUTOSUMMARIZE=N` in your environment to let the SessionStart
+hook warm the `N` most-central un-summarized files in the background each session
+(detached, non-blocking). **Off by default** — it spends tokens via `claude -p`, so
+opt in deliberately. Coverage then grows on its own as you work.
+
+## Living docs (if you keep a markdown knowledge vault)
+
+```bash
+cerebro doc-audit  <vault> --aliases "backend_app=fenix-store-backend,…"   # flag stale notes
+cerebro doc-refresh <note>                                                  # re-audit one note vs live code
+```
+
+## Rule of thumb
+
+Don't babysit it. Use it for real work; if something feels slow or wrong, *measure it*
+(`cerebro <cmd>` timings) and fix that specific thing — not everything.

cerebro_code_memory-0.1.0/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "cerebro",
+  "version": "0.1.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",
+  "license": "MIT",
+  "mcpServers": "./.mcp.json",
+  "hooks": "./hooks/hooks.json"
+}

cerebro_code_memory-0.1.0/plugin/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cerebro": {
+      "command": "uvx",
+      "args": ["cerebro-code-memory"]
+    }
+  }
+}

cerebro_code_memory-0.1.0/plugin/agents/cerebro-architect.md

@@ -0,0 +1,46 @@
+---
+name: cerebro-architect
+description: >-
+  Use BEFORE writing code for a feature or a new project — this is the design gate
+  that prevents hallucinated work. It (1) grounds itself in the project's REAL
+  standards (CLAUDE.md + Cerebro), (2) asks you in detail what functionality to
+  include/design, and (3) returns a grounded spec/plan to approve. It does NOT write
+  implementation code. Triggers (es): "quiero hacer/diseñar un proyecto/feature",
+  "cómo deberíamos implementar X", "antes de codear planéame esto".
+tools: mcp__cerebro__cerebro_map, mcp__cerebro__cerebro_search, mcp__cerebro__cerebro_get, mcp__cerebro__cerebro_recall, mcp__cerebro__cerebro_impact, mcp__cerebro__cerebro_callers, mcp__cerebro__cerebro_calls, mcp__cerebro__cerebro_cycles, mcp__cerebro__cerebro_orphans, mcp__cerebro__cerebro_dead_symbols, AskUserQuestion, Read, Grep, Glob, Write
+---
+
+Eres el **Arquitecto Cerebro**: el portón de diseño que evita que se programe sobre alucinaciones. Diseñas y preguntas; **no escribes código de implementación** (solo documentos de plan/estándares). No entregas nada para implementar hasta que el usuario apruebe.
+
+## Regla anti-alucinación (la más importante)
+**Citar o callar.** Toda afirmación sobre cómo funciona el proyecto debe venir con evidencia `path:line` obtenida de Cerebro o de leer el archivo. Distingue SIEMPRE:
+- ✅ "El proyecto ya hace X (verificado en `path:line`)"
+- 💡 "Propongo X (nuevo, no existe aún)"
+- ❓ "No sé / hay que verificar" — nunca lo rellenes con una suposición.
+Si no puedes verificar algo, dilo explícitamente. Prefiere "no estoy seguro" antes que inventar una API, un patrón o una ruta.
+
+## Modo A — Feature en proyecto existente
+1. Lee `CLAUDE.md` del proyecto si existe (estándares oficiales).
+2. Aterriza en lo real: `cerebro_map` (módulos centrales), `cerebro_search`/`cerebro_get` para los archivos que tocaría la feature, `cerebro_recall` para el *porqué* de decisiones previas.
+3. Detecta los patrones REALES en uso (naming, capas, manejo de errores, estilo de tests) leyendo 1-2 archivos análogos al que vas a crear. No asumas patrones de "buenas prácticas genéricas": usa los del proyecto.
+4. Mide el impacto: `cerebro_impact`/`cerebro_callers` sobre lo que cambiarías.
+
+## Modo B — Proyecto nuevo (entrevista de requisitos)
+Pregunta en detalle ANTES de proponer nada. Usa `AskUserQuestion` (o, si no está disponible, termina tu salida con una lista numerada "❓ Necesito que respondas"). Cubre:
+- **Funcionalidad**: qué debe hacer, casos de uso concretos, qué queda FUERA de alcance (no-goals).
+- **Stack y restricciones**: lenguaje/framework, dónde corre, dependencias permitidas/prohibidas.
+- **Datos**: qué se persiste, integraciones externas.
+- **Calidad**: tests esperados, performance, seguridad.
+No avances a diseño con huecos: si algo es ambiguo, pregúntalo.
+
+## Entrega (spec aterrizada, para aprobar)
+Devuelve un documento conciso con:
+1. **Requisitos confirmados** (lo que el usuario respondió).
+2. **Estándares aplicables** del proyecto, citados (`path:line` o `CLAUDE.md`).
+3. **Diseño propuesto**: archivos a crear/tocar, símbolos, capas; marca claramente lo ✅existente vs lo 💡nuevo.
+4. **Riesgos / blast-radius** (de `cerebro_impact`).
+5. **Plan de verificación**: qué tests/lint correr.
+6. **❓ Preguntas abiertas** que faltan resolver.
+7. Termina con: *"¿Apruebas este plan? Al confirmar, pásalo a cerebro-implementer."*
+
+Para proyecto nuevo puedes usar `Write` para crear un `SPEC.md` y un `CLAUDE.md` inicial de estándares — nunca código fuente.

cerebro_code_memory-0.1.0/plugin/agents/cerebro-explorer.md

@@ -0,0 +1,28 @@
+---
+name: cerebro-explorer
+description: >-
+  Use to ANSWER questions about an existing codebase — "where is X?", "how does Y
+  work?", "what depends on Z?", "explain this module or flow" — WITHOUT spending
+  tokens re-reading folders. Read-only navigator that queries the Cerebro brain
+  first and only opens files when the brain has no/stale info. Use PROACTIVELY
+  whenever a task begins by needing to understand the code. Triggers (es):
+  "¿dónde se valida el pago?", "explícame el flujo de checkout", "qué hace este módulo".
+tools: mcp__cerebro__cerebro_map, mcp__cerebro__cerebro_search, mcp__cerebro__cerebro_get, mcp__cerebro__cerebro_recall, mcp__cerebro__cerebro_impact, mcp__cerebro__cerebro_callers, mcp__cerebro__cerebro_calls, mcp__cerebro__cerebro_cycles, mcp__cerebro__cerebro_orphans, mcp__cerebro__cerebro_dead_symbols, mcp__cerebro__cerebro_stale, Read, Grep, Glob
+model: sonnet
+---
+
+Eres el **Explorador Cerebro**: encuentras y explicas código gastando el mínimo de tokens. Regla de oro: **nunca leas un archivo que Cerebro ya puede describirte.**
+
+## Orden de operaciones (barato → caro)
+1. `cerebro_map()` — panorama del proyecto y módulos más centrales. Úsalo si aún no conoces el repo.
+2. `cerebro_search(query)` — para localizar dónde vive algo; devuelve el `path:line` del símbolo exacto. Frasea la búsqueda en lenguaje natural.
+3. `cerebro_get(path)` — resumen + símbolos + dependencias de un archivo SIN abrirlo.
+4. `cerebro_recall(query)` — el *porqué* (decisiones/reglas/gotchas) antes de re-deducirlo.
+5. `cerebro_impact` / `cerebro_callers` / `cerebro_calls` / `cerebro_cycles` — relaciones entre archivos y símbolos.
+6. **Solo si** `cerebro_get` dice "no summary" o marca "⚠ STALE", o necesitas el detalle exacto de la implementación → recién ahí `Read` (de preferencia con offset/limit sobre la zona relevante), `Grep`, `Glob`.
+
+## Reglas
+- Eres **read-only**: no editas ni ejecutas nada. Si la tarea requiere cambios, dilo y entrega el contexto para que otro agente lo implemente.
+- Responde con rutas `path:line` clicables y citas mínimas; nunca vuelques archivos enteros.
+- Si el índice está vacío o desactualizado, dilo explícitamente y sugiere `cerebro_reindex` / `cerebro_sync`.
+- Entrega final: respuesta directa + lista de archivos/símbolos clave + (si aplica) qué conviene leer en detalle y por qué.

cerebro_code_memory-0.1.0/plugin/agents/cerebro-impact-analyst.md

@@ -0,0 +1,27 @@
+---
+name: cerebro-impact-analyst
+description: >-
+  Use BEFORE a refactor or risky change to assess blast radius and architectural
+  health, or to audit dead code and circular dependencies. Read-only. Answers
+  "what breaks if I change X?", "is this safe to delete?", "where are the import
+  cycles?", "which modules are most fragile?". Triggers (es): "qué riesgo tiene
+  refactorizar AuthService", "hay imports circulares", "qué código está muerto en pagos".
+tools: mcp__cerebro__cerebro_map, mcp__cerebro__cerebro_search, mcp__cerebro__cerebro_get, mcp__cerebro__cerebro_impact, mcp__cerebro__cerebro_cycles, mcp__cerebro__cerebro_callers, mcp__cerebro__cerebro_calls, mcp__cerebro__cerebro_orphans, mcp__cerebro__cerebro_dead_symbols, mcp__cerebro__cerebro_recall, Read, Grep, Glob
+---
+
+Eres el **Analista de Impacto Cerebro**: das un veredicto de riesgo ANTES de tocar código, apoyándote en el grafo de dependencias. Eres **read-only**.
+
+## Qué corres según la pregunta
+- **"¿Qué se rompe si cambio X?"** → `cerebro_impact(path)` (radio transitivo) + `cerebro_callers(symbol)` (call sites exactos con `path:line`).
+- **"¿Es seguro borrar esto?"** → `cerebro_orphans(prefix)` (archivos que nadie importa) + `cerebro_dead_symbols(prefix)` (exports sin uso). Advierte SIEMPRE que son heurísticos: acceso dinámico, reflexión o DI por string pueden ocultar un uso real.
+- **"¿Salud arquitectónica?"** → `cerebro_cycles()` (imports circulares) + `cerebro_map()` (los módulos más centrales son los más frágiles de tocar).
+- **"¿Por qué está así?"** → `cerebro_recall(query)` antes de asumir intención.
+
+## Entrega
+Un **veredicto accionable**, no un volcado de datos:
+- Nivel de riesgo (bajo / medio / alto) y la razón concreta.
+- Lista priorizada de archivos/símbolos a tocar o revisar, con `path:line`.
+- Orden de cambios sugerido para minimizar rotura.
+- Verificaciones recomendadas (qué tests correr, qué importadores revisar).
+
+No edites nada. Entregas el plan; el implementador ejecuta.

cerebro_code_memory-0.1.0/plugin/agents/cerebro-implementer.md

@@ -0,0 +1,28 @@
+---
+name: cerebro-implementer
+description: >-
+  Use to IMPLEMENT a focused code change — fix a bug, add a small feature, refactor
+  a function — once the goal is clear. Rebuilds context cheaply via Cerebro before
+  editing, makes surgical changes that match surrounding code, verifies, then records
+  what it learned and decided back into the brain. Triggers (es): "arregla el bug de
+  stock en checkout", "agrega validación de email al registro", "refactoriza esta función".
+tools: mcp__cerebro__cerebro_map, mcp__cerebro__cerebro_search, mcp__cerebro__cerebro_get, mcp__cerebro__cerebro_recall, mcp__cerebro__cerebro_record, mcp__cerebro__cerebro_note, mcp__cerebro__cerebro_impact, mcp__cerebro__cerebro_callers, mcp__cerebro__cerebro_calls, mcp__cerebro__cerebro_reindex, mcp__cerebro__cerebro_sync, mcp__cerebro__cerebro_stale, Read, Edit, Write, Bash, Grep, Glob, TodoWrite
+---
+
+Eres el **Implementador Cerebro**: haces cambios de código quirúrgicos y dejas el brain más inteligente de como lo encontraste.
+
+## Flujo
+1. **Entiende barato primero.** `cerebro_get` / `cerebro_search` / `cerebro_recall` para reconstruir contexto. Lee archivos completos solo si el resumen falta o está STALE.
+2. **Mide antes de tocar.** Si el archivo es central, `cerebro_impact(path)` y `cerebro_callers(symbol)` para saber qué podrías romper.
+3. **Cambia lo mínimo.** Edits quirúrgicos que imitan el estilo del código vecino (naming, densidad de comentarios, idioma). No reescribas de más ni agregues dependencias sin necesidad.
+4. **Verifica de verdad.** Corre los tests/linters del proyecto vía Bash si existen. Reporta resultados reales; si algo falla, dilo con el output, no lo ocultes.
+5. **Deja traza (esto es lo que ahorra tokens en el futuro):**
+   - `cerebro_record(path, "<1-3 frases densas en INGLÉS>")` por cada archivo que tocaste o entendiste a fondo.
+   - `cerebro_note(content, topic)` para cualquier decisión/regla/gotcha no obvio.
+   - `cerebro_reindex(paths)` si agregaste/renombraste símbolos o archivos.
+
+## Reglas
+- No hagas `git commit` ni `push` salvo que te lo pidan explícitamente.
+- Si la tarea es ambigua o el blast-radius es grande, detente y reporta antes de hacer cambios extensos.
+- Los resúmenes de `cerebro_record` van SIEMPRE en inglés (así los indexa el brain y tokenizan más barato).
+- Entrega final: qué cambiaste y por qué, resultado de la verificación, y qué registraste en el brain.