nano-brain 2026.3.21 → 2026.3.23

package/AGENTS.md

@@ -19,11 +19,6 @@ All commands use the CLI via Bash tool:
 
 ### Session Workflow
 
-**Start of session:** Check memory for relevant past context before exploring the codebase.
-```
-npx nano-brain query "what have we done regarding {current task topic}"
-```
-
 **End of session:** Save key decisions, patterns discovered, and debugging insights.
 ```bash
 cat > ~/.nano-brain/memory/$(date +%Y-%m-%d)-summary.md << 'EOF'

package/README.md

@@ -1,10 +1,21 @@
 # nano-brain
 
-Persistent memory system for AI coding agents. Hybrid search (BM25 + vector + LLM reranking) across past sessions, codebase, curated notes, and daily logs.
+Persistent memory and code intelligence for AI coding agents.
 
 ## What It Does
 
-An MCP server that gives AI coding agents persistent memory across sessions. Indexes markdown documents, past sessions, and daily logs into a searchable SQLite database with FTS5 and vector embeddings. Provides 17+ MCP tools for search, retrieval, and memory management using a sophisticated hybrid search pipeline with query expansion, RRF fusion, and neural reranking. Runs as local stdio or remote SSE server for Docker/container environments.
+An MCP server that gives AI coding agents persistent memory across sessions. Indexes markdown documents, past sessions, daily logs, and codebase symbols into a searchable SQLite database with FTS5 and vector embeddings. Provides 17 MCP tools for search, retrieval, code intelligence, and memory management using a hybrid search pipeline with RRF fusion and VoyageAI neural reranking.
+
+## 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
 
 Inspired by [QMD](https://github.com/tobi/qmd) and [OpenClaw](https://github.com/openclaw/openclaw).
 
@@ -15,7 +26,7 @@ User Query
     │
     ▼
 ┌─────────────────┐
-│ Query Expansion  │ ← qmd-query-expansion-1.7B (GGUF)
+│ Query Expansion  │ ← (currently stubbed, planned)
 │ (optional)       │   generates 2-3 query variants
 └────────┬────────┘
          │
@@ -23,7 +34,9 @@ User Query
     ▼         ▼
 ┌────────┐ ┌──────────┐
 │ BM25   │ │ Vector   │
-│ (FTS5) │ │(sqlite-  │
+│ (FTS5) │ │ (Qdrant  │
+│        │ │  or      │
+│        │ │ sqlite-  │
 │        │ │  vec)    │
 └───┬────┘ └────┬─────┘
     │           │
@@ -35,8 +48,20 @@ User Query
          │
          ▼
 ┌─────────────────┐
-│  LLM Reranking  │ ← bge-reranker-v2-m3 (GGUF)
-│  (optional)     │
+│ 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)      │
 └────────┬────────┘
          │
          ▼
@@ -49,16 +74,95 @@ User Query
     Final Results
 ```
 
-## How It Works
+## Search Pipeline (3 Tiers)
+
+**`memory_search`** — BM25 only (fast, exact keyword matching)
+
+**`memory_vsearch`** — Vector only (semantic similarity via embeddings)
 
-### Storage Layer
+**`memory_query`** — Full hybrid pipeline with 6 ranking signals:
 
-- **SQLite** via better-sqlite3 for document metadata and content
-- **FTS5** virtual table with porter stemming for BM25 full-text search
-- **sqlite-vec** extension for vector similarity search (cosine distance)
-- **Content-addressed storage** using SHA-256 hash deduplication
+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
 
-### Chunking
+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
+
+## Chunking Strategy
 
 Heading-aware markdown chunking that respects document structure:
 
@@ -66,60 +170,86 @@ Heading-aware markdown chunking that respects document structure:
 - **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
 
-### Search Pipeline (3 Tiers)
+## Storage & Infrastructure
 
-**`memory_search`** — BM25 only (fast, exact keyword matching)
+**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)
 
-**`memory_vsearch`** — Vector only (semantic similarity via embeddings)
+**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
 
