@nano-step/nano-brain 2026.1.14

package/openspec/specs/workspace-scoping/spec.md

@@ -0,0 +1,70 @@
+# workspace-scoping Specification
+
+## Purpose
+TBD - created by archiving change workspace-scoped-memory-and-storage-limits. Update Purpose after archive.
+## Requirements
+### Requirement: Workspace detection from PWD
+The MCP server SHALL compute a `projectHash` from `process.cwd()` at startup using `sha256(cwd).substring(0, 12)`. This hash SHALL be stored as `currentProjectHash` on the server context and used for all default search filtering.
+
+#### Scenario: Server starts in a workspace directory
+- **WHEN** the MCP server starts with `PWD=/Users/alice/projects/my-app`
+- **THEN** `currentProjectHash` is set to the first 12 characters of `sha256("/Users/alice/projects/my-app")`
+- **THEN** the hash is consistent across restarts in the same directory
+
+#### Scenario: Hash matches harvester convention
+- **WHEN** the MCP server computes `currentProjectHash` for a workspace
+- **THEN** the hash matches the directory name used by the harvester for that workspace's sessions (`sessions/{projectHash}/*.md`)
+
+### Requirement: Document-level project tagging
+The `documents` table SHALL have a `project_hash TEXT` column. Every document indexed from a session file SHALL be tagged with the projectHash extracted from its file path. Non-session documents (MEMORY.md, daily logs) SHALL be tagged with `'global'`.
+
+#### Scenario: New document indexed from session file
+- **WHEN** a document is indexed from path `sessions/abc123def456/session-title.md`
+- **THEN** the document's `project_hash` column is set to `abc123def456`
+
+#### Scenario: New document indexed from non-session file
+- **WHEN** a document is indexed from `MEMORY.md` or a daily log file
+- **THEN** the document's `project_hash` column is set to `'global'`
+
+#### Scenario: Document path does not match session pattern
+- **WHEN** a document is indexed from a path that does not match `sessions/{hash}/*.md`
+- **THEN** the document's `project_hash` column is set to `'global'`
+
+### Requirement: Database migration for existing documents
+On startup, the store SHALL add the `project_hash` column if it does not exist, then backfill existing documents by extracting the projectHash from their file paths.
+
+#### Scenario: First startup after upgrade
+- **WHEN** the store opens a database that lacks the `project_hash` column
+- **THEN** the column is added via `ALTER TABLE documents ADD COLUMN project_hash TEXT DEFAULT 'global'`
+- **THEN** existing documents with paths matching `sessions/{hash}/*.md` are updated with the correct projectHash
+- **THEN** existing documents not matching the pattern retain `project_hash = 'global'`
+
+#### Scenario: Subsequent startup
+- **WHEN** the store opens a database that already has the `project_hash` column
+- **THEN** no migration runs
+- **THEN** no data is modified
+
+### Requirement: Default search scoping to current workspace
+All search operations SHALL filter results to documents matching `currentProjectHash` or `'global'` by default. This ensures searches return only results relevant to the current workspace plus cross-project notes.
+
+#### Scenario: Search without workspace parameter
+- **WHEN** `memory_search` is called with `{"query": "authentication"}` and no `workspace` parameter
+- **THEN** only documents with `project_hash = currentProjectHash` or `project_hash = 'global'` are returned
+- **THEN** documents from other workspaces are excluded
+
+#### Scenario: Global documents always included
+- **WHEN** a search is performed with default workspace scoping
+- **THEN** MEMORY.md entries and daily logs (tagged `'global'`) are included in results
+- **THEN** session documents from other workspaces are excluded
+
+### Requirement: Cross-workspace search opt-in
+All search tools SHALL accept an optional `workspace` parameter. When set to `"all"`, search results SHALL include documents from all workspaces. When set to a specific hash, results SHALL be filtered to that workspace plus `'global'`.
+
+#### Scenario: Search with workspace="all"
+- **WHEN** `memory_search` is called with `{"query": "auth", "workspace": "all"}`
+- **THEN** documents from all workspaces are included in results
+
+#### Scenario: Search with specific workspace hash
+- **WHEN** `memory_search` is called with `{"query": "auth", "workspace": "abc123def456"}`
+- **THEN** only documents with `project_hash = 'abc123def456'` or `project_hash = 'global'` are returned
+

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nano-step/nano-brain",
+  "version": "2026.1.14",
+  "type": "module",
+  "bin": {
+    "nano-brain": "./bin/cli.js"
+  },
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "bun src/index.ts",
+    "start": "node bin/cli.js",
+    "mcp": "node bin/cli.js mcp",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:esm": "! grep -r 'require(' src/ --include='*.ts'"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "chokidar": "^5.0.0",
+    "fast-glob": "^3.3.3",
+    "node-llama-cpp": "^3.3.3",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "tsx": "^4.21.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "bun-types": "^1.3.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/site/build.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, readdirSync, watchFile, statSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const SITE_DIR = __dirname
+const ROOT_DIR = resolve(SITE_DIR, '..')
+const PARTIALS_DIR = join(SITE_DIR, 'partials')
+const OUTPUT = join(ROOT_DIR, 'index.html')
+
+function readFile(path) {
+  return readFileSync(path, 'utf-8')
+}
+
+function build() {
+  const start = Date.now()
+
+  let shell = readFile(join(SITE_DIR, 'shell.html'))
+  const styles = readFile(join(SITE_DIR, 'styles.css'))
+  const script = readFile(join(SITE_DIR, 'script.js'))
+
+  shell = shell.replace('{{styles}}', styles)
+  shell = shell.replace('{{script}}', script)
+
+  shell = shell.replace(/\{\{partial:([a-z0-9-]+)\}\}/g, (_match, name) => {
+    const partialPath = join(PARTIALS_DIR, `_${name}.html`)
+    try {
+      return readFile(partialPath).trimEnd()
+    } catch (err) {
+      console.error(`  ❌ Missing partial: ${partialPath}`)
+      process.exit(1)
+    }
+  })
+
+  writeFileSync(OUTPUT, shell, 'utf-8')
+
+  const size = statSync(OUTPUT).size
+  const kb = (size / 1024).toFixed(1)
+  const ms = Date.now() - start
+  console.log(`  ✅ Built index.html (${kb} KB) in ${ms}ms`)
+}
+
+console.log('🔨 Building nano-brain landing page...')
+build()
+
+if (process.argv.includes('--watch')) {
+  console.log('👀 Watching for changes...')
+
+  const watchTargets = [
+    join(SITE_DIR, 'shell.html'),
+    join(SITE_DIR, 'styles.css'),
+    join(SITE_DIR, 'script.js'),
+    ...readdirSync(PARTIALS_DIR).map((f) => join(PARTIALS_DIR, f)),
+  ]
+
+  for (const file of watchTargets) {
+    watchFile(file, { interval: 300 }, () => {
+      console.log(`  🔄 Changed: ${file.replace(ROOT_DIR + '/', '')}`)
+      build()
+    })
+  }
+}

