@nano-step/nano-brain 2026.1.14 → 2026.5.25-beta.25

package/README.md

@@ -1,297 +1,280 @@
 # nano-brain
 
-Persistent memory system for AI coding agents. Hybrid search (BM25 + vector + LLM reranking) across past sessions, codebase, curated notes, and daily logs.
+**Persistent memory and code intelligence for AI coding agents.**
+
+[![Go 1.23](https://img.shields.io/badge/Go-1.23-00ADD8?logo=go)](https://go.dev/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-nano--step%2Fnano--brain-181717?logo=github)](https://github.com/nano-step/nano-brain)
 
 ## What It Does
 
-An MCP server that gives AI coding agents persistent memory across sessions. Indexes markdown documents, past sessions, and daily logs into a searchable SQLite database with FTS5 and vector embeddings. Provides 10 MCP tools for search, retrieval, and memory management using a sophisticated hybrid search pipeline with query expansion, RRF fusion, and neural reranking.
+nano-brain is a persistent memory server for AI coding agents that solves session amnesia. It automatically ingests AI sessions, notes, and codebase files, indexes everything with hybrid search (BM25 + pgvector), and serves memories via MCP tools and REST API. Built in Go with PostgreSQL — single static binary, zero CGO dependencies.
 
-Inspired by [QMD](https://github.com/tobi/qmd) and [OpenClaw](https://github.com/openclaw/openclaw).
+## Key Features
 
-## Architecture
+- **Hybrid search** — BM25 full-text + pgvector HNSW cosine similarity + RRF fusion + recency decay
+- **9 MCP tools** — query, search, vsearch, get, write, tags, status, update, wake_up
+- **Session harvesting** — auto-ingest OpenCode and Claude Code sessions
+- **File watcher** — fsnotify-based directory monitoring with debounce
+- **Content-addressed storage** — SHA-256 deduplication
+- **Heading-aware markdown chunking**
+- **Multi-workspace isolation** with per-workspace data
+- **Config hot-reload** — `POST /api/reload-config`
+- **V1 migration** — import from SQLite (pure Go, no CGO)
+- **Benchmarking suite** — generate, run, compare, stress
+- **Search telemetry** — local-only, 90-day retention, non-blocking
 
-```
-User Query
-    │
-    ▼
-┌─────────────────┐
-│ Query Expansion  │ ← qmd-query-expansion-1.7B (GGUF)
-│ (optional)       │   generates 2-3 query variants
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    ▼         ▼
-┌────────┐ ┌──────────┐
-│ BM25   │ │ Vector   │
-│ (FTS5) │ │(sqlite-  │
-│        │ │  vec)    │
-└───┬────┘ └────┬─────┘
-    │           │
-    ▼           ▼
-┌─────────────────┐
-│  RRF Fusion     │ ← k=60, original query 2× weight
-│                 │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│  LLM Reranking  │ ← bge-reranker-v2-m3 (GGUF)
-│  (optional)     │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Position-Aware  │ ← top 3: 75/25, 4-10: 60/40, 11+: 40/60
-│ Blending        │   (RRF weight / rerank weight)
-└────────┬────────┘
-         │
-         ▼
-    Final Results
-```
+## Prerequisites
 
-## How It Works
+- **Go 1.23+** (building from source) OR pre-built binary
+- **PostgreSQL 17** with **pgvector 0.8.2** extension
+- **Embedding provider:** Ollama (default, local) or Voyage AI
 
-### Storage Layer
+## Quick Start
 
-- **SQLite** via better-sqlite3 for document metadata and content
-- **FTS5** virtual table with porter stemming for BM25 full-text search
-- **sqlite-vec** extension for vector similarity search (cosine distance)
-- **Content-addressed storage** using SHA-256 hash deduplication
+### Option A: Via npx (no Go required)
 
-### Chunking
+```bash
+# Start PostgreSQL + pgvector
+docker run -d --name nanobrain-pg -p 5432:5432 \
+  -e POSTGRES_USER=nanobrain -e POSTGRES_PASSWORD=nanobrain -e POSTGRES_DB=nanobrain_dev \
+  pgvector/pgvector:pg17
 
-Heading-aware markdown chunking that respects document structure:
+# Start Ollama + pull embedding model
+ollama pull nomic-embed-text
 
-- **Target size:** 900 tokens (~3600 characters)
-- **Overlap:** 15% between chunks (~540 characters)
-- **Respects boundaries:** Code fences, headings, paragraphs
-- **Break point scoring:** h1=100, h2=90, h3=80, code-fence=80, hr=60, blank-line=40
+# Check prerequisites
+npx @nano-step/nano-brain@beta doctor
 
-### Search Pipeline (3 Tiers)
+# Start server
+npx @nano-step/nano-brain@beta
+```
 
-**`memory_search`** — BM25 only (fast, exact keyword matching)
+> **Also available as:** `npx nano-brain@beta` (unscoped alias)
+>
+> **Note:** Do NOT run `npx nano-brain` from the nano-brain source directory — npm will resolve the local package instead of the registry. Run from any other directory.
 
-**`memory_vsearch`** — Vector only (semantic similarity via embeddings)
+### Option B: Build from source
 
-**`memory_query`** — Full hybrid pipeline:
-1. Query expansion generates 2-3 variants (optional)
-2. Parallel BM25 + vector search
-3. RRF fusion (k=60, original query weighted 2×)
-4. LLM reranking with bge-reranker-v2-m3 (optional)
-5. Position-aware blending:
-   - Top 3 results: 75% RRF / 25% rerank
-   - Ranks 4-10: 60% RRF / 40% rerank
-   - Ranks 11+: 40% RRF / 60% rerank
+```bash
+# Build
+CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
 
-### Collections
+# Start PostgreSQL + pgvector (example with Docker)
+docker run -d --name nanobrain-pg -p 5432:5432 \
+  -e POSTGRES_USER=nanobrain -e POSTGRES_PASSWORD=nanobrain -e POSTGRES_DB=nanobrain_dev \
+  pgvector/pgvector:pg17
 
-- **YAML-configured** directories of markdown files
-- **Auto-indexing** via chokidar file watcher
-- **Incremental updates** using dirty-flag tracking
-- **Session harvesting** converts OpenCode JSON sessions into searchable markdown
+# Start server
+DATABASE_URL="postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev" ./nano-brain
 
-## MCP Tools
+# Register workspace
+curl -X POST http://localhost:3100/api/v1/init \
+  -H "Content-Type: application/json" \
+  -d '{"root_path":"/path/to/project","name":"my-project"}'
 
-| Tool | Description |
-|------|-------------|
-| `memory_search` | BM25 keyword search (fast) |
-| `memory_vsearch` | Semantic vector search |
-| `memory_query` | Full hybrid search with expansion + reranking |
-| `memory_get` | Retrieve document by path or docid (#abc123) |
-| `memory_multi_get` | Batch retrieve by glob pattern |
-| `memory_write` | Write to daily log (tagged with workspace) |
-| `memory_status` | Index health, collections, model status |
-| `memory_index_codebase` | Index codebase files in current workspace |
-| `memory_update` | Trigger reindex of all collections |
-
-## Installation
-```bash
-npm install -g nano-brain
+# Write a document
+curl -X POST http://localhost:3100/api/v1/write \
+  -H "Content-Type: application/json" \
+  -d '{"workspace":"<hash>","source_path":"notes/decision.md","content":"# Decision\nUse PostgreSQL.","tags":["decision"]}'
+
+# Search
+curl -X POST http://localhost:3100/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{"workspace":"<hash>","query":"database decision"}'
 ```
 
-### Quick Start
+## Configuration
 
-```bash
-# Initialize (creates config, indexes codebase, generates embeddings)
-npx nano-brain init --root=/path/to/your/project
+Config file: `~/.nano-brain/config.yml`
 
-# Check everything is working
-npx nano-brain status
-```
+```yaml
+server:
+  host: localhost
+  port: 3100
 
-Add to your AI agent's MCP config (e.g. `~/.config/opencode/opencode.json`):
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "local",
-      "command": ["npx", "nano-brain", "mcp"],
-      "enabled": true
-    }
-  }
-}
-```
+database:
+  url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev
 
-## Configuration
-Create `~/.nano-brain/config.yml` (auto-generated by `init`):
-```yaml
-collections:
-  memory:
-    path: ~/.nano-brain/memory
-    pattern: "**/*.md"
-    update: auto
-  sessions:
-    path: ~/.nano-brain/sessions
-    pattern: "**/*.md"
-    update: auto
-
-# Embedding configuration
 embedding:
