brain-cache 0.4.2 → 3.0.0

package/.claude/skills/brain-cache/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: brain-cache
+description: "Local codebase embeddings that save tokens and money. Use brain-cache MCP tools instead of reading files or grepping — they return better results with fewer tokens sent to Claude."
+allowed-tools: Bash Read Grep
+---
+
+## What brain-cache does
+
+brain-cache indexes your codebase locally using Ollama embeddings — no data leaves your machine. When you need to understand code, it retrieves only the relevant parts and fits them to a token budget before sending anything to Claude. This means Claude sees better, more focused context while you spend fewer tokens per query.
+
+Use brain-cache tools before reading files or using Grep/Glob for codebase questions. They return better, token-efficient results.
+
+## Tool routing
+
+| Query type | Tool | NOT this |
+|-----------|------|---------|
+| Locate a function, type, or symbol | `search_codebase` | `build_context` |
+| Understand how specific code works across files | `build_context` | file reads |
+| Diagnose brain-cache failures | `doctor` | -- |
+| Reindex the project | `index_repo` | -- |
+
+## search_codebase (locate code)
+
+Call `mcp__brain-cache__search_codebase` to find functions, types, definitions, or implementations by meaning rather than keyword match.
+
+Use for: "Where is X defined?", "Find the auth middleware", "Which file handles request validation?"
+
+Do NOT use for understanding how code works — use `build_context` once you have located the symbol.
+
+## build_context (understand behavior)
+
+Call `mcp__brain-cache__build_context` with a focused question about how specific code works. It retrieves semantically relevant code, deduplicates results, and fits them to a token budget.
+
+Use for: "How does X work?", "What does this function do?", debugging unfamiliar code paths.
+
+Do NOT use for locating symbols — use `search_codebase` first to find where code lives.
+
+Do NOT use just to get a file overview — ask a specific behavioral question.
+
+## index_repo (reindex)
+
+Call `mcp__brain-cache__index_repo` only when the user explicitly asks to reindex, or after major code changes such as a large refactor or pulling a significant upstream diff.
+
+Do not call proactively. Do not call at the start of each session.
+
+## doctor (diagnose issues)
+
+Call `mcp__brain-cache__doctor` when any brain-cache tool fails or returns unexpected results. It checks index health and Ollama connectivity and tells you what to fix.
+
+## Status line
+
+brain-cache displays cumulative token savings in the Claude Code status bar. After tool calls you will see `brain-cache down-arrow{pct}% {n} saved` — this confirms cost savings are working. If the status bar shows idle, no tools have been called yet in the current session.

package/README.md

@@ -1,65 +1,42 @@
 # brain-cache
 
-> Stop sending your entire repo to Claude.
+> Your local GPU finally has a job.
 
-brain-cache is an MCP server that gives Claude local, indexed access to your codebase — so it finds what matters instead of reading everything.
-
-→ ~90% fewer tokens sent to Claude
-→ Sharper, grounded answers
-→ No data leaves your machine
+brain-cache is a local AI runtime that sits between your codebase and Claude. It runs embeddings and retrieval on your machine — so Claude only sees what actually matters. Fewer tokens. Better answers. Your API bill stops looking like a mortgage payment.
 
 ![brain-cache only sends the parts of your codebase that matter — not everything.](assets/brain-cache.svg)
 
 ---
 
-## Use inside Claude Code (MCP)
-
-The primary way to use brain-cache is as an MCP server. Run `brain-cache init` once — it auto-configures `.mcp.json` in your project root so Claude Code connects immediately. No manual JSON setup needed.
+## How it works
 
