@nano-step/nano-brain 2026.1.14

package/.opencode/command/nano-brain-init.md

@@ -0,0 +1,13 @@
+---
+description: Initialize nano-brain persistent memory for the current workspace.
+---
+
+Run these MCP tools in order:
+
+1. `memory_status` — check if already initialized (codebase docs > 0 means skip to step 4)
+2. `memory_index_codebase` — index source files from workspace root
+3. `memory_update` — reindex sessions and curated notes
+4. `memory_status` — show final state
+
+Report: document counts, pending embeddings, and whether AGENTS.md snippet exists.
+If pending embeddings > 0, note they process in background.

package/.opencode/command/nano-brain-reindex.md

@@ -0,0 +1,11 @@
+---
+description: Rescan codebase and refresh all nano-brain indexes after branch switch or code changes.
+---
+
+Run these MCP tools:
+
+1. `memory_index_codebase` — rescan source files (detects new, changed, and deleted files via content hash)
+2. `memory_update` — refresh session and note indexes
+3. `memory_status` — show updated counts and pending embeddings
+
+Use after: branch switch, pull, major code changes, or when search results seem stale.

package/.opencode/command/nano-brain-status.md

@@ -0,0 +1,12 @@
+---
+description: Show nano-brain memory health and statistics.
+---
+
+Run `memory_status` and present a clean summary.
+
+Highlight: total docs, pending embeddings, collection breakdown, embedding server connectivity.
+
+Suggest actions if:
+- 0 codebase docs → "Run `/nano-brain-init`"
+- Pending embeddings > 0 → "Processing in background"
+- Embedding server unreachable → "Check Ollama: `ollama serve`"

package/AGENTS.md

@@ -0,0 +1,41 @@
+<!-- OPENCODE-MEMORY:START -->
+<!-- Managed block - do not edit manually. Updated by: npx nano-brain init -->
+
+## Memory System (nano-brain)
+
+This project uses **nano-brain** for persistent context across sessions.
+
+### Quick Reference
+
+| I want to... | Command |
+|--------------|---------|
+| Recall past work on a topic | `memory_query("topic")` |
+| Find exact error/function name | `memory_search("exact term")` |
+| Explore a concept semantically | `memory_vsearch("concept")` |
+| Save a decision for future sessions | `memory_write("decision context")` |
+| Check index health | `memory_status` |
+
+### Session Workflow
+
+**Start of session:** Check memory for relevant past context before exploring the codebase.
+```
+memory_query("what have we done regarding {current task topic}")
+```
+
+**End of session:** Save key decisions, patterns discovered, and debugging insights.
+```
+memory_write("## Summary\n- Decision: ...\n- Why: ...\n- Files: ...")
+```
+
+### When to Search Memory vs Codebase
+
+- **"Have we done this before?"** → `memory_query` (searches past sessions)
+- **"Where is this in the code?"** → grep / ast-grep (searches current files)
+- **"How does this concept work here?"** → Both (memory for past context + grep for current code)
+
+<!-- OPENCODE-MEMORY:END -->
+
+
+
+
+

package/AGENTS_SNIPPET.md