-  provider: ollama
-  url: http://localhost:11434        # Auto-detected: localhost natively, host.docker.internal in Docker
+  provider: ollama              # ollama or voyage
+  url: http://localhost:11434
   model: nomic-embed-text
+  dimension: 0                  # auto-detect from provider
+  concurrency: 3
+
+search:
+  rrf_k: 60
+  recency_weight: 0.3
+  recency_half_life_days: 180
+  limit: 20
+
+harvester:
+  opencode:
+    session_dir: ""             # e.g., ~/.local/share/opencode/storage
+  claudecode:
+    enabled: false
+    session_dir: ""
+
+watcher:
+  debounce_ms: 2000
+  reindex_interval: 300
+
+storage:
+  max_file_size: 314572800      # 300MB
+  max_size: 10737418240         # 10GB
+
+telemetry:
+  retention_days: 90
+
+logging:
+  level: info
+  file: ""                      # empty = stdout only
 ```
 
-**Collection options:**
-- `path` — Directory to index
-- `pattern` — Glob pattern for files
-- `update` — `auto` (watch for changes) or `manual`
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DATABASE_URL` | PostgreSQL connection string |
+| `VOYAGE_API_KEY` | Voyage AI API key |
+| `OPENCODE_STORAGE_DIR` | OpenCode session directory |
+| `NANO_BRAIN_*` | Override any config (e.g., `NANO_BRAIN_SERVER_PORT=3100`) |
+
+## REST API
+
+### Public Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| GET | `/api/status` | Server status with version, uptime, workspace stats |
+| POST | `/api/v1/init` | Register workspace |
+| GET | `/api/v1/workspaces` | List all workspaces (with doc counts) |
+| GET | `/api/v1/wake-up` | Workspace briefing |
+| POST | `/api/harvest` | Trigger session harvesting |
+| POST | `/api/reload-config` | Hot-reload configuration |
+
+### Workspace-Scoped Endpoints
+
+Workspace is passed in the JSON body for POST, query param for GET.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/v1/write` | Write/update document |
+| POST | `/api/v1/embed` | Trigger embedding |
+| POST | `/api/v1/search` | BM25 keyword search |
+| POST | `/api/v1/vsearch` | Vector similarity search |
+| POST | `/api/v1/query` | Hybrid search (BM25 + vector + RRF + recency) |
+| POST | `/api/v1/collections` | Add collection |
+| GET | `/api/v1/collections` | List collections |
+| PUT | `/api/v1/collections/:name` | Rename collection |
+| DELETE | `/api/v1/collections/:name` | Remove collection |
+| GET | `/api/v1/tags` | List tags with counts |
+| POST | `/api/v1/reindex` | Queue reindex (202) |
+| POST | `/api/v1/update` | Queue update (202) |
+| POST | `/api/v1/wake-up` | Workspace briefing with session_dir |
+
+### MCP Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET/POST | `/mcp` | Streamable HTTP (MCP 2025-03-26) |
+| GET/POST | `/sse` | SSE transport (legacy) |
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `nano-brain` (no args) | Start HTTP server (default: port 3100) |
+| `nano-brain init --root=<path>` | Register workspace |
+| `nano-brain write` | Write document via CLI |
+| `nano-brain query` | Hybrid search |
+| `nano-brain search` | BM25 keyword search |
+| `nano-brain vsearch` | Vector similarity search |
+| `nano-brain collection add\|remove\|list` | Manage collections |
+| `nano-brain harvest` | Trigger session harvesting |
+| `nano-brain bench generate\|run\|compare\|stress` | Benchmarking suite |
+| `nano-brain db:migrate` | Run pending goose migrations |
+| `nano-brain db:migrate --from-v1 <path>` | Import V1 SQLite data |
+| `nano-brain logs [-n 50] [-f]` | Tail log file |
+| `nano-brain docker start\|stop\|status` | Docker compose management |
+| `nano-brain status [--json]` | Server status |
+| `nano-brain doctor [--json]` | Check prerequisites (config, PostgreSQL, pgvector, Ollama, model) |
 
-**Embedding options:**
-- `provider` — `ollama` (default)
-- `url` — Ollama API URL (auto-detected during `init`)
-- `model` — Embedding model name (default: `nomic-embed-text`)
+## MCP Tools
 
-**Data directory layout (`~/.nano-brain/`):**
-```
-~/.nano-brain/
-├── config.yml    # Configuration
-├── data/         # SQLite databases (per-workspace)
-├── models/       # Embedding model cache
-├── memory/       # Curated notes
-└── sessions/     # Harvested sessions
-```
+nano-brain exposes 9 tools via MCP (Model Context Protocol):
 
-## CLI Usage
+| Tool | Description |
+|------|-------------|
+| `memory_query` | Hybrid search (BM25 + vector + RRF + recency) |
+| `memory_search` | BM25 keyword search |
+| `memory_vsearch` | Vector similarity search |
+| `memory_get` | Get document by path |
+| `memory_write` | Write/update document |
+| `memory_tags` | List tags with counts |
+| `memory_status` | Server and embedding status |
+| `memory_update` | Trigger re-embedding |
+| `memory_wake_up` | Workspace briefing |
+
+### MCP Configuration
 
-```bash
-# Setup
-nano-brain init               # Full initialization (config, index, embed, AGENTS.md)
-nano-brain init --root=/path  # Initialize for specific project
-# MCP server
-nano-brain mcp              # Start MCP server (stdio)
-nano-brain mcp --http       # Start MCP server (HTTP, port 8282)
-# Index management
-nano-brain status           # Show index health
-nano-brain update           # Reindex all collections
-# Search
-nano-brain search "query"   # BM25 search
-nano-brain vsearch "query"  # Vector search
-nano-brain query "query"    # Hybrid search
-# Collections
-nano-brain collection add <name> <path>     # Add collection
-nano-brain collection remove <name>         # Remove collection
-nano-brain collection list                  # List collections
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "remote",
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
 ```
 
-## Project Structure
+## Search Pipeline
 
 ```