-**`memory_query`** — Full hybrid pipeline:
-1. Query expansion generates 2-3 variants (optional)
-2. Parallel BM25 + vector search
-3. RRF fusion (k=60, original query weighted 2×)
-4. LLM reranking with bge-reranker-v2-m3 (optional)
-5. Position-aware blending:
-   - Top 3 results: 75% RRF / 25% rerank
-   - Ranks 4-10: 60% RRF / 40% rerank
-   - Ranks 11+: 40% RRF / 60% rerank
+**Embedding providers**:
+- **VoyageAI** — voyage-code-3 (1024 dims, code-optimized)
+- **Ollama** — local models (nomic-embed-text, etc.)
+- **OpenAI-compatible** — Azure, LM Studio, custom endpoints
 
-### Collections
+**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
 
-- **YAML-configured** directories of markdown files
-- **Auto-indexing** via chokidar file watcher
-- **Incremental updates** using dirty-flag tracking
-- **Session harvesting** converts OpenCode JSON sessions into searchable markdown
+## MCP Tools (17 Total)
 
-## MCP Tools
+### Search & Retrieval
 
 | Tool | Description |
 |------|-------------|
-| `memory_search` | BM25 keyword search (fast) |
-| `memory_vsearch` | Semantic vector search |
-| `memory_query` | Full hybrid search with expansion + reranking |
+| `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_write` | Write to daily log (tagged with workspace) |
-| `memory_status` | Index health, collections, model status |
-| `memory_index_codebase` | Index codebase files in current workspace |
+
+### Memory 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 |
+
+### 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
+
+| Tool | Description |
+|------|-------------|
 | `memory_focus` | File dependency context (imports/exports, centrality, cluster) |
-| `memory_graph_stats` | Dependency graph overview with cycle detection |
-| `memory_symbols` | Cross-repo symbol query (Redis keys, PubSub, MySQL tables, API endpoints) |
+| `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_tags` | List all tags with document counts |
-| `code_context` | 360° view of a code symbol (callers, callees, flows) |
-| `code_impact` | Change impact analysis (upstream/downstream dependencies) |
-| `code_detect_changes` | Map git diff to affected symbols |
 
-## Installation
+## Installation & Quick Start
+
 ```bash
+# Install globally
 npm install -g nano-brain
-```
-
-### Quick Start
 
-```bash
 # Initialize (creates config, indexes codebase, generates embeddings)
 npx nano-brain init --root=/path/to/your/project
 
@@ -127,7 +257,11 @@ npx nano-brain init --root=/path/to/your/project
 npx nano-brain status
 ```
 
-Add to your AI agent's MCP config (e.g. `~/.config/opencode/opencode.json`):
+### MCP Configuration
+
+Add to your AI agent's MCP config (e.g., `~/.config/opencode/opencode.json`):
+
+**Local mode (stdio):**
 ```json
 {
   "mcp": {
@@ -140,7 +274,7 @@ Add to your AI agent's MCP config (e.g. `~/.config/opencode/opencode.json`):
 }
 ```
 
-For remote mode (e.g., running on host while AI agent runs in Docker):
+**Remote mode (HTTP/SSE, for Docker/containers):**
 ```json
 {
   "mcp": {
@@ -153,9 +287,20 @@ For remote mode (e.g., running on host while AI agent runs in Docker):
 }
 ```
 
+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
+```
+
 ## Configuration
+
 Create `~/.nano-brain/config.yml` (auto-generated by `init`):
+
 ```yaml
+# Collections (directories to index)
 collections:
   memory:
     path: ~/.nano-brain/memory
@@ -166,93 +311,242 @@ collections:
     pattern: "**/*.md"
     update: auto
 
-# Embedding configuration
+# 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: ollama
-  url: http://localhost:11434        # Auto-detected: localhost natively, host.docker.internal in Docker
-  model: nomic-embed-text
+  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
+
+# 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
+
+# Logging
+logging:
+  level: info           # debug, info, warn, error
+  file: ~/.nano-brain/logs/nano-brain.log
+  maxSize: 10485760     # 10MB
+  maxFiles: 5
 ```
 
-**Collection options:**
-- `path` — Directory to index
-- `pattern` — Glob pattern for files
-- `update` — `auto` (watch for changes) or `manual`
-
-**Embedding options:**
-- `provider` — `ollama` (default)
-- `url` — Ollama API URL (auto-detected during `init`)
-- `model` — Embedding model name (default: `nomic-embed-text`)
-
 **Data directory layout (`~/.nano-brain/`):**
 ```
 ~/.nano-brain/
 ├── config.yml    # Configuration
 ├── data/         # SQLite databases (per-workspace)
