brain-cache 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Winter
+
+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 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.

package/README.md

@@ -0,0 +1,215 @@
+# brain-cache
+
+> Stop sending your entire repo to Claude.
+
+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 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. Once configured, Claude automatically calls brain-cache tools instead of reading raw files — no prompting required.
+
+```json
+// .claude/settings.json
+{
+  "mcpServers": {
+    "brain-cache": {
+      "command": "brain-cache",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+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.
+
+---
+
+## ⚡ 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
+
+---
+
+## 🧠 How it works
+
+brain-cache is the layer between your codebase and Claude.
+
+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
+
+AI should read the right parts — and nothing else. brain-cache is the layer that makes that possible.
+
+---
+
+## 🔥 Example
+
+```
+> "Explain the overall architecture of this project"
+
+brain-cache: context assembled (74 tokens, 97% reduction)
+
+Tokens sent to Claude:     74
+Estimated without:         ~2,795
+Reduction:                 97%
+```
+
+Claude gets only what matters → answers are sharper and grounded.
+
+---
+
+## ⚡ Quick start
+
+**Step 1: Install**
+
+```
+npm install -g brain-cache
+```
+
+**Step 2: Init and index your project**
+
+```
+brain-cache init
+brain-cache index
+```
+
+`brain-cache init` appends MCP tool instructions to your `CLAUDE.md` — so Claude knows when and how to prefer brain-cache tools over built-in file reading. Runs once; won’t duplicate.
+
+**Step 3: Add MCP server to Claude Code**
+
+```json
+// .claude/settings.json
+{
+  "mcpServers": {
+    "brain-cache": {
+      "command": "brain-cache",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+**Step 4: Use Claude normally**
+
+brain-cache tools are called automatically. You don’t change how you work — the context just gets better.
+
+---
+
+## 🧩 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
+
+The CLI is the setup and admin interface. Use it to init, index, debug, and diagnose — not as the primary interface.
+
+```
+brain-cache init                      Initialize brain-cache in a project
+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 doctor                    Check system health
+```
+
+---
+
+## 📊 Token savings
+
+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)
+
+---
+
+## 🛠 Requirements
+
+- Node.js 22+
+- Ollama running locally (`nomic-embed-text` model)
+- Anthropic API key (for `ask` command only)
+
+---
+
+## ⭐️ If this is useful
+
+Give it a star — or try it on your repo and let me know what breaks.
+
+---
+
+## 📄 License
+
+MIT — see LICENSE for details.
+
+---

package/dist/askCodebase-ECDSSTQ6.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import {
+  formatTokenSavings
+} from "./chunk-GGOUKACO.js";
+import {
+  runBuildContext
+} from "./chunk-7JLSJNKU.js";
+import "./chunk-OKWMQNH6.js";
+import "./chunk-ZLB4VJQK.js";
+import "./chunk-WCNMLSL2.js";
+import "./chunk-P7WSTGLE.js";
+import "./chunk-XXWJ57QP.js";
+import "./chunk-PA4BZBWS.js";
+import {
+  childLogger
+} from "./chunk-PDQXJSH4.js";
+
+// src/workflows/askCodebase.ts
+import Anthropic from "@anthropic-ai/sdk";
+var log = childLogger("ask-codebase");
+var DEFAULT_CLAUDE_MODEL = "claude-sonnet-4-20250514";
+var DEFAULT_MAX_RESPONSE_TOKENS = 4096;
+var SYSTEM_PROMPT = `You are a codebase assistant. Answer questions strictly based on the provided codebase context.
+
+- Do not hallucinate or infer implementation details not present in the provided context.
+- Prioritize code-level explanations and reference specific files and functions when available.
+- If the provided context is insufficient to answer the question, say "I don't see enough context to answer that" rather than guessing.
+- Be precise and grounded in the actual code shown.`;
+async function runAskCodebase(question, opts) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new Error("ANTHROPIC_API_KEY environment variable is not set.");
+  }
+  const buildOpts = {
+    maxTokens: opts?.maxContextTokens,
+    path: opts?.path
+  };
+  const contextResult = await runBuildContext(question, buildOpts);
+  process.stderr.write(
+    `brain-cache: context assembled
+${formatTokenSavings({ tokensSent: contextResult.metadata.tokensSent, estimatedWithout: contextResult.metadata.estimatedWithoutBraincache, reductionPct: contextResult.metadata.reductionPct })}
+`
+  );
+  const model = process.env.BRAIN_CACHE_CLAUDE_MODEL ?? DEFAULT_CLAUDE_MODEL;
+  const maxTokens = opts?.maxResponseTokens ?? DEFAULT_MAX_RESPONSE_TOKENS;
+  const client = new Anthropic();
+  const response = await client.messages.create({
+    model,
+    max_tokens: maxTokens,
+    system: SYSTEM_PROMPT,
+    messages: [
+      {
+        role: "user",
+        content: `Here is relevant context from the codebase:
+
+${contextResult.content}
+
+Question: ${question}`
+      }
+    ]
+  });
+  const textBlock = response.content.find((b) => b.type === "text");
+  const answer = textBlock?.text ?? "(no text response from Claude)";
+  log.info(
+    {
+      model,
+      inputTokens: response.usage?.input_tokens,
+      outputTokens: response.usage?.output_tokens
+    },
+    "ask-codebase complete"
+  );
+  return {
+    answer,
+    contextMetadata: {
+      tokensSent: contextResult.metadata.tokensSent,
+      estimatedWithoutBraincache: contextResult.metadata.estimatedWithoutBraincache,
+      reductionPct: contextResult.metadata.reductionPct
+    },
+    model
+  };
+}
+export {
+  runAskCodebase
+};