-Claude then has access to:
-
-- **`build_context`** — Assembles relevant context for any question. Use this instead of reading files.
-- **`search_codebase`** — Finds functions, types, and symbols by meaning, not keyword. Use this instead of grep.
-- **`index_repo`** — Rebuilds the local vector index.
-- **`doctor`** — Diagnoses index health and Ollama connectivity.
-
-No copy/pasting code into prompts. No manual file opens. Claude knows where to look.
+1. Embeds your query locally via Ollama (fast, free, no API calls)
+2. Retrieves the most relevant code chunks from its local vector index
+3. Trims and deduplicates the context to fit a tight token budget
+4. Hands Claude a clean, minimal context — not your entire repo
 
 ---
 
-## ⚡ The problem
-
-When you ask Claude about your codebase, you either:
-
-- paste huge chunks of code ❌
-- rely on vague context ❌
-- or let tools send way too much ❌
-
-Result:
-
-- worse answers
-- hallucinations
-- massive token usage
+## Use inside Claude Code (MCP)
 
----
+The primary way to use brain-cache is as an MCP server. Run `brain-cache init` once — it auto-configures `.mcp.json` in your project root so Claude Code connects immediately. No manual JSON setup needed.
 
-## 🧠 How it works
+Claude then has access to:
 
-brain-cache is the layer between your codebase and Claude.
+- **`build_context`** — Assembles relevant context for any question. Use instead of reading files.
+- **`search_codebase`** — Finds functions, types, and symbols by meaning, not keyword. Use instead of grep.
+- **`index_repo`** — Rebuilds the local vector index.
 
-1. Your code is indexed locally using Ollama embeddings — nothing leaves your machine
-2. When you ask Claude a question, it calls `build_context` or `search_codebase` automatically
-3. brain-cache retrieves only the relevant files, trims duplicates, and fits them to a token budget
-4. Claude gets tight, useful context — not your entire repo
+Also included: **`doctor`** — diagnoses index health and Ollama connectivity.
 
-AI should read the right parts — and nothing else. brain-cache is the layer that makes that possible.
+No copy/pasting code into prompts. No manual file opens. Claude knows where to look.
 
 ---
 
-## 🔥 Example
+## Example
 
 ```
-> "Explain the overall architecture of this project"
+> "How does the auth middleware work?"
 
 brain-cache: context assembled (74 tokens, 97% reduction)
 
@@ -68,11 +45,11 @@ Estimated without:         ~2,795
 Reduction:                 97%
 ```
 
-Claude gets only what matters → answers are sharper and grounded.
+Claude gets only what matters — answers are sharper and grounded.
 
 ---
 
-## ⚡ Quick start
+## Quick start
 
 **Step 1: Install**
 
@@ -87,11 +64,11 @@ brain-cache init
 brain-cache index
 ```
 
-`brain-cache init` sets up your project: configures `.mcp.json` so Claude Code connects to brain-cache automatically, and appends MCP tool instructions to `CLAUDE.md`. Runs once; idempotent.
+`brain-cache init` sets up your project: configures `.mcp.json` so Claude Code connects to brain-cache automatically, appends MCP tool instructions to `CLAUDE.md`, installs the brain-cache skill to `.claude/skills/brain-cache/SKILL.md`, and installs a status line in Claude Code that shows cumulative token savings. Runs once; idempotent.
 
 **Step 3: Use Claude normally**
 
-brain-cache tools are called automatically. You don’t change how you work — the context just gets better.
+brain-cache tools are called automatically. You don't change how you work — the context just gets better.
 
 > **Advanced:** `init` creates `.mcp.json` automatically. If you need to customise it manually, the expected shape is:
 > ```json
@@ -107,7 +84,24 @@ brain-cache tools are called automatically. You don’t change how you work —
 
 ---
 
-## 📊 Optional: Token savings footer
+## Install as Claude Code skill
+
+brain-cache ships as a Claude Code skill. After `brain-cache init`, the skill is
+installed at `.claude/skills/brain-cache/SKILL.md` in your project. Claude
+automatically learns when and how to use brain-cache tools.
+
+To install manually, copy the `.claude/skills/brain-cache/` directory into your
+project root.
+
+---
+
+## Status line
+
+After `brain-cache init`, the status line in Claude Code's bottom bar shows your cumulative token savings session by session. You see the reduction without doing anything different.
+
+---
+
+## Optional: Token savings footer
 
 brain-cache returns token usage stats in its tool responses (tokens sent, estimated without, reduction %). By default, Claude decides whether to surface these — no footer is forced.
 
