nano-brain 2026.7.13 → 2026.7.102

package/README.md

@@ -1,1064 +1,561 @@
 # nano-brain
 
-Persistent memory and code intelligence for AI coding agents.
+**Built for agents. Not humans.**
 
-## What It Does
-
-A persistent memory server for AI coding agents. It solves the #1 problem with AI assistants: **they forget everything between sessions.**
+Agent-oriented memory and code intelligence. AI agents don't read docs — they need structured context, impact analysis, and call chains. nano-brain provides exactly that via MCP.
 
-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.
+[![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)
+[![npm](https://img.shields.io/badge/npm-@nano--step%2Fnano--brain-CC3533?logo=npm)](https://www.npmjs.com/package/@nano-step/nano-brain)
+[![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/nano-step/nano-brain)
+[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/nano-brain)
 
-## 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).
+### Install
 
-## Architecture
+```bash
+# Via npm (recommended)
+npm install -g @nano-step/nano-brain
 
-```
-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
+# Or build from source
+CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
 ```
 
-### Write Pipeline
+### 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  │
-           └──────────┘
-```
-
-## 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):
-- Included in `nano-brain docker start` compose stack, or managed standalone via `qdrant up/down/status` commands
-- 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/
+# Start PostgreSQL
+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
 
-# Load the service
-launchctl load ~/Library/LaunchAgents/com.tamlh.nano-brain.plist
+# Start nano-brain
+nano-brain serve -d
 
-# Check status
-launchctl list | grep nano-brain
+# Register your project
+nano-brain init --root=/path/to/your/project
 ```
+---
 
-**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)
+## Why Star This Project?
 
-**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
+**If you've ever wished your AI agent stopped flying blind in your codebase.**
 
-**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)
+Most memory tools optimize for conversation recall. nano-brain optimizes for **agent comprehension** — the ability to understand codebases, trace dependencies, and predict the blast radius of changes.
 
-## MCP Tools (22+ Total)
+nano-brain is:
 
-### Search & Retrieval
+- **Agent-oriented** — Built around how agents actually work: impact analysis before edits, call chain tracing, symbol lookup. Not a document store with MCP slapped on top.
+- **Self-hosted** — Your data stays on your server. No cloud dependency.
+- **Works everywhere** — OpenCode, Claude Code, Cursor, any MCP client.
+- **Actually useful** — Not a toy demo. Production-ready with 16 MCP tools, hybrid search, code intelligence, and agent-oriented benchmarks.
+- **Built for developers** — Go binary, PostgreSQL, zero magic. You can read the code.
+- **Beating competitors** — P@5 of 80% vs LlamaIndex's 55% and Qdrant's 27% on real-world queries.
 
-| 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 |
+Star it if you want agents that understand your code, not just search it.
 
-### 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 |
+## What It Does
 
-### Code Intelligence
+nano-brain is an **agent-oriented infrastructure layer** that sits between your AI agent and your codebase.
 
-| 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) |
+It solves two problems agents have:
 
-### Dependency Graph
+1. **Session amnesia** — Agents forget everything when the session ends. nano-brain persists context across sessions via harvesting, indexing, and retrieval.
+2. **Codebase blindness** — Agents can't trace dependencies, measure blast radius, or understand control flow. nano-brain builds a live code graph and exposes it via 16 MCP tools.
 
-| 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 |
+**Why MCP?** Because agents don't read docs. They call tools. Every capability is a tool call — no REST API ceremony, no JSON parsing, no manual file reading.
 
-## Installation & Quick Start
+### How agents use it
 
-```bash
-# Install globally
-npm install -g nano-brain
+| Agent needs to... | Tool | What it returns |
+|---|---|---|
+| Understand a feature | `memory_query` | Hybrid search results with context |
+| Check what breaks before editing | `memory_impact` | Blast radius — all dependent files |
+| Trace an execution path | `memory_trace` | Call chain from entry point |
+| Find a function definition | `memory_symbols` | Symbol location + kind |
+| Recall a past decision | `memory_query` | Past session context |
+| Save a discovery | `memory_write` | Persisted for future sessions |
+
+---
 
-# Initialize (creates config, indexes codebase, generates embeddings)
-npx nano-brain init --root=/path/to/your/project
+## Architecture
 
-# Check everything is working
-npx nano-brain status
+```mermaid
+graph LR
+    A[Your AI Agent] -->|MCP Protocol| B[nano-brain]
+    B --> C[PostgreSQL + pgvector]
+    B --> D[Session Harvesting]
+    B --> E[Code Intelligence]
+    B --> F[Hybrid Search]
+    
+    D --> D1[OpenCode Sessions]
+    D --> D2[Claude Code Sessions]
+    
+    E --> E1[Symbol Graph]
+    E --> E2[Flow Diagrams]
+    E --> E3[Impact Analysis]
+    
+    F --> F1[BM25 Full-Text]
+    F --> F2[Vector Similarity]
+    F --> F3[RRF Fusion]
 ```
 
-### Docker Deployment (Recommended)
+---
 
-The simplest way to run nano-brain as a persistent service:
+## Agent-Oriented Design
 
-```bash
-# Start nano-brain + Qdrant containers
-npx nano-brain docker start
+nano-brain isn't a memory tool with MCP bolted on. It's designed from the ground up around **how agents actually behave**.
 
-# Check status
-npx nano-brain docker status
+### The agent workflow loop
 
-# Stop
-npx nano-brain docker stop
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  Agent       │────▶│  memory_query │────▶│  Context     │
+│  receives    │     │  /impact/trace│     │  window      │
+│  task        │     │              │     │  filled      │
+└─────────────┘     └──────────────┘     └──────┬──────┘
+                                                 │
+                                          ┌──────▼──────┐
+                                          │  Agent       │
+                                          │  implements  │
+                                          │  change      │
+                                          └──────┬──────┘
+                                                 │
+                                          ┌──────▼──────┐
+                                          │  memory_write │
+                                          │  (persist)    │
+                                          └─────────────┘
 ```
 
-This runs the bundled `docker-compose.yml` which starts nano-brain (HTTP/SSE on port 3100) and Qdrant (ports 6333/6334). A `config.default.yml` is included as a starting template — copy it to `~/.nano-brain/config.yml` and customize.
+### Why agent behavior matters
 
-**Environment variables:**
-- `NANO_BRAIN_APP` — Path to nano-brain source directory (default: package install location)
-- `NANO_BRAIN_HOME` — Path to `~/.nano-brain` data directory (default: `~/.nano-brain`)
-- `NANO_BRAIN_WORKSPACE` — Path to your project workspace to index (mounted read-only and passed as `--root`)
+| Human workflow | Agent workflow | nano-brain response |
+|---|---|---|
+| Opens file, reads it | `memory_get` or `memory_search` | Returns structured content, not raw bytes |
+| Traces call chain manually | `memory_trace` | Returns function-by-function chain with line numbers |
+| Greps for callers | `memory_graph(direction="in")` | Returns all callers in one call |
+| Thinks "what breaks?" | `memory_impact` | Returns full blast radius in <50ms |
+| Remembers past decisions | `memory_query` | Returns cross-session context |
 
-**HTTP API** (available when Docker is running):
+### The 50ms rule
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/health` | GET | Health check |
-| `/api/status` | GET | Index health, collections, model status |
-| `/api/query` | POST | Hybrid search (body: `{query, tags, scope, limit}`) |
-| `/api/search` | POST | BM25 keyword search (body: `{query, limit}`) |
-| `/api/write` | POST | Write memory (body: `{content, tags, supersedes}`) |
-| `/api/reindex` | POST | Trigger reindex (body: `{root}`) |
-| `/mcp` | — | MCP endpoint (for AI agent integration) |
-| `/sse` | — | SSE transport (for MCP remote clients) |
+At 50ms latency, agents run impact analysis on every edit. At 500ms, they skip it. nano-brain is designed for the 50ms world — every code intelligence tool call is sub-50ms, making it practical for agents to use them on every operation.
 
-### MCP Configuration
+### What agents actually need
 
-Add to your AI agent's MCP config (e.g., `~/.config/opencode/opencode.json`):
+Research from 15+ production code intelligence tools shows:
 
-**Docker mode (recommended):**
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "remote",
-      "url": "http://host.docker.internal:3100/mcp",
-      "enabled": true
-    }
-  }
-}
-```
-
-Start the server via Docker:
-```bash
-npx nano-brain docker start       # Start nano-brain + Qdrant containers
-npx nano-brain docker status      # Check if running
-npx nano-brain docker stop        # Stop containers
-```
-
-**Local mode (stdio, for development):**
-```json
-{
-  "mcp": {
-    "nano-brain": {
-      "type": "local",
-      "command": ["npx", "nano-brain", "mcp"],
-      "enabled": true
-    }
-  }
-}
-```
+1. **Impact analysis is #1** — "What breaks if I change this?" is the most common agent query
+2. **Call chains > control flow** — Agents trace across files (inter-procedural), not within functions (intra-procedural)
+3. **Component composition > internal logic** — For frontend frameworks, "who uses this component?" matters more than "what does the template do?"
 
-**Claude Code (`.mcp.json`):**
-```json
-{
-  "mcpServers": {
-    "nano-brain": {
-      "command": "npx",
-      "args": ["mcp-remote", "http://localhost:3100/sse"]
-    }
-  }
-}
-```
+nano-brain optimizes for exactly these three patterns.
 
-## Configuration
+---
 
-Create `~/.nano-brain/config.yml` (auto-generated by `init`):
+## Key Features
 
-```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}
-  dimensions: 1024                    # Output dimensions (default: 1024); omit to use model default
-  # 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
-
-# File watcher
-watcher:
-  enabled: true
-  debounce: 300         # ms
-  reindexInterval: 300  # seconds (5 minutes)
-
-# 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
-```
+### Hybrid Search
 
-**Data directory layout (`~/.nano-brain/`):**
-```
-~/.nano-brain/
-├── config.yml    # Configuration
-├── data/         # SQLite databases (per-workspace)
-├── memory/       # Curated notes
-├── sessions/     # Harvested sessions
-└── logs/         # Application logs
+```mermaid
+graph LR
+    Q[Query] --> BM25[BM25 Full-Text]
+    Q --> Vector[Vector Similarity]
+    BM25 --> RRF[RRF Fusion]
+    Vector --> RRF
+    RRF --> Results[Ranked Results]
 ```
 
-## CLI Commands (27 Total)
+BM25 full-text + pgvector HNSW cosine similarity + Reciprocal Rank Fusion + recency decay.
 
-### Setup & Initialization
+### Code Intelligence
 
-```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
+```mermaid
+graph TD
+    A[Entry Point] --> B[Function Call]
+    B --> C[Method Call]
+    B --> D[Database Query]
+    C --> E[External Service]
+    D --> F[Redis Cache]
 ```
 
-### MCP Server
+- **Symbol extraction** — Functions, types, interfaces, constants
+- **Call chain tracing** — Follow execution paths across files
+- **Impact analysis** — "What breaks if I change this?"
+- **Flow diagrams** — Mermaid flowcharts and sequence diagrams
 
-```bash
-nano-brain mcp                                      # Start MCP server (stdio)
-nano-brain mcp --http --port=3100 --host=0.0.0.0   # Start MCP server (HTTP/SSE)
-```
+### Session Harvesting
 
-### Remote Server (Daemon)
-
-```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
+```mermaid
+graph LR
+    S1[OpenCode DB] --> H[Harvester]
+    S2[Claude Code JSONL] --> H
+    H --> L[LLM Summarizer]
+    L --> I[Indexer]
+    I --> DB[PostgreSQL]
 ```
 
-### Docker Deployment
+Auto-ingest from OpenCode and Claude Code sessions. Map-reduce LLM summarization. Incremental harvest with dedup.
 
-```bash
-nano-brain docker start       # Start nano-brain + Qdrant via docker compose
-nano-brain docker status      # Check container status
-nano-brain docker stop        # Stop containers
-```
+### 16 MCP Tools
 
-The `docker start` command runs the bundled `docker-compose.yml` which starts:
-- **nano-brain** — HTTP/SSE server on port 3100 (node:22-slim)
-- **Qdrant** — Vector store on ports 6333/6334
+| Tool | Description |
+|------|-------------|
+| `memory_query` | Hybrid search — default first tool for broad questions |
+| `memory_search` | BM25 keyword search for exact text/errors |
+| `memory_vsearch` | Vector similarity for fuzzy concepts |
+| `memory_get` | Get document by path or ID |
+| `memory_write` | Write/update document |
+| `memory_graph` | One-hop callers/callees/imports |
+| `memory_trace` | Downstream call chain trace |
+| `memory_impact` | Pre-change blast radius analysis |
+| `memory_symbols` | Symbol search (functions, types, interfaces) |
+| `memory_flow` | HTTP route execution flow |
+| `memory_flowchart` | Function-level control-flow graph |
+| `memory_workspaces_resolve` | Resolve path to workspace hash |
+| `memory_tags` | List tags with counts |
+| `memory_status` | Server and queue health |
+| `memory_update` | Trigger re-embedding |
+| `memory_wake_up` | Session-start workspace briefing |
 
-Environment variables for volume mounts:
-- `NANO_BRAIN_APP` — Path to nano-brain source (default: current directory)
-- `NANO_BRAIN_HOME` — Path to data directory (default: `~/.nano-brain`)
-- `NANO_BRAIN_WORKSPACE` — Path to your project workspace to index as codebase (mounted read-only, passed as `--root`)
+---
 
-### Search
+## Quick Start
 
-```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
-```
+### Prerequisites
 
-### Memory Management
+- **Go 1.23+** OR pre-built binary
+- **PostgreSQL 17** with **pgvector 0.8.2**
+- **Ollama** (for embeddings) or any OpenAI-compatible provider
 
-```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
-```
+### Configure Your AI Agent
 
-### Index Management
+Add to your MCP client config (Claude Code, OpenCode, Cursor, etc.):
 
-```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
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "http",
+      "url": "http://localhost:3100/mcp"
+    }
+  }
+}
 ```
 
-### Collections
+Optionally bind a default workspace to the connection by appending `?workspace=<name-or-hash>` to the URL (e.g. `"url": "http://localhost:3100/mcp?workspace=nano-brain"`) — tool calls can then omit the `workspace` argument. Run `nano-brain workspaces list` to see the registered name/hash for a project. An explicit `workspace` argument always overrides the connection default; the value must be a name or full hash, not `"all"`.
 
-```bash
-nano-brain collection add <name> <path>     # Add collection
-nano-brain collection remove <name>         # Remove collection
-nano-brain collection list                  # List collections
-```
+---
 
-### Workspace Management
-
-```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
-```
+## Demo
 
-### Qdrant Management
-
-> **Note:** If using `nano-brain docker start`, Qdrant is already included in the compose stack. These commands manage a standalone Qdrant container separately.
+### Query Your Codebase
 
 ```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
+# Search for authentication patterns
+curl -X POST http://localhost:3100/api/v1/query \
+  -H "Content-Type: application/json" \
+  -d '{"workspace": "abc123", "query": "how does authentication work"}'
 ```
 
-### Cache Management
+### Trace Call Chains
 
 ```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
+# Trace from entry point
+curl -X POST http://localhost:3100/api/v1/graph/trace \
+  -H "Content-Type: application/json" \
+  -d '{"workspace": "abc123", "node": "main.go::main", "max_depth": 5}'
 ```
 
-### Benchmarking
+### Analyze Impact
 
 ```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
+# What breaks if I change this file?
+curl -X POST http://localhost:3100/api/v1/graph/impact \
+  -H "Content-Type: application/json" \
+  -d '{"workspace": "abc123", "node": "src/auth/login.ts", "max_depth": 2}'
 ```
 
-### Logging
+### Generate Flow Diagrams
 
 ```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
+# Get flow diagram for a controller
+curl -X POST http://localhost:3100/api/v1/graph/flow \
+  -H "Content-Type: application/json" \
+  -d '{"workspace": "abc123", "entry": "POST /users"}'
 ```
 
-## Project Structure
+Returns Mermaid flowchart:
 
-```
-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
+```mermaid
+flowchart LR
+  POST_/users["POST /users"]
+  POST_/users --> UsersController#create
+  UsersController#create --> User.create
+  UsersController#create --> Mailer.welcome
 ```
 
-## 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)
+## Use Cases
 
-## Embedding & Reranking Providers
+### Agent-assisted refactoring
+Before refactoring, your agent calls `memory_impact` on the target function. Gets the full blast radius. Decides whether to split the change. After refactoring, runs affected tests only — not the full suite.
 
-**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
+### Multi-session feature development
+Session 1: Agent explores the codebase, discovers patterns. `memory_write` saves findings. Session 2: Agent recalls session 1's discoveries via `memory_query`. No context lost between sessions.
 
-**Reranking:**
-- **VoyageAI** — rerank-2.5-lite (neural reranking, recommended)
+### Legacy codebase onboarding
+Index a 5-year-old codebase. Your agent can now answer "what does this function do?", "why does this class exist?", "if I change this file, what else breaks?" — without reading every file.
 
-**Query Expansion:**
-- Pipeline support exists but no active provider. The interface is ready for future integration.
+### Cross-service debugging
+Agent traces a bug from frontend to backend. `memory_trace` follows the call chain across services. `memory_graph` shows which microservices depend on the failing endpoint.
 
-## How nano-brain Compares
+### Team knowledge sharing
+One server, whole team. Every developer's AI agent connects to the same PostgreSQL. Decisions, architecture notes, code intelligence — instantly shared. New hires get full context from day one.
 
-| | 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 |
+---
 
-### Where nano-brain shines
+## Performance
 
-- **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
+### Search Quality vs Competitors
 
-### Consider alternatives if
+| Metric | nano-brain | LlamaIndex | Qdrant/Mem0 | Cognee | GraphRAG | Zep |
+|--------|------------|------------|-------------|--------|----------|-----|
+| P@5 | **80%** | 55% | 27% | — | — | — |
+| MRR | **95%** | — | — | — | — | — |
+| Latency | **42ms** | — | — | — | — | — |
+| Code Intelligence | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Symbol Graph | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Impact Analysis | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Flow Diagrams | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
 
-- 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)
+Tested on 60 domain-specific queries across 3 workspaces. nano-brain is the **only** solution with code intelligence — competitors focus on conversation memory and document retrieval.
 