package/dist/buildContext-6755TRND.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import {
+  runBuildContext
+} from "./chunk-7JLSJNKU.js";
+import "./chunk-OKWMQNH6.js";
+import "./chunk-ZLB4VJQK.js";
+import "./chunk-WCNMLSL2.js";
+import "./chunk-P7WSTGLE.js";
+import "./chunk-XXWJ57QP.js";
+import "./chunk-PA4BZBWS.js";
+import "./chunk-PDQXJSH4.js";
+export {
+  runBuildContext
+};

package/dist/chunk-7JLSJNKU.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import {
+  assembleContext,
+  countChunkTokens
+} from "./chunk-OKWMQNH6.js";
+import {
+  RETRIEVAL_STRATEGIES,
+  classifyQueryIntent,
+  deduplicateChunks,
+  searchChunks
+} from "./chunk-ZLB4VJQK.js";
+import {
+  embedBatchWithRetry
+} from "./chunk-WCNMLSL2.js";
+import {
+  isOllamaRunning
+} from "./chunk-P7WSTGLE.js";
+import {
+  openDatabase,
+  readIndexState
+} from "./chunk-XXWJ57QP.js";
+import {
+  readProfile
+} from "./chunk-PA4BZBWS.js";
+import {
+  DEFAULT_TOKEN_BUDGET
+} from "./chunk-PDQXJSH4.js";
+
+// src/workflows/buildContext.ts
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+async function runBuildContext(query, opts) {
+  const profile = await readProfile();
+  if (profile === null) {
+    throw new Error("No profile found. Run 'brain-cache init' first.");
+  }
+  const running = await isOllamaRunning();
+  if (!running) {
+    throw new Error("Ollama is not running. Start it with 'ollama serve' or run 'brain-cache init'.");
+  }
+  const rootDir = resolve(opts?.path ?? ".");
+  const indexState = await readIndexState(rootDir);
+  if (indexState === null) {
+    throw new Error(`No index found at ${rootDir}. Run 'brain-cache index' first.`);
+  }
+  const db = await openDatabase(rootDir);
+  const tableNames = await db.tableNames();
+  if (!tableNames.includes("chunks")) {
+    throw new Error("No chunks table found. Run 'brain-cache index' first.");
+  }
+  const table = await db.openTable("chunks");
+  const intent = classifyQueryIntent(query);
+  const strategy = {
+    limit: opts?.limit ?? RETRIEVAL_STRATEGIES[intent].limit,
+    distanceThreshold: RETRIEVAL_STRATEGIES[intent].distanceThreshold
+  };
+  const maxTokens = opts?.maxTokens ?? DEFAULT_TOKEN_BUDGET;
+  process.stderr.write(
+    `brain-cache: building context (intent=${intent}, budget=${maxTokens} tokens)
+`
+  );
+  const vectors = await embedBatchWithRetry(indexState.embeddingModel, [query]);
+  const queryVector = vectors[0];
+  const results = await searchChunks(table, queryVector, strategy);
+  const deduped = deduplicateChunks(results);
+  const assembled = assembleContext(deduped, { maxTokens });
+  const uniqueFiles = [...new Set(assembled.chunks.map((c) => c.filePath))];
+  let estimatedWithoutBraincache = 0;
+  for (const filePath of uniqueFiles) {
+    try {
+      const fileContent = await readFile(filePath, "utf-8");
+      estimatedWithoutBraincache += countChunkTokens(fileContent);
+    } catch {
+    }
+  }
+  const reductionPct = estimatedWithoutBraincache > 0 ? Math.round((1 - assembled.tokenCount / estimatedWithoutBraincache) * 100) : 0;
+  const result = {
+    content: assembled.content,
+    chunks: assembled.chunks,
+    metadata: {
+      tokensSent: assembled.tokenCount,
+      estimatedWithoutBraincache,
+      reductionPct,
+      localTasksPerformed: ["embed_query", "vector_search", "dedup", "token_budget"],
+      cloudCallsMade: 0
+    }
+  };
+  process.stderr.write(
+    `brain-cache: context assembled (${assembled.tokenCount} tokens, ${reductionPct}% reduction, ${assembled.chunks.length} chunks)
+`
+  );
+  return result;
+}
+
+export {
+  runBuildContext
+};