@@ -119,7 +113,7 @@ When using brain-cache build_context, include the token savings summary from the
 
 This keeps it transparent and under your control.
 
-## 🎛 Tuning how much Claude uses brain-cache
+## Tuning how much Claude uses brain-cache
 
 `brain-cache init` adds a section to your project's `CLAUDE.md` with clear instructions to use brain-cache tools first. This works well for most users.
 
@@ -134,37 +128,7 @@ Or soften it if you prefer Claude to decide on its own. It's your `CLAUDE.md`
 
 ---
 
-## 🧩 Core capabilities
-
-- 🧠 Local embeddings via Ollama — no API calls, no data sent out
-- 🔍 Semantic vector search over your codebase
-- ✂️ Context trimming and deduplication
-- 🎯 Token budget optimisation
-- 🤖 MCP server for Claude Code integration
-- ⚡ CLI for setup, debugging, and admin
-
----
-
-## 🧠 Why it’s different
-
-Most AI coding tools:
-
-- send too much context
-- hide retrieval behind hosted services
-- require you to prompt-engineer your way to good answers
-
-brain-cache is:
-
-- 🏠 Local-first — embeddings run on your machine
-- 🔍 Transparent — you can inspect exactly what context gets sent
-- 🎯 Token-aware — every call shows the reduction
-- ⚙️ Developer-controlled — no vendor lock-in, no cloud dependency
-
-Think: **Vite, but for LLM context.**
-
----
-
-## 🧪 CLI commands
+## CLI commands
 
 The CLI is the setup and admin interface. Use it to init, index, debug, and diagnose — not as the primary interface.
 
@@ -174,12 +138,13 @@ brain-cache index                     Build/rebuild the vector index
 brain-cache search "auth middleware"  Manual search (useful for debugging)
 brain-cache context "auth flow"       Manual context building (useful for debugging)
 brain-cache ask "how does auth work?" Direct Claude query via CLI
+brain-cache status                    Show index and system status
 brain-cache doctor                    Check system health
 ```
 
 ---
 
-## 📊 Token savings
+## Token savings
 
 Every call shows exactly what was saved:
 
@@ -187,41 +152,25 @@ Every call shows exactly what was saved:
 context: 1,240 tokens (93% reduction)
 ```
 
-Less noise → better reasoning → cheaper usage.
-
----
-
-## 🧠 Built with GSD
-
-This project uses the GSD (Get Shit Done) framework — an AI-driven workflow for going from idea → research → plan → execution. brain-cache is both a product of that philosophy and a tool that makes it work better: tight context, better outcomes.
-
----
-
-## ⚠️ Status
-
-Early stage — actively improving:
-
-- ⏳ reranking (planned)
-- ⏳ context compression
-- ⏳ live indexing (watch mode)
+Less noise — better reasoning — cheaper usage.
 
 ---
 
-## 🛠 Requirements
+## Requirements
 
-- Node.js 22+
-- Ollama running locally (`nomic-embed-text` model)
+- Node.js >= 22
+- Ollama running locally (`nomic-embed-text` model recommended)
 - Anthropic API key (for `ask` command only)
 
 ---
 
-## ⭐️ If this is useful
+## If this is useful
 
 Give it a star — or try it on your repo and let me know what breaks.
 
 ---
 
-## 📄 License
+## License
 
 MIT — see LICENSE for details.
 

package/dist/{askCodebase-BZIXS3EV.js → askCodebase-EE32B7BP.js}