-src/
-├── index.ts          # CLI entry point
-├── server.ts         # MCP server (10 tools, stdio/HTTP)
-├── store.ts          # SQLite storage (FTS5 + sqlite-vec)
-├── search.ts         # Hybrid search pipeline (RRF, reranking, blending)
-├── chunker.ts        # Heading-aware markdown chunking
-├── collections.ts    # YAML config, collection scanning
-├── embeddings.ts     # Embedding providers (Ollama API + GGUF fallback)
-├── reranker.ts       # GGUF reranker model (bge-reranker-v2-m3)
-├── expansion.ts      # GGUF query expansion (qmd-query-expansion-1.7B)
-├── harvester.ts      # OpenCode session → markdown converter
-├── watcher.ts        # File watcher (chokidar, dirty flags)
-└── types.ts          # TypeScript interfaces
-bin/
-└── cli.js            # CLI wrapper
-
-test/
-└── *.test.ts         # 428 tests (vitest)
-SKILL.md              # AI agent routing instructions (auto-loaded by OpenCode)
-AGENTS_SNIPPET.md     # Optional project-level AGENTS.md managed block
+Query --> BM25 (ts_rank_cd) ---+
+                               +--> RRF Fusion (k=60) --> Recency Decay --> Results
+Query --> Vector (HNSW cos) ---+
 ```
 
-## Tech Stack
-
-- **TypeScript + Node.js** (via tsx)
-- **better-sqlite3** + **sqlite-vec** for storage
-- **@modelcontextprotocol/sdk** for MCP server
-- **node-llama-cpp** for GGUF model inference
-- **chokidar** for file watching
-- **vitest** for testing (428 tests)
-
-## Models
-
-All models are GGUF format, loaded on-demand:
-
-- **Embeddings:** nomic-embed-text-v1.5 (~270MB)
-- **Reranker:** bge-reranker-v2-m3 (~1.1GB)
-- **Query Expansion:** qmd-query-expansion-1.7B (~1GB)
+- **BM25:** `websearch_to_tsquery` + `ts_rank_cd` on PostgreSQL tsvector
+- **Vector:** pgvector HNSW index with cosine distance
+- **RRF:** Reciprocal Rank Fusion (k=60), scores normalized to [0,1]
+- **Recency:** exponential half-life decay (default 180 days, weight 0.3)
 
-Models are downloaded automatically on first use to `~/.nano-brain/models/`.
-
-## How nano-brain Compares
-
-| | nano-brain | Mem0 / OpenMemory | Zep / Graphiti | OMEGA | Letta (MemGPT) | Claude Native |
-|---|---|---|---|---|---|---|
-| **Search** | Hybrid (BM25 + vector + LLM reranking) | Vector only | Graph traversal + vector | Semantic + BM25 | Agent-managed | Text file read |
-| **Storage** | SQLite (single file) | PostgreSQL + Qdrant | Neo4j | SQLite | PostgreSQL / SQLite | Flat text files |
-| **MCP Tools** | 10 | 4-9 | 9-10 | 12 | 7 | 0 |
-| **Local-First** | Yes (zero cloud) | Requires OpenAI API key | Requires Docker + Neo4j | Yes | Yes | Yes |
-| **AI Models** | Local GGUF (nomic-embed, bge-reranker) | Cloud API (OpenAI) | Cloud API | Local ONNX | Cloud API | None |
-| **Codebase Indexing** | Yes (structural boundary detection) | No | No | No | No | No |
-| **Session Recall** | Yes (auto-harvests past sessions) | No | No | No | No | Limited (CLAUDE.md) |
-| **Query Expansion** | Yes (local LLM) | No | No | No | No | No |
-| **LLM Reranking** | Yes (bge-reranker-v2-m3) | No | No | No | No | No |
-| **Privacy** | 100% local, no data leaves machine | Cloud API calls | Cloud or self-host | 100% local | Self-host or cloud | Local files |
-| **Dependencies** | SQLite + GGUF models (~1.5GB) | Docker + PostgreSQL + Qdrant + OpenAI key | Docker + Neo4j | SQLite + ONNX | PostgreSQL | None |
-| **Pricing** | Free (open source, MIT) | Free tier / Pro $249/mo | Free self-host / Cloud $25-475/mo | Free (Apache-2.0) | Free (Apache-2.0) | Free (with Claude) |
-| **GitHub Stars** | New | ~47K | ~23K | ~25 | ~21K | N/A |
-
-### Where nano-brain shines
-
-- **Hybrid search pipeline** — the only MCP memory server with BM25 + vector + query expansion + LLM reranking in a single pipeline
-- **Codebase indexing** — index your source files with structural boundary detection, not just conversations
-- **Session recall** — automatically harvests and indexes past AI coding sessions
-- **Zero dependencies** — single SQLite file, local GGUF models, no Docker/PostgreSQL/Neo4j/API keys
-- **Privacy** — 100% local processing, your code and conversations never leave your machine
-
-### Consider alternatives if
-
-- You need a knowledge graph with temporal reasoning (Zep/Graphiti)
-- You want a full agent framework, not just memory (Letta)
-- You need cloud-hosted memory shared across teams (Mem0 Cloud)
-- You only need basic session notes (Claude native memory)
-
-## AI Agent Integration
-
-nano-brain ships with a SKILL.md that teaches AI agents when and how to use memory tools. When loaded as an OpenCode skill, agents automatically:
-
-- **Check memory before starting work** — recall past decisions, patterns, and context
-- **Save context after completing work** — persist key decisions and debugging insights
-- **Route queries to the right search tool** — BM25 for exact terms, vector for concepts, hybrid for best quality
-
-### SKILL.md (Auto-loaded)
-
-The skill file at `SKILL.md` provides routing rules, trigger phrases, tool selection guides, and integration patterns. It's automatically loaded when any agent references the `nano-brain` skill.
+## Architecture
 
-### AGENTS_SNIPPET.md (Optional, project-level)
+- 15 internal packages: config, server, handlers, storage, sqlc, embed, search, watcher, harvest, mcp, migrate, telemetry, health, bench
+- 7 goose SQL migrations (embedded)
+- Constructor injection (no DI framework)
+- errgroup + context for goroutine lifecycle
+- Echo v4 middleware: workspace extraction, content-type enforcement, version header
 
-For project-level integration, `AGENTS_SNIPPET.md` provides a managed block that can be injected into a project's `AGENTS.md`:
+## Migration from V1
 
 ```bash