-## AI Agent Integration
+### Competitive Landscape
 
-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:
+**What competitors offer:**
+- **Mem0 / Zep** — Conversation memory, temporal ranking, chat history recall
+- **Cognee / GraphRAG** — Document-level knowledge graphs, multi-hop reasoning
+- **LlamaIndex** — Flexible RAG pipelines, document retrieval
 
-- **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
+**What nano-brain adds (agent-oriented):**
+- **Impact analysis** — "What breaks if I change this?" — the #1 question agents ask. Pre-computed blast radius in <50ms.
+- **Call chain tracing** — Follow execution paths across files. Agent gets a structured trace, not raw source.
+- **Symbol graph** — Find definitions, callers, callees. `memory_symbols` + `memory_graph`.
+- **Agent-oriented benchmarks** — Measures how well agents find context for domain tasks — not just search precision in isolation.
 
-### SKILL.md (Auto-loaded)
+**The difference:** Competitors optimize for "did the agent find the right document?" nano-brain optimizes for "did the agent understand the codebase well enough to make the right change?"
 
-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.
+At 50ms latency, agents run impact analysis on every edit. At 500ms, they skip it. nano-brain is designed for the 50ms world.
 
-### AGENTS_SNIPPET.md (Optional, project-level)
+### Agent-Oriented Capability Benchmarks
 
