npm package: @nano-step/nano-brain
Description: Persistent memory system for AI coding agents. Hybrid search (BM25 + vector + LLM reranking) across past sessions, codebase, curated notes, and daily logs.
Latest version: 2026.1.14

# 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