package/site/partials/_api.html

@@ -0,0 +1,83 @@
+      <section id="api" class="fade-in">
+        <h2 class="section-title">API Reference</h2>
+        <p class="section-subtitle">MCP tools for hybrid search, retrieval, and maintenance.</p>
+        <div class="grid api-grid">
+          <div class="api-card">
+            <h4><span class="chip">memory_search</span></h4>
+            <p>BM25 keyword search.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_vsearch</span></h4>
+            <p>Semantic vector search using embeddings.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_query</span></h4>
+            <p>Full hybrid search with query expansion, RRF fusion, and LLM reranking.</p>
+            <div class="params">
+              <span class="chip">query (required)</span>
+              <span class="chip">limit (default 10)</span>
+              <span class="chip">collection</span>
+              <span class="chip">minScore</span>
+              <span class="chip">workspace</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_get</span></h4>
+            <p>Retrieve document by path or docid (#abc123).</p>
+            <div class="params">
+              <span class="chip">id (required)</span>
+              <span class="chip">fromLine</span>
+              <span class="chip">maxLines</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_multi_get</span></h4>
+            <p>Batch retrieve by glob pattern.</p>
+            <div class="params">
+              <span class="chip">pattern (required)</span>
+              <span class="chip">maxBytes (default 50000)</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_write</span></h4>
+            <p>Write to daily log or MEMORY.md.</p>
+            <div class="params">
+              <span class="chip">content (required)</span>
+              <span class="chip">target ("daily" or "memory")</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_status</span></h4>
+            <p>Show index health, collections, model status.</p>
+            <div class="params">
+              <span class="chip">no params</span>
+            </div>
+          </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_update</span></h4>
+            <p>Trigger immediate reindex of all collections.</p>
+            <div class="params">
+              <span class="chip">no params</span>
+            </div>
+          <div class="api-card">
+            <h4><span class="chip">memory_index_codebase</span></h4>
+            <p>Index source files in the current workspace.</p>
+            <div class="params">
+              <span class="chip">root (optional)</span>
+            </div>
+          </div>
+          </div>
+        </div>
+      </section>

package/site/partials/_compare.html

@@ -0,0 +1,100 @@
+      <section id="compare" class="fade-in">
+        <h2 class="section-title">How nano-brain Compares</h2>
+        <p class="section-subtitle">The only MCP memory server with a full hybrid search pipeline — BM25 + vector + query expansion + LLM reranking. All local.</p>
+        <div class="compare-table-wrap">
+          <table class="compare-table">
+            <thead>
+              <tr>
+                <th>Feature</th>
+                <th class="highlight">nano-brain</th>
+                <th>Mem0</th>
+                <th>Zep</th>
+                <th>OMEGA</th>
+                <th>Letta</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Search</td>
+                <td class="highlight">BM25 + Vector + Reranking</td>
+                <td>Vector only</td>
+                <td>Graph + Vector</td>
+                <td>Semantic + BM25</td>
+                <td>Agent-managed</td>
+              </tr>
+              <tr>
+                <td>Storage</td>
+                <td class="highlight">SQLite (single file)</td>
+                <td>PostgreSQL + Qdrant</td>
+                <td>Neo4j</td>
+                <td>SQLite</td>
+                <td>PostgreSQL</td>
+              </tr>
+              <tr>
+                <td>Local AI Models</td>
+                <td class="highlight">GGUF (nomic + bge)</td>
+                <td>Cloud API</td>
+                <td>Cloud API</td>
+                <td>ONNX</td>
+                <td>Cloud API</td>
+              </tr>
+              <tr>
+                <td>Codebase Indexing</td>
+                <td class="highlight">&#10003;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+              </tr>
+              <tr>
+                <td>Session Recall</td>
+                <td class="highlight">&#10003;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+              </tr>
+              <tr>
+                <td>Query Expansion</td>
+                <td class="highlight">&#10003;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+              </tr>
+              <tr>
+                <td>LLM Reranking</td>
+                <td class="highlight">&#10003;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+                <td>&#10007;</td>
+              </tr>
+              <tr>
+                <td>Privacy</td>
+                <td class="highlight">100% local</td>
+                <td>Cloud API calls</td>
+                <td>Cloud / self-host</td>
+                <td>100% local</td>
+                <td>Self-host / cloud</td>
+              </tr>
+              <tr>
+                <td>External Deps</td>
+                <td class="highlight">None</td>
+                <td>Docker + PG + Qdrant</td>
+                <td>Docker + Neo4j</td>
+                <td>None</td>
+                <td>PostgreSQL</td>
+              </tr>
+              <tr>
+                <td>Pricing</td>
+                <td class="highlight">Free (MIT)</td>
+                <td>Free / $249/mo</td>
+                <td>Free / $25-475/mo</td>
+                <td>Free (Apache-2.0)</td>
+                <td>Free (Apache-2.0)</td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </section>

package/site/partials/_config.html

@@ -0,0 +1,23 @@
+      <section id="config" class="fade-in">
+        <h2 class="section-title">Configuration</h2>
+        <p class="section-subtitle">Drop this MCP config into your OpenCode settings.</p>
+        <pre class="codeblock"><code>{
+  <span class="token-string">"mcp"</span>: {
+    <span class="token-string">"nano-brain"</span>: {
+      <span class="token-string">"type"</span>: <span class="token-string">"local"</span>,
+      <span class="token-string">"command"</span>: [<span class="token-string">"node"</span>, <span class="token-string">"path/to/nano-brain/bin/cli.js"</span>, <span class="token-string">"mcp"</span>],
+      <span class="token-string">"enabled"</span>: <span class="token-boolean">true</span>
+    }
+  }
+}</code></pre>
+        <pre class="codeblock"><code><span class="token-comment"># ~/.config/nano-brain/config.yml</span>
+<span class="token-key">collections</span>:
+  <span class="token-key">memory</span>:
+    <span class="token-key">path</span>: <span class="token-string">~/.nano-brain</span>
+    <span class="token-key">pattern</span>: <span class="token-string">"**/*.md"</span>
+    <span class="token-key">update</span>: <span class="token-string">auto</span>
+  <span class="token-key">sessions</span>:
+    <span class="token-key">path</span>: <span class="token-string">~/.local/share/opencode/sessions</span>
+    <span class="token-key">pattern</span>: <span class="token-string">"**/*.json"</span>
+    <span class="token-key">update</span>: <span class="token-string">auto</span></code></pre>
+      </section>

package/site/partials/_features.html

@@ -0,0 +1,43 @@
+      <section id="features" class="fade-in">
+        <h2 class="section-title">Features</h2>
+        <p class="section-subtitle">
+          Premium local memory with a hybrid search pipeline, SQLite foundations, codebase indexing, and MCP-first ergonomics.
+        </p>
+        <div class="grid features">
+          <div class="card">
+            <div class="icon">🔍</div>
+            <h3>Hybrid Search Pipeline</h3>
+            <p>Query expansion → parallel BM25 + vector search → RRF fusion → LLM reranking</p>
+          </div>
+          <div class="card">
+            <div class="icon">🧠</div>
+            <h3>Local AI Models</h3>
+            <p>nomic-embed-text-v1.5, bge-reranker-v2-m3, qmd-query-expansion-1.7B — all GGUF, fully offline</p>
+          </div>
+          <div class="card">
+            <div class="icon">🗄️</div>
+            <h3>SQLite + sqlite-vec</h3>
+            <p>FTS5 for BM25 keyword search, sqlite-vec for vector similarity — single-file database</p>
+          </div>
+          <div class="card">
+            <div class="icon">🔌</div>
+            <h3>MCP Server</h3>
+            <p>10 tools via stdio transport, integrates with any MCP-compatible AI agent</p>
+          </div>
+          <div class="card">
+            <div class="icon">📚</div>
+            <h3>Multi-Collection</h3>
+            <p>Sessions, daily logs, curated memory — all indexed and searchable</p>
+          </div>
+          <div class="card">
+            <div class="icon">🔒</div>
+            <h3>Privacy First</h3>
+            <p>100% local processing, no cloud dependencies, your data stays on your machine</p>
+          </div>
+          <div class="card">
+            <div class="icon">🧬</div>
+            <h3>Codebase Indexing</h3>
+            <p>Index source files with structural boundary detection. Workspace-scoped search across sessions and code.</p>
+          </div>
+        </div>
+      </section>

package/site/partials/_footer.html

@@ -0,0 +1,6 @@
+      <footer>
+        <div>MIT License · Inspired by <a href="https://github.com/tobi/qmd">QMD</a> & <a href="https://github.com/openclaw/openclaw">OpenClaw</a></div>
+        <div>
+          <a href="https://github.com/kokorolx/nano-brain">GitHub</a>
+        </div>
+      </footer>

package/site/partials/_hero.html

@@ -0,0 +1,9 @@
+      <section class="hero fade-in" id="hero">
+        <span class="badge">v2026.1.0</span>
+        <h1>nano-brain</h1>
+        <p>Persistent hybrid search memory for AI coding agents.</p>
+        <div class="hero-actions">
+          <a class="button primary" href="https://github.com/kokorolx/nano-brain">GitHub</a>
+          <span class="code-pill">npm i nano-brain</span>
+        </div>
+      </section>

package/site/partials/_how-it-works.html

@@ -0,0 +1,26 @@
+      <section id="how" class="fade-in">
+        <h2 class="section-title">How It Works</h2>
+        <p class="section-subtitle">
+          Query expansion and dual retrieval streams converge through RRF fusion (k=60), then a reranker refines the final ordering.
+        </p>
+        <div class="pipeline">
+          <div class="pipeline-row">
+            <div class="node">Query</div>
+            <div class="connector"></div>
+            <div class="node">Query Expansion</div>
+          </div>
+          <div class="merge"></div>
+          <div class="pipeline-row split">
+            <div class="node">BM25 Search</div>
+            <div class="node">Vector Search</div>
+          </div>
+          <div class="merge"></div>
+          <div class="pipeline-row">
+            <div class="node">RRF Fusion (k=60)</div>
+            <div class="connector"></div>
+            <div class="node">LLM Reranking</div>
+            <div class="connector"></div>
+            <div class="node">Results</div>
+          </div>
+        </div>
+      </section>

package/site/partials/_models.html

@@ -0,0 +1,18 @@
+      <section id="models" class="fade-in">
+        <h2 class="section-title">Models</h2>
+        <p class="section-subtitle">Local GGUF models sized for efficient offline retrieval.</p>
+        <div class="grid models">
+          <div class="model-card">
+            <h4>nomic-embed-text-v1.5 (~270MB)</h4>
+            <p>Embeddings</p>
+          </div>
+          <div class="model-card">
+            <h4>bge-reranker-v2-m3 (~1.1GB)</h4>
+            <p>Reranking</p>
+          </div>
+          <div class="model-card">
+            <h4>qmd-query-expansion-1.7B (~1GB)</h4>
+            <p>Query Expansion</p>
+          </div>
+        </div>
+      </section>

package/site/partials/_quick-start.html

@@ -0,0 +1,15 @@
+      <section id="quick-start" class="fade-in">
+        <h2 class="section-title">Quick Start</h2>
+        <p class="section-subtitle">CLI workflows for MCP, search, and indexing.</p>
+        <pre class="codeblock"><code><span class="token-comment"># MCP server</span>
+nano-brain mcp              <span class="token-comment"># Start MCP server (stdio)</span>
+nano-brain mcp --http       <span class="token-comment"># Start MCP server (HTTP)</span>
+
+<span class="token-comment"># Search</span>
+nano-brain search "query"   <span class="token-comment"># BM25 search</span>
+nano-brain query "query"    <span class="token-comment"># Hybrid search</span>
+
+<span class="token-comment"># Index management</span>
+nano-brain status           <span class="token-comment"># Show index health</span>
+nano-brain update           <span class="token-comment"># Reindex all collections</span></code></pre>
+      </section>

package/site/partials/_stats.html

@@ -0,0 +1 @@
+      <div class="stats fade-in">2700+ documents indexed | 15 workspaces | 3 AI models | 10 MCP tools | 428 tests passing</div>

package/site/partials/_tech-stack.html

@@ -0,0 +1,13 @@
+      <section id="tech" class="fade-in">
+        <h2 class="section-title">Tech Stack</h2>
+        <div class="tech-stack">
+          <span class="tech-pill">TypeScript</span>
+          <span class="tech-pill">Bun</span>
+          <span class="tech-pill">SQLite</span>
+          <span class="tech-pill">sqlite-vec</span>
+          <span class="tech-pill">FTS5</span>
+          <span class="tech-pill">node-llama-cpp</span>
+          <span class="tech-pill">MCP SDK</span>
+          <span class="tech-pill">chokidar</span>
+        </div>
+      </section>

package/site/script.js

@@ -0,0 +1,12 @@
+const observer = new IntersectionObserver(
+  (entries) => {
+    entries.forEach((entry) => {
+      if (entry.isIntersecting) {
+        entry.target.classList.add('visible')
+      }
+    })
+  },
+  { threshold: 0.15 }
+)
+
+document.querySelectorAll('.fade-in').forEach((el) => observer.observe(el))

package/site/shell.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>nano-brain · MCP Server</title>
+    <style>
+      {{styles}}
+    </style>
+  </head>
+  <body>
+    <header class="nav">
+      <div class="nav-inner">
+        <div class="brand"><span class="brand-dot"></span>nano-brain</div>
+        <nav class="nav-links">
+          <a href="#features">Features</a>
+          <a href="#compare">Compare</a>
+          <a href="#how">How It Works</a>
+          <a href="#api">API</a>
+          <a href="#config">Config</a>
+          <a href="#models">Models</a>
+        </nav>
+      </div>
+    </header>
+
+    <div class="page">
+      {{partial:hero}}
+      {{partial:features}}
+      {{partial:compare}}
+      {{partial:how-it-works}}
+      {{partial:api}}
+      {{partial:config}}
+      {{partial:quick-start}}
+      {{partial:models}}
+      {{partial:tech-stack}}
+      {{partial:stats}}
+      {{partial:footer}}
+    </div>
+
+    <script>
+      {{script}}
+    </script>
+  </body>
+</html>