nano-brain 2026.6.26 → 2026.6.102

package/README.md

@@ -1,998 +1,459 @@
 # nano-brain
 
-Persistent memory and code intelligence for AI coding agents.
+**Persistent memory and code intelligence for AI coding agents.**
 
-## What It Does
+[![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)
 
-A persistent memory server for AI coding agents. It solves the #1 problem with AI assistants: **they forget everything between sessions.**
+## What It Does
 
-nano-brain automatically ingests your AI sessions, notes, and codebase, indexes everything with full-text search + vector embeddings + knowledge graph, serves memories via 22 MCP tools, and learns which memories matter most to you over time.
+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.
 
 ## Key Features
 
-- **Hybrid search pipeline** — BM25 + vector + RRF fusion + VoyageAI neural reranking with 6 ranking signals
-- **Code intelligence** — symbol graph, call flow detection, impact analysis, change detection via Tree-sitter AST
-- **Automatic data ingestion** — session harvesting (2min poll), file watching (chokidar), codebase indexing
-- **Multi-workspace isolation** — per-workspace SQLite databases, cross-workspace search with `--scope=all`
-- **Flexible embedding providers** — VoyageAI, Ollama, OpenAI-compatible
-- **Dual vector stores** — Qdrant (production) or sqlite-vec (embedded)
-- **Privacy-first** — 100% local processing option, your code never leaves your machine
-- **MCP + CLI** — stdio/HTTP/SSE transports for local or containerized environments
-- **Automatic corruption recovery** — detects & recovers from database corruption on startup with zero user intervention
-- **Self-learning system** — Thompson Sampling tunes search parameters, preference learning personalizes results
-- **Knowledge graph** — LLM-extracted entities and relationships, graph traversal, temporal queries
-- **Memory intelligence** — LLM categorization, entity pruning, proactive suggestions
-
-Inspired by [QMD](https://github.com/tobi/qmd) and [OpenClaw](https://github.com/openclaw/openclaw).
+- **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
 
-## Architecture
+## Prerequisites
 
-```
-User Query
-    │
-    ▼
-┌─────────────────┐
-│ Query Expansion  │ ← (currently stubbed, planned)
-│ (optional)       │   generates 2-3 query variants
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    ▼         ▼
-┌────────┐ ┌──────────┐
-│ BM25   │ │ Vector   │
-│ (FTS5) │ │ (Qdrant  │
-│        │ │  or      │
-│        │ │ sqlite-  │
-│        │ │  vec)    │
-└───┬────┘ └────┬─────┘
-    │           │
-    ▼           ▼
-┌─────────────────┐
-│  RRF Fusion     │ ← k=60, original query 2× weight
-│                 │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ PageRank Boost  │ ← Centrality from file dependency graph
-│                 │   weight: 0.1 (default)
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Supersede       │ ← 0.3× demotion for replaced documents
-│ Demotion        │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Neural Reranking│ ← VoyageAI rerank-2.5-lite
-│ (optional)      │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│ Position-Aware  │ ← top 3: 75/25, 4-10: 60/40, 11+: 40/60
-│ Blending        │   (RRF weight / rerank weight)
-└────────┬────────┘
-         │
-         ▼
-    Final Results
-```
+- **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
 
-### Write Pipeline
+## Quick Start
 
-```
-Memory Write
-    │
-    ▼
-┌─────────────────┐
-│ Save to File     │ → ~/.nano-brain/memory/
-│ Hash + DB Insert │ → documents + content tables
-│ FTS5 Index       │ → documents_fts (auto-trigger)
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    ▼         ▼
-┌────────┐ ┌──────────┐
-│Keyword │ │  Async   │ (fire-and-forget)
-│Categorize│ │ Processes│
-│auto:*  │ │          │
-└────────┘ ├──────────┤
-           │ LLM      │ → llm:* tags
-           │ Categorize│
-           ├──────────┤
-           │ Entity   │ → knowledge graph
-           │ Extract  │
-           └──────────┘
-```
+### Option A: Via npx (no Go required)
 
-## Search Pipeline (3 Tiers)
-
-**`memory_search`** — BM25 only (fast, exact keyword matching)
-
-**`memory_vsearch`** — Vector only (semantic similarity via embeddings)
-
-**`memory_query`** — Full hybrid pipeline with 6 ranking signals:
-
-1. **BM25 full-text scoring** — SQLite FTS5 with porter stemming
-2. **Vector cosine similarity** — Qdrant or sqlite-vec embeddings
-3. **RRF fusion** — k=60, original query weighted 2×
-4. **PageRank centrality boost** — from file dependency graph (weight: 0.1)
-5. **Supersede demotion** — 0.3× penalty for replaced documents
-6. **VoyageAI neural reranking** — rerank-2.5-lite with position-aware blending:
-   - Top 3 results: 75% RRF / 25% rerank
-   - Ranks 4-10: 60% RRF / 40% rerank
-   - Ranks 11+: 40% RRF / 60% rerank
-
-Query expansion generates 2-3 query variants before search. The pipeline supports it, but no expansion provider is currently active.
-
-## Code Intelligence
-
-Built on Tree-sitter AST parsing for TypeScript, JavaScript, and Python:
-
-**`code_context`** — 360° view of a code symbol:
-- Direct callers and callees
-- Transitive call flows (upstream/downstream)
-- File location, definition, and references
-- Centrality score (PageRank) and cluster membership
-
-**`code_impact`** — Change impact analysis:
-- Upstream dependencies (what calls this?)
-- Downstream dependencies (what does this call?)
-- BFS traversal with configurable depth
-- Risk assessment for refactoring
-
-**`code_detect_changes`** — Map git diff to affected symbols:
-- Parses `git diff` output
-- Identifies modified symbols via Tree-sitter
-- Returns symbol names, types, and file locations
-- Scope: `staged`, `unstaged`, or `all`
-
-**`memory_focus`** — File dependency context:
-- Import/export graph for a file
-- Centrality score (PageRank)
-- Cluster membership (Louvain algorithm)
-- Direct dependencies and dependents
-
-**`memory_graph_stats`** — Dependency graph overview:
-- Total files, symbols, edges
-- Cycle detection
-- Clustering coefficient
-- Top central files
-
-**Symbol tracking** — Cross-repo symbol queries:
-- Redis keys, PubSub channels
-- MySQL tables, columns
-- API endpoints (Express, FastAPI)
-- Bull/BullMQ queues
-- GraphQL types, queries, mutations
-
-## Data Ingestion
-
-All data sources are indexed automatically:
-
-**Session harvesting** — Converts OpenCode JSON sessions into searchable markdown:
-- Polls `~/.opencode/sessions/` every 2 minutes
-- Extracts user queries, assistant responses, tool calls
-- Incremental append (hash-based deduplication)
-
-**File watching** — Monitors collections for changes:
-- Chokidar watches configured directories
-- Dirty-flag tracking for incremental updates
-- Reindexes every 5 minutes if changes detected
-
-**Codebase indexing** — Tree-sitter AST → symbol graph:
-- Parses TS/JS/Python files
-- Extracts functions, classes, methods, variables
-- Builds call graph (caller → callee edges)
-- Computes PageRank centrality
-- Detects clusters via Louvain algorithm
-- Identifies call flows (entry points → leaf functions)
-
-**Incremental behavior**:
-- Hash-based file skipping (SHA-256 content addressing)
-- Adaptive embedding backoff (exponential retry)
-- Batch processing for large codebases
-
-## Background Jobs
-
-nano-brain runs 9 background jobs to keep your memory fresh and intelligent:
-
-| Job | Interval | What It Does |
-|-----|----------|-------------|
-| File reindex | 5 min | Watch collections, reindex changed files |
-| Session harvest | 2 min | Convert OpenCode sessions → searchable markdown |
-| Embedding | 60s (adaptive) | Generate vector embeddings for new docs |
-| Learning cycle | 10 min | Thompson Sampling + preference weight updates |
-| Consolidation | 1 hour | LLM summarizes related memories |
-| Importance | 30 min | Rescore document importance from usage |
-| Sequence analysis | 30 min | Detect query patterns for proactive suggestions |
-| Pruning (soft) | 6 hours | Soft-delete contradicted/orphan entities |
-| Pruning (hard) | 7 days | Permanently delete old soft-deleted entities |
-
-## Chunking Strategy
-
-Heading-aware markdown chunking that respects document structure:
-
-- **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
-- **Content-addressed storage:** SHA-256 hash deduplication
-
-## Storage & Infrastructure
-
-**SQLite** (via better-sqlite3):
-- `documents` — metadata, content, embeddings
-- `chunks` — heading-aware markdown chunks (900 tokens, 15% overlap)
-- `fts_index` — FTS5 virtual table with porter stemming
-- `vec_index` — sqlite-vec extension (cosine distance)
-- `symbols` — code symbols (functions, classes, variables)
-- `call_edges` — caller → callee relationships
-- `file_deps` — import/export graph
-- `clusters` — Louvain clustering results
-- `flows` — detected call flows (entry → leaf)
-
-**Qdrant** (optional, production vector store):
-- Managed via `qdrant up/down/status/migrate/verify/activate/cleanup` commands
-- Docker-based deployment
-- Automatic migration from sqlite-vec
-- Verification and cleanup tools
-
-**Embedding providers**:
-- **VoyageAI** — voyage-code-3 (1024 dims, code-optimized)
-- **Ollama** — local models (nomic-embed-text, etc.)
-- **OpenAI-compatible** — Azure, LM Studio, custom endpoints
-
-**Reranking**:
-- **VoyageAI** — rerank-2.5-lite (neural reranking)
-
-**Storage management**:
-- Per-workspace SQLite databases (isolated)
-- Content-addressed storage (SHA-256 deduplication)
-- Retention policies (maxSize budget, auto-cleanup)
-- Disk space checks before indexing
-
-## Database Schema
-
-nano-brain uses 18 SQLite tables organized into 5 functional groups:
-
-| Table | Purpose |
-|-------|---------|
-| **Core Documents** | |
-| `documents` | Document metadata, content, embeddings |
-| `chunks` | Heading-aware markdown chunks (900 tokens, 15% overlap) |
-| `content` | Raw content storage (content-addressed) |
-| **Search Indexes** | |
-| `documents_fts` | FTS5 full-text search index (porter stemming) |
-| `vec_index` | sqlite-vec vector index (cosine distance) |
-| **Code Intelligence** | |
-| `symbols` | Code symbols (functions, classes, variables) |
-| `call_edges` | Caller → callee relationships |
-| `file_deps` | Import/export graph |
-| `clusters` | Louvain clustering results |
-| `flows` | Detected call flows (entry → leaf) |
-| **Knowledge Graph** | |
-| `entities` | LLM-extracted entities (people, concepts, tools) |
-| `relationships` | Entity-to-entity connections |
-| **Learning & Intelligence** | |
-| `telemetry` | Search queries, results, expand feedback |
-| `bandit_variants` | Thompson Sampling search parameter tuning |
-| `config_versions` | Search config version history |
-| `consolidations` | LLM-generated memory summaries |
-| `query_sequences` | Query pattern detection for proactive suggestions |
-| `category_preferences` | Per-workspace category weights from expand patterns |
-
-## Database Reliability & Corruption Recovery
-
-**Why corruption happens**:
-SQLite databases can become corrupted due to:
-- Unexpected process termination during write operations
-- Filesystem crashes or power loss during WAL (Write-Ahead Log) checkpoint
-- Disk I/O errors or hardware faults
-- Rare race conditions in concurrent access (even with better-sqlite3 serialization)
-
-**Automatic corruption detection**:
-nano-brain automatically detects database corruption on startup via `PRAGMA integrity_check`:
-- Runs before any database operations in `createStore()`
-- Checks database file integrity without modifying data
-- Takes 50-500ms depending on database size
-
-**Automatic recovery**:
-When corruption is detected:
-1. **Backup corrupted file** — Renamed to `.corrupted.{ISO-timestamp}` for forensics/recovery
-2. **Clear WAL/SHM files** — Removes Write-Ahead Log and shared memory files
-3. **Initialize fresh database** — Creates clean SQLite database from scratch
-4. **Verify fresh database** — Runs integrity check to confirm recovery succeeded
-5. **Emit metric** — `database_corruption_detected` counter for monitoring/alerting
-
-**Why this works**:
-The database is a **cache/index** — all data is re-derivable from source files. Recovery involves:
-- Session harvesting (re-ingests from session logs)
-- Codebase reindexing (rescan source files)
-- Memory re-embedding (regenerates vectors)
-- Call graph rebuilding (reparses symbols)
-
-**Automatic restart with launchd**:
-On macOS, nano-brain runs as a launchd service (`com.tamlh.nano-brain`):
-- If corruption causes a fatal error, process exits
-- launchd automatically restarts it after 10-second throttle
-- On restart, `checkAndRecoverDB()` detects corruption and recovers
-- Service comes back online automatically with fresh database
-
-**Installation (macOS)**:
 ```bash
-# Copy plist to launchd directory
-cp ~/.config/nano-brain/launchd/com.tamlh.nano-brain.plist ~/Library/LaunchAgents/
-
-# Load the service
-launchctl load ~/Library/LaunchAgents/com.tamlh.nano-brain.plist
-
-# Check status
-launchctl list | grep nano-brain
-```
+# 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
 
-**Monitoring**:
-Check for corruption metrics in your monitoring/alerting system:
-- Counter: `database_corruption_detected`
-- Alert threshold: > 3 events per 24 hours (indicates underlying hardware/filesystem issue)
+# Start Ollama + pull embedding model
+ollama pull nomic-embed-text
 
-**Troubleshooting**:
-If corruption happens frequently:
-1. Check system logs for disk I/O errors: `log stream --predicate 'eventMessage contains[c] "I/O error"'`
-2. Verify filesystem health: `diskutil verifyVolume /` (macOS)
-3. Check disk space: `df -h ~/.nano-brain/`
-4. Review database size: `ls -lh ~/.nano-brain/index.db`
-5. Consider moving database to a different drive if corruption persists
-
-**Forensics**:
-Corrupted backups are kept for analysis:
-- Located at: `~/.nano-brain/index.db.corrupted.{ISO-timestamp}`
-- Last 5 backups are kept by default; older ones are auto-cleaned
-- File size indicates when corruption occurred (if truncated vs intact)
-
-## MCP Tools (22+ Total)
-
-### Search & Retrieval
-
-| Tool | Description |
-|------|-------------|
-| `memory_search` | BM25 keyword search (fast, exact matching) |
-| `memory_vsearch` | Semantic vector search (embeddings) |
-| `memory_query` | Full hybrid search (BM25 + vector + RRF + reranking) |
-| `memory_get` | Retrieve document by path or docid (#abc123) |
-| `memory_multi_get` | Batch retrieve by glob pattern |
-
-### Memory Management
-
-| Tool | Description |
-|------|-------------|
-| `memory_write` | Write to daily log (supports tags, supersedes) |
-| `memory_tags` | List all tags with document counts |
-| `memory_status` | Index health, collections, model status, graph stats |
-| `memory_update` | Trigger reindex of all collections |
-| `memory_consolidate` | Trigger LLM memory consolidation |
-| `memory_suggestions` | Proactive next-query predictions based on patterns |
+# Check prerequisites
+npx @nano-step/nano-brain@beta doctor
 
-### Code Intelligence
-
-| Tool | Description |
-|------|-------------|
-| `code_context` | 360° view of a code symbol (callers, callees, flows, centrality) |
-| `code_impact` | Change impact analysis (upstream/downstream BFS) |
-| `code_detect_changes` | Map git diff to affected symbols (staged/unstaged/all) |
-| `memory_index_codebase` | Index codebase files in current workspace (Tree-sitter AST) |
-
-### Dependency Graph
+# Start server
+npx @nano-step/nano-brain@beta
+```
 
-| Tool | Description |
-|------|-------------|
-| `memory_focus` | File dependency context (imports/exports, centrality, cluster) |
-| `memory_graph_stats` | Dependency graph overview (files, symbols, edges, cycles) |
-| `memory_symbols` | Cross-repo symbol query (Redis, MySQL, API endpoints, queues) |
-| `memory_impact` | Cross-repo impact analysis (writers vs readers) |
-| `memory_graph_query` | BFS traversal from entity through knowledge graph |
-| `memory_related` | Find related memories via entity graph connections |
-| `memory_timeline` | Temporal view of entity changes over time |
+> **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.
 
-## Installation & Quick Start
+### Option B: Build from source
 
 ```bash
-# Install globally
-npm install -g nano-brain
+# Build
+CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
 
-# Initialize (creates config, indexes codebase, generates embeddings)
-npx nano-brain init --root=/path/to/your/project
+# 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
 
-# Check everything is working
-npx nano-brain status
-```
-
-### MCP Configuration
+# Start server
+DATABASE_URL="postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev" ./nano-brain
 
-Add to your AI agent's MCP config (e.g., `~/.config/opencode/opencode.json`):
-
-**Local mode (stdio):**
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "local",
-      "command": ["npx", "nano-brain", "mcp"],
-      "enabled": true
-    }
-  }
-}
-```
+# 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"}'
 
-**Remote mode (HTTP/SSE, for Docker/containers):**
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "remote",
-      "url": "http://host.docker.internal:3100/mcp",
-      "enabled": true
-    }
-  }
-}
-```
+# 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"]}'
 
-Start the remote server:
-```bash
-npx nano-brain serve              # Background daemon (port 3100)
-npx nano-brain serve --foreground # Foreground (for debugging)
-npx nano-brain serve status       # Check if running
-npx nano-brain serve stop         # Stop daemon
+# Search
+curl -X POST http://localhost:3100/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{"workspace":"<hash>","query":"database decision"}'
 ```
 
 ## Configuration
 
-Create `~/.nano-brain/config.yml` (auto-generated by `init`):
+Config file: `~/.nano-brain/config.yml`
 
 ```yaml