-For project-level integration, `AGENTS_SNIPPET.md` provides a managed block that can be injected into a project's `AGENTS.md`:
+nano-brain is built for agents. These benchmarks measure how well agents can **find relevant context for real-world domain tasks** using nano-brain's MCP tools — not just search quality in isolation.
 
-```bash
-npx nano-brain init --root=/path/to/project
-```
+Each benchmark runs a deterministic agent workflow:
+1. **query_question** — natural-language domain question
+2. **query_input** — optimized search query
+3. **symbols_identifiers** — symbol lookup for known identifiers
 
-This adds a managed block to your project's `AGENTS.md` with quick reference tables for CLI commands and MCP tools (if available).
+This mimics how a real agent explores a codebase: broad understanding first, then targeted retrieval.
 
-See [SKILL.md](./SKILL.md) for full routing rules and [AGENTS_SNIPPET.md](./AGENTS_SNIPPET.md) for the project-level snippet.
+#### Scores
 
-## Self-Learning Configuration
+| Workspace | Domain | Overall | Multi-tool | Search-QA | Symbol-Lookup |
+|-----------|--------|---------|------------|-----------|---------------|
+| **nano-brain** | Go daemon | **1.000** | 1.000 | 1.000 | 1.000 |
+| **TypeScript** | CS2 item trading | **0.885** | 1.000 | 0.817 | 1.000 |
+| **Rails** | CS2 item trading | **0.795** | 1.000 | 0.726 | 0.667 |
 