@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 import {
   runBuildContext
-} from "./chunk-JZQWPHAQ.js";
-import "./chunk-ZKVZTDND.js";
+} from "./chunk-KMRPAVMM.js";
+import "./chunk-DFFMV3RR.js";
+import "./chunk-4IOR54GU.js";
+import "./chunk-3HQRTLBH.js";
 import {
   formatTokenSavings
-} from "./chunk-ZGYLHFHJ.js";
-import "./chunk-SBSMKI4B.js";
-import "./chunk-KQZSBRRH.js";
-import "./chunk-FQL4HV4R.js";
-import "./chunk-Y7BU7IYX.js";
-import "./chunk-PJQNHMQH.js";
+} from "./chunk-6C2OYMKD.js";
+import "./chunk-RKPICQU7.js";
+import "./chunk-HRJ3OT6Q.js";
+import "./chunk-DPH5X5HL.js";
 import {
   childLogger
-} from "./chunk-EEC7KYPY.js";
+} from "./chunk-TXLCXXKY.js";
 
 // src/workflows/askCodebase.ts
 import Anthropic from "@anthropic-ai/sdk";

package/dist/buildContext-GWVDAYH6.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  runBuildContext
+} from "./chunk-KMRPAVMM.js";
+import "./chunk-DFFMV3RR.js";
+import "./chunk-4IOR54GU.js";
+import "./chunk-3HQRTLBH.js";
+import "./chunk-RKPICQU7.js";
+import "./chunk-HRJ3OT6Q.js";
+import "./chunk-DPH5X5HL.js";
+import "./chunk-TXLCXXKY.js";
+export {
+  runBuildContext
+};

package/dist/{chunk-Y7BU7IYX.js → chunk-3HQRTLBH.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   IndexStateSchema
-} from "./chunk-PJQNHMQH.js";
+} from "./chunk-DPH5X5HL.js";
 import {
   DEFAULT_EMBEDDING_DIMENSION,
   EMBEDDING_DIMENSIONS,
@@ -9,7 +9,7 @@ import {
   PROJECT_DATA_DIR,
   VECTOR_INDEX_THRESHOLD,
   childLogger
-} from "./chunk-EEC7KYPY.js";
+} from "./chunk-TXLCXXKY.js";
 
 // src/services/lancedb.ts
 import * as lancedb from "@lancedb/lancedb";
@@ -18,6 +18,12 @@ import { Schema, Field, Utf8, Int32, Float32, FixedSizeList } from "apache-arrow
 import { join } from "path";
 import { readFile, writeFile, mkdir } from "fs/promises";
 var log = childLogger("lancedb");
+var _writeMutex = Promise.resolve();
+function withWriteLock(fn) {
+  const next = _writeMutex.then(() => fn());
+  _writeMutex = next.then(() => void 0, () => void 0);
+  return next;
+}
 function chunkSchema(dim) {
   return new Schema([
     new Field("id", new Utf8(), false),
@@ -35,6 +41,16 @@ function chunkSchema(dim) {
     )
   ]);
 }