-# Collections (directories to index)
-collections:
-  memory:
-    path: ~/.nano-brain/memory
-    pattern: "**/*.md"
-    update: auto
-  sessions:
-    path: ~/.nano-brain/sessions
-    pattern: "**/*.md"
-    update: auto
-
-# Vector store (qdrant or sqlite-vec)
-vector:
-  provider: qdrant
-  url: http://localhost:6333
-  collection: nano_brain
-  # OR: provider: sqlite-vec (embedded, no external service)
-
-# Embedding provider
-embedding:
-  provider: openai                    # 'ollama' or 'openai' (OpenAI-compatible)
-  url: https://api.voyageai.com       # VoyageAI, Azure, LM Studio, etc.
-  model: voyage-code-3
-  apiKey: ${VOYAGE_API_KEY}
-  # OR: provider: ollama, url: http://localhost:11434, model: nomic-embed-text
-
-# Reranker (uses embedding.apiKey if not set separately)
-reranker:
-  model: rerank-2.5-lite
-  # apiKey: ${VOYAGE_API_KEY}  # optional, falls back to embedding.apiKey
-
-# Codebase indexing
-codebase:
-  enabled: true
-  languages: [typescript, javascript, python]
-  exclude: [node_modules, dist, build, .git]
-  maxFileSize: 1048576  # 1MB
+server:
+  host: localhost
+  port: 3100
 