-nano-brain includes an adaptive self-learning system that improves search quality over time.
+**What this means:**
+- **Multi-tool 1.000** — When agents combine search + symbols, they find every expected context item
+- **Overall 0.885** — TypeScript workspace: agent finds 88.5% of expected domain artifacts
+- **Fixed vs Agent** — Agent workflow improves recall by 15-40% over single-tool queries
+- **Unique capability** — No competitor offers agent-oriented benchmarks or code intelligence
 
-### Quick Start
+#### How to Run
 
-Add to your `config.yml`:
+```bash
+# TypeScript workspace (CS2 item trading domain)
+NANO_BRAIN_URL=http://localhost:3100 \
+NANO_BRAIN_WORKSPACE=<your-workspace-hash> \
+go test -v -tags=capbench -run TestCapabilityBenchmark \
+  ./benchmarks/typescript/capability/
 
-```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
+# Rails workspace (CS2 item trading domain)
+NANO_BRAIN_URL=http://localhost:3100 \
+NANO_BRAIN_WORKSPACE=<your-workspace-hash> \
+go test -v -tags=capbench -run TestCapabilityBenchmark \
+  ./benchmarks/rails/capability/
+
+# nano-brain itself (Go daemon)
+NANO_BRAIN_URL=http://localhost:3100 \
+NANO_BRAIN_WORKSPACE=nano-brain \
+go test -v -tags=capbench -run TestCapabilityBenchmark \
+  ./benchmarks/capability/
 ```
 
-### How It Works
+#### Task Categories
 
-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.
+| Category | What It Tests | Tools Used |
+|----------|---------------|------------|
+| **search-qa** | Domain concept retrieval via search | `query_question`, `query_input` |
+| **symbol-lookup** | Known identifier resolution | `query_input`, `symbols_identifiers` |
+| **multi-tool** | Cross-tool workflow (search → symbols) | All three tools in sequence |
 
-### CLI Commands
+See individual benchmark READMEs for full task breakdowns:
+- [`benchmarks/typescript/capability/README.md`](benchmarks/typescript/capability/README.md)
+- [`benchmarks/rails/capability/README.md`](benchmarks/rails/capability/README.md)
+- [`benchmarks/capability/README.md`](benchmarks/capability/README.md)
 
-- `nano-brain learning rollback [version_id]` — View or rollback to a previous config version
-- `nano-brain consolidate` — Trigger a manual consolidation cycle
+---
 
-### MCP Tools
+## Ruby / Rails Support
 
-- `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)
+nano-brain supports Ruby and Ruby on Rails code intelligence:
 