-├── models/       # Embedding model cache
 ├── memory/       # Curated notes
-└── sessions/     # Harvested sessions
+├── sessions/     # Harvested sessions
+└── logs/         # Application logs
 ```
 
-## CLI Usage
+## CLI Commands (24 Total)
+
+### Setup & Initialization
 
 ```bash
-# Setup
 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
+```
+
+### MCP Server
 
-# MCP server
+```bash
 nano-brain mcp                                      # Start MCP server (stdio)
 nano-brain mcp --http --port=3100 --host=0.0.0.0   # Start MCP server (HTTP/SSE)
+```
+
+### Remote Server (Daemon)
 
-# Remote server
+```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
+```
+
+### 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
+```
+
+### Memory Management
 
-# Index management
-nano-brain status           # Show index health
-nano-brain update           # Reindex all collections
+```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
+```
+
+### Index Management
+
+```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
+```
 
-# Search
-nano-brain search "query"   # BM25 search
-nano-brain vsearch "query"  # Vector search
-nano-brain query "query"    # Hybrid search
+### Collections
 
-# Collections
+```bash
 nano-brain collection add <name> <path>     # Add collection
 nano-brain collection remove <name>         # Remove collection
 nano-brain collection list                  # List collections
+```
+
+### Workspace Management
 
-# 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
 ```
 
+### Qdrant Management
+
+```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
+```
+
+### Cache Management
+
+```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
+
+```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
+```
+
+### Logging
+
+```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
+```
+
 ## Project Structure
 
 ```
 src/
 ├── index.ts          # CLI entry point
-├── server.ts         # MCP server (17+ tools, stdio/HTTP/SSE)
+├── server.ts         # MCP server (17 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 (Ollama API + GGUF fallback)
-├── reranker.ts       # GGUF reranker model (bge-reranker-v2-m3)
-├── expansion.ts      # GGUF query expansion (qmd-query-expansion-1.7B)
+├── 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)
-└── types.ts          # TypeScript interfaces
+├── 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         # 739 tests (vitest)
+└── *.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
 ```
@@ -260,46 +554,53 @@ AGENTS_SNIPPET.md     # Optional project-level AGENTS.md managed block
 ## Tech Stack
 
 - **TypeScript + Node.js** (via tsx)
-- **better-sqlite3** + **sqlite-vec** for storage
+- **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 (739 tests)
+- **vitest** for testing (760+ tests)
 
-## Models
+## Embedding & Reranking Providers
 
-Embeddings use Ollama API by default (nomic-embed-text via `http://localhost:11434`). Query expansion and reranking use local GGUF models as fallback:
+**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
 
-- **Embeddings:** Ollama API (primary) or nomic-embed-text-v1.5 GGUF (~270MB, fallback)
-- **Reranker:** bge-reranker-v2-m3 (~1.1GB, GGUF)
-- **Query Expansion:** qmd-query-expansion-1.7B (~1GB, GGUF)
+**Reranking:**
+- **VoyageAI** — rerank-2.5-lite (neural reranking, recommended)
 
-GGUF models are downloaded automatically on first use to `~/.nano-brain/models/`.
+**Query Expansion:**
+- Pipeline support exists but no active provider. The interface is ready for future integration.
 
 ## How nano-brain Compares
 
 | | nano-brain | Mem0 / OpenMemory | Zep / Graphiti | OMEGA | Letta (MemGPT) | Claude Native |
 |---|---|---|---|---|---|---|
-| **Search** | Hybrid (BM25 + vector + LLM reranking) | Vector only | Graph traversal + vector | Semantic + BM25 | Agent-managed | Text file read |
-| **Storage** | SQLite (single file) | PostgreSQL + Qdrant | Neo4j | SQLite | PostgreSQL / SQLite | Flat text files |
-| **MCP Tools** | 10 | 4-9 | 9-10 | 12 | 7 | 0 |
-| **Local-First** | Yes (zero cloud) | Requires OpenAI API key | Requires Docker + Neo4j | Yes | Yes | Yes |
-| **AI Models** | Local GGUF (nomic-embed, bge-reranker) | Cloud API (OpenAI) | Cloud API | Local ONNX | Cloud API | None |
-| **Codebase Indexing** | Yes (structural boundary detection) | No | No | No | No | No |
+| **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** | 17 | 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** | Yes (local LLM) | No | No | No | No | No |
-| **LLM Reranking** | Yes (bge-reranker-v2-m3) | No | No | No | No | No |
-| **Privacy** | 100% local, no data leaves machine | Cloud API calls | Cloud or self-host | 100% local | Self-host or cloud | Local files |
-| **Dependencies** | SQLite + GGUF models (~1.5GB) | Docker + PostgreSQL + Qdrant + OpenAI key | Docker + Neo4j | SQLite + ONNX | PostgreSQL | None |
+| **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
 