-# File watcher
-watcher:
-  enabled: true
-  debounce: 300         # ms
-  reindexInterval: 300  # seconds (5 minutes)
+database:
+  url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev
+
+embedding:
+  provider: ollama              # ollama or voyage
+  url: http://localhost:11434
+  model: nomic-embed-text
+  dimension: 0                  # auto-detect from provider
+  concurrency: 3
 
-# Search configuration
 search:
   rrf_k: 60
-  top_k: 30
-  expansion:
-    enabled: true
-    weight: 1
-  reranking:
-    enabled: true
-  blending:
-    top3:
-      rrf: 0.75
-      rerank: 0.25
-    mid:
-      rrf: 0.60
-      rerank: 0.40
-    tail:
-      rrf: 0.40
-      rerank: 0.60
-  centrality_weight: 0.1
-  supersede_demotion: 0.3
-
-# Polling intervals
-intervals:
-  sessionHarvest: 120   # seconds (2 minutes)
-  healthCheck: 60       # seconds
-
-# Storage management
-storage:
-  maxSize: 10737418240  # 10GB
-  retention:
-    sessions: 90        # days
-    logs: 30            # days
-
-# Workspaces
-workspaces:
-  isolation: true       # Per-workspace SQLite databases
-  defaultScope: current # or 'all' for cross-workspace search
-
-# Entity pruning (Memory Intelligence v2)
-pruning:
-  enabled: true
-  interval_ms: 21600000      # 6 hours
-  contradicted_ttl_days: 30
-  orphan_ttl_days: 90
-  batch_size: 100
-  hard_delete_after_days: 30
-
-# LLM categorization (Memory Intelligence v2)
-categorization:
-  llm_enabled: true
-  confidence_threshold: 0.6
-  max_content_length: 2000
-
-# Preference learning (Memory Intelligence v2)
-preferences:
-  enabled: true
-  min_queries: 20
-  weight_min: 0.5
-  weight_max: 2.0
-  baseline_expand_rate: 0.1
-
-# Logging
-logging:
-  level: info           # debug, info, warn, error
-  file: ~/.nano-brain/logs/nano-brain.log
-  maxSize: 10485760     # 10MB
-  maxFiles: 5
-```
-
-**Data directory layout (`~/.nano-brain/`):**
-```
-~/.nano-brain/
-├── config.yml    # Configuration
-├── data/         # SQLite databases (per-workspace)
-├── memory/       # Curated notes
-├── sessions/     # Harvested sessions
-└── logs/         # Application logs
-```
-
-## CLI Commands (24 Total)
+  recency_weight: 0.3
+  recency_half_life_days: 180
+  limit: 20
+
+harvester:
+  opencode:
+    db_root: ""                 # e.g., ~/.ai-sandbox/opencode-dbs (multi-DB, highest priority)
+    db_path: ""                 # e.g., ~/.local/share/opencode/opencode.db (single DB)
+    session_dir: ""             # e.g., ~/.local/share/opencode/storage (legacy JSON)
+  claudecode:
+    enabled: false
+    session_dir: ""
 
-### Setup & Initialization
-
-```bash
-nano-brain init               # Full initialization (config, index, embed, AGENTS.md)
-nano-brain init --root=/path  # Initialize for specific project
-nano-brain status             # Show index health, collections, model status
-```
+watcher:
+  debounce_ms: 2000
+  reindex_interval: 300
+  # Per-collection exclude_patterns and allowed_extensions are also supported
+  # via the workspaces map. See "Global ignore patterns" section below for
+  # the cross-collection .nano-brainignore file.
 
-### MCP Server
+storage:
+  max_file_size: 314572800      # 300MB
+  max_size: 10737418240         # 10GB
 
-```bash
-nano-brain mcp                                      # Start MCP server (stdio)
-nano-brain mcp --http --port=3100 --host=0.0.0.0   # Start MCP server (HTTP/SSE)
-```
+telemetry:
+  retention_days: 90
 
-### Remote Server (Daemon)
+logging:
+  level: info
+  file: ""                      # empty = stdout only
 
-```bash
-nano-brain serve              # Start SSE server as background daemon (port 3100)
-nano-brain serve status       # Check if server is running
-nano-brain serve stop         # Stop the daemon
-nano-brain serve --foreground # Run in foreground (for debugging)
-nano-brain serve --port=8080  # Custom port
+summarization:
+  enabled: false                # set to true to generate LLM summaries of harvested sessions
+  provider_url: ""              # OpenAI-compatible endpoint, e.g. https://ai-proxy.example.com/v1
+  api_key: ""                   # or set NANO_BRAIN_SUMMARIZE_API_KEY env var
+  model: "nano-brain"           # model name passed to the provider
+  max_tokens: 8000              # max tokens per LLM completion
+  concurrency: 3                # parallel map-phase LLM calls
 ```
 
-### Search
-
-```bash
-nano-brain search "query"           # BM25 keyword search
-nano-brain vsearch "query"          # Vector semantic search
-nano-brain query "query"            # Hybrid search (BM25 + vector + reranking)
-nano-brain query "query" --tags=bug,fix  # Filter by tags
-nano-brain query "query" --scope=all     # Cross-workspace search
-```
+### Authentication (VPS / remote deployment)
 
-### Memory Management
+When binding to a non-loopback address, enable auth to protect your memory:
 
-```bash
-nano-brain write "content"          # Write to daily log
-nano-brain write "content" --tags=decision,architecture
-nano-brain write "content" --supersedes=abc123  # Mark as replacement
-nano-brain get <path>               # Retrieve document by path
-nano-brain get "#abc123"            # Retrieve by docid
-nano-brain tags                     # List all tags with counts
+```yaml
+server:
+  host: 0.0.0.0
+  port: 3100
+  auth:
+    enabled: true
+    realm: nano-brain
+    users:
+      - username: admin
+        password_hash: "$2a$10$..."   # from: nano-brain auth hash <password>
+    tokens:
+      - "nbt_..."                     # from: nano-brain auth token
+    bypass_paths:
+      - /health
 ```
 
