@nano-step/nano-brain 2026.1.14

package/openspec/changes/codebase-indexing/tasks.md

@@ -0,0 +1,56 @@
+## 1. Types and Configuration
+
+- [x] 1.1 Add `CodebaseConfig` interface to `src/types.ts` with fields: `enabled: boolean`, `exclude?: string[]`, `extensions?: string[]`, `maxFileSize?: string`, `maxSize?: string`
+- [x] 1.2 Add optional `codebase?: CodebaseConfig` field to `CollectionConfig` interface in `src/types.ts`
+- [x] 1.3 Add `CodebaseIndexResult` interface to `src/types.ts` with fields: `filesScanned`, `filesIndexed`, `filesSkippedUnchanged`, `filesSkippedTooLarge`, `filesSkippedBudget`, `chunksCreated`, `storageUsedBytes`, `maxSizeBytes`
+- [x] 1.4 Add `codebase` stats to `IndexHealth` interface: `codebase?: { enabled: boolean; documents: number; chunks: number; extensions: string[]; excludeCount: number; storageUsed: number; maxSize: number }`
+
+## 2. Codebase Scanner Module
+
+- [x] 2.1 Create `src/codebase.ts` with built-in default exclude patterns, project type marker file map
+- [x] 2.2 Implement `detectProjectType(workspaceRoot: string): string[]` — check marker files, return merged extensions list, always include `.md`
+- [x] 2.3 Implement `loadGitignorePatterns(workspaceRoot: string): string[]` — parse `.gitignore` from workspace root, return patterns array, return empty array if file missing
+- [x] 2.4 Implement `mergeExcludePatterns(config: CodebaseConfig, workspaceRoot: string): string[]` — merge config excludes + .gitignore + built-in defaults into single array
+- [x] 2.5 Implement `resolveExtensions(config: CodebaseConfig, workspaceRoot: string): string[]` — return config extensions if set, otherwise auto-detect from project type
+- [x] 2.6 Implement `scanCodebaseFiles(workspaceRoot: string, config: CodebaseConfig): Promise<{ files: string[]; skippedTooLarge: number }>` — use fast-glob with resolved extensions as pattern and merged excludes as ignore, filter by maxFileSize (default 5MB), return absolute paths
+- [x] 2.7 Implement `indexCodebase(store, workspaceRoot, config, projectHash, embedder?): Promise<CodebaseIndexResult>` — scan files, compute hashes, skip unchanged, chunk with `chunkSourceCode`, index via store, deactivate deleted files, embed new chunks, enforce maxSize budget
+
+## 3. Source Code Chunker
+
+- [x] 3.1 Add `findSourceCodeBreakPoints(content: string): BreakPoint[]` to `src/chunker.ts` — score structural boundaries: double blank lines (score 90), function/class/type definitions at line start (score 80), single blank lines (score 40), import/export blocks (score 60), regular line breaks (score 1)
+- [x] 3.2 Add `chunkSourceCode(content: string, hash: string, filePath: string, workspaceRoot: string, options?: ChunkOptions): MemoryChunk[]` to `src/chunker.ts` — split using source code break points, prepend metadata header (`File:`, `Language:`, `Lines:`) to each chunk, use same target size (3600 chars) and overlap (540 chars) as markdown chunker
+- [x] 3.3 Add `inferLanguage(filePath: string): string` helper — map file extension to language name (`.ts` → `typescript`, `.py` → `python`, `.go` → `go`, etc.)
+
+## 4. Watcher Integration
+
+- [x] 4.1 Add `codebaseConfig?: CodebaseConfig` and `workspaceRoot?: string` and `projectHash?: string` fields to `WatcherOptions` interface in `src/watcher.ts`
+- [x] 4.2 In `setupWatcher()`, when `codebaseConfig?.enabled`, add workspace root as additional chokidar watch target with merged exclude patterns as `ignored` option
+- [x] 4.3 In watcher file change handlers (`add`, `change`, `unlink`), check if file matches codebase extensions (not just `.md`) and trigger `handleFileChange` accordingly
+- [x] 4.4 In `triggerReindex()`, after collection reindex loop, if codebase is enabled, call `indexCodebase()` for the workspace root
+
+## 5. MCP Server Integration
+
+- [x] 5.1 Register `memory_index_codebase` tool in `src/server.ts` — no required params, calls `indexCodebase()`, returns `CodebaseIndexResult` summary with storage usage. If codebase not enabled, return error message.
+- [x] 5.2 Update `memory_status` handler in `src/server.ts` to include codebase stats section (enabled, document count, storage used/limit, resolved extensions, exclude count) when codebase is enabled
+- [x] 5.3 Load codebase config from `CollectionConfig.codebase` at server startup and pass to watcher setup
+
+## 6. Storage Budget
+
+- [x] 6.1 Add `maxSize?: string` to `CodebaseConfig` (default 2GB)
+- [x] 6.2 Add `getCollectionStorageSize(collection: string): number` to Store interface and implement in `src/store.ts`
+- [x] 6.3 Enforce budget in `indexCodebase()` — track cumulative storage, skip files when over limit
+- [x] 6.4 Report storage usage in `getCodebaseStats()` and `formatStatus()`
+
+## 7. Tests
+
+- [ ] 7.1 Add unit tests for `detectProjectType()` — Node.js, Python, Go, Rust, multi-marker, no-marker scenarios
+- [ ] 7.2 Add unit tests for `loadGitignorePatterns()` — existing .gitignore, missing .gitignore, complex patterns
+- [ ] 7.3 Add unit tests for `mergeExcludePatterns()` — all three sources, missing sources, deduplication
+- [ ] 7.4 Add unit tests for `resolveExtensions()` — explicit config, auto-detect, fallback
+- [ ] 7.5 Add unit tests for `chunkSourceCode()` — TypeScript file, Python file, small file (single chunk), large file (multiple chunks with overlap), metadata header format
+- [ ] 7.6 Add unit tests for `findSourceCodeBreakPoints()` — function defs, class defs, blank lines, import blocks
+- [ ] 7.7 Add unit tests for `inferLanguage()` — all supported extensions, unknown extension
+- [ ] 7.8 Add unit tests for `scanCodebaseFiles()` — respects exclude patterns, respects extensions, skips files over maxFileSize
+- [ ] 7.9 Add integration test for `indexCodebase()` — indexes files, skips unchanged, detects deleted, tags with projectHash, enforces budget
+- [ ] 7.10 Add integration test for `memory_index_codebase` MCP tool — enabled case, disabled case
+- [ ] 7.11 Add integration test for `getCollectionStorageSize()` — returns correct size for collection

