nano-brain 2026.1.0

package/nano-brain

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -e
+DIR="$(cd "$(dirname "$0")" && pwd)"
+exec bun "$DIR/src/index.ts" "$@"

package/opencode-mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "nano-brain": {
+      "type": "local",
+      "command": ["bun", "run", "/path/to/nano-brain/src/index.ts", "mcp"],
+      "description": "Memory system with hybrid search (BM25 + vector + LLM reranking)"
+    }
+  }
+}

package/openspec/changes/archive/2026-02-16-fix-mcp-server-bugs/.openspec.yaml

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

package/openspec/changes/archive/2026-02-16-fix-mcp-server-bugs/design.md

@@ -0,0 +1,68 @@
+## Context
+
+nano-brain is an MCP server that provides hybrid search (BM25 + vector) over indexed markdown documents. It runs as a subprocess spawned by OpenCode via stdio transport. The server uses better-sqlite3 with FTS5 for full-text search and sqlite-vec for vector search.
+
+Three categories of bugs surfaced during real-world testing that unit tests failed to catch:
+
+1. **FTS5 query injection** — User queries passed directly to FTS5 `MATCH` without sanitization. FTS5 interprets bare words matching column names (`filepath`, `title`, `body`) as column references, and hyphens as `NOT` operators.
+2. **ESM/CJS mismatch** — `require('crypto')` in an ESM module crashes under Node.js. Tests use vitest which transpiles CJS-style requires, masking the error.
+3. **Static config loading** — Collections loaded once at server startup. Adding a collection requires server restart.
+
+## Goals / Non-Goals
+
+**Goals:**
+- All MCP tool handlers work correctly when called through real JSON-RPC over stdio
+- User queries with hyphens, special characters, and FTS5 reserved words search correctly
+- Zero `require()` calls in any `.ts` source file
+- Integration tests that catch runtime errors before deployment
+
+**Non-Goals:**
+- Changing the MCP tool API or adding new tools
+- Improving search relevance or ranking algorithms
+- Adding new features beyond bug fixes
+
+## Decisions
+
+### D1: FTS5 Query Sanitization Strategy
+
+**Decision:** Quote each search term individually and join with implicit AND.
+
+**Rationale:** FTS5 has complex query syntax where bare words can be interpreted as column names, `AND`/`OR`/`NOT`/`NEAR` as operators, and `-` as NOT prefix. Rather than trying to escape individual characters, we split the user query into tokens, wrap each in double quotes (`"term"`), and join them. This ensures every token is treated as a literal search term.
+
+**Example:** `nano-brain architecture` → `"opencode" "memory" "architecture"` (hyphen splits into separate quoted terms since FTS5 treats `-` as NOT)
+
+Actually, better approach: wrap the entire query in double quotes to preserve phrases, and escape any internal double quotes.
+
+**Final decision:** `"nano-brain architecture"` → `"nano-brain architecture"` (single quoted phrase). Escape internal `"` as `""`.
+
+**Alternatives considered:**
+- Column-prefixed queries (`body:"query"`) — too restrictive, we want to search all columns
+- FTS5 `simple` tokenizer — would lose porter stemming benefits
+
+### D2: Integration Test Approach
+
+**Decision:** Create a test helper that starts the real MCP server in-process, sends JSON-RPC messages, and asserts on responses. Use a temporary SQLite database with pre-indexed test documents.
+
+**Rationale:** The current tests mock `Store` and `SearchProviders`, which means the actual SQL queries, FTS5 interactions, and parameter binding are never tested. An integration test that uses a real database catches the exact class of bugs we hit.
+
+**Alternatives considered:**
+- Subprocess-based testing (spawn `node bin/cli.js mcp` and pipe JSON-RPC) — too slow, harder to debug
+- Just adding more unit tests — wouldn't catch ESM/CJS issues or SQL parameter binding bugs
+
+### D3: ESM Compliance Audit
+
+**Decision:** `grep -r "require(" src/` as a CI-enforceable check. All imports must use ESM `import` syntax.
+
+**Rationale:** vitest transpiles `require()` calls, so they work in tests but fail at runtime under Node.js ESM. A simple grep catches this at lint time.
+
+### D4: Dynamic Config Reload in memory_update
+
+**Decision:** `memory_update` tool handler reloads `config.yml` on every invocation instead of using the cached startup value.
+
+**Rationale:** Users add collections via CLI (`collection add`) which writes to config.yml. The MCP server is a long-running process — it shouldn't require restart to see new collections. The config file is tiny (< 1KB), so re-reading it on each update call has negligible cost.
+
+## Risks / Trade-offs
+
+- **FTS5 quoting may reduce search flexibility** — Users can't use FTS5 advanced syntax (OR, NEAR, column filters). This is acceptable because MCP tool users are AI agents, not power users writing FTS5 queries. → Mitigation: If needed later, add a `raw` parameter to bypass sanitization.
+- **Integration tests add test runtime** — Real SQLite operations are slower than mocks. → Mitigation: Keep integration test count small (5-10 critical paths), run unit tests separately.
+- **Dynamic config reload on every update** — Tiny performance cost. → Mitigation: Config file is < 1KB, `fs.readFileSync` + YAML parse is < 1ms.