-### Index Management
+Generate credentials:
 
 ```bash
-nano-brain update               # Reindex all collections
-nano-brain index-codebase       # Index codebase in current workspace
-nano-brain reset --confirm      # Reset all data (requires confirmation)
-nano-brain reset --dry-run      # Preview what would be deleted
-```
-
-### Collections
+# Generate bcrypt hash for Basic Auth
+nano-brain auth hash mypassword
 
-```bash
-nano-brain collection add <name> <path>     # Add collection
-nano-brain collection remove <name>         # Remove collection
-nano-brain collection list                  # List collections
+# Generate bearer token
+nano-brain auth token
 ```
 
-### Workspace Management
+Usage examples:
 
 ```bash
-nano-brain rm --list                        # List all workspaces
-nano-brain rm <workspace> --dry-run         # Preview what would be deleted
-nano-brain rm <workspace>                   # Remove workspace and all its data
-# <workspace> can be: absolute path, hash prefix, or workspace name
-```
+# Basic Auth
+curl -u admin:mypassword http://host:3100/api/v1/query -d '{"query":"test"}'
 
-### Qdrant Management
+# Bearer token
+curl -H "Authorization: Bearer nbt_..." http://host:3100/api/v1/query -d '{"query":"test"}'
 
-```bash
-nano-brain qdrant up            # Start Qdrant Docker container
-nano-brain qdrant down          # Stop Qdrant container
-nano-brain qdrant status        # Check Qdrant status
-nano-brain qdrant migrate       # Migrate from sqlite-vec to Qdrant
-nano-brain qdrant verify        # Verify Qdrant data integrity
-nano-brain qdrant activate      # Switch to Qdrant (update config)
-nano-brain qdrant cleanup       # Remove orphaned vectors
+# MCP client with URL-embedded credentials
+# url: http://admin:mypassword@host:3100/mcp
 ```
 