package/openspec/changes/fix-session-harvest-workspace-scoping/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-28

package/openspec/changes/fix-session-harvest-workspace-scoping/design.md

@@ -0,0 +1,84 @@
+## Context
+
+The `workspace-scoped-memory-and-storage-limits` change (archived 2026-02-23) introduced workspace-scoped search by adding a `project_hash` column to the `documents` table and filtering search results by `currentProjectHash`. The spec requires that session documents be tagged with the projectHash **extracted from their file path** (`sessions/{hash}/*.md`).
+
+However, the implementation has a bug in four code paths where session documents are indexed with the **wrong** projectHash:
+
+1. **`watcher.ts` → `triggerReindex()`** (line 122): Passes the watcher's own `projectHash` (current workspace) to `indexDocument()` for ALL collection files, including session files from other workspaces.
+2. **`index.ts` → `handleInit()`** (line 429): Indexes session collection files with no `projectHash`, defaulting to `undefined` → `'global'`.
+3. **`index.ts` → `handleUpdate()`** (line 539): Same issue as `handleInit`.
+4. **`server.ts` → `memory_update` tool** (line 460): Indexes all collection files without projectHash extraction.
+
+The session files on disk are correctly organized by projectHash (`~/.nano-brain/sessions/{projectHash}/*.md`), and the harvester correctly writes them there. The bug is purely in the indexing step that reads these files into the database.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Fix all four indexing code paths to extract projectHash from session file paths
+- Create a shared utility function for projectHash extraction
+- Ensure existing incorrectly-tagged documents get re-tagged on next reindex
+- Maintain backward compatibility — no API or config changes
+
+**Non-Goals:**
+- Changing the harvester itself (it already works correctly)
+- Modifying the search layer (already correctly filters by projectHash)
+- Adding new MCP tools or parameters
+- Changing the session file format or directory structure
+
+## Decisions
+
+### Decision 1: Shared `extractProjectHashFromPath()` utility
+
+**Choice**: Create a function in `store.ts` (or a new `utils.ts`) that extracts projectHash from a file path.
+
+```typescript
+export function extractProjectHashFromPath(filePath: string, sessionsDir: string): string | undefined {
+  // If filePath is under sessionsDir, extract the projectHash from the subdirectory name
+  // e.g., ~/.nano-brain/sessions/abc123def456/2026-02-16-session.md → 'abc123def456'
+  // Returns undefined for non-session files (caller defaults to their own projectHash or 'global')
+}
+```
+
+**Rationale**: All four bug sites need the same logic. A shared function prevents divergence and is easy to test.
+
+**Alternative considered**: Parsing YAML frontmatter from session files to read `projectHash`. Rejected because:
+- Slower (requires reading and parsing file content)
+- The directory structure is the canonical source of truth (set by the harvester)
+- Frontmatter could be missing or malformed
+
+### Decision 2: Collection-aware indexing in watcher
+
+**Choice**: In `triggerReindex()`, check if the collection being indexed is `sessions`. If so, extract projectHash from each file's path. Otherwise, use the watcher's own `projectHash`.
+
+```typescript
+for (const filePath of files) {
+  const effectiveProjectHash = collection.name === 'sessions'
+    ? extractProjectHashFromPath(filePath, outputDir) ?? projectHash
+    : projectHash;
+  indexDocument(store, collection.name, filePath, content, title, effectiveProjectHash);
+}
+```
+
+**Rationale**: Only session files have per-project scoping. Memory files, codebase files, and custom collections should continue using the watcher's projectHash.
+
+**Alternative considered**: Always extracting from path for all collections. Rejected because non-session collections don't have projectHash in their directory structure.
+
+### Decision 3: Self-healing via reindex
+
+**Choice**: No explicit migration for existing incorrectly-tagged documents. The fix naturally corrects tags on the next reindex cycle because:
+- The watcher periodically reindexes all collections
+- `indexDocument()` uses `INSERT OR REPLACE` (UPSERT), so re-indexing a file updates its `project_hash`
+- Running `memory_update` or restarting the MCP server triggers a full reindex
+
+**Rationale**: Simpler than writing a one-time migration. The data self-heals within one reindex cycle (typically < 2 minutes after server restart).
+
+**Alternative considered**: Adding a startup migration that scans all session documents and fixes their `project_hash`. Rejected because:
+- Adds complexity for a one-time fix
+- The reindex already handles it
+- Users can trigger immediate fix via `memory_update` tool
+
+## Risks / Trade-offs
+
+- **[Risk] Existing sessions tagged with wrong projectHash until reindex** → Mitigation: First reindex after the fix corrects all tags. Users can force immediate reindex via `memory_update`. Document this in release notes.
+- **[Risk] Collection name `sessions` is hardcoded in the check** → Mitigation: The sessions collection name is already hardcoded in `handleInit()` and is a core convention. If collection naming changes, this would need updating — but that's a broader refactor.
+- **[Risk] Path parsing assumes `sessions/{hash}/` directory structure** → Mitigation: The harvester is the only writer to this directory, and it always uses this structure. The extraction function validates the hash format (12-char hex) as a safety check.

