project-brain 0.2.0

package/README.md

@@ -0,0 +1,158 @@
+# project-brain
+
+Local-first MCP server that gives AI tools semantic memory of your codebase.
+
+project-brain indexes your project files into a local LanceDB vector store using Ollama embeddings. Once indexed, AI assistants connected via MCP can search your codebase semantically, track module documentation, and maintain knowledge that persists across sessions.
+
+## Quick Start
+
+```bash
+# 1. Install globally
+bun install -g project-brain
+
+# 2. One-time: register in your AI tools (Claude, Codex, Cursor, Gemini)
+project-brain setup
+
+# 3. Per-project: initialize, index, and install git hook
+cd my-project
+project-brain init
+```
+
+After `init`, the following run **automatically** without any extra steps:
+
+| Trigger | What happens |
+|---|---|
+| `git commit` | git hook runs `project-brain sync` — keeps the index fresh |
+| File save (while server is running) | File watcher detects the change and re-indexes it |
+| AI tool connects | MCP server starts on stdio, tools are ready |
+
+## Prerequisites
+
+- **Bun** ≥ 1.3.14 — required runtime ([install](https://bun.sh))
+- **Ollama** (optional, for semantic search) — download from [ollama.com](https://ollama.com). Pull `nomic-embed-text` for embeddings: `ollama pull nomic-embed-text`
+
+## Install
+
+### Registry (recommended)
+
+```bash
+bun install -g project-brain
+# or
+npm install -g project-brain
+```
+
+### Standalone binary (no runtime required)
+
+```bash
+git clone https://github.com/jcsoftdev/project-brain
+cd project-brain
+bun build ./src/cli.ts --compile --outfile project-brain
+./project-brain --help
+```
+
+## Usage modes
+
+project-brain runs in two modes — CLI and inside AI tools. Both call the same underlying commands.
+
+### CLI (terminal)
+
+Run commands directly from your terminal in any project directory.
+
+### Inside AI tools (slash commands)
+
+Once `project-brain setup` has registered the MCP server in your AI tool, you can invoke commands as slash commands from within Claude Code, Codex, Cursor, or any MCP-compatible AI:
+
+| Slash command | Equivalent CLI | What it does |
+|---|---|---|
+| `/brain-setup` | `project-brain setup` | One-time global registration in AI tools |
+| `/brain-init` | `project-brain init` | Initialize current project + index + git hook |
+| `/brain-sync` | `project-brain sync` | Incremental sync of changed files |
+| `/brain-reindex` | `project-brain reindex` | Drop and rebuild full index |
+| `/brain-health` | `project-brain health` | Diagnose Ollama, index staleness, git hook |
+
+The slash commands are Claude Code skills installed globally at `~/.claude/skills/brain-*/SKILL.md`. They work in any session regardless of the current project.
+
+## Commands
+
+### `setup`
+
+One-time global setup. Detects your environment and registers project-brain with AI tools (Claude, Cursor, Gemini, Codex).
+
+```bash
+project-brain setup
+```
+
+### `init`
+
+Initialize a project. Detects the stack, writes a `CLAUDE.md` with MCP instructions, installs a git hook, scaffolds module stubs in `docs/modules/`, and indexes the project.
+
+```bash
+project-brain init [--skip-index]
+```
+
+- `--skip-index` — skip the initial index pass (useful when Ollama is not yet running)
+
+### `sync`
+
+Incremental sync — re-indexes files that changed since the last sync.
+
+```bash
+project-brain sync
+```
+
+### `reindex`
+
+Full re-index — drops and rebuilds the entire vector index for the current project.
+
+```bash
+project-brain reindex
+```
+
+### `health`
+
+Check system health: Ollama availability, LanceDB status, and staleness of the index.
+
+```bash
+project-brain health
+```
+
+### `serve`
+
+Start the MCP server. Default mode uses stdio (for local AI tool connections).
+
+```bash
+project-brain serve
+```
+
+#### `serve --http`
+
+Start the MCP server over Streamable HTTP with bearer-token authentication. Useful for remote access or multi-client setups.
+
+```bash
+BRAIN_HTTP_TOKEN=your-secret project-brain serve --http [--port 3000]
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `BRAIN_HTTP_PORT` | `3000` | Port for HTTP server mode |
+| `BRAIN_HTTP_TOKEN` | — | **Required** for `serve --http`. Bearer secret. |
+| `BRAIN_DATA_DIR` | `~/.project-brain/data` | LanceDB data directory |
+| `BRAIN_EMBED_MODEL` | `nomic-embed-text` | Ollama embedding model name |
+
+## Module Documentation Workflow
+
+When you run `project-brain init`, it detects top-level source directories and creates stub files in `docs/modules/<name>.md`. These stubs are indexed immediately so semantic search works even before they are filled.
+
+To populate a stub:
+1. Open a project session with your AI assistant.
+2. The AI reads `CLAUDE.md` and finds the `## Module Documentation` section.
+3. The AI fills each stub (Purpose, Key Files, Dependencies, Data Flow, Gotchas, Last Updated).
+4. The AI calls `add_knowledge` with the filled content so it is vectorized into project-brain.
+
+Run `project-brain sync` after filling stubs to ensure they are re-indexed with their full content.
+
+## Author
+
+[jcsoftdev](https://github.com/jcsoftdev)

package/bin/project-brain

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const nativeBin = join(__dirname, "project-brain-native");
+
+if (!existsSync(nativeBin)) {
+  console.error("project-brain: binary not found. Run `npm install` to download it.");
+  process.exit(1);
+}
+
+execFileSync(nativeBin, process.argv.slice(2), { stdio: "inherit" });

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "project-brain",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Local-first MCP server that gives AI tools semantic memory of your codebase.",
+  "author": "jcsoftdev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jcsoftdev/project-brain.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "rag",
+    "codebase",
+    "embeddings",
+    "lancedb",
+    "ollama"
+  ],
+  "files": [
+    "bin",
+    "scripts",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "project-brain": "bin/project-brain"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "test": "bun test",
+    "setup": "bun run src/cli.ts setup",
+    "init": "bun run src/cli.ts init",
+    "build": "bun build ./src/cli.ts --compile --outfile dist/project-brain",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@lancedb/lancedb": "^0.30.0",
+    "ollama": "^0.6.3",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "@lancedb/lancedb-darwin-arm64": "0.30.0",
+    "@lancedb/lancedb-linux-x64-gnu": "0.30.0",
+    "@lancedb/lancedb-linux-arm64-gnu": "0.30.0",
+    "@lancedb/lancedb-linux-x64-musl": "0.30.0",
+    "@lancedb/lancedb-linux-arm64-musl": "0.30.0",
+    "@lancedb/lancedb-win32-x64-msvc": "0.30.0",
+    "@lancedb/lancedb-win32-arm64-msvc": "0.30.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.5.4"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { createWriteStream, mkdirSync, chmodSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { get } from "https";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  await import("fs").then((fs) =>
+    fs.promises.readFile(join(__dirname, "../package.json"), "utf-8")
+  )
+);
+
+const VERSION = pkg.version;
+const REPO = "jcsoftdev/project-brain";
+
+const platform = process.platform; // darwin, linux, win32
+const arch = process.arch; // arm64, x64
+
+const targetMap = {
+  "darwin-arm64": "darwin-arm64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+  "win32-x64": "windows-x64",
+  "win32-arm64": "windows-arm64",
+};
+
+const key = `${platform}-${arch}`;
+const target = targetMap[key];
+
+if (!target) {
+  console.error(`project-brain: unsupported platform ${key}. Skipping binary download.`);
+  process.exit(0);
+}
+
+const ext = platform === "win32" ? ".exe" : "";
+const binaryName = `project-brain-${target}${ext}`;
+const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${binaryName}`;
+const destDir = join(__dirname, "../bin");
+const destPath = join(destDir, `project-brain-native${ext}`);
+
+if (existsSync(destPath)) {
+  process.exit(0);
+}
+
+mkdirSync(destDir, { recursive: true });
+
+console.log(`project-brain: downloading binary for ${key}...`);
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+    const request = (u) =>
+      get(u, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return request(res.headers.location);
+        }
+        if (res.statusCode !== 200) {
+          reject(new Error(`HTTP ${res.statusCode} for ${u}`));
+          return;
+        }
+        res.pipe(file);
+        file.on("finish", () => file.close(resolve));
+      }).on("error", reject);
+    request(url);
+  });
+}
+
+try {
+  await download(url, destPath);
+  chmodSync(destPath, 0o755);
+  console.log(`project-brain: binary installed.`);
+} catch (err) {
+  console.error(`project-brain: failed to download binary — ${err.message}`);
+  console.error(`project-brain: manual download: ${url}`);
+  process.exit(0);
+}