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

cerebro/db.py

@@ -0,0 +1,245 @@
+"""SQLite storage: schema, connection, and low-level write/query helpers.
+
+A single file, `.cerebro/brain.db`, holds every "trace": the structural index
+(files, symbols, edges), the cached English summaries, the decision notes
+(reserved for v2), and an FTS5 index used by keyword search.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS files (
+    path        TEXT PRIMARY KEY,
+    lang        TEXT,
+    hash        TEXT NOT NULL,
+    mtime       REAL,
+    size        INTEGER,
+    indexed_at  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS symbols (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    file_path  TEXT NOT NULL,
+    kind       TEXT NOT NULL,
+    name       TEXT NOT NULL,
+    line       INTEGER,
+    signature  TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_symbols_file ON symbols(file_path);
+CREATE INDEX IF NOT EXISTS idx_symbols_name ON symbols(name);
+
+CREATE TABLE IF NOT EXISTS edges (
+    src_path  TEXT NOT NULL,
+    dst_path  TEXT NOT NULL,
+    kind      TEXT NOT NULL DEFAULT 'import',
+    PRIMARY KEY (src_path, dst_path, kind)
+);
+CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_path);
+
+-- Symbol-level call graph (tree-sitter, name-resolved): src_symbol in src_path
+-- calls/references a symbol named dst_name. src_symbol is NULL at module scope.
+CREATE TABLE IF NOT EXISTS calls (
+    src_path   TEXT NOT NULL,
+    src_symbol TEXT,
+    dst_name   TEXT NOT NULL,
+    line       INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_calls_dst ON calls(dst_name);
+CREATE INDEX IF NOT EXISTS idx_calls_src ON calls(src_path);
+
+-- Identifier references: a distinct (path, name) for every name USED in a file
+-- (calls, JSX, type annotations, value reads), EXCLUDING the file's own
+-- definition sites. Lets dead_symbols() ask "is this symbol's name referenced
+-- anywhere?" — a name absent from refs entirely is an unused-export candidate.
+CREATE TABLE IF NOT EXISTS refs (
+    path TEXT NOT NULL,
+    name TEXT NOT NULL,
+    PRIMARY KEY (path, name)
+);
+CREATE INDEX IF NOT EXISTS idx_refs_name ON refs(name);
+
+CREATE TABLE IF NOT EXISTS summaries (
+    path        TEXT PRIMARY KEY,
+    summary_en  TEXT NOT NULL,
+    model       TEXT,
+    source_hash TEXT,
+    updated_at  TEXT NOT NULL
+);
+
+-- Reserved for v2 (decision log). Created now so the schema is stable.
+CREATE TABLE IF NOT EXISTS notes (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    topic      TEXT,
+    content    TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT
+);
+
+-- Optional semantic layer (legacy, file-level): one vector per file. Superseded
+-- by symbol_embeddings below; kept so older brains still open cleanly.
+CREATE TABLE IF NOT EXISTS embeddings (
+    path       TEXT PRIMARY KEY,
+    dim        INTEGER,
+    vec        BLOB NOT NULL,
+    doc_hash   TEXT,
+    updated_at TEXT NOT NULL
+);
+
+-- Symbol-level semantic vectors: one row per symbol (function/class), plus one
+-- whole-file row (name IS NULL) for files with no indexable symbols. Lets search
+-- land on the exact symbol + line, not just the file. doc_hash is a per-file
+-- fingerprint (identical on every row of a file) so build() skips unchanged files.
+CREATE TABLE IF NOT EXISTS symbol_embeddings (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    path       TEXT NOT NULL,
+    name       TEXT,
+    line       INTEGER,
+    kind       TEXT,
+    dim        INTEGER,
+    vec        BLOB NOT NULL,
+    doc_hash   TEXT,
+    updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_symemb_path ON symbol_embeddings(path);
+
+-- One row per (path, kind). kind='symbol' aggregates a file's symbol names;
+-- kind='summary' holds the file's English summary. Maintained manually.
+CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5(
+    path UNINDEXED,
+    kind UNINDEXED,
+    text
+);
+"""
+
+
+def connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    # Set busy_timeout FIRST: switching to WAL itself takes a write lock, so a
+    # concurrent connection (e.g. the post-edit hook's reindex while the MCP
+    # server connects) must wait here rather than fail with "database is locked".
+    conn.execute("PRAGMA busy_timeout=5000")
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.executescript(SCHEMA)
+    return conn
+
+
+# --- structural index writes -------------------------------------------------
+
+def upsert_file(conn, path, lang, file_hash, mtime, size, indexed_at):
+    conn.execute(
+        """INSERT INTO files(path, lang, hash, mtime, size, indexed_at)
+           VALUES(?,?,?,?,?,?)
+           ON CONFLICT(path) DO UPDATE SET
+             lang=excluded.lang, hash=excluded.hash, mtime=excluded.mtime,
+             size=excluded.size, indexed_at=excluded.indexed_at""",
+        (path, lang, file_hash, mtime, size, indexed_at),
+    )
+
+
+def replace_symbols(conn, path, symbols):
+    """symbols: iterable of (kind, name, line, signature)."""
+    conn.execute("DELETE FROM symbols WHERE file_path=?", (path,))
+    conn.executemany(
+        "INSERT INTO symbols(file_path, kind, name, line, signature) VALUES(?,?,?,?,?)",
+        [(path, k, n, ln, sig) for (k, n, ln, sig) in symbols],
+    )
+    names = " ".join(sorted({n for (_, n, _, _) in symbols}))
+    conn.execute("DELETE FROM fts WHERE path=? AND kind='symbol'", (path,))
+    if names:
+        conn.execute(
+            "INSERT INTO fts(path, kind, text) VALUES(?, 'symbol', ?)", (path, names)
+        )
+
+
+def replace_edges(conn, src_path, edges):
+    """edges: an iterable of dst paths (all recorded as kind 'import'), or a
+    mapping {dst_path: kind} to record edge kinds (e.g. type-only TS imports)."""
+    items = edges.items() if isinstance(edges, dict) else ((d, "import") for d in edges)
+    rows = sorted({(src_path, d, k) for d, k in items})
+    conn.execute("DELETE FROM edges WHERE src_path=?", (src_path,))
+    conn.executemany(
+        "INSERT OR IGNORE INTO edges(src_path, dst_path, kind) VALUES(?,?,?)",
+        rows,
+    )
+
+
+def replace_calls(conn, src_path, calls):
+    """calls: iterable of (src_symbol|None, dst_name, line)."""
+    conn.execute("DELETE FROM calls WHERE src_path=?", (src_path,))
+    conn.executemany(
+        "INSERT INTO calls(src_path, src_symbol, dst_name, line) VALUES(?,?,?,?)",
+        [(src_path, sym, name, line) for (sym, name, line) in calls],
+    )
+
+
+def replace_refs(conn, src_path, names):
+    """names: iterable of identifier names used (referenced) in src_path."""
+    conn.execute("DELETE FROM refs WHERE path=?", (src_path,))
+    conn.executemany(
+        "INSERT OR IGNORE INTO refs(path, name) VALUES(?,?)",
+        [(src_path, n) for n in sorted(set(names))],
+    )
+
+
+def forget_file(conn, path):
+    """Remove every trace of a file that no longer exists on disk."""
+    conn.execute("DELETE FROM files WHERE path=?", (path,))
+    conn.execute("DELETE FROM symbols WHERE file_path=?", (path,))
+    conn.execute("DELETE FROM edges WHERE src_path=? OR dst_path=?", (path, path))
+    conn.execute("DELETE FROM calls WHERE src_path=?", (path,))
+    conn.execute("DELETE FROM refs WHERE path=?", (path,))
+    conn.execute("DELETE FROM summaries WHERE path=?", (path,))
+    conn.execute("DELETE FROM embeddings WHERE path=?", (path,))
+    conn.execute("DELETE FROM symbol_embeddings WHERE path=?", (path,))
+    conn.execute("DELETE FROM fts WHERE path=?", (path,))
+
+
+# --- reads -------------------------------------------------------------------
+
+def stored_hashes(conn) -> dict[str, str]:
+    return {r["path"]: r["hash"] for r in conn.execute("SELECT path, hash FROM files")}
+
+
+def symbols_for(conn, path):
+    return conn.execute(
+        "SELECT kind, name, line, signature FROM symbols WHERE file_path=? ORDER BY line",
+        (path,),
+    ).fetchall()
+
+
+def lang_counts(conn):
+    return conn.execute(
+        "SELECT COALESCE(lang,'other') AS lang, COUNT(*) AS n "
+        "FROM files GROUP BY lang ORDER BY n DESC"
+    ).fetchall()
+
+
+def search(conn, query: str, limit: int = 15):
+    """Keyword search over symbol names + summaries. Falls back to LIKE if the
+    FTS5 MATCH syntax rejects the raw query."""
+    try:
+        rows = conn.execute(
+            # summaries are higher-signal than symbol-name matches → rank them first
+            "SELECT path, kind, snippet(fts, 2, '[', ']', '…', 12) AS snip "
+            "FROM fts WHERE fts MATCH ? AND kind != 'note' "
+            "ORDER BY (kind != 'summary'), rank LIMIT ?",
+            (query, limit),
+        ).fetchall()
+        if rows:
+            return rows
+    except sqlite3.OperationalError:
+        pass
+    like = f"%{query}%"
+    return conn.execute(
+        "SELECT path, kind, substr(text,1,120) AS snip FROM fts "
+        "WHERE text LIKE ? AND kind != 'note' LIMIT ?",
+        (like, limit),
+    ).fetchall()