-### Cache Management
+### Global ignore patterns (`~/.nano-brain/.nano-brainignore`)
 
-```bash
-nano-brain cache clear          # Clear all caches
-nano-brain cache clear --type=embeddings  # Clear specific cache type
-nano-brain cache stats          # Show cache statistics
-```
-
-### Benchmarking
+The watcher loads a global gitignore-style file at `~/.nano-brain/.nano-brainignore`
+on startup. Patterns in this file apply to **all** registered collections, removing
+the need to repeat the same exclusions in each `watcher.workspaces` block.
 
-```bash
-nano-brain bench                # Run default benchmark suite
-nano-brain bench --suite=search # Run specific suite
-nano-brain bench --iterations=100 --json --save
-nano-brain bench --compare=baseline.json  # Compare with baseline
-```
+**Format**: standard `.gitignore` syntax (one pattern per line, supports `**`, `!negation`, blank lines, `#` comments).
 
-### Logging
+**Example** `~/.nano-brain/.nano-brainignore`:
 
-```bash
-nano-brain logs                 # Show recent logs (last 50 lines)
-nano-brain logs -f              # Tail logs in real-time
-nano-brain logs -n 100          # Show last 100 lines
-nano-brain logs --date=2026-03-01  # Show log for specific date
-nano-brain logs --clear         # Delete all log files
-nano-brain logs path            # Print log directory path
 ```
+# Skip generated files everywhere
+*.png
+*.jpg
+*.pdf
+build/
+dist/
+node_modules/
 
-## Project Structure
-
-```
-src/
-├── index.ts          # CLI entry point
-├── server.ts         # MCP server (22+ tools, stdio/HTTP/SSE)
-├── store.ts          # SQLite storage (FTS5 + sqlite-vec)
-├── storage.ts        # Storage management (retention, disk space)
-├── vector-store.ts   # Vector store abstraction (Qdrant + 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 (VoyageAI, Ollama, OpenAI-compatible)
-├── reranker.ts       # VoyageAI reranker
-├── expansion.ts      # Query expansion (interface only, no active provider)
-├── harvester.ts      # OpenCode session → markdown converter
-├── watcher.ts        # File watcher (chokidar, dirty flags)
-├── codebase.ts       # Codebase indexing orchestrator
-├── treesitter.ts     # Tree-sitter AST parsing
-├── symbols.ts        # Symbol extraction (functions, classes, variables)
-├── graph.ts          # File dependency graph (imports/exports)
-├── symbol-graph.ts   # Symbol call graph (caller → callee)
-├── flow-detection.ts # Call flow detection (entry → leaf)
-├── types.ts          # TypeScript interfaces
-└── providers/        # Vector store implementations
-    ├── qdrant.ts     # Qdrant vector store
-    └── sqlite-vec.ts # sqlite-vec vector store
-bin/
-└── cli.js            # CLI wrapper
-
-test/
-└── *.test.ts         # 760+ tests (vitest)
-SKILL.md              # AI agent routing instructions (auto-loaded by OpenCode)
-AGENTS_SNIPPET.md     # Optional project-level AGENTS.md managed block
+# But keep this one icon
+!icons/important.png
 ```
 
-## Tech Stack
-
-- **TypeScript + Node.js** (via tsx)
-- **better-sqlite3** + **sqlite-vec** for embedded storage
-- **Qdrant** for production vector store (optional)
-- **Tree-sitter** for AST parsing (TS, JS, Python)
-- **@modelcontextprotocol/sdk** for MCP server (stdio/HTTP/SSE transports)
-- **chokidar** for file watching
-- **vitest** for testing (760+ tests)
+**Order of evaluation** (most aggressive first):
 
