@nano-step/nano-brain 2026.6.402 → 2026.6.404

package/README.md

@@ -6,6 +6,26 @@
 [![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)
 
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Use Cases](#use-cases)
+- [Key Features](#key-features)
+- [Prerequisites](#prerequisites)
+- [Quick Start](#quick-start)
+- [Verifying Downloads](#verifying-downloads)
+- [Configuration](#configuration)
+- [REST API](#rest-api)
+- [CLI Commands](#cli-commands)
+- [MCP Tools](#mcp-tools)
+- [Search Pipeline](#search-pipeline)
+- [Architecture](#architecture)
+- [Migration from V1](#migration-from-v1)
+- [Tech Stack](#tech-stack)
+- [License](#license)
+
+---
+
 ## What It Does
 
 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.
@@ -32,6 +52,33 @@ nano-brain builds a symbol graph of your codebase: functions, types, dependencie
 ### Notes and documentation search
 Write structured notes, ADRs, or decision records into nano-brain. Hybrid search (BM25 + semantic) retrieves them by keyword or concept. Agents can surface the right context without you having to remember where you put it.
 
+### Team knowledge base (no per-member setup)
+Deploy one nano-brain server for the whole team. Every developer's AI agent connects to the same PostgreSQL instance — decisions, architecture notes, code intelligence, and session learnings are instantly shared across the team. New team members get full project context from day one without any setup on their machine.
+
+```
+Dev A (office)   ──┐
+Dev B (remote)   ──┼──► nano-brain on team server ──► shared PostgreSQL
+Dev C (new hire) ──┘
+```
+
+Role-based access: admins get full read/write, developers get read/write scoped to their workspace, stakeholders or reviewers get read-only access.
+
+### Knowledge preservation when an engineer leaves
+A senior engineer resigns. Without nano-brain, their institutional knowledge — why certain decisions were made, which parts of the codebase are fragile, what was tried and failed — walks out the door with them.
+
+With nano-brain, their sessions are already harvested and indexed. The team can still ask "why did we pick this approach?" or "what did Alice know about the payment service?" and get answers from her past sessions.
+
+### Freelancer / consultant context switching
+You work on 3 client projects in parallel. Each is a separate workspace. When you switch clients, run `nano-brain wake-up` to get an instant briefing — recent work, active collections, key context — and your AI agent picks up exactly where you left off without re-reading the codebase.
+
+### Legacy codebase archaeology
+You inherit a 5-year-old codebase with minimal documentation and no original authors to ask. Index it into nano-brain. Your AI agent can now answer "what does this function do?", "why does this class exist?", and "if I change this file, what else breaks?" — navigating cross-file relationships without reading 200k lines manually.
+
+Go, TypeScript, Python, JavaScript supported today. Rust, Java, and others planned.
+
+### Pre-commit / pre-PR impact check
+Before pushing, run `memory_impact` on your changed files to discover what else in the codebase depends on them — across files, across repos in the same workspace. Catch breaking changes before they hit CI. *(Multi-file diff-aware mode in roadmap.)*
+
 ## Key Features
 
 - **Hybrid search** — BM25 full-text + pgvector HNSW cosine similarity + RRF fusion + recency decay
@@ -54,70 +101,105 @@ Write structured notes, ADRs, or decision records into nano-brain. Hybrid search
 
 ## Quick Start
 
-### Option A: Via MCP (recommended for AI agents)
+> **Let your AI agent set this up for you.** See [SETUP_AGENT.md](docs/SETUP_AGENT.md) — a step-by-step guide your agent can follow to install, configure, and verify nano-brain, checking for missing dependencies and asking before installing anything.
 
-Add to your MCP client config — no install required if the server is already running:
+---
 
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "remote",
-      "url": "http://localhost:3100/mcp"
-    }
-  }
-}
-```
+### Path 1 — Local machine (Ollama + Docker, ~5 min)
 
-### Option B: Install globally (fast, no cold-start overhead)
+The fastest way to get started on a single machine.
+
+**Prerequisites:** [Docker](https://docs.docker.com/get-docker/), [Ollama](https://ollama.com/download), Node.js 18+
 
 ```bash
+# 1. Install nano-brain
 npm install -g @nano-step/nano-brain
 
-# Start PostgreSQL + pgvector
+# 2. 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
 
-# Start Ollama + pull embedding model
+# 3. Pull embedding model
 ollama pull nomic-embed-text
 
-# Check prerequisites
+# 4. Verify everything is in order
 nano-brain doctor
 
-# Start server
+# 5. Start the server (background)
 nano-brain serve -d
+
+# 6. Register your project
+nano-brain init --root=/path/to/your/project
 ```
 
-### Option C: Via npx (no install, slower cold-start)
+**Add to your MCP client** (Claude Code, OpenCode, Cursor, etc.):
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "http",
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
+
+Your AI agent now has persistent memory. It will automatically index your project files and harvest sessions as you work.
 
+---
+
+### Path 2 — VPS / team server (shared memory across machines)
+
+Deploy once, connect from any machine. The whole team shares the same knowledge base.
+
+**On the server:**
 ```bash
-# Start PostgreSQL + pgvector
+# 1. 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
 
-# Start Ollama + pull embedding model
-ollama pull nomic-embed-text
+# 2. Install and start nano-brain (with auth + public binding)
+npm install -g @nano-step/nano-brain
+nano-brain serve -d --host=0.0.0.0
 
-# Check prerequisites
-npx @nano-step/nano-brain@latest doctor
+# 3. Generate a bearer token for your team
+nano-brain auth token
+# → nbt_xxxxxxxxxxxxxxxx
+```
 
-# Start server
-npx @nano-step/nano-brain@latest
+**On each developer machine** — add to MCP client config:
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "http",
+      "url": "http://YOUR_VPS_IP:3100/mcp",
+      "headers": {
+        "Authorization": "Bearer nbt_xxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+```bash
+# Register your local project against the remote server
+NANO_BRAIN_SERVER=http://YOUR_VPS_IP:3100 nano-brain init --root=/path/to/project
 ```
 
-> **Also available as:** `npx nano-brain@latest` (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.
+See [Authentication](#authentication-vps--remote-deployment) for role-based tokens (admin / developer / read-only).
 
-### Option D: Build from source
+---
+
+### Path 3 — Build from source
 
 ```bash
 # Build
 CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
 
-# Start PostgreSQL + pgvector (example with Docker)
+# 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
@@ -125,22 +207,22 @@ docker run -d --name nanobrain-pg -p 5432:5432 \
 # Start server
 DATABASE_URL="postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev" ./nano-brain
 
-# 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"}'
+# Register workspace and check status
+./nano-brain init --root=/path/to/project
+./nano-brain status
+```
+
+---
 
-# 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"]}'
+### Via npx (no global install)
 
-# Search
-curl -X POST http://localhost:3100/api/v1/query \
-  -H "Content-Type: application/json" \
-  -d '{"workspace":"<hash>","query":"database decision"}'
+```bash
+npx @nano-step/nano-brain@latest doctor
+npx @nano-step/nano-brain@latest serve -d
 ```
 
+> Also available as `npx nano-brain@latest`. Do NOT run from the nano-brain source directory — npm will resolve the local package instead of the registry.
+
 ## Verifying Downloads
 
 Every release ships a `SHA256SUMS` asset alongside the four platform binaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-step/nano-brain",
-  "version": "2026.6.402",
+  "version": "2026.6.404",
   "description": "Persistent memory and code intelligence for AI coding agents",
   "bin": {
     "nano-brain": "npm/run.js"