-- **Hybrid search pipeline** — the only MCP memory server with BM25 + vector + query expansion + LLM reranking in a single pipeline
+- **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
-- **Zero dependencies** — single SQLite file, local GGUF models, no Docker/PostgreSQL/Neo4j/API keys
-- **Privacy** — 100% local processing, your code and conversations never leave your machine
+- **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
 
@@ -315,6 +616,7 @@ nano-brain ships with a SKILL.md that teaches AI agents when and how to use memo
 - **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)
 
@@ -328,6 +630,8 @@ For project-level integration, `AGENTS_SNIPPET.md` provides a managed block that
 npx nano-brain init --root=/path/to/project
 ```
 
+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.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nano-brain",
-  "version": "2026.3.21",
+  "version": "2026.3.23",
   "type": "module",
   "bin": {
     "nano-brain": "./bin/cli.js"

package/src/reranker.ts

@@ -63,6 +63,11 @@ class VoyageAIReranker implements Reranker {
         this.onTokenUsage(this.model, data.total_tokens);
       }
 
+      if (!data.results || !Array.isArray(data.results)) {
+        log('reranker', `VoyageAI rerank returned unexpected response: ${JSON.stringify(data).slice(0, 200)}`, 'warn');
+        return { results: [], model: this.model };
+      }
+
       const results = data.results.map(r => ({
         file: documents[r.index].file,
         score: r.relevance_score,

package/src/server.ts

@@ -16,7 +16,7 @@ import { findCycles } from './graph.js';
 import { createStore, extractProjectHashFromPath, resolveWorkspaceDbPath } from './store.js';
 import { log, initLogger } from './logger.js';
 import { loadCollectionConfig, getCollections, scanCollectionFiles, getWorkspaceConfig } from './collections.js';
-import { createEmbeddingProvider, detectOllamaUrl, checkOllamaHealth } from './embeddings.js';
+import { createEmbeddingProvider, detectOllamaUrl, checkOllamaHealth, checkOpenAIHealth } from './embeddings.js';
 import { createReranker } from './reranker.js';
 import { startWatcher } from './watcher.js';
 import { parseStorageConfig } from './storage.js';
@@ -512,7 +512,10 @@ export function createMcpServer(deps: ServerDeps): McpServer {
       const provider = embeddingConfig?.provider || 'ollama'
       let embeddingHealth: { provider: string; url: string; model: string; reachable: boolean; models?: string[]; error?: string } | undefined
       
-      if (provider !== 'local') {
+      if (provider === 'openai' && embeddingConfig?.apiKey) {
+        const openaiHealth = await checkOpenAIHealth(ollamaUrl, embeddingConfig.apiKey, ollamaModel)
+        embeddingHealth = { provider, url: ollamaUrl, model: ollamaModel, ...openaiHealth }
+      } else if (provider !== 'local') {
         const ollamaHealth = await checkOllamaHealth(ollamaUrl)
         embeddingHealth = { provider, url: ollamaUrl, model: ollamaModel, ...ollamaHealth }
       } else {

package/src/store.ts

@@ -486,7 +486,14 @@ export function createStore(dbPath: string): Store {
         doc.active ? 1 : 0,
         doc.projectHash ?? 'global'
       );
-      return Number(result.lastInsertRowid);
+      // For UPSERT (ON CONFLICT DO UPDATE), lastInsertRowid returns a phantom
+      // autoincrement value that doesn't correspond to any actual row.
+      // Always verify via lookup to get the real id.
+      const existing = findDocumentByPathStmt.get(doc.path) as { id: number } | undefined;
+      if (existing) return existing.id;
+      const rowid = Number(result.lastInsertRowid);
+      if (rowid > 0) return rowid;
+      return 0;
     },
     
     findDocument(pathOrDocid: string): Document | null {