package/openspec/changes/archive/2026-02-16-fix-mcp-server-bugs/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+The MCP server has multiple runtime bugs that only surface in real usage (not caught by unit tests). The server crashes or returns SQL errors when users call the tools through OpenCode. These bugs exist because: (1) tests mock internals rather than exercising real code paths, (2) ESM/CJS incompatibilities weren't caught, and (3) FTS5 query syntax isn't sanitized.
+
+## What Changes
+
+- Fix FTS5 search query sanitization — raw user queries containing words that match FTS5 syntax (column names, operators) cause `no such column` errors. Queries must be properly quoted/escaped before passing to `MATCH`.
+- Remove all `require()` calls from ESM source files — `require('crypto')` in `server.ts` crashes at runtime under Node.js ESM mode. All CJS-style requires must use ESM `import`.
+- Add integration tests that exercise real MCP tool handlers end-to-end — current tests mock store/server internals, missing runtime errors like the above.
+- Fix `memory_update` to reload collection config dynamically — already patched but needs proper test coverage.
+- Audit all prepared statements for parameter binding correctness — ensure collection filter parameters are bound in the right order.
+
+## Capabilities
+
+### New Capabilities
+- `mcp-integration-testing`: End-to-end integration tests that start the real MCP server, send JSON-RPC requests, and verify responses against a real SQLite database with indexed documents.
+
+### Modified Capabilities
+- `search-pipeline`: Fix FTS5 query sanitization so user queries with hyphens, special characters, and words matching FTS5 column names don't cause SQL errors.
+- `mcp-server`: Fix ESM compatibility (no `require()`), fix dynamic config reload in `memory_update`, ensure all tool handlers work under Node.js/tsx runtime.
+
+## Impact
+
+- **src/store.ts**: `searchFTS()` — must sanitize/quote FTS5 MATCH queries
+- **src/server.ts**: Remove `require('crypto')` (already done), verify all tool handlers work end-to-end
+- **tests/**: New integration test file exercising real MCP tool calls against real DB
+- **No breaking changes** — all fixes are internal, MCP tool API unchanged

package/openspec/changes/archive/2026-02-16-fix-mcp-server-bugs/specs/mcp-integration-testing/spec.md

@@ -0,0 +1,50 @@
+## ADDED 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/changes/archive/2026-02-16-fix-mcp-server-bugs/specs/mcp-server/spec.md

@@ -0,0 +1,40 @@
+## MODIFIED 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

package/openspec/changes/archive/2026-02-16-fix-mcp-server-bugs/specs/search-pipeline/spec.md

@@ -0,0 +1,29 @@
+## MODIFIED 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/changes/archive/2026-02-16-fix-mcp-server-bugs/tasks.md

@@ -0,0 +1,37 @@
+## 1. FTS5 Query Sanitization
+
+- [x] 1.1 Create `sanitizeFTS5Query(query: string): string` helper in `src/store.ts` that wraps user input in double quotes and escapes internal double quotes
+- [x] 1.2 Handle edge cases: empty/whitespace-only queries return empty string, hyphenated words preserved as phrases
+- [x] 1.3 Apply `sanitizeFTS5Query` in `searchFTS()` before passing to prepared statements
+- [x] 1.4 Add unit tests for `sanitizeFTS5Query`: normal words, hyphens, FTS5 operators, double quotes, empty input, column name words
+- [x] 1.5 Verify `memory_search` works via MCP with query `nano-brain architecture` (manual test)
+
+## 2. ESM Compliance
+
+- [x] 2.1 Audit all `src/*.ts` files for `require()` calls — confirm the `require('crypto')` fix in server.ts is the only instance
+- [x] 2.2 Add a lint check script in package.json: `"lint:esm": "grep -r 'require(' src/ --include='*.ts' && exit 1 || exit 0"`
+- [x] 2.3 Run lint:esm and verify it passes
+
+## 3. Dynamic Config Reload
+
+- [x] 3.1 Verify `memory_update` handler in server.ts reloads config from disk (already patched — confirm code is correct)
+- [x] 3.2 Add test: start server with empty config, add collection to config file, call memory_update, verify it indexes the new collection's documents
+
+## 4. Integration Tests
+
+- [x] 4.1 Create `tests/integration.test.ts` with test helper that creates a real temp SQLite DB with sqlite-vec loaded
+- [x] 4.2 Add test fixture: index 2-3 markdown documents into the real DB with FTS5 triggers firing
+- [x] 4.3 Test `memory_search` handler end-to-end: valid query returns results with title, path, snippet
+- [x] 4.4 Test `memory_search` with hyphenated query (`nano-brain`) — no SQL error
+- [x] 4.5 Test `memory_search` with FTS5 operator words (`AND OR NOT`) — no SQL error
+- [x] 4.6 Test `memory_search` with collection filter — only matching collection returned
+- [x] 4.7 Test `memory_search` with empty query — returns empty results, no error
+- [x] 4.8 Test `memory_update` handler: add file to collection dir, call update, verify document count increases
+- [x] 4.9 Test `memory_status` handler: returns correct document count and collection info
+- [x] 4.10 Teardown: verify temp DB is cleaned up after tests
+
+## 5. Verification
+
+- [x] 5.1 Run full test suite (`npm test`) — all existing 246 tests + new integration tests pass
+- [x] 5.2 Start MCP server via `node bin/cli.js mcp`, send JSON-RPC initialize + tools/list, verify 8 tools listed
+- [x] 5.3 Manual end-to-end: write memory, update index, search — full cycle works through MCP tools

package/openspec/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/.openspec.yaml

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

package/openspec/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/design.md

@@ -0,0 +1,111 @@
+## Context
+
+nano-brain is an MCP server providing persistent memory across OpenCode sessions. It harvests session JSON from `~/.local/share/opencode/storage/`, converts to markdown, indexes into SQLite (FTS5 + sqlite-vec), and exposes search via MCP tools.
+
+Current state:
+- **956 sessions** across 7 workspaces are mixed into one flat index (30MB SQLite DB)
+- **No workspace awareness** — searching in project A returns results from projects B, C, D
+- **No storage limits** — DB grows unbounded, no eviction, no disk safety checks
+- The MCP server is launched per-workspace by OpenCode with `PWD` set to the workspace root
+- Harvested sessions are already organized by projectHash on disk (`sessions/{hash}/*.md`)
+- The `documents` table has a `collection` column but no `project_hash` column
+
+Key constraint: The MCP server runs as a stdio process spawned by OpenCode. It knows `PWD` but receives no explicit workspace identifier.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Search results scoped to current workspace by default
+- Cross-workspace search available via explicit opt-in
+- Configurable storage cap with automatic eviction of oldest sessions
+- Disk safety guard preventing writes when disk is critically low
+- Backward-compatible config (all new fields optional with safe defaults)
+- Zero data loss for recent sessions during eviction
+
+**Non-Goals:**
+- Per-workspace separate SQLite databases (too complex, breaks cross-workspace search)
+- Real-time workspace switching within a session (server restarts on workspace change anyway)
+- Compression or deduplication of session content
+- Cloud sync or backup of memory data
+- Embedding eviction (only session documents are evicted, embeddings are orphaned and cleaned lazily)
+
+## Decisions
+
+### D1: Workspace detection via PWD + SHA-256 hash
+
+**Decision**: Compute `projectHash = sha256(process.cwd()).substring(0, 12)` at server startup. Store as `currentProjectHash` on the server context.
+
+**Why**: OpenCode already sets `PWD` to the workspace root when spawning MCP servers. The harvester already uses the same `sha256(directory).substring(0, 12)` scheme for organizing session output directories. Reusing this ensures consistency.
+
+**Alternative considered**: Use an explicit `--workspace` CLI flag. Rejected because it requires config changes in every OpenCode installation and the PWD approach works automatically.
+
+### D2: Document-level project_hash column in SQLite
+
+**Decision**: Add a `project_hash TEXT` column to the `documents` table. Populate it during indexing by extracting the projectHash from the file path (sessions are stored at `sessions/{projectHash}/*.md`). For non-session documents (MEMORY.md, daily logs), set `project_hash = 'global'`.
+
+**Why**: Column-level filtering is fast (indexed), works with existing FTS5 queries, and doesn't require restructuring collections.
+
+**Alternative considered**: Separate collections per workspace. Rejected because it would require dynamic collection creation and complicate the config.
+
+**Migration**: `ALTER TABLE documents ADD COLUMN project_hash TEXT DEFAULT 'global'`. Then backfill from file paths for existing documents.
+
+### D3: Search filtering with workspace parameter
+
+**Decision**: All search MCP tools (`memory_search`, `memory_vsearch`, `memory_query`) gain an optional `workspace` parameter:
+- Default: `undefined` → filter to `currentProjectHash` + `'global'` documents
+- `"all"` → no filtering, search everything
+- `"<specific-hash>"` → filter to that project
+
+**Why**: Default scoping prevents cross-project pollution. The `"all"` escape hatch preserves the ability to search across workspaces when needed. Including `'global'` in default ensures MEMORY.md and daily logs are always searchable.
+
+### D4: Storage config with safe defaults
+
+**Decision**: New `storage` section in `config.yml`:
+```yaml
+storage:
+  maxSize: 2GB          # Max total size (DB + sessions dir)
+  retention: 90d        # Auto-evict sessions older than this
+  minFreeDisk: 100MB    # Stop writes if disk free below this
+```
+
+All fields optional. Defaults: `maxSize: 2GB`, `retention: 90d`, `minFreeDisk: 100MB`.
+
+**Why**: These defaults are safe for most users. 2GB accommodates ~100K sessions. 90 days keeps recent context. 100MB prevents disk-full crashes.
+
+**Parsing**: `maxSize` and `minFreeDisk` accept human-readable sizes (`500MB`, `2GB`, `1TB`). `retention` accepts duration strings (`30d`, `90d`, `1y`).
+
+### D5: Eviction strategy — oldest sessions first
+
+**Decision**: Eviction runs during the harvest cycle (every 2 minutes). Order of operations:
+1. **Retention eviction**: Delete session markdown files older than `retention` period. Remove corresponding documents from SQLite.
+2. **Size eviction**: If total size still exceeds `maxSize`, delete oldest remaining sessions until under limit.
+3. **Orphan cleanup**: Periodically (every 10 cycles) remove orphaned embeddings whose documents no longer exist.
+
+**Why**: Oldest-first is simple, predictable, and preserves the most relevant (recent) context. Running during harvest avoids adding a separate eviction timer.
+
+**Alternative considered**: LRU (least recently accessed). Rejected because tracking access timestamps adds complexity and the access pattern (search) doesn't map cleanly to document-level access.
+
+### D6: Disk safety guard via statfs
+
+**Decision**: Before any write operation (harvest, reindex, embed), call `os.statfs()` (Node 18+) or `child_process.execSync('df')` to check available disk space. If below `minFreeDisk`, skip the write and log `[storage] Disk space critically low (<100MB free), skipping writes`.
+
+**Why**: Prevents the most catastrophic failure mode (disk full → SQLite corruption). The check is cheap (~1ms) and runs at most every 2 minutes.
+
+**Fallback**: If `statfs` is unavailable (older Node), skip the check and log a warning.
+
+## Risks / Trade-offs
+
+**[Risk] Existing documents lack project_hash** → Migration backfills from file paths. Documents not matching `sessions/{hash}/*.md` pattern get `project_hash = 'global'`. No data loss.
+
+**[Risk] PWD might not match session directory** → The session's `directory` field in JSON is the original workspace path. PWD is the current workspace. These should match for the current project's sessions. For harvested sessions from other projects, the projectHash from the file path is authoritative.
+
+**[Risk] Eviction deletes data permanently** → Eviction only removes harvested markdown and index entries. The original OpenCode session JSON in `~/.local/share/opencode/storage/` is never touched. Sessions can be re-harvested if needed.
+
+**[Risk] Size calculation is approximate** → Checking DB file size + sessions dir size via `fs.statSync` is fast but doesn't account for WAL files or pending transactions. Acceptable for a soft limit.
+
+**[Risk] statfs not available in all environments** → Docker containers and some Node versions may not support `os.statfs`. Fallback: skip the check, rely on size-based eviction only.
+
+## Open Questions
+
+- Should evicted sessions be logged somewhere (e.g., `eviction.log`) for auditability?
+- Should there be a `memory_evict` MCP tool for manual eviction, or is automatic-only sufficient?

package/openspec/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+All sessions from every workspace are harvested into a single flat index. Searching in project A returns results from unrelated projects B, C, D — polluting context and wasting tokens. Additionally, storage grows unbounded: a heavy user accumulates GBs of sessions over months with no eviction, eventually hitting OOM or disk-full crashes. Both problems must be solved before the auto-persistence pipeline is production-ready.
+
+## What Changes
+
+- **Workspace-scoped search by default**: The MCP server detects the current workspace from `PWD` at startup, computes its projectHash, and filters all search results to that workspace. Cross-workspace search remains available via explicit parameter.
+- **Per-workspace session collections**: Harvested sessions are organized by projectHash (already the case on disk). The indexer tags each document with its projectHash so filtering is efficient at the database level.
+- **Configurable storage limits**: New `storage` section in `config.yml` with `maxSize`, `retention`, and `minFreeDisk` options.
+- **Automatic eviction**: When storage exceeds `maxSize`, oldest sessions are evicted first (by date). Sessions older than `retention` period are cleaned up on each harvest cycle.
+- **Disk safety guard**: Before any write operation (harvest, reindex, embed), check available disk space. If below `minFreeDisk`, stop all writes and log a warning.
+- **Global memory preserved**: `MEMORY.md` and daily logs remain unscoped — they are the user's personal cross-project notes.
+
+## Capabilities
+
+### New Capabilities
+- `workspace-scoping`: Workspace detection from PWD, projectHash computation, per-workspace search filtering, cross-workspace search opt-in, document-level project tagging
+- `storage-limits`: Configurable maxSize/retention/minFreeDisk, automatic eviction of oldest sessions, disk space safety checks, storage config parsing and validation
+
+### Modified Capabilities
+- `mcp-server`: Search tools (`memory_search`, `memory_vsearch`, `memory_query`) gain default workspace filtering and optional cross-workspace parameter. `memory_status` reports per-workspace and total storage usage.
+
+## Impact
+
+- **Config schema**: New `storage` section in `config.yml` (backward-compatible — all fields optional with safe defaults)
+- **Database schema**: Documents table needs a `project_hash` column (migration required for existing DBs)
+- **MCP tool API**: Search tools gain optional `workspace` parameter (`"current"` default, `"all"` for cross-workspace). Non-breaking — existing calls work unchanged.
+- **Files affected**: `src/server.ts`, `src/store.ts`, `src/watcher.ts`, `src/harvester.ts`, `src/collections.ts`, `src/types.ts`, `config.yml` schema
+- **Disk I/O**: Eviction adds periodic delete operations. Disk space check adds `statfs` call before writes.
+- **No new dependencies required**

package/openspec/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/specs/mcp-server/spec.md

@@ -0,0 +1,33 @@
+## ADDED Requirements
+
+### 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/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/specs/storage-limits/spec.md

@@ -0,0 +1,90 @@
+## ADDED 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

package/openspec/changes/archive/2026-02-23-workspace-scoped-memory-and-storage-limits/specs/workspace-scoping/spec.md

@@ -0,0 +1,66 @@
+## ADDED 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