package/dist/chunk-GGOUKACO.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// src/lib/format.ts
+function formatTokenSavings(input) {
+  const PAD = 27;
+  const lines = [
+    ["Tokens sent to Claude:", input.tokensSent.toLocaleString()],
+    ["Estimated without:", `~${input.estimatedWithout.toLocaleString()}`],
+    ["Reduction:", `${input.reductionPct}%`]
+  ];
+  return lines.map(([label, value]) => `${label.padEnd(PAD)}${value}`).join("\n");
+}
+
+export {
+  formatTokenSavings
+};

package/dist/chunk-OKWMQNH6.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import {
+  childLogger
+} from "./chunk-PDQXJSH4.js";
+
+// src/services/tokenCounter.ts
+import { countTokens } from "@anthropic-ai/tokenizer";
+var log = childLogger("tokenCounter");
+function countChunkTokens(text) {
+  if (text.length === 0) return 0;
+  return countTokens(text);
+}
+function formatChunk(chunk) {
+  return `// File: ${chunk.filePath} (lines ${chunk.startLine}-${chunk.endLine})
+${chunk.content}`;
+}
+function assembleContext(chunks, opts) {
+  const kept = [];
+  let totalTokens = 0;
+  const separator = "\n\n---\n\n";
+  const separatorTokens = countChunkTokens(separator);
+  for (const chunk of chunks) {
+    const formatted = formatChunk(chunk);
+    const chunkTokens = countChunkTokens(formatted);
+    const sepCost = kept.length > 0 ? separatorTokens : 0;
+    if (totalTokens + chunkTokens + sepCost > opts.maxTokens) {
+      log.debug({ totalTokens, chunkTokens, maxTokens: opts.maxTokens }, "Token budget reached");
+      break;
+    }
+    kept.push(chunk);
+    totalTokens += chunkTokens + sepCost;
+  }
+  const content = kept.map(formatChunk).join(separator);
+  return { content, chunks: kept, tokenCount: totalTokens };
+}
+
+export {
+  countChunkTokens,
+  assembleContext
+};