-npx nano-brain init --root=/path/to/project
+# Import V1 SQLite data to PostgreSQL
+nano-brain db:migrate --from-v1 /path/to/old/index.db
+
+# Idempotent — safe to run multiple times
+# Uses content-addressed SHA-256 hashing
+# Pure Go SQLite reader (modernc.org/sqlite, no CGO)
 ```
 
-See [SKILL.md](./SKILL.md) for full routing rules and [AGENTS_SNIPPET.md](./AGENTS_SNIPPET.md) for the project-level snippet.
+## Tech Stack
+
+- **Go 1.23** — compiled to single static binary (`CGO_ENABLED=0`)
+- **PostgreSQL 17** — relational storage + full-text search (tsvector/tsquery)
+- **pgvector 0.8.2** — HNSW vector indexing
+- **Echo v4** — HTTP framework
+- **sqlc** — type-safe SQL code generation
+- **goose v3** — database migrations
+- **zerolog** — structured JSON logging
+- **koanf** — YAML + env configuration
+- **fsnotify** — file system watching
+- **modernc.org/sqlite** — V1 migration reader (pure Go)
 
 ## License
 

package/npm/postinstall.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+"use strict";
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const VERSION = require("../package.json").version;
+const REPO = "nano-step/nano-brain";
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+};
+const ARCH_MAP = {
+  arm64: "arm64",
+  x64: "amd64",
+};
+
+function getPlatformKey() {
+  const platform = PLATFORM_MAP[os.platform()];
+  const arch = ARCH_MAP[os.arch()];
+  if (!platform || !arch) {
+    console.error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
+    console.error("Build from source: CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain");
+    process.exit(0);
+  }
+  return `${platform}-${arch}`;
+}
+
+function download(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(dest);
+    https.get(url, (res) => {
+      if (res.statusCode === 301 || res.statusCode === 302) {
+        file.close();
+        fs.unlinkSync(dest);
+        return download(res.headers.location, dest).then(resolve).catch(reject);
+      }
+      if (res.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(dest);
+        return reject(new Error(`Download failed: HTTP ${res.statusCode}`));
+      }
+      res.pipe(file);
+      file.on("finish", () => {
+        file.close(resolve);
+      });
+    }).on("error", (err) => {
+      fs.unlinkSync(dest);
+      reject(err);
+    });
+  });
+}
+
+async function main() {
+  const platformKey = getPlatformKey();
+  const binName = os.platform() === "win32" ? "nano-brain.exe" : "nano-brain";
+  const binPath = path.join(__dirname, binName);
+
+  if (fs.existsSync(binPath)) {
+    try {
+      const output = execSync(`"${binPath}" version --json`, { timeout: 5000 }).toString();
+      if (output.includes(VERSION)) {
+        console.log(`nano-brain v${VERSION} already installed.`);
+        return;
+      }
+    } catch {
+      // Wrong version or can't run — redownload
+    }
+  }
+
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/nano-brain-${platformKey}`;
+  console.log(`Downloading nano-brain v${VERSION} for ${platformKey}...`);
+
+  try {
+    await download(url, binPath);
+    fs.chmodSync(binPath, 0o755);
+    console.log(`nano-brain v${VERSION} installed successfully.`);
+  } catch (err) {
+    console.error(`Failed to download binary: ${err.message}`);
+    console.error("Build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain");
+    process.exit(0);
+  }
+}
+
+main();

package/npm/run.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+
+const binName = os.platform() === "win32" ? "nano-brain.exe" : "nano-brain";
+const binPath = path.join(__dirname, binName);
+
+if (!fs.existsSync(binPath)) {
+  console.error("nano-brain binary not found. Run: npx nano-brain (it will download automatically)");
+  console.error("Or build from source: CGO_ENABLED=0 go build -o npm/nano-brain ./cmd/nano-brain");
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}