-## Embedding & Reranking Providers
+1. Hardcoded default exclude dirs (`node_modules`, `.git`, `dist`, `build`, `target`, etc.)
+2. **Global `.nano-brainignore`** (this feature)
+3. Per-collection `.gitignore` (in collection root)
+4. Per-collection `exclude_patterns` (config-level)
+5. Per-collection `allowed_extensions` (whitelist)
 
-**Embeddings:**
-- **VoyageAI** — voyage-code-3 (1024 dims, code-optimized, recommended)
-- **Ollama** — nomic-embed-text, mxbai-embed-large, etc. (local, free)
-- **OpenAI-compatible** — Azure OpenAI, LM Studio, custom endpoints
+**Restart required**: changes to `.nano-brainignore` take effect on next server start (hot-reload deferred to a follow-up). Issue #263.
 
-**Reranking:**
-- **VoyageAI** — rerank-2.5-lite (neural reranking, recommended)
+### Session Summarization
 
-**Query Expansion:**
-- Pipeline support exists but no active provider. The interface is ready for future integration.
+When `summarization.enabled: true`, nano-brain automatically generates structured markdown summaries of each harvested session using an OpenAI-compatible LLM provider. Summaries are:
 
-## How nano-brain Compares
+- Stored in PostgreSQL under collection `session-summary` for semantic search via the standard query/vsearch API (PG is the source of truth)
+- Optionally written to disk as Markdown files for Obsidian-compatible access (see [Disk persistence](#disk-persistence-obsidian-compatible) below)
+- Idempotent — unchanged sessions are skipped; re-harvested sessions overwrite old summaries
 
-| | nano-brain | Mem0 / OpenMemory | Zep / Graphiti | OMEGA | Letta (MemGPT) | Claude Native |
-|---|---|---|---|---|---|---|
-| **Search** | Hybrid (BM25 + vector + 6 ranking signals) | Vector only | Graph traversal + vector | Semantic + BM25 | Agent-managed | Text file read |
-| **Storage** | SQLite + Qdrant (optional) | PostgreSQL + Qdrant | Neo4j | SQLite | PostgreSQL / SQLite | Flat text files |
-| **MCP Tools** | 22+ | 4-9 | 9-10 | 12 | 7 | 0 |
-| **Code Intelligence** | Yes (Tree-sitter AST, symbol graph, impact analysis) | No | No | No | No | No |
-| **Codebase Indexing** | Yes (AST → symbols → call graph → flows) | No | No | No | No | No |
-| **Session Recall** | Yes (auto-harvests past sessions) | No | No | No | No | Limited (CLAUDE.md) |
-| **Query Expansion** | Pipeline ready (no active provider) | No | No | No | No | No |
-| **Neural Reranking** | Yes (VoyageAI rerank-2.5-lite) | No | No | No | No | No |
-| **Local-First** | Yes (Ollama + sqlite-vec) | Requires OpenAI API key | Requires Docker + Neo4j | Yes | Yes | Yes |
-| **Cloud Option** | Yes (VoyageAI, OpenAI-compatible) | Cloud API (OpenAI) | Cloud API | Local ONNX | Cloud API | None |
-| **Privacy** | 100% local option available | Cloud API calls | Cloud or self-host | 100% local | Self-host or cloud | Local files |
-| **Dependencies** | SQLite + embedding API (+ optional Qdrant) | 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 |
+#### Disk persistence (Obsidian-compatible)
 
-### Where nano-brain shines
+By default, summaries are written to disk as Markdown files at the path configured in
+`summarization.output_dir` (default: `~/.nano-brain/summaries`). The file layout is:
 
-- **6-signal hybrid search** — BM25 + vector + RRF + PageRank + supersede + neural reranking in a single pipeline
-- **Code intelligence** — Tree-sitter AST parsing, symbol graph, call flow detection, impact analysis
-- **Codebase indexing** — index your source files with structural boundary detection, not just conversations
-- **Session recall** — automatically harvests and indexes past AI coding sessions
-- **Flexible deployment** — 100% local (Ollama + sqlite-vec) or cloud (VoyageAI + Qdrant)
-- **Privacy-first** — local processing option, your code never leaves 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
-- **Use code intelligence** — understand symbol relationships, assess change impact, detect affected code
-
-### 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.
-
-### AGENTS_SNIPPET.md (Optional, project-level)
-
-For project-level integration, `AGENTS_SNIPPET.md` provides a managed block that can be injected into a project's `AGENTS.md`:
-
-```bash
-npx nano-brain init --root=/path/to/project
+```
+<output_dir>/<workspace_name>/<source>_<slugified-title>_<YYYY-MM-DD>.md
 ```
 
-This adds a managed block to your project's `AGENTS.md` with quick reference tables for CLI commands and MCP tools (if available).
-
-See [SKILL.md](./SKILL.md) for full routing rules and [AGENTS_SNIPPET.md](./AGENTS_SNIPPET.md) for the project-level snippet.
-
-## Self-Learning Configuration
-
-nano-brain includes an adaptive self-learning system that improves search quality over time.
-
-### Quick Start
+Files are byte-identical to the `documents.content` field in PostgreSQL — disk is a
+derivative view, DB is source of truth. Disk write failures (permission denied, disk
+full) log a WARN but do not roll back the DB transaction.
 
-Add to your `config.yml`:
+To opt out (DB-only persistence):
 
 ```yaml
-telemetry:
-  enabled: true          # Log search queries and feedback (default: true)
-  retention_days: 90     # How long to keep telemetry data
-
-learning:
-  enabled: true          # Enable adaptive search tuning
-  update_interval_ms: 600000  # Cold-path update interval (10 min)
-
-consolidation:
-  enabled: true          # Enable memory consolidation
-  interval_ms: 3600000   # Consolidation interval (60 min)
-  model: gpt-4o-mini     # LLM model for consolidation
-  endpoint: https://api.openai.com/v1  # OpenAI-compatible endpoint
-  apiKey: sk-...         # API key (not required for Ollama)
-  provider: openai       # 'openai' (default) or 'ollama'
-
-extraction:
-  enabled: true          # Enable fact extraction from sessions
-  model: gpt-4o-mini     # LLM model for extraction
-  endpoint: https://api.openai.com/v1
-  apiKey: sk-...
-  maxFactsPerSession: 20 # Max facts to extract per session
-
-importance:
-  enabled: true          # Enable importance scoring
-  weight: 0.1            # Importance boost weight
-  decay_half_life_days: 30
-
-intents:
-  enabled: true          # Enable query intent classification
+summarization:
+  write_to_disk: false
 ```
 
-### How It Works
-
-1. **Telemetry**: Every search query is logged with results and timing. When you expand a result, it's recorded as positive feedback.
-2. **Thompson Sampling**: Search parameters (rrf_k, centrality_weight) are automatically tuned using multi-armed bandits based on expand feedback.
-3. **Consolidation**: Periodically, an LLM reviews recent memories and finds connections, generating consolidated insights.
-4. **Importance Scoring**: Documents accessed frequently get boosted in search results. Unused documents decay over time.
-5. **Intent Classification**: Queries are classified by intent (lookup, explanation, architecture, recall) and routed to optimized search configs.
-
-### CLI Commands
+To backfill historical summaries already in the DB:
 
-- `nano-brain learning rollback [version_id]` — View or rollback to a previous config version
-- `nano-brain consolidate` — Trigger a manual consolidation cycle
-
-### MCP Tools
-
-- `memory_consolidate` — Trigger consolidation manually
-- `memory_consolidation_status` — View consolidation queue stats and recent logs
-- `memory_importance` — View document importance scores
-- `memory_status` — View learning system status (telemetry records, bandit variants, config version)
-
-## Memory Intelligence v2
-
-nano-brain includes three advanced intelligence features that make your memory smarter over time.
-
-### Entity Pruning
-
-Automatically cleans up outdated or contradicted information from the knowledge graph.
+```
+nano-brain backfill-summaries
+```
 
-**How it works:**
-- Background job runs every 6 hours
-- Soft-deletes contradicted entities after 30 days (when newer information supersedes them)
-- Soft-deletes orphan entities after 90 days (entities with no relationships)
-- Hard-deletes soft-deleted entities after 30-day retention period
-- Processes in batches of 100 to avoid SQLite lock contention
+**Quick setup with ai-proxy:**
 
-**Configuration:**
 ```yaml
-pruning:
+summarization:
   enabled: true
-  interval_ms: 21600000      # 6 hours
-  contradicted_ttl_days: 30  # How long before contradicted entities are soft-deleted
-  orphan_ttl_days: 90        # How long before orphan entities are soft-deleted
-  batch_size: 100            # Max entities to process per cycle
-  hard_delete_after_days: 30 # Retention period for soft-deleted entities
+  provider_url: "https://ai-proxy.example.com/v1"
+  api_key: ""           # set NANO_BRAIN_SUMMARIZE_API_KEY instead
+  model: "claude-sonnet-4-5"
+  max_tokens: 8000
+  concurrency: 3
 ```
 
-**Why this matters:** Prevents your knowledge graph from accumulating stale information. When you update a decision or pattern, the old version is automatically pruned after the TTL expires.
+Or via environment variable:
 
-### LLM Categorization
+```bash
+export NANO_BRAIN_SUMMARIZE_API_KEY="sk-..."
+```
 
-Adds semantic categorization to your memories using an LLM, going beyond simple keyword matching.
+Large sessions (100K+ tokens) are handled via map-reduce chunking — no session is too large.
 
-**How it works:**
-- Runs asynchronously after the keyword categorizer (fire-and-forget)
-- Uses the same LLM provider configured for consolidation (same endpoint/model/apiKey)
-- Adds tags prefixed with `llm:` (e.g., `llm:architecture-decision`, `llm:debugging-insight`)
-- Only processes documents under 2000 characters (configurable)
-- Requires confidence threshold of 0.6 or higher (configurable)
+### Environment Variables
 
-**7 semantic categories:**
-1. `llm:architecture-decision` — System design choices, trade-offs, patterns
-2. `llm:debugging-insight` — Root cause analysis, fix patterns, gotchas
-3. `llm:tool-config` — Setup instructions, configuration patterns
-4. `llm:pattern` — Reusable code patterns, best practices
-5. `llm:preference` — User preferences, workflow choices
-6. `llm:context` — Background information, explanations
-7. `llm:workflow` — Process documentation, how-to guides
+| Variable | Description |
+|----------|-------------|
+| `NANO_BRAIN_CONFIG` | Path to YAML config file (12-factor; useful in Docker/k8s). Precedence: `--config` flag > `NANO_BRAIN_CONFIG` > `~/.nano-brain/config.yml`. Leading/trailing whitespace is stripped. If the env-pointed file does not exist, a `WARNING:` is printed to stderr and defaults are used (operator can spot typos). |
+| `DATABASE_URL` | PostgreSQL connection string |
+| `VOYAGE_API_KEY` | Voyage AI API key |
+| `OPENCODE_DB_ROOT` | OpenCode per-project DB root directory (multi-DB mode) |
+| `OPENCODE_DB_PATH` | OpenCode single SQLite database path |
+| `OPENCODE_STORAGE_DIR` | OpenCode session directory (legacy) |
+| `NANO_BRAIN_SUMMARIZE_API_KEY` | API key for the summarization LLM provider |
+| `NANO_BRAIN_AUTH_ENABLED` | Enable Basic Auth + Bearer Token (`true`/`false`) |
+| `NANO_BRAIN_AUTH_TOKENS` | Comma-separated bearer tokens |
+| `NANO_BRAIN_*` | Override any config field (e.g., `NANO_BRAIN_SERVER_PORT=3100`) |
 
-**Configuration:**
-```yaml
-categorization:
-  llm_enabled: true
-  confidence_threshold: 0.6   # Minimum confidence to apply a category
-  max_content_length: 2000    # Skip documents longer than this
-```
+**Docker example** — run the server in a container against a host PostgreSQL:
 
-**Why this matters:** Enables semantic filtering like `--tags=llm:architecture-decision` to find all design decisions, even if they don't use the word "architecture."
+```bash
+# /path/to/container-config.yml uses host.docker.internal for DB/Ollama
+docker run -d \
+  -e NANO_BRAIN_CONFIG=/etc/nano-brain/config.yml \
+  -v /path/to/container-config.yml:/etc/nano-brain/config.yml:ro \
+  -p 3100:3100 \
+  nano-brain:latest
+```
+
+## 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) |
+| DELETE | `/api/v1/workspaces/:hash` | Permanently delete a workspace + cascade docs/chunks/embeddings |
+| 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/get` | Get single document by source_path or id |
+| POST | `/api/v1/multi-get` | Batch fetch documents by paths or ids |
+| POST | `/api/v1/reindex` | Queue reindex (202) |
+| POST | `/api/v1/update` | Queue update (202) |
+| POST | `/api/v1/summarize` | Trigger LLM summarization of harvested sessions |
+| 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 workspaces list` | List registered workspaces with doc counts |
+| `nano-brain workspaces remove --workspace=<hash> [--dry-run\|--force]` | Permanently delete a workspace + all its documents/chunks/embeddings |
+| `nano-brain write` | Write document via CLI |
+| `nano-brain query [--scope=all] [--tags=t1,t2]` | Hybrid search (BM25 + vector + RRF + recency) |
+| `nano-brain search [--scope=all] [--tags=t1,t2]` | BM25 keyword search |
+| `nano-brain vsearch [--scope=all] [--tags=t1,t2]` | Vector similarity search |
+| `nano-brain wake-up --workspace=<hash>` | Workspace briefing (collections, stats, recent memories) |
+| `nano-brain get <source_path\|uuid> --workspace=<hash>` | Fetch a single document by source_path or UUID |
+| `nano-brain tags --workspace=<hash>` | List all tags with document counts |
+| `nano-brain multi-get --workspace=<hash> --paths=p1,p2` | Fetch multiple documents in one round-trip |
+| `nano-brain collection add\|remove\|list` | Manage collections |
+| `nano-brain harvest` | Trigger session harvesting |
+| `nano-brain backfill-summaries [--dry-run] [--workspace=] [--since=]` | Export existing DB summaries to disk (.md files for Obsidian etc.) |
+| `nano-brain cleanup-stale-raw [--dry-run]` | Delete pre-#192 raw OpenCode session docs superseded by summaries |
+| `nano-brain cleanup-orphan-workspaces [--dry-run]` | Delete documents/chunks under workspace_hash values not registered in `workspaces`. Run BEFORE migration 00011 (issue #238). |
+| `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 auth hash <password>` | Generate bcrypt password hash for config |
+| `nano-brain auth token` | Generate random bearer token (`nbt_`-prefixed) |
+| `nano-brain doctor [--json]` | Check prerequisites (config, PostgreSQL, pgvector, Ollama, model) |
+
+## MCP Tools
+
+nano-brain exposes 13 tools via MCP (Model Context Protocol):
 
-### Preference Learning
+| 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 |
+| `memory_graph` | Knowledge graph view (module → function → dep) |
+| `memory_trace` | Call chain trace from entry point |
+| `memory_impact` | Cross-file change impact analysis |
+| `memory_symbols` | Symbol search (functions, types, constants) |
 
-Learns which types of memories you expand most often and boosts them in future searches.
+### MCP Configuration
 
-**How it works:**
-- Tracks expand events per category per workspace
-- Calculates category weights based on expand rate vs baseline (10% default)
-- Applies weights as multipliers in search scoring (0.5× to 2.0× range)
-- Cold start: uses neutral weights until 20 queries collected
-- Updates every 10 minutes via learning cycle background job
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "remote",
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
+```
 
-**Example:** If you expand `llm:debugging-insight` memories 30% of the time (vs 10% baseline), those memories get a 1.5× boost in future searches.
+## Search Pipeline
 
-**Configuration:**
-```yaml
-preferences:
-  enabled: true
-  min_queries: 20             # Minimum queries before personalization kicks in
-  weight_min: 0.5             # Minimum category weight (demotion)
-  weight_max: 2.0             # Maximum category weight (boost)
-  baseline_expand_rate: 0.1   # Expected expand rate (10%)
+```
+Query --> BM25 (ts_rank_cd) ---+
+                               +--> RRF Fusion (k=60) --> Recency Decay --> Results
+Query --> Vector (HNSW cos) ---+
 ```
 
-**Why this matters:** Your memory system adapts to your workflow. If you're debugging, debugging insights automatically surface higher. If you're designing, architecture decisions get prioritized.
-
-## Proactive Intelligence
+- **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)
 
-nano-brain can predict what you'll need next based on your query patterns.
+## Architecture
 
-### How It Works
+- 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
 
-1. **Query chains**: Groups of related queries within 5-minute windows are detected
-2. **Clustering**: Similar queries are grouped into semantic clusters using embeddings
-3. **Transition learning**: The system learns which clusters follow which (e.g., "auth questions" → "token refresh questions")
-4. **Predictions**: When you ask about topic A, nano-brain predicts you'll need topic B next
+## Migration from V1
 
-### Configuration
+```bash
+# Import V1 SQLite data to PostgreSQL
+nano-brain db:migrate --from-v1 /path/to/old/index.db
 
-```yaml
-proactive:
-  enabled: true
-  chain_timeout_ms: 300000      # 5 min window for grouping queries
-  min_queries_for_prediction: 50 # Minimum queries before predictions activate
-  max_suggestions: 5
-  confidence_threshold: 0.3
-  cluster_count: 50
-  analysis_interval_ms: 1800000  # Rebuild every 30 min
+# Idempotent — safe to run multiple times
+# Uses content-addressed SHA-256 hashing
+# Pure Go SQLite reader (modernc.org/sqlite, no CGO)
 ```
 
-### MCP Tool
-
-- `memory_suggestions` — Get predicted next queries based on current context
-  - `context` (optional): Current query or topic
-  - `workspace` (optional): Workspace path
-  - `limit` (optional): Max suggestions (default 3)
-
-## Troubleshooting
-
-**LLM provider unreachable**: Check endpoint URL and network connectivity. For Ollama, ensure `ollama serve` is running.
-
-**Invalid API key**: Verify `apiKey` in config or `CONSOLIDATION_API_KEY` env var. Ollama doesn't require an API key.
-
-**Empty LLM responses**: Check model name is correct. For Ollama, run `ollama list` to see available models.
+## Tech Stack
 
-**Consolidation not running**: Ensure `consolidation.enabled: true` and check `memory_consolidation_status` for queue state.
+- **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