cerebro/docaudit.py

@@ -0,0 +1,174 @@
+"""Living-docs audit: cross-check a knowledge vault (Markdown notes) against the
+Cerebro code index to find notes whose referenced code has changed or vanished.
+
+This automates the rule every wiki states but no wiki enforces — "if the doc
+contradicts the code, the code wins, mark the doc stale". A note is flagged when:
+  - a code path it references no longer exists in the index (broken), or
+  - a referenced file changed after the note's `ultima_verificacion` / `fecha`, or
+  - a referenced symbol (method/class) is no longer defined anywhere (heuristic).
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+from . import db as _db
+from . import graph as _graph
+
+_EXT = r"(?:ts|tsx|js|jsx|mjs|cjs|py)"
+# a real code path: at least one '/', ending in a code extension, optional :line
+_PATH_RE = re.compile(r"([\w.@-]+(?:/[\w.@-]+)+\." + _EXT + r")(?::(\d+))?")
+_FM_RE = re.compile(r"^---\s*\n(.*?)\n---", re.S)
+_DATE_RE = re.compile(r"(?:ultima_verificacion|fecha)\s*:\s*(\d{4}-\d{2}-\d{2})")
+_BACKTICK_RE = re.compile(r"`([^`\n]+)`")
+
+
+def parse_note(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    fm = _FM_RE.match(text)
+    fm_text = fm.group(1) if fm else ""
+    dm = _DATE_RE.search(fm_text)
+    files = {(m.group(1), m.group(2)) for m in _PATH_RE.finditer(text)}
+    symbols = set()
+    for m in _BACKTICK_RE.finditer(text):
+        content = m.group(1)
+        for call in re.findall(r"\b([A-Za-z_]\w{2,})\s*\(", content):  # foo(...)
+            symbols.add(call)
+        for tok in re.findall(r"\b([A-Za-z_]\w{2,})\b", content):  # mixedCase ident
+            if re.search(r"[a-z]", tok) and re.search(r"[A-Z]", tok):
+                symbols.add(tok)
+    return {"date": dm.group(1) if dm else None, "files": files, "symbols": symbols}
+
+
+def _normalize_ref(ref: str, aliases: dict[str, str]) -> str:
+    """Resolve wiki naming to real repo paths: map logical app aliases
+    (backend_app -> fenix-store-backend) and strip ../ / cross-machine prefixes."""
+    parts = [p for p in ref.split("/") if p not in ("", ".")]
+    for i, p in enumerate(parts):  # cut at the first known app-alias segment
+        if p in aliases:
+            parts = [aliases[p]] + parts[i + 1:]
+            return "/".join(parts)
+    while parts and parts[0] == "..":
+        parts.pop(0)
+    return "/".join(parts)
+
+
+def _resolve(conn, ref: str, aliases: dict[str, str]) -> str | None:
+    ref = _normalize_ref(ref, aliases)
+    if conn.execute("SELECT 1 FROM files WHERE path=?", (ref,)).fetchone():
+        return ref
+    rows = conn.execute("SELECT path FROM files WHERE path LIKE ?", ("%/" + ref,)).fetchall()
+    return rows[0]["path"] if len(rows) == 1 else None
+
+
+def _epoch(date: str) -> float:
+    return datetime.strptime(date, "%Y-%m-%d").timestamp()
+
+
+def audit_note(conn, note: dict, known_symbols: set[str], aliases: dict[str, str]) -> list[tuple[str, str]]:
+    issues: list[tuple[str, str]] = []
+    note_epoch = _epoch(note["date"]) if note["date"] else None
+    for ref, _line in sorted(note["files"]):
+        resolved = _resolve(conn, ref, aliases)
+        if resolved is None:
+            issues.append(("broken", f"{ref} — not in the index"))
+            continue
+        if note_epoch is not None:
+            row = conn.execute("SELECT mtime FROM files WHERE path=?", (resolved,)).fetchone()
+            if row and row["mtime"] and row["mtime"] > note_epoch:
+                mod = datetime.fromtimestamp(row["mtime"]).date().isoformat()
+                issues.append(("changed", f"{resolved} changed {mod} (note verified {note['date']})"))
+    for s in sorted(note["symbols"]):
+        if s not in known_symbols:
+            issues.append(("symbol?", f"`{s}` — not defined anywhere (renamed/removed?)"))
+    return issues
+
+
+def audit_vault(conn, vault: Path, aliases: dict[str, str] | None = None) -> list[dict]:
+    aliases = aliases or {}
+    known = {r["name"] for r in conn.execute("SELECT DISTINCT name FROM symbols")}
+    results = []
+    for md in sorted(vault.rglob("*.md")):
+        if any(part.startswith(".") for part in md.parts):  # skip .obsidian etc.
+            continue
+        note = parse_note(md)
+        if not note["files"] and not note["symbols"]:
+            continue  # purely conceptual note — nothing to verify against code
+        issues = audit_note(conn, note, known, aliases)
+        hard = [i for i in issues if i[0] in ("broken", "changed")]
+        status = "stale" if hard else ("hint" if issues else "fresh")
+        results.append({"note": md, "status": status, "date": note["date"], "issues": issues})
+    return results
+
+
+def relocate(conn, ref: str) -> list[str]:
+    """Where a moved/renamed file likely lives now — same basename in the index."""
+    base = ref.split("/")[-1]
+    return [r["path"] for r in conn.execute(
+        "SELECT path FROM files WHERE path LIKE ?", ("%/" + base,)).fetchall()]
+
+
+def refresh_briefing(conn, note_path: Path, aliases: dict[str, str] | None = None) -> dict:
+    """Re-audit a stale note against the LIVE code: for each reference, the current
+    facts (symbols, summary, dependents, last-change) or a relocation candidate if
+    moved. This is the structured context an agent uses to propose the update."""
+    aliases = aliases or {}
+    note = parse_note(Path(note_path))
+    note_epoch = _epoch(note["date"]) if note["date"] else None
+    refs = []
+    for ref, line in sorted(note["files"]):
+        resolved = _resolve(conn, ref, aliases)
+        if resolved is None:
+            refs.append({"ref": ref, "status": "moved/missing", "candidates": relocate(conn, ref)})
+            continue
+        row = conn.execute("SELECT mtime FROM files WHERE path=?", (resolved,)).fetchone()
+        changed = bool(note_epoch and row and row["mtime"] and row["mtime"] > note_epoch)
+        srow = conn.execute("SELECT summary_en FROM summaries WHERE path=?", (resolved,)).fetchone()
+        refs.append({
+            "ref": ref, "resolved": resolved,
+            "status": "changed" if changed else "current",
+            "changed_date": datetime.fromtimestamp(row["mtime"]).date().isoformat() if row and row["mtime"] else None,
+            "symbols": [f"L{s['line']} {s['kind']} {s['signature'] or s['name']}" for s in _db.symbols_for(conn, resolved)],
+            "summary": srow["summary_en"] if srow else None,
+            "dependents": _graph.dependents(conn, resolved)[:8],
+        })
+    return {"note": str(note_path), "date": note["date"], "refs": refs}
+
+
+def format_briefing(b: dict) -> str:
+    out = [f"# Refresh briefing — {Path(b['note']).name}  (verified {b['date'] or 'n/a'})", ""]
+    for r in b["refs"]:
+        if r["status"] == "moved/missing":
+            cand = ", ".join(r["candidates"]) or "no candidate found"
+            out.append(f"## ⚠ MOVED/MISSING: {r['ref']}\n   likely now → {cand}\n")
+            continue
+        tag = "CHANGED since note" if r["status"] == "changed" else "current"
+        out.append(f"## {r['resolved']}  [{tag}, last change {r['changed_date']}]")
+        if r["summary"]:
+            out.append(f"   summary: {r['summary']}")
+        if r["symbols"]:
+            out.append("   symbols now:")
+            out += [f"     {s}" for s in r["symbols"][:25]]
+        if r["dependents"]:
+            out.append("   used by: " + ", ".join(r["dependents"]))
+        out.append("")
+    return "\n".join(out)
+
+
+_ESTADO_RE = re.compile(r"^(estado|status)\s*:.*$", re.M)
+
+
+def mark_stale(path: Path) -> bool:
+    """Patch the note's frontmatter to estado: revisar (their convention)."""
+    text = path.read_text(encoding="utf-8", errors="ignore")
+    fm = _FM_RE.match(text)
+    if not fm:
+        return False
+    block = fm.group(1)
+    if _ESTADO_RE.search(block):
+        new_block = _ESTADO_RE.sub("estado: revisar", block, count=1)
+    else:
+        new_block = block + "\nestado: revisar"
+    path.write_text(text[: fm.start(1)] + new_block + text[fm.end(1):], encoding="utf-8")
+    return True