-## Memory Intelligence v2
+- **Rails routes** — `resources`, `get`/`post`/`patch`/`put`/`delete`, `namespace`
+- **Control-flow graphs** — `if`/`else`, loops, `begin`/`rescue`, method defs
+- **Cross-file resolution** — Class→file index, resolver, reconcile edges
+- **Flow diagrams** — Controller→service→model chains (20-34 nodes)
 
-nano-brain includes three advanced intelligence features that make your memory smarter over time.
+Example flow for a Rails controller action:
 
-### Entity Pruning
+```mermaid
+flowchart LR
+  POST_/users["POST /users"]
+  POST_/users --> UsersController#create
+  UsersController#create --> User.create
+  UsersController#create --> Mailer.welcome
+```
 
-Automatically cleans up outdated or contradicted information from the knowledge graph.
+---
 
-**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
+## Tech Stack
 
-**Configuration:**
-```yaml
-pruning:
-  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
-```
+- **Go 1.23** — Single static binary (`CGO_ENABLED=0`)
+- **PostgreSQL 17** — 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
+
+---
 
-**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.
+## Configuration
 
-### LLM Categorization
+Config file: `~/.nano-brain/config.yml`
 
-Adds semantic categorization to your memories using an LLM, going beyond simple keyword matching.
+```yaml
+server:
+  host: localhost
+  port: 3100
 
-**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)
+database:
+  url: postgres://nanobrain:nanobrain@localhost:5432/nanobrain_dev
 
-**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
+embedding:
+  provider: ollama
+  url: http://localhost:11434
+  model: nomic-embed-text
 
-**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
+search:
+  rrf_k: 60
+  recency_weight: 0.3
+  limit: 20
 ```
 