@@ -0,0 +1,44 @@
+<!-- OPENCODE-MEMORY:START -->
+<!-- Managed block - do not edit manually. Updated by: npx nano-brain init -->
+
+## Memory System (nano-brain)
+
+This project uses **nano-brain** for persistent context across sessions.
+
+### Quick Reference
+
+All commands use the CLI via Bash tool:
+
+| I want to... | Command |
+|--------------|---------|
+| Recall past work on a topic | `npx nano-brain query "topic"` |
+| Find exact error/function name | `npx nano-brain search "exact term"` |
+| Explore a concept semantically | `npx nano-brain vsearch "concept"` |
+| Save a decision for future sessions | Create file in `~/.nano-brain/memory/`, then `npx nano-brain update` |
+| Check index health | `npx nano-brain status` |
+
+### 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'
+## Summary
+- Decision: ...
+- Why: ...
+- Files: ...
+EOF
+npx nano-brain update
+```
+
+### When to Search Memory vs Codebase
+
+- **"Have we done this before?"** → `npx nano-brain query` (searches past sessions)
+- **"Where is this in the code?"** → grep / ast-grep (searches current files)
+- **"How does this concept work here?"** → Both (memory for past context + grep for current code)
+
+<!-- OPENCODE-MEMORY:END -->

package/CHANGELOG.md

@@ -0,0 +1,186 @@
+# Changelog
+
+## [2026.1.14] - 2026-03-03
+
+### Added
+
+- **Keyed memory tools**: 3 new MCP tools for updatable, topic-keyed memories that replace previous values on the same key — solving the long-standing problem of `memory_write` being append-only with no way to supersede stale knowledge.
+  - `memory_set(key, content)`: Write or update a keyed memory. Writes to `~/.nano-brain/memory/keys/{slug}.md` using `writeFileSync` (overwrite, not append). Leverages existing `insertDocument` upsert logic — FTS triggers rebuild search index on hash change, embedding pipeline handles orphaned vectors automatically.
+  - `memory_delete(key)`: Delete a keyed memory entry from disk and deactivate it in the search index. Returns informational message (not error) if key doesn't exist.
+  - `memory_keys()`: List all keyed memory entries with names and last-modified timestamps. Handles missing/empty directory gracefully.
+- **`memory_write` unchanged**: Existing chronological daily logging continues to work as before. Keyed memories are a complementary mechanism, not a replacement.
+## [2026.1.13] - 2026-02-28
+
+### Fixed
+
+- **Workspace-scoped session indexing**: Session documents were indexed with the current workspace's `projectHash` instead of extracting it from the session file's directory path (`sessions/{hash}/*.md`). This caused all sessions from every workspace to be tagged as belonging to the current workspace, defeating workspace-scoped search. Added `extractProjectHashFromPath()` utility and fixed all 4 indexing code paths (watcher, init, update, memory_update tool).
+
+## [2026.1.12] - 2026-02-24
+
+### Fixed
+
+- **Session harvesting on Linux/Docker**: Harvester hardcoded `~/.opencode/storage` (macOS path). On Linux, OpenCode follows XDG and stores sessions at `~/.local/share/opencode/storage`. Added `resolveOpenCodeStorageDir()` that checks XDG path first and falls back to `~/.opencode/storage`, so harvesting now works on both platforms.
+
+### Changed
+
+- **Expanded built-in codebase exclude patterns**: `BUILTIN_EXCLUDE_PATTERNS` grew from 12 to 55 patterns covering all major ecosystems — prevents accidental indexing of large generated directories that cause OOM and DB bloat:
+  - **JS/TS**: `.pnpm-store`, `.yarn`, `bower_components`, `out`, `.svelte-kit`, `.astro`, `.remix`, `.turbo`, `.vercel`, `.cache`, `.parcel-cache`, `.vite`, `storybook-static`, `*.min.css`, `*.tsbuildinfo`, `.eslintcache`
+  - **Python**: `.venv`, `venv`, `env`, `.conda`, `*.egg-info`, `.mypy_cache`, `.ruff_cache`, `.pytest_cache`, `htmlcov`, `.tox`
+  - **Java/JVM**: `.gradle`, `.mvn`, `*.class`, `*.jar`, `*.war`
+  - **Ruby**: `gems`, `.bundle`
+  - **PHP**: `storage/framework`, `bootstrap/cache`
+  - **Mobile**: `Pods`, `*.xcworkspace`, `DerivedData`, `generated`
+  - **DevOps**: `.terraform`, `terraform.tfstate*`
+  - **Logs/tmp**: `logs`, `log`, `tmp`, `temp`, `*.log`
+  - **Test coverage**: `coverage`, `.nyc_output`, `lcov-report`
+  - **Version control**: `.svn`, `.hg`
+
+## [2026.1.11] - 2026-02-24
+
+### Fixed
+
+- **MCP singleton guard**: Multiple nano-brain MCP server instances would pile up (OpenCode respawns MCP servers on reconnect), causing SQLite lock contention and Ollama timeout errors. New PID-based singleton guard ensures only one instance runs — new instances kill the previous one, and old instances detect they've been superseded and exit gracefully.
+- **Ollama auto-reconnect**: If Ollama is unreachable at MCP server startup, the server falls back to local GGUF embeddings and now retries Ollama every 60 seconds. When Ollama becomes available, the embedding provider is hot-swapped without restart.
+
+## [2026.1.10] - 2026-02-24
+
+### Fixed
+
+- **Ollama timeout issues in Docker**: Increased health check timeout from 3s to 10s to handle Docker networking latency. Added 30s timeout to `embed()` and 60s timeout to `embedBatch()` — previously these had no timeout and could hang indefinitely.
+
+## [2026.1.9] - 2026-02-24
+
+### Changed
+
+- **Consolidated all data paths under `~/.nano-brain/`**: DB, models, config, sessions, and memory now all live under `~/.nano-brain/` instead of scattered across `~/.cache/nano-brain/` and `~/.config/nano-brain/`. This fixes data loss in Docker containers where `~/.cache` was an ephemeral anonymous volume.
+- **New directory layout**:
+  ```
+  ~/.nano-brain/
+  ├── config.yml    # Configuration (was ~/.config/nano-brain/config.yml)
+  ├── data/         # SQLite databases (was ~/.cache/nano-brain/)
+  ├── models/       # Embedding models (was ~/.cache/nano-brain/models/)
+  ├── memory/       # Curated notes
+  └── sessions/     # Harvested sessions
+  ```
+- **Cleanup command**: After upgrading, remove old paths with `rm -rf ~/.cache/nano-brain ~/.config/nano-brain`
+
+## [2026.1.8] - 2026-02-24
+
+### Fixed
+
+- **`init` no longer hangs on large collections**: Init now only indexes core collections (memory, sessions) and defers other collections to the MCP watcher. Previously, scanning a large project collection (e.g., thousands of source files) would block init indefinitely.
+- **`init` caps embedding at 50 documents**: Embeds first 50 docs for quick startup, reports remaining count, and defers the rest to the MCP server's background embedding interval. Previously tried to embed all documents synchronously.
+- **Per-collection progress logging**: Init now shows per-collection file counts and new/skipped stats.
+
+## [2026.1.7] - 2026-02-24
+
+### Fixed
+
+- **CLI per-workspace DB resolution**: CLI commands (`status`, `search`, `init`, etc.) now resolve the same per-workspace database as the MCP server (`{dirName}-{hash}.sqlite`). Previously CLI always read `default.sqlite`, showing stale data from the old global DB.
+- **"Chunks" → "Embedded" label**: Status output renamed misleading "Chunks" count (which counted `content_vectors` rows) to "Embedded" — accurately reflecting what it measures.
+
+## [2026.1.6] - 2026-02-24
+
+### Added
+
+- **Per-workspace codebase config**: Global config now supports a `workspaces` map, allowing different codebase settings (enabled, extensions, exclude) per project. `init --root=/path` creates a workspace entry with codebase enabled by default.
+- **`getWorkspaceConfig()` resolver**: Resolution order: workspace map → top-level `codebase` fallback → default (enabled). Existing configs with top-level `codebase` continue working without migration.
+- **`setWorkspaceConfig()` helper**: Programmatic API for adding/updating workspace entries in config.
+
+### Changed
+
+- **`init` writes workspace entries**: Instead of a single global `codebase` field, `handleInit()` now adds per-workspace entries to the `workspaces` map. Multiple `init --root=` calls for different projects coexist.
+- **Server resolves workspace config**: `startServer()` uses `getWorkspaceConfig()` to resolve codebase config for the current workspace instead of reading the top-level `codebase` field.
+
+## [2026.1.4] - 2026-02-23
+
+### Added
+
+- **Slash commands**: 3 OpenCode slash commands shipped in `commands/` dir — `/nano-brain-init` (first-time setup), `/nano-brain-status` (health check), `/nano-brain-reindex` (rescan after branch switch). Installed to both global and project `.opencode/command/` during `init`.
+- **Slash command auto-install in `init`**: `handleInit()` copies slash command `.md` files from the package's `commands/` directory to global (`~/.config/opencode/.opencode/command/`) and project-level (`.opencode/command/`) directories.
+
+### Changed
+
+- **SKILL.md rewritten**: Cut from 153 lines to 45. Concise tool selection table, slash command reference, collection filtering, complementary tools note. No redundant parameter docs.
+
+## [2026.1.3] - 2026-02-23
+
+### Added
+
+- **`init` command**: Full self-initializing setup via `npx nano-brain init --root=/path`. Creates config with auto-detected Ollama URL, indexes codebase, harvests sessions, indexes collections, generates embeddings, and injects AGENTS.md snippet. One command to go from zero to fully operational.
+- **Ollama embedding support**: Configurable embedding provider in `~/.config/nano-brain/config.yml`. Supports Ollama API with auto-detected URL (localhost:11434 natively, host.docker.internal:11434 in Docker). User-overridable model and URL.
+- **Embedding server health in `status`**: `npx nano-brain status` and MCP `memory_status` tool now show embedding server connectivity, model availability, and available models.
+- **`checkOllamaHealth()` utility**: Probes Ollama API for connectivity and model availability, used by both `init` and `status`.
+
+### Fixed
+
+- **ESM `require()` bug in Docker detection**: `detectOllamaUrl()` used `require('fs')` inside an ESM module, which silently failed and always returned localhost even inside Docker. Fixed by using ESM `import { accessSync, readFileSync } from 'fs'`.
+- **sqlite-vec `INSERT OR REPLACE` bug**: sqlite-vec virtual tables don't support `INSERT OR REPLACE` — they treat it as plain `INSERT`, causing `UNIQUE constraint failed` errors on re-embedding. Fixed with DELETE-then-INSERT pattern.
+- **`init` never generated embeddings**: `handleInit()` indexed documents but never created an embedding provider or called `embedPendingCodebase()`. Documents stayed permanently "pending". Fixed by adding embedding step after indexing.
+
+## [2026.1.0] - 2026-02-23
+
+### Added
+
+- **AI agent routing instructions (SKILL.md)**: Enhanced SKILL.md with trigger phrases, when-to-use rules, tool selection guide, collection filtering, and integration patterns for orchestrator and subagent workflows. Agents now auto-route to memory for recall, past decisions, cross-session context, and repeated patterns.
+- **AGENTS_SNIPPET.md**: Optional managed block for project-level AGENTS.md installation. Provides quick reference table, session workflow (start/end), and memory vs codebase search guidance. Designed for `npx nano-brain init` injection.
+- **`memory_index_codebase` documented**: Added to SKILL.md, README, and site API reference.
+- **`workspace` parameter documented**: Added to search tool docs showing workspace scoping.
+
+## [0.3.0] - 2026-02-23
+
+### Added
+
+- **Codebase indexing**: Opt-in source code indexing via `codebase: { enabled: true }` in config.yml. Indexes source files from the current workspace into the search pipeline for semantic code search.
+- **Source code chunker**: Line-based chunking with structural boundary detection (function/class/type definitions, import blocks). Same 900-token target and 15% overlap as markdown chunker. Metadata headers (`File:`, `Language:`, `Lines:`) prepended to each chunk.
+- **Project type auto-detection**: Detects project type from marker files (package.json, pyproject.toml, go.mod, Cargo.toml, etc.) and selects appropriate file extensions to index. Falls back to all common extensions.
+- **Exclude pattern merging**: Combines exclude patterns from three sources: config `codebase.exclude`, `.gitignore`, and built-in defaults (node_modules, .git, dist, build, etc.).
+- **Codebase storage budget**: Independent `codebase.maxSize` (default 2GB) limits codebase storage separately from session storage. Indexing stops when budget is exceeded. Storage usage reported in `memory_status`.
+- **Max file size guard**: Skips files larger than `codebase.maxFileSize` (default 5MB) to avoid indexing generated/minified files.
+- **`memory_index_codebase` MCP tool**: On-demand full codebase scan and index with summary stats (files scanned, indexed, skipped, storage usage).
+- **Codebase stats in `memory_status`**: Shows enabled state, document count, storage used/limit, resolved extensions, and exclude pattern count.
+- **Watcher integration**: File watcher monitors workspace directory for source code changes with exclude patterns, triggering incremental reindex.
+- **`getCollectionStorageSize()`**: New Store method to query per-collection storage usage.
+- **118 new tests**: `codebase.test.ts` (68 tests), `codebase-chunker.test.ts` (50 tests). Total: 428 tests.
+
+### Changed
+
+- Increased vitest worker heap size to 8GB to prevent OOM during test runs with large test suites.
+
+## [0.2.0] - 2026-02-23
+
+### Added
+
+- **Workspace scoping**: Search results are now scoped to the current workspace by default. Each workspace is identified by a SHA-256 hash of its directory path, matching the harvester convention. Cross-workspace search is available via `workspace: "all"` parameter.
+- **Storage limits**: Configurable `maxSize` (default 2GB), `retention` (default 90d), and `minFreeDisk` (default 100MB) in `config.yml` under a `storage` section. Human-readable values like `500MB`, `30d`, `1y` are supported.
+- **Disk safety guard**: Checks available disk space via `fs.statfsSync()` before writes. Skips harvest/reindex/embed when disk is critically low.
+- **Retention-based eviction**: Automatically deletes harvested session markdown older than the retention period during each harvest cycle.
+- **Size-based eviction**: If total storage exceeds `maxSize` after retention eviction, deletes oldest sessions until under limit. Original OpenCode session JSON is never touched.
+- **Orphan embedding cleanup**: Removes embedding vectors for deleted documents every 10 harvest cycles.
+- **Incremental harvesting**: Tracks session file mtimes in `.harvest-state.json` to skip unchanged files, reducing harvest time from O(all) to O(changed).
+- **`workspace` parameter** on `memory_search`, `memory_vsearch`, and `memory_query` MCP tools. Omit for current workspace, `"all"` for cross-workspace.
+- **Per-workspace stats** in `memory_status` output showing document counts per workspace hash.
+- **45 new tests**: `workspace.test.ts` (18), `storage.test.ts` (27), plus integration tests in `server.test.ts` and `watcher.test.ts`. Total: 310 tests.
+
+### Changed
+
+- Switched embedding model from EmbeddingGemma-300M (384d) to **nomic-embed-text-v1.5** (768d) for better search quality.
+- Switched reranker from Qwen3-Reranker-0.6B to **bge-reranker-v2-m3** (8192 context) for improved reranking.
+- Updated prompt format to nomic `search_query:`/`search_document:` convention.
+- `documents` table now has a `project_hash` column with automatic migration and backfill on first startup.
+
+### Fixed
+
+- Crash when session JSON has undefined `slug` field (now falls back to session id).
+
+## [0.1.0] - 2026-02-16
+
+### Added
+
+- Initial release with hybrid search (BM25 + vector + LLM reranking).
+- 8 MCP tools: `memory_search`, `memory_vsearch`, `memory_query`, `memory_get`, `memory_multi_get`, `memory_write`, `memory_status`, `memory_update`.
+- SQLite storage with FTS5 and sqlite-vec.
+- Heading-aware markdown chunking.
+- YAML-configured collections with auto-indexing via chokidar.
+- OpenCode session harvesting (JSON to markdown).
+- GGUF model inference via node-llama-cpp.

package/README.md

@@ -0,0 +1,298 @@
+# nano-brain
+
+Persistent memory system for AI coding agents. Hybrid search (BM25 + vector + LLM reranking) across past sessions, codebase, curated notes, and daily logs.
+
+## What It Does
+
+An MCP server that gives AI coding agents persistent memory across sessions. Indexes markdown documents, past sessions, and daily logs into a searchable SQLite database with FTS5 and vector embeddings. Provides 10 MCP tools for search, retrieval, and memory management using a sophisticated hybrid search pipeline with query expansion, RRF fusion, and neural reranking.
+
+Inspired by [QMD](https://github.com/tobi/qmd) and [OpenClaw](https://github.com/openclaw/openclaw).
+
+## Architecture
+
+```
+User Query
+    │
+    ▼
+┌─────────────────┐
+│ Query Expansion  │ ← qmd-query-expansion-1.7B (GGUF)
+│ (optional)       │   generates 2-3 query variants
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+┌────────┐ ┌──────────┐
+│ BM25   │ │ Vector   │
+│ (FTS5) │ │(sqlite-  │
+│        │ │  vec)    │
+└───┬────┘ └────┬─────┘
+    │           │
+    ▼           ▼
+┌─────────────────┐
+│  RRF Fusion     │ ← k=60, original query 2× weight
+│                 │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  LLM Reranking  │ ← bge-reranker-v2-m3 (GGUF)
+│  (optional)     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Position-Aware  │ ← top 3: 75/25, 4-10: 60/40, 11+: 40/60
+│ Blending        │   (RRF weight / rerank weight)
+└────────┬────────┘
+         │
+         ▼
+    Final Results
+```
+
+## How It Works
+
+### Storage Layer
+
+- **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
+
+### Chunking
+
+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
+
+### 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:
+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
+
+### Collections
+
+- **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
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | BM25 keyword search (fast) |
+| `memory_vsearch` | Semantic vector search |
+| `memory_query` | Full hybrid search with expansion + reranking |
+| `memory_get` | Retrieve document by path or docid (#abc123) |
+| `memory_multi_get` | Batch retrieve by glob pattern |
+| `memory_write` | Write to daily log (tagged with workspace) |
+| `memory_status` | Index health, collections, model status |
+| `memory_index_codebase` | Index codebase files in current workspace |
+| `memory_update` | Trigger reindex of all collections |
+
+## Installation
+```bash
+npm install -g nano-brain
+```
+
+### Quick Start
+
+```bash
+# Initialize (creates config, indexes codebase, generates embeddings)
+npx nano-brain init --root=/path/to/your/project
+
+# Check everything is working
+npx nano-brain status
+```
+
+Add to your AI agent's MCP config (e.g. `~/.config/opencode/opencode.json`):
+```json
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "local",
+      "command": ["npx", "nano-brain", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Configuration
+Create `~/.nano-brain/config.yml` (auto-generated by `init`):
+```yaml
+collections:
+  memory:
+    path: ~/.nano-brain/memory
+    pattern: "**/*.md"
+    update: auto
+  sessions:
+    path: ~/.nano-brain/sessions
+    pattern: "**/*.md"
+    update: auto
+
+# Embedding configuration
+embedding:
+  provider: ollama
+  url: http://localhost:11434        # Auto-detected: localhost natively, host.docker.internal in Docker
+  model: nomic-embed-text
+```
+
+**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
+```
+
+## CLI Usage
+
+```bash
+# Setup
+nano-brain init               # Full initialization (config, index, embed, AGENTS.md)
+nano-brain init --root=/path  # Initialize for specific project
+# MCP server
+nano-brain mcp              # Start MCP server (stdio)
+nano-brain mcp --http       # Start MCP server (HTTP, port 8282)
+# Index management
+nano-brain status           # Show index health
+nano-brain update           # Reindex all collections
+# Search
+nano-brain search "query"   # BM25 search
+nano-brain vsearch "query"  # Vector search
+nano-brain query "query"    # Hybrid search
+# Collections
+nano-brain collection add <name> <path>     # Add collection
+nano-brain collection remove <name>         # Remove collection
+nano-brain collection list                  # List collections
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts          # CLI entry point
+├── server.ts         # MCP server (10 tools, stdio/HTTP)
+├── store.ts          # SQLite storage (FTS5 + sqlite-vec)
+├── search.ts         # Hybrid search pipeline (RRF, reranking, blending)
+├── chunker.ts        # Heading-aware markdown chunking
+├── collections.ts    # YAML config, collection scanning
+├── embeddings.ts     # Embedding providers (Ollama API + GGUF fallback)
+├── reranker.ts       # GGUF reranker model (bge-reranker-v2-m3)
+├── expansion.ts      # GGUF query expansion (qmd-query-expansion-1.7B)
+├── harvester.ts      # OpenCode session → markdown converter
+├── watcher.ts        # File watcher (chokidar, dirty flags)
+└── types.ts          # TypeScript interfaces
+bin/
+└── cli.js            # CLI wrapper
+
+test/
+└── *.test.ts         # 428 tests (vitest)
+SKILL.md              # AI agent routing instructions (auto-loaded by OpenCode)
+AGENTS_SNIPPET.md     # Optional project-level AGENTS.md managed block
+```
+
+## Tech Stack
+
+- **TypeScript + Node.js** (via tsx)
+- **better-sqlite3** + **sqlite-vec** for storage
+- **@modelcontextprotocol/sdk** for MCP server
+- **node-llama-cpp** for GGUF model inference
+- **chokidar** for file watching
+- **vitest** for testing (428 tests)
+
+## Models
+
+All models are GGUF format, loaded on-demand:
+
+- **Embeddings:** nomic-embed-text-v1.5 (~270MB)
+- **Reranker:** bge-reranker-v2-m3 (~1.1GB)
+- **Query Expansion:** qmd-query-expansion-1.7B (~1GB)
+
+Models are downloaded automatically on first use to `~/.nano-brain/models/`.
+
+## How nano-brain Compares
+
+| | nano-brain | Mem0 / OpenMemory | Zep / Graphiti | OMEGA | Letta (MemGPT) | Claude Native |
+|---|---|---|---|---|---|---|
+| **Search** | Hybrid (BM25 + vector + LLM reranking) | Vector only | Graph traversal + vector | Semantic + BM25 | Agent-managed | Text file read |
+| **Storage** | SQLite (single file) | PostgreSQL + Qdrant | Neo4j | SQLite | PostgreSQL / SQLite | Flat text files |
+| **MCP Tools** | 10 | 4-9 | 9-10 | 12 | 7 | 0 |
+| **Local-First** | Yes (zero cloud) | Requires OpenAI API key | Requires Docker + Neo4j | Yes | Yes | Yes |
+| **AI Models** | Local GGUF (nomic-embed, bge-reranker) | Cloud API (OpenAI) | Cloud API | Local ONNX | Cloud API | None |
+| **Codebase Indexing** | Yes (structural boundary detection) | No | No | No | No | No |
+| **Session Recall** | Yes (auto-harvests past sessions) | No | No | No | No | Limited (CLAUDE.md) |
+| **Query Expansion** | Yes (local LLM) | No | No | No | No | No |
+| **LLM Reranking** | Yes (bge-reranker-v2-m3) | No | No | No | No | No |
+| **Privacy** | 100% local, no data leaves machine | Cloud API calls | Cloud or self-host | 100% local | Self-host or cloud | Local files |
+| **Dependencies** | SQLite + GGUF models (~1.5GB) | Docker + PostgreSQL + Qdrant + OpenAI key | Docker + Neo4j | SQLite + ONNX | PostgreSQL | None |
+| **Pricing** | Free (open source, MIT) | Free tier / Pro $249/mo | Free self-host / Cloud $25-475/mo | Free (Apache-2.0) | Free (Apache-2.0) | Free (with Claude) |
+| **GitHub Stars** | New | ~47K | ~23K | ~25 | ~21K | N/A |
+
+### Where nano-brain shines
+
+- **Hybrid search pipeline** — the only MCP memory server with BM25 + vector + query expansion + LLM reranking in a single pipeline
+- **Codebase indexing** — index your source files with structural boundary detection, not just conversations
+- **Session recall** — automatically harvests and indexes past AI coding sessions
+- **Zero dependencies** — single SQLite file, local GGUF models, no Docker/PostgreSQL/Neo4j/API keys
+- **Privacy** — 100% local processing, your code and conversations never leave your machine
+
+### Consider alternatives if
+
+- You need a knowledge graph with temporal reasoning (Zep/Graphiti)
+- You want a full agent framework, not just memory (Letta)
+- You need cloud-hosted memory shared across teams (Mem0 Cloud)
+- You only need basic session notes (Claude native memory)
+
+## AI Agent Integration
+
+nano-brain ships with a SKILL.md that teaches AI agents when and how to use memory tools. When loaded as an OpenCode skill, agents automatically:
+
+- **Check memory before starting work** — recall past decisions, patterns, and context
+- **Save context after completing work** — persist key decisions and debugging insights
+- **Route queries to the right search tool** — BM25 for exact terms, vector for concepts, hybrid for best quality
+
+### SKILL.md (Auto-loaded)
+
+The skill file at `SKILL.md` provides routing rules, trigger phrases, tool selection guides, and integration patterns. It's automatically loaded when any agent references the `nano-brain` skill.
+
+### AGENTS_SNIPPET.md (Optional, project-level)
+
+For project-level integration, `AGENTS_SNIPPET.md` provides a managed block that can be injected into a project's `AGENTS.md`:
+
+```bash
+npx nano-brain init --root=/path/to/project
+```
+
+See [SKILL.md](./SKILL.md) for full routing rules and [AGENTS_SNIPPET.md](./AGENTS_SNIPPET.md) for the project-level snippet.
+
+## License
+
+MIT