cerebro/embeddings.py

@@ -0,0 +1,175 @@
+"""Optional semantic search layer.
+
+Keyword search (FTS5) misses intent — "where do we validate stock during purchase?"
+shares no keywords with the checkout service. This embeds one vector per SYMBOL
+(function/class: `path kind name signature` + the file summary), plus a whole-file
+vector for files with no indexable symbols, with a small LOCAL model (model2vec, no
+torch, no API key, nothing leaves the machine) and ranks by cosine similarity in
+numpy — so a hit lands on the exact symbol + line, not just the file.
+
+It is fully optional: install with `uv sync --extra semantic`. Without the extra,
+every function degrades to a no-op and search stays keyword-only.
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+
+from . import db
+from . import summaries
+
+# Keep the local model quiet — no progress bars / HTTP chatter (set before any
+# huggingface import, which model2vec does lazily inside _model()).
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+try:  # optional dependencies — guarded so the module imports either way
+    import numpy as np
+except Exception:  # pragma: no cover
+    np = None
+
+_MODEL = None
+_MODEL_NAME = "minishlab/potion-base-8M"
+
+
+def model_available() -> bool:
+    if np is None:
+        return False
+    try:
+        import model2vec  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def _model():
+    global _MODEL
+    if _MODEL is None:
+        from model2vec import StaticModel
+        _MODEL = StaticModel.from_pretrained(_MODEL_NAME)
+    return _MODEL
+
+
+def _docs_for(conn, path: str):
+    """One document per symbol — `path kind name signature` + the file summary for
+    context (there are no per-symbol summaries). A file with no indexable symbols
+    gets a single whole-file document (name/line/kind None) so it stays searchable.
+    Returns a list of (name, line, kind, doc)."""
+    row = conn.execute(
+        "SELECT summary_en FROM summaries WHERE path=?", (path,)
+    ).fetchone()
+    summary = row["summary_en"] if row else ""
+    syms = db.symbols_for(conn, path)
+    if syms:
+        return [
+            (
+                s["name"],
+                s["line"],
+                s["kind"],
+                f"{path} {s['kind']} {s['name']} {s['signature'] or s['name']}\n{summary}".strip(),
+            )
+            for s in syms
+        ]
+    return [(None, None, None, f"{path}\n{summary}".strip())]
+
+
+def has_index(conn) -> bool:
+    if np is None:
+        return False
+    return (
+        conn.execute("SELECT COUNT(*) AS n FROM symbol_embeddings").fetchone()["n"]
+        > 0
+    )
+
+
+def build(config, conn, only_missing: bool = True) -> dict:
+    """Embed each file's symbols (one vector per symbol, plus a whole-file vector
+    for symbol-less files). doc_hash is a per-file fingerprint — identical across a
+    file's rows — so an unchanged file is skipped wholesale and a changed one has
+    all its rows replaced atomically. `embedded` counts files re-embedded."""
+    if not model_available():
+        return {"ok": False, "reason": "semantic extra not installed (uv sync --extra semantic)"}
+    model = _model()
+    files = [
+        r["path"]
+        for r in conn.execute("SELECT path FROM files WHERE lang IS NOT NULL")
+    ]
+    have: dict[str, str] = {}
+    for r in conn.execute("SELECT path, doc_hash FROM symbol_embeddings"):
+        have.setdefault(r["path"], r["doc_hash"])
+
+    targets, docs = [], []  # targets: (path, name, line, kind, fhash)
+    for p in files:
+        file_docs = _docs_for(conn, p)
+        fhash = hashlib.sha1(
+            "\x00".join(d for (_, _, _, d) in file_docs).encode("utf-8")
+        ).hexdigest()
+        if only_missing and have.get(p) == fhash:
+            continue
+        # Changed (or new) file: drop its stale rows, re-embed all of them.
+        conn.execute("DELETE FROM symbol_embeddings WHERE path=?", (p,))
+        for (name, line, kind, doc) in file_docs:
+            targets.append((p, name, line, kind, fhash))
+            docs.append(doc)
+    if not docs:
+        conn.commit()
+        return {"ok": True, "embedded": 0, "total": len(files)}
+
+    vecs = np.asarray(model.encode(docs), dtype="float32")
+    dim = int(vecs.shape[1])
+    now = summaries.now_iso()
+    for (p, name, line, kind, fhash), v in zip(targets, vecs):
+        conn.execute(
+            "INSERT INTO symbol_embeddings"
+            "(path, name, line, kind, dim, vec, doc_hash, updated_at) "
+            "VALUES(?,?,?,?,?,?,?,?)",
+            (p, name, line, kind, dim, v.tobytes(), fhash, now),
+        )
+    conn.commit()
+    return {
+        "ok": True,
+        "embedded": len({t[0] for t in targets}),
+        "total": len(files),
+    }
+
+
+def search(config, conn, query: str, limit: int = 10):
+    """Return [(path, name, line, cosine_score), ...] best-first — name/line are
+    None for a whole-file hit. [] if unavailable."""
+    if not model_available() or not has_index(conn):
+        return []
+    rows = conn.execute(
+        "SELECT path, name, line, vec FROM symbol_embeddings"
+    ).fetchall()
+    if not rows:
+        return []
+    q = np.asarray(_model().encode([query])[0], dtype="float32")
+    q /= np.linalg.norm(q) + 1e-9
+    mat = np.frombuffer(b"".join(r["vec"] for r in rows), dtype="float32").reshape(
+        len(rows), -1
+    )
+    mat = mat / (np.linalg.norm(mat, axis=1, keepdims=True) + 1e-9)
+    sims = mat @ q
+    order = np.argsort(-sims)[:limit]
+    return [
+        (rows[i]["path"], rows[i]["name"], rows[i]["line"], float(sims[i]))
+        for i in order
+    ]
+
+
+def main():  # `cerebro-embed` entry point
+    import json
+
+    from . import config as cfg
+
+    config = cfg.Config.load()
+    conn = db.connect(config.db_path)
+    result = build(config, conn)
+    result["root"] = str(config.root)
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()