-**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."
+See [Configuration](docs/CONFIGURATION.md) for full options.
 
-### Preference Learning
+---
 
-Learns which types of memories you expand most often and boosts them in future searches.
+## Documentation
 
-**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
+- [Getting Started](docs/GETTING_STARTED.md) — Step-by-step setup guide
+- [Configuration](docs/CONFIGURATION.md) — All config options
+- [REST API](docs/API.md) — HTTP endpoints
+- [CLI Commands](docs/CLI.md) — Command reference
+- [MCP Tools](docs/MCP.md) — Tool documentation
+- [Architecture](docs/ARCHITECTURE.md) — System design
+- [Changelog](CHANGELOG.md) — What's new
+- [Roadmap](docs/ROADMAP.md) — What's planned
+- [Feature Showcase](docs/FEATURES.md) — Visual examples
 
-**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.
+---
 
-**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%)
-```
+## Contributing
 
-**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.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-## Proactive Intelligence
+### Development Setup
 
-nano-brain can predict what you'll need next based on your query patterns.
+```bash
+# Clone the repo
+git clone https://github.com/nano-step/nano-brain.git
+cd nano-brain
+
+# Build
+CGO_ENABLED=0 go build -o nano-brain ./cmd/nano-brain
 
-### How It Works
+# Run tests
+go test -race -short ./...
 
