cerebro-code-memory 0.1.0__py3-none-any.whl

cerebro/viz.py

@@ -0,0 +1,374 @@
+"""Visualizations built from the brain: a self-contained interactive HTML
+dependency graph, and an Obsidian vault (one note per file, imports as [[links]]).
+
+Both read only the existing index — no new analysis. The HTML graph defaults to the
+most central files so it stays responsive on large repos; the Obsidian export writes
+every indexed file so its graph view is complete.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from . import config as cfg
+from . import db
+from . import graph as graphmod
+
+
+def _select(conn, limit: int | None, prefix: str | None):
+    from . import insights
+
+    ranked = graphmod.rank(conn)  # [(path, score)] desc
+    scores = dict(ranked)
+    in_scope = [p for p, _ in ranked if not prefix or p.startswith(prefix)]
+    files = in_scope[:limit] if limit else list(in_scope)
+    keep = set(files)
+    # Orphans (in_degree 0) rank lowest by centrality, so the top-N cut drops every
+    # one of them — leaving the "Orphans" overlay with nothing to highlight. Pull
+    # the overlay nodes (orphans + cycle members, within scope) in explicitly so
+    # both buttons actually do something.
+    scope = set(in_scope)
+    highlight = (set(insights.orphans(conn, prefix)["dead"]) | insights.cycle_members(conn)) & scope
+    files += [f for f in in_scope if f in highlight and f not in keep]
+    keep = set(files)
+    edges = [
+        (r["src_path"], r["dst_path"])
+        for r in conn.execute("SELECT src_path, dst_path FROM edges")
+        if r["src_path"] in keep and r["dst_path"] in keep
+    ]
+    return files, scores, edges
+
+
+def graph_html(conn, limit: int = 400, prefix: str | None = None) -> str:
+    from . import insights
+
+    files, scores, edges = _select(conn, limit, prefix)
+    summ = {
+        r["path"]: r["summary_en"]
+        for r in conn.execute("SELECT path, summary_en FROM summaries")
+    }
+    orphan_set = set(insights.orphans(conn).get("dead", []))
+    cycle_set = insights.cycle_members(conn)
+    nodes = []
+    for p in files:
+        nodes.append(
+            {
+                "id": p,
+                "label": p.split("/")[-1],
+                "group": p.split("/", 1)[0],
+                "value": round(scores.get(p, 0.0) * 1000, 3) + 1,
+                "score": round(scores.get(p, 0.0), 5),
+                "summary": summ.get(p, ""),
+                "orphan": p in orphan_set,
+                "cycle": p in cycle_set,
+            }
+        )
+    data = {"nodes": nodes, "edges": [{"from": s, "to": d} for s, d in edges]}
+    total = conn.execute("SELECT COUNT(*) AS n FROM files WHERE lang IS NOT NULL").fetchone()["n"]
+    meta = {
+        "shown": len(files),
+        "total": total,
+        "prefix": prefix or "",
+        "orphans": sum(1 for p in files if p in orphan_set),
+        "cycles": sum(1 for p in files if p in cycle_set),
+    }
+    return _TEMPLATE.replace("__DATA__", json.dumps(data)).replace(
+        "__META__", json.dumps(meta)
+    )
+
+
+def export_obsidian(config, conn, out_dir: Path) -> dict:
+    out = Path(out_dir)
+    ranked = dict(graphmod.rank(conn))
+    summ = {
+        r["path"]: r["summary_en"]
+        for r in conn.execute("SELECT path, summary_en FROM summaries")
+    }
+    deps_by: dict[str, list[str]] = {}
+    for r in conn.execute("SELECT src_path, dst_path FROM edges"):
+        deps_by.setdefault(r["src_path"], []).append(r["dst_path"])
+
+    files = [
+        r["path"] for r in conn.execute("SELECT path FROM files WHERE lang IS NOT NULL")
+    ]
+    count = 0
+    for p in files:
+        pkg = p.split("/", 1)[0]
+        lang = config.lang_for(p) or "other"
+        lines = [
+            "---",
+            f"tags: [{pkg}, {lang}]",
+            f"centrality: {ranked.get(p, 0.0):.4f}",
+            "---",
+            "",
+            f"`{p}`",
+            "",
+            summ.get(p) or "_No summary yet — run cerebro-summarize._",
+            "",
+        ]
+        syms = db.symbols_for(conn, p)
+        if syms:
+            lines.append("## Symbols")
+            lines += [f"- L{s['line']} {s['kind']} `{s['name']}`" for s in syms[:60]]
+            lines.append("")
+        deps = sorted(set(deps_by.get(p, [])))
+        if deps:
+            lines.append("## Imports (depends on)")
+            lines += [f"- [[{d}]]" for d in deps]
+        note = out / (p + ".md")
+        note.parent.mkdir(parents=True, exist_ok=True)
+        note.write_text("\n".join(lines), encoding="utf-8")
+        count += 1
+    return {"notes": count, "vault": str(out)}
+
+
+# --- CLI entry points --------------------------------------------------------
+
+def graph_main():
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Write an interactive dependency graph HTML")
+    ap.add_argument("--limit", type=int, default=400, help="max nodes (by centrality)")
+    ap.add_argument("--prefix", default=None, help="only files under this path prefix")
+    ap.add_argument("-o", "--out", default=None)
+    args = ap.parse_args()
+    config = cfg.Config.load()
+    conn = db.connect(config.db_path)
+    out = Path(args.out) if args.out else config.db_path.parent / "cerebro-graph.html"
+    out.write_text(graph_html(conn, args.limit, args.prefix), encoding="utf-8")
+    print(json.dumps({"html": str(out), "open_with": f"open '{out}'"}))
+
+
+def obsidian_main():
+    import argparse
+
+    ap = argparse.ArgumentParser(description="Export an Obsidian vault of the codebase")
+    ap.add_argument("-o", "--out", default=None)
+    args = ap.parse_args()
+    config = cfg.Config.load()
+    conn = db.connect(config.db_path)
+    out = Path(args.out) if args.out else config.db_path.parent / "vault"
+    result = export_obsidian(config, conn, out)
+    result["open"] = "Open this folder as a vault in Obsidian"
+    print(json.dumps(result))
+
+
+_TEMPLATE = r"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Cerebro · dependency graph</title>
+<script src="https://unpkg.com/force-graph"></script>
+<style>
+  :root{
+    --bg:#0d1117; --surface:#161b22; --surface2:#1c2230; --border:#30363d;
+    --text:#e6edf3; --muted:#7d8590; --accent:#4c8dff; --radius:10px;
+    --font: ui-sans-serif,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+    --mono: ui-monospace,SFMono-Regular,"SF Mono",Menlo,monospace;
+  }
+  *{box-sizing:border-box}
+  html,body{margin:0;height:100%}
+  body{background:var(--bg);color:var(--text);font-family:var(--font);font-size:13px;overflow:hidden}
+  #app{display:flex;height:100vh}
+  #side{width:330px;flex:none;background:var(--surface);border-right:1px solid var(--border);
+        display:flex;flex-direction:column;overflow:hidden}
+  .brand{display:flex;align-items:baseline;gap:8px;padding:16px 16px 4px}
+  .brand b{font-size:15px;font-weight:650;letter-spacing:.2px}
+  .brand span{color:var(--muted);font-size:11px}
+  #meta{padding:0 16px 12px;color:var(--muted);font-size:11.5px}
+  .sec{padding:12px 16px;border-top:1px solid var(--border)}
+  .sec.grow{flex:1;overflow:auto}
+  .lbl{font-size:10px;letter-spacing:.08em;text-transform:uppercase;color:var(--muted);margin-bottom:8px}
+  #search{width:100%;padding:9px 11px;border-radius:var(--radius);border:1px solid var(--border);
+          background:var(--bg);color:var(--text);font-size:12.5px;outline:none}
+  #search:focus{border-color:var(--accent);box-shadow:0 0 0 3px rgba(76,141,255,.15)}
+  #hits{color:var(--muted);font-size:11px;margin-top:6px;min-height:14px}
+  #legend{display:flex;flex-wrap:wrap;gap:6px}
+  .chip{display:inline-flex;align-items:center;gap:6px;padding:4px 9px;border-radius:999px;
+        border:1px solid var(--border);background:var(--bg);cursor:pointer;font-size:11px;
+        user-select:none;transition:opacity .15s,border-color .15s}
+  .chip.off{opacity:.35}
+  .chip .dot{width:9px;height:9px;border-radius:50%}
+  #info .empty{color:var(--muted);line-height:1.5}
+  #info .path{font-family:var(--mono);font-size:11px;color:#9fb4ff;word-break:break-all;margin-bottom:8px}
+  #info .row{display:flex;align-items:center;gap:8px;flex-wrap:wrap;margin-bottom:10px}
+  .badge{font-size:10.5px;padding:2px 8px;border-radius:999px;color:#0d1117;font-weight:600}
+  .stat{font-size:11px;color:var(--muted)}
+  .stat b{color:var(--text);font-weight:600}
+  #info .sum{font-size:12.5px;line-height:1.5;margin:4px 0 6px;color:#cdd6e3}
+  #info h4{font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--muted);margin:14px 0 6px}
+  #info ul{list-style:none;margin:0;padding:0}
+  #info li{font-family:var(--mono);font-size:11px;padding:4px 8px;border-radius:7px;cursor:pointer;
+           color:#c9d1d9;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+  #info li:hover{background:var(--surface2);color:#fff}
+  #info li .pkg{color:var(--muted)}
+  #main{position:relative;flex:1}
+  #graph{position:absolute;inset:0}
+  #bar{position:absolute;top:14px;right:14px;display:flex;gap:6px;z-index:5}
+  .btn{background:rgba(22,27,34,.82);backdrop-filter:blur(6px);border:1px solid var(--border);color:var(--text);
+       padding:7px 12px;border-radius:8px;font-size:12px;cursor:pointer;font-family:var(--font);
+       transition:background .15s,border-color .15s}
+  .btn:hover{background:var(--surface2);border-color:#3d4654}
+  .btn.active{border-color:var(--accent);color:var(--accent)}
+  #load{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;
+        flex-direction:column;gap:14px;background:var(--bg);z-index:8;transition:opacity .6s}
+  #load.hidden{opacity:0;pointer-events:none}
+  .spin{width:30px;height:30px;border-radius:50%;border:3px solid var(--border);
+        border-top-color:var(--accent);animation:spin .8s linear infinite}
+  @keyframes spin{to{transform:rotate(360deg)}}
+  #load span{color:var(--muted);font-size:12px}
+  ::-webkit-scrollbar{width:9px} ::-webkit-scrollbar-thumb{background:#2b3340;border-radius:9px}
+</style></head>
+<body><div id="app">
+  <aside id="side">
+    <div class="brand"><b>🧠 cerebro</b><span>dependency graph</span></div>
+    <div id="meta"></div>
+    <div class="sec">
+      <input id="search" placeholder="Search a file…" autocomplete="off" spellcheck="false">
+      <div id="hits"></div>
+    </div>
+    <div class="sec"><div class="lbl">Packages</div><div id="legend"></div></div>
+    <div class="sec grow"><div class="lbl">Selection</div><div id="info">
+      <div class="empty">Hover a node to light up what it connects to. Drag a node and the web
+      follows. Click to pin its details. Size = centrality (PageRank).</div></div></div>
+  </aside>
+  <div id="main">
+    <div id="bar">
+      <button class="btn" id="cyc">⚠ Cycles</button>
+      <button class="btn" id="orph">○ Orphans</button>
+      <button class="btn" id="fit">Fit</button>
+      <button class="btn active" id="freeze">❚❚ Pause</button>
+    </div>
+    <div id="graph"></div>
+    <div id="load"><div class="spin"></div><span>simulating layout…</span></div>
+  </div>
+</div>
+<script>
+const DATA = __DATA__, META = __META__;
+const PALETTE = ["#4c8dff","#3fb950","#db6d28","#e3597b","#a371f7","#1f9ce4",
+                 "#f0a02c","#39c5bb","#e2c044","#ec6a5e","#57ab5a","#bc8cff"];
+const groups=[...new Set(DATA.nodes.map(n=>n.group))].sort();
+const color={}; groups.forEach((g,i)=>color[g]=PALETTE[i%PALETTE.length]);
+const byId={}; DATA.nodes.forEach(n=>byId[n.id]=n);
+
+const nbr={}, outM={}, inM={};
+DATA.nodes.forEach(n=>nbr[n.id]=new Set());
+DATA.edges.forEach(e=>{(outM[e.from]=outM[e.from]||[]).push(e.to);(inM[e.to]=inM[e.to]||[]).push(e.from);
+  nbr[e.from].add(e.to); nbr[e.to].add(e.from);});
+
+document.getElementById('meta').innerHTML =
+  `<b style="color:var(--text)">${META.shown}</b> of ${META.total} files`+
+  `${META.prefix?` · <span style="color:#9fb4ff">${META.prefix}</span>`:''} · ${DATA.edges.length} imports`+
+  `${META.cycles?` · <span style="color:#e2c044">⚠ ${META.cycles} in cycles</span>`:''}`+
+  `${META.orphans?` · <span style="color:#ec6a5e">○ ${META.orphans} orphans</span>`:''}`;
+
+const hidden=new Set();
+const legend=document.getElementById('legend');
+groups.forEach(g=>{
+  const c=document.createElement('div'); c.className='chip'; c.dataset.g=g;
+  c.innerHTML=`<i class="dot" style="background:${color[g]}"></i>${g}`;
+  c.onclick=()=>{ c.classList.toggle('off'); hidden.has(g)?hidden.delete(g):hidden.add(g); };
+  legend.appendChild(c);
+});
+
+let hl=new Set(), focusId=null, pinned=null, overlay=null;
+const lid=x=>typeof x==='object'?x.id:x;
+const overlaySet=k=>new Set(DATA.nodes.filter(n=>k==='cycle'?n.cycle:n.orphan).map(n=>n.id));
+const REL=3.4;
+const el=document.getElementById('graph');
+
+const Graph = ForceGraph()(el)
+  .backgroundColor('#0d1117')
+  .graphData({nodes:DATA.nodes.map(n=>Object.assign({},n)),
+              links:DATA.edges.map(e=>({source:e.from,target:e.to}))})
+  .nodeId('id').nodeVal(n=>n.value)
+  .nodeRelSize(REL)
+  .autoPauseRedraw(false)
+  .cooldownTicks(Infinity).d3VelocityDecay(0.30).d3AlphaMin(0)
+  .linkDirectionalArrowLength(2).linkDirectionalArrowRelPos(1).linkCurvature(0)
+  .linkColor(l=>{const s=lid(l.source),t=lid(l.target);
+    if(hidden.has(byId[s].group)||hidden.has(byId[t].group))return 'rgba(0,0,0,0)';
+    if(focusId)return (s===focusId||t===focusId)?'rgba(76,141,255,.85)':'rgba(48,54,61,.12)';
+    return 'rgba(70,80,95,.28)';})
+  .linkWidth(l=>{const s=lid(l.source),t=lid(l.target);return focusId&&(s===focusId||t===focusId)?1.4:0.5;})
+  .linkDirectionalParticles(l=>{const s=lid(l.source),t=lid(l.target);return focusId&&(s===focusId||t===focusId)?3:0;})
+  .linkDirectionalParticleWidth(2.2).linkDirectionalParticleColor(()=>'#7fb0ff').linkDirectionalParticleSpeed(0.012)
+  .nodeCanvasObject((node,ctx,scale)=>{
+    if(hidden.has(node.group))return;
+    const r=Math.sqrt(node.value)*REL, dim=hl.size&&!hl.has(node.id);
+    if(node.id===focusId){ctx.shadowColor=color[node.group];ctx.shadowBlur=22;}
+    ctx.beginPath(); ctx.arc(node.x,node.y,r,0,6.2832);
+    ctx.globalAlpha=dim?0.45:1; ctx.fillStyle=dim?'#6e7681':color[node.group]; ctx.fill();
+    ctx.shadowBlur=0;
+    if(node.id===pinned){ctx.lineWidth=2/scale;ctx.strokeStyle='#fff';ctx.stroke();}
+    if(!dim&&node.cycle){ctx.strokeStyle='rgba(226,192,68,.9)';ctx.lineWidth=1.6/scale;
+      ctx.beginPath();ctx.arc(node.x,node.y,r+2.5/scale,0,6.2832);ctx.stroke();}
+    if(!dim&&node.orphan){ctx.strokeStyle='rgba(236,106,94,.95)';ctx.lineWidth=1.4/scale;
+      ctx.setLineDash([3/scale,2.5/scale]);ctx.beginPath();
+      ctx.arc(node.x,node.y,r+(node.cycle?5:2.5)/scale,0,6.2832);ctx.stroke();ctx.setLineDash([]);}
+    ctx.globalAlpha=1;
+    if(!dim&&(node.value>9||scale>1.8||hl.has(node.id))){
+      ctx.font=`${11/scale}px ${getComputedStyle(document.body).fontFamily}`;
+      ctx.textAlign='center'; ctx.textBaseline='top';
+      ctx.fillStyle=hl.size&&!hl.has(node.id)?'rgba(230,237,243,.2)':'rgba(230,237,243,.92)';
+      ctx.fillText(node.label, node.x, node.y+r+2/scale);
+    }
+  })
+  .nodePointerAreaPaint((node,col,ctx)=>{
+    if(hidden.has(node.group))return;
+    ctx.fillStyle=col; ctx.beginPath();
+    ctx.arc(node.x,node.y,Math.sqrt(node.value)*REL+2,0,6.2832); ctx.fill();
+  })
+  .onNodeHover(node=>{ el.style.cursor=node?'pointer':'default';
+    if(node) setHL(node);
+    else if(pinned) setHL(live[pinned]||{id:pinned});
+    else setHL(null); })
+  .onNodeClick(node=>{ pinned=node.id; setHL(node); panel(node.id);
+    Graph.centerAt(node.x,node.y,600); Graph.zoom(Math.max(Graph.zoom(),2.4),600); })
+  .onBackgroundClick(()=>{ pinned=null; setHL(null);
+    document.getElementById('info').innerHTML='<div class="empty">Hover a node to light up what it connects to. Drag a node and the web follows. Click to pin its details.</div>'; });
+
+Graph.d3Force('charge').strength(-260).distanceMax(900);
+Graph.d3Force('link').distance(42).strength(.45);
+
+const live={}; Graph.graphData().nodes.forEach(n=>live[n.id]=n);
+function setHL(node){ if(node){focusId=node.id; hl=new Set([node.id]); nbr[node.id].forEach(x=>hl.add(x));}
+  else if(overlay){focusId=null; hl=overlaySet(overlay);}
+  else {focusId=null; hl=new Set();} }
+const esc=s=>(s||'').replace(/[&<>]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+function li(id){const parts=id.split('/');const base=parts.pop();
+  return `<li data-id="${esc(id)}" title="${esc(id)}"><span class="pkg">${esc(parts[0]||'')}/…/</span>${esc(base)}</li>`;}
+function panel(id){const n=byId[id];if(!n)return;const o=(outM[id]||[]),inn=(inM[id]||[]);
+  document.getElementById('info').innerHTML=
+    `<div class="path">${esc(id)}</div>`+
+    `<div class="row"><span class="badge" style="background:${color[n.group]}">${esc(n.group)}</span>`+
+    `<span class="stat">PageRank <b>${n.score}</b></span></div>`+
+    `<div class="sum">${esc(n.summary)||'<span style="color:var(--muted)">No summary yet — run cerebro-summarize.</span>'}</div>`+
+    `<h4>Imports · ${o.length}</h4><ul>${o.map(li).join('')||'<li style="color:var(--muted);cursor:default">none</li>'}</ul>`+
+    `<h4>Imported by · ${inn.length}</h4><ul>${inn.map(li).join('')||'<li style="color:var(--muted);cursor:default">none</li>'}</ul>`;}
+function focusNode(id){const node=live[id];if(!node)return;pinned=id;setHL({id});panel(id);
+  Graph.centerAt(node.x,node.y,600);Graph.zoom(Math.max(Graph.zoom(),2.4),600);}
+document.getElementById('info').addEventListener('click',e=>{const li=e.target.closest('li[data-id]');if(li)focusNode(li.dataset.id);});
+
+const search=document.getElementById('search'),hits=document.getElementById('hits');
+search.addEventListener('input',()=>{const q=search.value.toLowerCase().trim();
+  hits.textContent=q?`${DATA.nodes.filter(n=>n.id.toLowerCase().includes(q)).length} match`:'';});
+search.addEventListener('keydown',e=>{if(e.key!=='Enter')return;const q=search.value.toLowerCase().trim();
+  const m=DATA.nodes.find(n=>n.id.toLowerCase().includes(q));if(m)focusNode(m.id);});
+
+const cycB=document.getElementById('cyc'),orphB=document.getElementById('orph');
+if(META.cycles)cycB.textContent='⚠ Cycles '+META.cycles; if(META.orphans)orphB.textContent='○ Orphans '+META.orphans;
+function setOverlay(k){overlay=overlay===k?null:k;
+  cycB.classList.toggle('active',overlay==='cycle'); orphB.classList.toggle('active',overlay==='orphan');
+  pinned=null; setHL(null);}
+cycB.onclick=()=>setOverlay('cycle'); orphB.onclick=()=>setOverlay('orphan');
+
+document.getElementById('fit').onclick=()=>Graph.zoomToFit(600,60);
+let running=true;const fb=document.getElementById('freeze');
+fb.onclick=()=>{running=!running; running?Graph.resumeAnimation():Graph.pauseAnimation();
+  fb.classList.toggle('active',running); fb.textContent=running?'❚❚ Pause':'▶ Resume';};
+
+function size(){Graph.width(el.clientWidth).height(el.clientHeight);}
+size(); window.addEventListener('resize',size);
+setTimeout(()=>Graph.zoomToFit(700,70),1200);
+setTimeout(()=>document.getElementById('load').classList.add('hidden'),900);
+</script></body></html>"""