package/dist/chunk-P7WSTGLE.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import {
+  childLogger
+} from "./chunk-PDQXJSH4.js";
+
+// src/services/ollama.ts
+import { execFile, spawn } from "child_process";
+import { promisify } from "util";
+import ollama from "ollama";
+var execFileAsync = promisify(execFile);
+var log = childLogger("ollama");
+function getOllamaHost() {
+  return process.env.OLLAMA_HOST ?? "http://localhost:11434";
+}
+async function isOllamaInstalled() {
+  try {
+    const cmd = process.platform === "win32" ? "where" : "which";
+    await execFileAsync(cmd, ["ollama"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isOllamaRunning() {
+  try {
+    const res = await fetch(getOllamaHost());
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function startOllama() {
+  const host = getOllamaHost();
+  const isLocalhost = host === "http://localhost:11434" || host === "http://127.0.0.1:11434";
+  if (!isLocalhost) {
+    throw new Error(
+      `OLLAMA_HOST is set to a remote address (${host}). brain-cache cannot auto-start a remote Ollama server. Ensure Ollama is running at ${host} and try again.`
+    );
+  }
+  const alreadyRunning = await isOllamaRunning();
+  if (alreadyRunning) {
+    log.info("Ollama is already running, skipping spawn");
+    return true;
+  }
+  log.info("Starting Ollama server...");
+  const child = spawn("ollama", ["serve"], {
+    detached: true,
+    stdio: "ignore"
+  });
+  const pid = child.pid;
+  child.unref();
+  const MAX_ATTEMPTS = 10;
+  const POLL_INTERVAL_MS = 500;
+  const cleanup = () => {
+    try {
+      if (pid !== void 0) process.kill(pid, "SIGTERM");
+    } catch {
+    }
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+  let succeeded = false;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    const running = await isOllamaRunning();
+    if (running) {
+      log.info({ pid, attempt: attempt + 1 }, "Ollama is now running");
+      succeeded = true;
+      break;
+    }
+    log.debug({ attempt: attempt + 1, maxAttempts: MAX_ATTEMPTS }, "Waiting for Ollama to start...");
+  }
+  process.removeListener("SIGINT", cleanup);
+  process.removeListener("SIGTERM", cleanup);
+  if (succeeded) {
+    return true;
+  }
+  try {
+    if (pid !== void 0) process.kill(pid, "SIGTERM");
+  } catch {
+  }
+  log.warn({ pid }, "Ollama did not start within timeout \u2014 killed spawned process (PID: " + pid + ")");
+  return false;
+}
+function modelMatches(listedName, profileModel) {
+  const listedBase = listedName.split(":")[0];
+  const profileBase = profileModel.split(":")[0];
+  return listedBase === profileBase;
+}
+async function pullModelIfMissing(model, onProgress) {
+  const list = await ollama.list();
+  const alreadyExists = list.models.some((m) => modelMatches(m.name, model));
+  if (alreadyExists) {
+    log.info({ model }, "Model already present, skipping pull");
+    return;
+  }
+  log.info({ model }, "Model not found locally, pulling...");
+  const defaultProgress = (status) => {
+    process.stderr.write(`\rPulling ${model}: ${status}`);
+  };
+  const progress = onProgress ?? defaultProgress;
+  let lastStatus = "";
+  const stream = await ollama.pull({ model, stream: true });
+  for await (const chunk of stream) {
+    const pct = chunk.total ? ` ${Math.round((chunk.completed ?? 0) / chunk.total * 100)}%` : "";
+    const status = `${chunk.status}${pct}`;
+    if (status !== lastStatus) {
+      progress(status);
+      lastStatus = status;
+    }
+  }
+  if (!onProgress) process.stderr.write("\n");
+  log.info({ model }, "Model pull complete");
+}
+async function getOllamaVersion() {
+  try {
+    const { stdout } = await execFileAsync("ollama", ["--version"]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+export {
+  isOllamaInstalled,
+  isOllamaRunning,
+  startOllama,
+  modelMatches,
+  pullModelIfMissing,
+  getOllamaVersion
+};