-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
+# Run integration tests (requires PostgreSQL)
+go test -race -tags=integration ./...
+```
 
-### Configuration
+### Project Structure
 
-```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
+```
+nano-brain/
+├── cmd/nano-brain/       # CLI dispatcher + server startup
+├── internal/
+│   ├── config/           # Configuration management
+│   ├── server/           # HTTP server + handlers
+│   ├── storage/          # PostgreSQL + sqlc
+│   ├── search/           # Hybrid search pipeline
+│   ├── embed/            # Embedding queue
+│   ├── watcher/          # File system watcher
+│   ├── harvest/          # Session harvesting
+│   ├── mcp/              # MCP protocol tools
+│   ├── graph/            # Code intelligence
+│   └── ...
+├── migrations/           # Database migrations
+└── benchmarks/           # Performance benchmarks
 ```
 
-### 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)
+## Community
 
-## Troubleshooting
+- [GitHub Discussions](https://github.com/nano-step/nano-brain/discussions) — Ask questions, share ideas
+- [Discord](https://discord.gg/nano-brain) — Real-time chat
+- [Twitter](https://twitter.com/nano_brain) — Updates and announcements
 
-**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.
+## License
 
-**Empty LLM responses**: Check model name is correct. For Ollama, run `ollama list` to see available models.
+MIT — see [LICENSE](LICENSE) for details.
 
-**Consolidation not running**: Ensure `consolidation.enabled: true` and check `memory_consolidation_status` for queue state.
+---
 
-## License
+## Acknowledgments
 
-MIT
+Built with:
+- [Go](https://go.dev/) — Fast, statically typed language
+- [PostgreSQL](https://www.postgresql.org/) — The world's most advanced open source database
+- [pgvector](https://github.com/pgvector/pgvector) — Open-source vector similarity search
+- [Echo](https://echo.labstack.com/) — High performance, extensible, minimalist Go web framework
+- [sqlc](https://sqlc.dev/) — Generate type-safe code from SQL
+- [goose](https://github.com/pressly/goose) — Database migration tool
+- [zerolog](https://github.com/rs/zerolog) — Zero allocation JSON logger
+- [koanf](https://github.com/knadh/koanf) — Configuration manager
+- [fsnotify](https://github.com/fsnotify/fsnotify) — Cross-platform file system notifications