+function edgeSchema() {
+  return new Schema([
+    new Field("from_chunk_id", new Utf8(), false),
+    new Field("from_file", new Utf8(), false),
+    new Field("from_symbol", new Utf8(), true),
+    new Field("to_symbol", new Utf8(), false),
+    new Field("to_file", new Utf8(), true),
+    new Field("edge_type", new Utf8(), false)
+  ]);
+}
 async function openDatabase(projectRoot) {
   const dataDir = join(projectRoot, PROJECT_DATA_DIR);
   await mkdir(dataDir, { recursive: true });
@@ -52,6 +68,10 @@ async function openOrCreateChunkTable(db, projectRoot, model, dim) {
         "Embedding model or dimension changed \u2014 dropping and recreating chunks table"
       );
       await db.dropTable("chunks");
+      if (tableNames.includes("edges")) {
+        await db.dropTable("edges");
+        log.warn("Also dropped edges table (stale chunk IDs)");
+      }
     } else {
       log.info({ model, dim }, "Opened existing chunks table");
       return db.openTable("chunks");
@@ -67,8 +87,10 @@ async function insertChunks(table, rows) {
   if (rows.length === 0) {
     return;
   }
-  await table.add(rows);
-  log.debug({ count: rows.length }, "Inserted chunk rows");
+  await withWriteLock(async () => {
+    await table.add(rows);
+    log.debug({ count: rows.length }, "Inserted chunk rows");
+  });
 }
 async function createVectorIndexIfNeeded(table, embeddingModel) {
   const rowCount = await table.countRows();
@@ -135,10 +157,49 @@ async function writeFileHashes(projectRoot, hashes) {
 }
 async function deleteChunksByFilePath(table, filePath) {
   const escaped = filePath.replace(/'/g, "''");
-  await table.delete(`file_path = '${escaped}'`);
+  await withWriteLock(async () => {
+    await table.delete(`file_path = '${escaped}'`);
+  });
+}
+async function openOrCreateEdgesTable(db, opts) {
+  const tableNames = await db.tableNames();
+  if (tableNames.includes("edges")) {
+    if (opts?.shouldReset) {
+      log.warn("Resetting edges table (chunks table was recreated)");
+      await db.dropTable("edges");
+    } else {
+      log.info("Opened existing edges table");
+      return db.openTable("edges");
+    }
+  }
+  const schema = edgeSchema();
+  const emptyData = lancedb.makeArrowTable([], { schema });
+  const table = await db.createTable("edges", emptyData, { mode: "overwrite" });
+  log.info("Created new edges table");
+  return table;
+}
+async function insertEdges(table, edges) {
+  if (edges.length === 0) return;
+  const rows = edges.map((e) => ({
+    from_chunk_id: e.fromChunkId,
+    from_file: e.fromFile,
+    from_symbol: e.fromSymbol,
+    to_symbol: e.toSymbol,
+    to_file: e.toFile,
+    edge_type: e.edgeType
+  }));
+  await withWriteLock(async () => {
+    await table.add(rows);
+    log.debug({ count: rows.length }, "Inserted edge rows");
+  });
+}
+async function queryEdgesFrom(edgesTable, fromChunkId) {
+  const escaped = fromChunkId.replace(/'/g, "''");
+  return edgesTable.query().where(`from_chunk_id = '${escaped}'`).toArray();
 }
 
 export {
+  withWriteLock,
   openDatabase,
   openOrCreateChunkTable,
   insertChunks,
@@ -147,5 +208,8 @@ export {
   writeIndexState,
   readFileHashes,
   writeFileHashes,
-  deleteChunksByFilePath
+  deleteChunksByFilePath,
+  openOrCreateEdgesTable,
+  insertEdges,
+  queryEdgesFrom
 };

package/dist/{chunk-ZKVZTDND.js → chunk-4IOR54GU.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   childLogger
-} from "./chunk-EEC7KYPY.js";
+} from "./chunk-TXLCXXKY.js";
 
 // src/services/tokenCounter.ts
 import { countTokens } from "@anthropic-ai/tokenizer";
@@ -36,5 +36,6 @@ function assembleContext(chunks, opts) {
 
 export {
   countChunkTokens,
+  formatChunk,
   assembleContext
 };

package/dist/chunk-6C2OYMKD.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// src/lib/format.ts
+import dedent from "dedent";
+function formatTokenSavings(input) {
+  const fileSuffix = input.filesInContext !== 1 ? "s" : "";
+  return [
+    `Tokens sent to Claude: ${input.tokensSent.toLocaleString()}`,
+    `Estimated without: ~${input.estimatedWithout.toLocaleString()}  (${input.filesInContext} file${fileSuffix} + overhead)`,
+    `Reduction: ${input.reductionPct}%`
+  ].join("\n");
+}
+
+export {
+  formatTokenSavings
+};