cerebro_code_memory-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,23 @@
+cerebro/__init__.py,sha256=eEEQ_sWw07H2kZ4wTCirZ26kRZG-NhHdvOQ1UqEMCnU,99
+cerebro/callgraph.py,sha256=Uzto-AltX1EIYsNCz4GCGTkK5I4aOykb1uTy6oaHEII,1538
+cerebro/cli.py,sha256=I1TcHfDiR_u6qETwEkV3hdG2cKXpHevVqX3sp3O-b4Y,14102
+cerebro/config.py,sha256=fCgkyyCAAY7bCrTiNakQBajYf1blGJflCyaXeNojC1Y,4555
+cerebro/db.py,sha256=nZbtrBMPFmFmpt9wXz7-Xvk3EEbyu0sw7oHYQBYN25w,8933
+cerebro/docaudit.py,sha256=zZn-t3_ql4RG_w_7g-wmcQJKP_cK22EBi9mBpvEN240,8036
+cerebro/embeddings.py,sha256=yZAVlDqvuE9ussAUIcKmJlUfZB7oEF_1nSfJdxfJL5E,5987
+cerebro/gitsync.py,sha256=83S-Mz3LX22v6DLuwJFfkyNNDiXfqllKuNLjmNV5W7g,3957
+cerebro/graph.py,sha256=DWsZ82Vdtej4HX3YpNhPgBx7VbjTeOW8Q1hOUcjgNoE,2821
+cerebro/indexer.py,sha256=uETgCOxU5sk9IBF_UpqLDkDKgVxohE0oewURlVTyL-Q,35385
+cerebro/insights.py,sha256=fBUzRJ-t0bcVXaiW9JEHxr5U6jpOAn7GM9dwfOp2Gls,9167
+cerebro/notes.py,sha256=Xek2NYQFzxs-Sl51aQLtIskuZ3iRNDbqth39mFOp9wA,2456
+cerebro/server.py,sha256=YcKQ6cnAZgYHbRpr8Cb1SHYlJT4QNG8N58XVQOKOvmc,14992
+cerebro/summaries.py,sha256=idmrzSnNtcT8WpqMHpEcS7yVYujSzeE7bMXBP8w0nyY,2607
+cerebro/summarizer.py,sha256=axDVlKoSjjsg6flhxvmNJd-YjvIic3-fl26zxhZVpBE,4008
+cerebro/tsconfig.py,sha256=LxlJyzrtDOobcPwps7f1HxnRvt6UOn7FSdTPR5mpWQc,5708
+cerebro/views.py,sha256=Z7_13r3ys0YM5lNPT7SXBUic-su9kmmcjC70Fz5h3p4,2149
+cerebro/viz.py,sha256=nrcp2yvfm5fECWVmTXMrYz64srvoomXazW6MoY_Blag,18911
+cerebro_code_memory-0.1.0.dist-info/METADATA,sha256=0ThTvg8kCv0XLp2p1ZJjfmxp4PK6-H2pH8ngHkfPf9s,8353
+cerebro_code_memory-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cerebro_code_memory-0.1.0.dist-info/entry_points.txt,sha256=OJahPgB6TbsPizn_dibpKP8dOfd2ZPcMfcXjZ43eSnQ,417
+cerebro_code_memory-0.1.0.dist-info/licenses/LICENSE,sha256=yiho2YjFT755EnCviLP8pTWu64JpvwqqK9ZNF5aG1_k,1069
+cerebro_code_memory-0.1.0.dist-info/RECORD,,

cerebro_code_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

cerebro_code_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,11 @@
+[console_scripts]
+cerebro = cerebro.cli:main
+cerebro-code-memory = cerebro.server:main
+cerebro-embed = cerebro.embeddings:main
+cerebro-export-obsidian = cerebro.viz:obsidian_main
+cerebro-graph = cerebro.viz:graph_main
+cerebro-index = cerebro.indexer:main
+cerebro-map = cerebro.server:map_main
+cerebro-recall = cerebro.server:recall_main
+cerebro-summarize = cerebro.summarizer:main
+cerebro-sync = cerebro.gitsync:main

cerebro_code_memory-0.1.0.dist-info/licenses/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.