package/openspec/changes/fix-session-harvest-workspace-scoping/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+Session harvesting collects ALL sessions from every workspace into a single `~/.nano-brain/sessions/` directory, and the watcher's reindex stamps every session document with the **current workspace's** `projectHash` instead of extracting it from the session file's actual path. This means if nano-brain runs in workspace A, sessions from workspaces B, C, D all get tagged as belonging to A — defeating the workspace-scoped search that was implemented in the previous `workspace-scoped-memory-and-storage-limits` change. The result: searching in any project returns sessions from all projects, polluting context and wasting tokens.
+
+## What Changes
+
+- **Fix projectHash extraction during session indexing**: The watcher's `triggerReindex()` currently passes its own `projectHash` to `indexDocument()` for ALL files including session files. For the `sessions` collection, the projectHash must be extracted from the file's directory structure (`sessions/{projectHash}/*.md`) instead of using the watcher's workspace hash.
+- **Fix `handleInit` session indexing**: The `init` command indexes session collection files with no projectHash, defaulting to `'global'`. It should also extract projectHash from the file path.
+- **Fix `handleUpdate` session indexing**: Same issue — indexes all collection files without workspace-aware projectHash extraction.
+- **Fix `memory_update` tool**: The MCP tool's reindex handler indexes all collection files without extracting projectHash from session paths.
+- **Add projectHash extraction utility**: Create a shared helper that extracts projectHash from a session file path by matching the `sessions/{hash}/` directory pattern, returning `'global'` for non-session files.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `workspace-scoping`: The "Document-level project tagging" requirement is already specified correctly (extract from file path), but the implementation violates it. This change fixes the implementation to match the spec. No spec text changes needed — only implementation fixes.
+
+## Impact
+
+- **Files affected**: `src/watcher.ts` (triggerReindex projectHash logic), `src/index.ts` (handleInit, handleUpdate session indexing), `src/server.ts` (memory_update tool), `src/store.ts` or new utility (projectHash extraction helper)
+- **Database**: Existing documents with incorrect `project_hash` values need re-tagging. A one-time migration or re-harvest will fix stale data.
+- **No API changes**: MCP tool interfaces remain unchanged.
+- **No new dependencies**: Pure logic fix using existing path parsing.
+- **Risk**: Low — this is a bug fix aligning implementation with existing spec. All search tools already support workspace filtering; they just receive wrong data today.

package/openspec/changes/fix-session-harvest-workspace-scoping/specs/workspace-scoping/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: ProjectHash extraction from session file path
+The system SHALL provide a utility function `extractProjectHashFromPath(filePath, sessionsDir)` that extracts the projectHash from a session file's path. The function SHALL match the pattern `{sessionsDir}/{projectHash}/*.md` where `projectHash` is a 12-character hexadecimal string. For paths that do not match this pattern, the function SHALL return `undefined`.
+
+#### Scenario: Valid session file path
+- **WHEN** `extractProjectHashFromPath` is called with path `~/.nano-brain/sessions/abc123def456/2026-02-16-session.md` and sessionsDir `~/.nano-brain/sessions`
+- **THEN** the function returns `'abc123def456'`
+
+#### Scenario: Non-session file path
+- **WHEN** `extractProjectHashFromPath` is called with path `~/.nano-brain/memory/2026-02-16.md` and sessionsDir `~/.nano-brain/sessions`
+- **THEN** the function returns `undefined`
+
+#### Scenario: Nested path under session directory without valid hash
+- **WHEN** `extractProjectHashFromPath` is called with a path under sessionsDir where the subdirectory name is not a 12-character hex string
+- **THEN** the function returns `undefined`
+
+### Requirement: Collection-aware projectHash during watcher reindex
+The watcher's `triggerReindex()` SHALL use collection-aware projectHash assignment when indexing documents. For the `sessions` collection, the projectHash SHALL be extracted from each file's path using `extractProjectHashFromPath()`. For all other collections, the watcher's own `projectHash` (current workspace) SHALL be used. If extraction returns `undefined` for a session file, the watcher's `projectHash` SHALL be used as fallback.
+
+#### Scenario: Watcher reindexes session file from another workspace
+- **WHEN** the watcher runs in workspace A (projectHash `aaa111bbb222`) and reindexes a session file at `sessions/ccc333ddd444/2026-02-16-session.md`
+- **THEN** the document is indexed with `project_hash = 'ccc333ddd444'` (extracted from path)
+- **THEN** the document is NOT indexed with `project_hash = 'aaa111bbb222'`
+
+#### Scenario: Watcher reindexes non-session collection file
+- **WHEN** the watcher runs in workspace A (projectHash `aaa111bbb222`) and reindexes a memory file at `memory/2026-02-16.md`
+- **THEN** the document is indexed with `project_hash = 'aaa111bbb222'` (watcher's own hash)
+
+#### Scenario: Watcher reindexes session file with unrecognized path structure
+- **WHEN** the watcher reindexes a session file whose path does not match the `sessions/{hash}/*.md` pattern
+- **THEN** the document is indexed with the watcher's own `projectHash` as fallback
+
+### Requirement: Correct projectHash during init indexing
+The `init` command SHALL extract projectHash from session file paths when indexing the `sessions` collection, using the same `extractProjectHashFromPath()` utility. Non-session collections SHALL use the workspace's projectHash.
+
+#### Scenario: Init indexes session files from multiple workspaces
+- **WHEN** `nano-brain init` runs in workspace A and indexes session files from `sessions/aaa111bbb222/` and `sessions/ccc333ddd444/`
+- **THEN** documents from `sessions/aaa111bbb222/` are tagged with `project_hash = 'aaa111bbb222'`
+- **THEN** documents from `sessions/ccc333ddd444/` are tagged with `project_hash = 'ccc333ddd444'`
+
+### Requirement: Correct projectHash during manual update
+The `memory_update` MCP tool and the `update` CLI command SHALL extract projectHash from session file paths when reindexing the `sessions` collection, using the same `extractProjectHashFromPath()` utility.
+
+#### Scenario: memory_update reindexes session files
+- **WHEN** the `memory_update` tool triggers a reindex
+- **THEN** session documents are tagged with projectHash extracted from their file paths
+- **THEN** non-session documents retain their existing projectHash assignment
+
+## MODIFIED Requirements
+
+### 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 by the `extractProjectHashFromPath()` utility. Non-session documents (memory files, daily logs, codebase files) SHALL be tagged with the indexer's contextual projectHash (workspace hash for codebase, `'global'` for shared files). All indexing code paths (watcher reindex, init, update, memory_update tool) SHALL use this extraction consistently.
+
+#### 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 the indexer's contextual projectHash

package/openspec/changes/fix-session-harvest-workspace-scoping/tasks.md

@@ -0,0 +1,33 @@
+## 1. ProjectHash Extraction Utility
+
+- [x] 1.1 Create `extractProjectHashFromPath(filePath: string, sessionsDir: string): string | undefined` function in `src/store.ts` (or `src/utils.ts`). It should parse the path to find a `{sessionsDir}/{12-char-hex}/` segment and return the hex string, or `undefined` if not matched.
+- [x] 1.2 Export the function so it can be imported by `watcher.ts`, `index.ts`, and `server.ts`.
+- [x] 1.3 Add unit tests for `extractProjectHashFromPath` covering: valid session path, non-session path, path with non-hex subdirectory, path without sessionsDir prefix, edge cases (empty string, trailing slashes).
+
+## 2. Fix Watcher Reindex
+
+- [x] 2.1 In `src/watcher.ts` `triggerReindex()`, import `extractProjectHashFromPath` and the sessions output directory path.
+- [x] 2.2 Modify the indexing loop: for the `sessions` collection, call `extractProjectHashFromPath(filePath, sessionsOutputDir)` and use the result (falling back to the watcher's `projectHash` if `undefined`). For other collections, keep using the watcher's `projectHash`.
+- [x] 2.3 Add/update test in `test/watcher.test.ts` verifying that session files from different workspaces get tagged with their respective projectHash, not the watcher's.
+
+## 3. Fix Init Command Indexing
+
+- [x] 3.1 In `src/index.ts` `handleInit()`, modify the session collection indexing loop (around line 423-435) to extract projectHash from each session file path using `extractProjectHashFromPath`. Pass the extracted hash to `indexDocument()`.
+- [x] 3.2 Ensure non-session collections (`memory`) continue using the workspace's `projectHash`.
+
+## 4. Fix Update Command and MCP Tool
+
+- [x] 4.1 In `src/index.ts` `handleUpdate()`, modify the collection indexing loop to use `extractProjectHashFromPath` for the `sessions` collection.
+- [x] 4.2 In `src/server.ts` `memory_update` tool handler, modify the reindex loop to use `extractProjectHashFromPath` for the `sessions` collection. Pass the server's `outputDir + '/sessions'` as the sessionsDir.
+
+## 5. Integration Testing
+
+- [x] 5.1 Add an integration test that: (a) creates session files in two different projectHash subdirectories, (b) runs a reindex, (c) verifies each document has the correct `project_hash` in the database.
+- [x] 5.2 Add a test verifying that after reindex, searching with workspace=projectHashA returns only sessions from A (not B), and workspace="all" returns both.
+- [x] 5.3 Run full test suite (`npm test`) and verify all existing tests pass.
+
+## 6. Verification
+
+- [ ] 6.1 Run `npx nano-brain init` in a workspace and verify `memory_status` shows correct per-workspace document counts.
+- [ ] 6.2 Run `memory_search` with default workspace scoping and confirm only current-workspace sessions appear.
+- [ ] 6.3 Run `memory_search` with `workspace="all"` and confirm cross-workspace sessions appear.

package/openspec/changes/performance-and-search-quality/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-24

package/openspec/changes/performance-and-search-quality/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+nano-brain's search quality and embedding pipeline have several gaps discovered during real-world usage: embedding truncation loses context from the second half of chunks, the chunking strategy doesn't optimize for embedding quality, there's no way to measure or benchmark search relevance, and the embedding pipeline processes documents sequentially with no batching optimization. These issues compound — poor embeddings lead to poor vector search, which degrades hybrid search, which makes the entire memory system less useful for AI agents.
+
+## What Changes
+
+- **Smarter embedding truncation**: Replace the hard `substring(0, 1800)` cut with word/sentence-boundary-aware truncation that preserves semantic completeness
+- **Chunk size alignment**: Align chunk size with embedding model's effective context window so chunks don't need truncation at all — currently chunks are 3600 chars but only the first 1800 are embedded, wasting half the stored content for vector search
+- **Embedding batch pipeline**: Implement proper batch embedding with configurable concurrency, progress tracking, and resume-on-failure — currently processes one doc at a time with no parallelism
+- **Search result scoring transparency**: Add `--explain` flag to CLI that shows which search mode (FTS/vector/hybrid) contributed to each result's score, enabling users to diagnose search quality issues
+- **Cross-workspace search**: Allow querying across all workspace DBs from any workspace, with results tagged by project — currently each workspace is fully isolated
+- **Embedding model warm-up**: Pre-warm the Ollama embedding model on MCP server start to avoid cold-start latency on first query (currently 1.4s first request vs 150ms warm)
+- **Incremental session indexing**: Index new sessions into the DB immediately after harvest instead of requiring a separate `embed` step — currently harvest writes markdown files but doesn't trigger indexing or embedding
+
+## Capabilities
+
+### New Capabilities
+- `embedding-pipeline`: Batch embedding with concurrency, progress tracking, resume-on-failure, and model warm-up
+- `search-explain`: Transparent scoring with `--explain` flag showing per-result breakdown of FTS score, vector similarity, and RRF fusion contribution
+- `cross-workspace-search`: Query across all workspace DBs with project-tagged results
+
+### Modified Capabilities
+- `search-pipeline`: Chunk size alignment with embedding window, word-boundary-aware truncation, and scoring transparency
+- `storage-limits`: Incremental session indexing after harvest (currently harvest and indexing are decoupled)
+
+## Impact
+
+- **`src/chunker.ts`**: Adjust `maxChunkSize` default and add overlap tuning to align with embedding window
+- **`src/codebase.ts`**: Replace `truncateForEmbedding()` with sentence-boundary-aware truncation, add batch concurrency to `embedPendingCodebase()`
+- **`src/search.ts`**: Add explain/debug metadata to search results, implement cross-workspace query routing
+- **`src/index.ts`**: Add `--explain` CLI flag, add cross-workspace `--all` flag, wire incremental indexing after harvest
+- **`src/server.ts`**: Add model warm-up on startup, expose explain metadata in MCP tool responses
+- **`src/harvester.ts`**: Trigger document indexing + embedding after successful harvest
+- **`src/embeddings.ts`**: Add batch concurrency control, warm-up method, progress callbacks
+- **`src/store.ts`**: Support querying multiple DB files for cross-workspace search
+- **Config**: New `embedding.batchSize`, `embedding.concurrency`, `embedding.warmup` options in `config.yml`
+- **Dependencies**: No new dependencies expected — all changes use existing SQLite, Ollama, and fast-glob

package/openspec/specs/mcp-integration-testing/spec.md

@@ -0,0 +1,50 @@
+## Requirements
+
+### Requirement: Integration test infrastructure
+The project SHALL have an integration test file that exercises MCP tool handlers against a real SQLite database with real FTS5 indexes and real sqlite-vec tables.
+
+#### Scenario: Test setup creates real database with indexed documents
+- **WHEN** the integration test suite starts
+- **THEN** a temporary SQLite database is created with sqlite-vec loaded
+- **THEN** at least 2 test documents are indexed with FTS5 entries
+- **THEN** the MCP server's tool handlers are initialized with the real store
+
+#### Scenario: Test teardown cleans up
+- **WHEN** the integration test suite completes
+- **THEN** the temporary database file is deleted
+- **THEN** no test artifacts remain on disk
+
+### Requirement: Search integration tests
+Integration tests SHALL verify that `memory_search` works end-to-end with real FTS5 queries.
+
+#### Scenario: Search finds indexed document
+- **WHEN** `memory_search` handler is called with a query matching an indexed document
+- **THEN** the response contains the matching document with title, path, and snippet
+
+#### Scenario: Search with hyphenated query
+- **WHEN** `memory_search` handler is called with query `nano-brain`
+- **THEN** the response completes without error
+- **THEN** results include documents containing the term
+
+#### Scenario: Search with collection filter
+- **WHEN** `memory_search` handler is called with a collection filter
+- **THEN** only documents from that collection are returned
+
+#### Scenario: Search with empty query
+- **WHEN** `memory_search` handler is called with an empty string query
+- **THEN** the response returns empty results without error
+
+### Requirement: Update integration tests
+Integration tests SHALL verify that `memory_update` works end-to-end.
+
+#### Scenario: Update indexes new files
+- **WHEN** a new markdown file is added to a collection directory
+- **THEN** calling the `memory_update` handler indexes the new file
+- **THEN** the file is searchable via `memory_search`
+
+### Requirement: Status integration tests
+Integration tests SHALL verify that `memory_status` returns accurate information.
+
+#### Scenario: Status reflects indexed documents
+- **WHEN** documents have been indexed
+- **THEN** `memory_status` handler returns correct document count and collection info

package/openspec/specs/mcp-server/spec.md

@@ -0,0 +1,75 @@
+## Purpose
+
+MCP server providing persistent memory tools (search, status, update, get) for AI coding agents via the Model Context Protocol.
+## Requirements
+### Requirement: ESM module compliance
+All source files in `src/` SHALL use ESM `import` syntax exclusively. No `require()` calls SHALL exist in any TypeScript source file.
+
+#### Scenario: Server starts under Node.js ESM runtime
+- **WHEN** the MCP server is started via `node bin/cli.js mcp`
+- **THEN** the server starts without `require is not defined` errors
+- **THEN** all tool handlers execute without CJS/ESM compatibility errors
+
+#### Scenario: No require() in source files
+- **WHEN** running `grep -r "require(" src/` on the source directory
+- **THEN** zero matches are returned (excluding comments and string literals)
+
+### Requirement: Dynamic collection config reload
+The `memory_update` tool handler SHALL reload the collection configuration file on every invocation, not use the cached startup value.
+
+#### Scenario: Collection added after server start
+- **WHEN** a user adds a collection via CLI (`collection add`) while the MCP server is running
+- **THEN** calling `memory_update` through MCP indexes documents from the newly added collection
+- **THEN** no server restart is required
+
+#### Scenario: Collection removed after server start
+- **WHEN** a user removes a collection via CLI while the MCP server is running
+- **THEN** calling `memory_update` through MCP no longer indexes documents from the removed collection
+
+### Requirement: All MCP tool handlers return valid responses
+Every registered MCP tool SHALL return a valid JSON-RPC response for valid inputs, never an unhandled exception.
+
+#### Scenario: memory_search with valid query
+- **WHEN** `memory_search` is called with `{"query": "test"}` via JSON-RPC
+- **THEN** a valid response with `content` array is returned
+
+#### Scenario: memory_update with configured collections
+- **WHEN** `memory_update` is called via JSON-RPC with collections configured
+- **THEN** a valid response with reindex summary is returned, not a runtime error
+
+#### Scenario: memory_status returns health info
+- **WHEN** `memory_status` is called via JSON-RPC
+- **THEN** a valid response with document count, chunk count, and collection info is returned
+
+### Requirement: Search tools support workspace filtering
+The `memory_search`, `memory_vsearch`, and `memory_query` MCP tools SHALL accept an optional `workspace` parameter. When omitted, results are scoped to the current workspace and global documents. When set to `"all"`, results include all workspaces.
+
+#### Scenario: memory_search with default workspace scoping
+- **WHEN** `memory_search` is called with `{"query": "test"}` and no `workspace` parameter
+- **THEN** results are filtered to `currentProjectHash` and `'global'` documents only
+
+#### Scenario: memory_vsearch with workspace="all"
+- **WHEN** `memory_vsearch` is called with `{"query": "test", "workspace": "all"}`
+- **THEN** results include documents from all workspaces
+
+#### Scenario: memory_query with specific workspace
+- **WHEN** `memory_query` is called with `{"query": "test", "workspace": "abc123def456"}`
+- **THEN** results are filtered to `project_hash = 'abc123def456'` and `project_hash = 'global'`
+
+### Requirement: memory_status reports storage usage
+The `memory_status` tool SHALL report per-workspace document counts and total storage size, in addition to existing health information.
+
+#### Scenario: memory_status with workspace data
+- **WHEN** `memory_status` is called after documents from multiple workspaces are indexed
+- **THEN** the response includes a breakdown of document counts per workspace (projectHash)
+- **THEN** the response includes total storage size (DB + sessions directory)
+- **THEN** the response includes storage limit configuration (maxSize, retention, minFreeDisk)
+
+### Requirement: Search tool parameter schema includes workspace
+The MCP tool registration for `memory_search`, `memory_vsearch`, and `memory_query` SHALL include `workspace` in their input schema as an optional string parameter with description explaining the scoping behavior.
+
+#### Scenario: Tool schema advertises workspace parameter
+- **WHEN** an MCP client lists available tools
+- **THEN** `memory_search`, `memory_vsearch`, and `memory_query` each show a `workspace` parameter in their input schema
+- **THEN** the parameter description explains: omit for current workspace, `"all"` for cross-workspace search
+

package/openspec/specs/search-pipeline/spec.md

@@ -0,0 +1,29 @@
+## Requirements
+
+### Requirement: FTS5 query sanitization
+The `searchFTS` function SHALL sanitize user queries before passing them to FTS5 `MATCH`. All user-provided query strings MUST be treated as literal search text, never as FTS5 syntax.
+
+#### Scenario: Query containing hyphenated words
+- **WHEN** user searches for `nano-brain`
+- **THEN** the search treats the entire hyphenated term as a literal phrase, not as `opencode NOT memory`
+
+#### Scenario: Query containing FTS5 column names
+- **WHEN** user searches for `memory architecture`
+- **THEN** the search treats `memory` as a search term, not as a column reference
+- **THEN** no `no such column` error is thrown
+
+#### Scenario: Query containing FTS5 operators
+- **WHEN** user searches for `AND OR NOT NEAR`
+- **THEN** the search treats these as literal words, not as FTS5 boolean operators
+
+#### Scenario: Query containing double quotes
+- **WHEN** user searches for `he said "hello"`
+- **THEN** internal double quotes are escaped and the search completes without SQL error
+
+#### Scenario: Empty or whitespace-only query
+- **WHEN** user searches for `   ` or empty string
+- **THEN** the search returns an empty result set without error
+
+#### Scenario: Normal multi-word query
+- **WHEN** user searches for `sqlite vector search`
+- **THEN** the search returns documents containing those terms, ranked by BM25 relevance

package/openspec/specs/storage-limits/spec.md

@@ -0,0 +1,94 @@
+# storage-limits Specification
+
+## Purpose
+TBD - created by archiving change workspace-scoped-memory-and-storage-limits. Update Purpose after archive.
+## Requirements
+### Requirement: Storage configuration with safe defaults
+The `config.yml` SHALL support a `storage` section with `maxSize`, `retention`, and `minFreeDisk` fields. All fields SHALL be optional with safe defaults: `maxSize: 2GB`, `retention: 90d`, `minFreeDisk: 100MB`.
+
+#### Scenario: Config with all storage fields
+- **WHEN** config.yml contains `storage: { maxSize: "1GB", retention: "30d", minFreeDisk: "200MB" }`
+- **THEN** the server uses those values for eviction and disk safety
+
+#### Scenario: Config with no storage section
+- **WHEN** config.yml has no `storage` section
+- **THEN** the server uses defaults: maxSize=2GB, retention=90d, minFreeDisk=100MB
+
+#### Scenario: Config with partial storage section
+- **WHEN** config.yml contains `storage: { maxSize: "500MB" }`
+- **THEN** `maxSize` is 500MB, `retention` defaults to 90d, `minFreeDisk` defaults to 100MB
+
+### Requirement: Human-readable size and duration parsing
+The storage config parser SHALL accept human-readable size strings (`500MB`, `2GB`, `1TB`) and duration strings (`30d`, `90d`, `1y`). Invalid values SHALL cause a warning log and fall back to defaults.
+
+#### Scenario: Valid size string
+- **WHEN** `maxSize` is set to `"2GB"`
+- **THEN** it is parsed as 2,147,483,648 bytes
+
+#### Scenario: Valid duration string
+- **WHEN** `retention` is set to `"30d"`
+- **THEN** it is parsed as 30 days (2,592,000,000 milliseconds)
+
+#### Scenario: Invalid size string
+- **WHEN** `maxSize` is set to `"banana"`
+- **THEN** a warning is logged: `[storage] Invalid maxSize "banana", using default 2GB`
+- **THEN** the default value of 2GB is used
+
+### Requirement: Retention-based eviction
+During each harvest cycle, the system SHALL delete session markdown files older than the `retention` period and remove their corresponding documents from the SQLite database.
+
+#### Scenario: Session older than retention period
+- **WHEN** a session file has mtime older than `retention` (e.g., 91 days old with 90d retention)
+- **THEN** the session markdown file is deleted from disk
+- **THEN** the corresponding document rows are removed from the `documents` table
+
+#### Scenario: Session within retention period
+- **WHEN** a session file has mtime within the `retention` period (e.g., 30 days old with 90d retention)
+- **THEN** the session file is not deleted
+- **THEN** the document rows remain in the database
+
+### Requirement: Size-based eviction
+After retention eviction, if total storage (SQLite DB + sessions directory) still exceeds `maxSize`, the system SHALL delete the oldest remaining session files until total size is under the limit.
+
+#### Scenario: Storage exceeds maxSize after retention eviction
+- **WHEN** total storage is 2.5GB and `maxSize` is 2GB after retention eviction
+- **THEN** the oldest session files are deleted one by one
+- **THEN** deletion stops when total size drops below 2GB
+
+#### Scenario: Storage under maxSize
+- **WHEN** total storage is 1.5GB and `maxSize` is 2GB
+- **THEN** no size-based eviction occurs
+
+### Requirement: Original session JSON is never deleted
+Eviction SHALL only remove harvested markdown files and their database entries. The original OpenCode session JSON files in `~/.local/share/opencode/storage/` SHALL never be touched by eviction.
+
+#### Scenario: Session evicted
+- **WHEN** a session is evicted due to retention or size limits
+- **THEN** only the harvested markdown file in `~/.nano-brain/sessions/` is deleted
+- **THEN** the original JSON in `~/.local/share/opencode/storage/sessions/` remains untouched
+
+### Requirement: Disk safety guard
+Before any write operation (harvest, reindex, embed), the system SHALL check available disk space. If free disk space is below `minFreeDisk`, all write operations SHALL be skipped and a warning logged.
+
+#### Scenario: Disk space below minFreeDisk
+- **WHEN** available disk space is 50MB and `minFreeDisk` is 100MB
+- **THEN** harvest, reindex, and embed operations are skipped
+- **THEN** a warning is logged: `[storage] Disk space critically low (<100MB free), skipping writes`
+
+#### Scenario: Disk space above minFreeDisk
+- **WHEN** available disk space is 500MB and `minFreeDisk` is 100MB
+- **THEN** all write operations proceed normally
+
+#### Scenario: statfs unavailable
+- **WHEN** `os.statfs()` is not available (older Node.js or restricted environment)
+- **THEN** the disk check is skipped with a warning: `[storage] statfs unavailable, disk safety check disabled`
+- **THEN** all other storage limits (maxSize, retention) still function normally
+
+### Requirement: Orphan embedding cleanup
+Periodically (every 10 harvest cycles), the system SHALL remove embedding vectors whose corresponding documents no longer exist in the `documents` table.
+
+#### Scenario: Document deleted but embedding remains
+- **WHEN** a document is evicted and its row removed from `documents`
+- **THEN** on the next orphan cleanup cycle, the corresponding embedding vector is removed
+- **THEN** no orphaned embeddings accumulate indefinitely
+