nano-brain 2026.3.7 → 2026.3.8

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [2026.3.8] - 2026-03-08
+
+### Fixed
+
+- **Embedding 0 chunks infinite loop**: When `chunkMarkdown` returned 0 chunks (empty/whitespace-only body), the batch was counted as embedded but no `content_vectors` rows were inserted. Next iteration fetched the same docs, looping forever. Now skips empty-body docs and adds them to `failedHashes`.
+- **Qdrant fire-and-forget desync**: `insertEmbedding` upserted to Qdrant via `.catch()` (fire-and-forget) then immediately wrote to `content_vectors`. If Qdrant failed, SQLite thought the doc was embedded but Qdrant didn't have it. Now awaits Qdrant `batchUpsert` before writing `content_vectors`.
+- **Qdrant socket errors under load**: Individual per-chunk upserts created hundreds of concurrent HTTP requests, overwhelming the connection. Replaced with batched upserts (100 vectors/request) with retry + exponential backoff (up to 3 retries) for `UND_ERR_SOCKET`, `ECONNRESET`, and `ECONNREFUSED` errors.
+
+### Added
+
+- **Embed batch file logging**: Embed log now shows file names being processed: `[embed] Batch 3 docs, 10 chunks: package.json, tsconfig.json, README.md`.
+- **`insertEmbeddingLocal`**: SQLite-only embedding record method for use when external vector store is handled separately.
+
 ## [2026.2.0] - 2026-03-05
 
 ### Added

package/openspec/changes/nano-brain-phase1-memory-intelligence/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-07

package/openspec/changes/nano-brain-phase1-memory-intelligence/design.md

@@ -0,0 +1,206 @@
+# Design: Memory Intelligence Phase 1
+
+## Context
+
+nano-brain currently treats all memories equally regardless of age or usage. A 6-month-old debugging note ranks the same as yesterday's architecture decision. The search pipeline (RRF fusion → top rank bonus → centrality boost → supersede demotion → position-aware blending) has no awareness of memory lifecycle. This design adds three lightweight intelligence features to the existing pipeline without introducing LLM dependencies or blocking operations.
+
+The search scoring pipeline lives in `search.ts` and follows this flow:
+1. `rrfFuse` — combines BM25 (FTS) and vector search results
+2. `applyTopRankBonus` — boosts top-ranked results (not currently in use)
+3. `applyCentralityBoost` — multiplies score by `(1 + centralityWeight * centrality)`
+4. `applySupersedeDemotion` — multiplies score by `demotionFactor` for superseded docs
+5. `positionAwareBlend` — blends RRF and rerank scores based on position (top3/mid/tail)
+
+Schema is in `store.ts` with tables: `documents`, `content`, `document_tags`, `content_vectors`, `documents_fts`. The `documents` table currently tracks `created_at`, `modified_at`, and `active` but has no access tracking.
+
+## Goals
+
+**In Scope:**
+- Track memory access patterns (count and timestamp) without performance overhead
+- Apply time-based relevance decay to search scoring using a configurable half-life model
+- Auto-categorize memories on write using fast heuristic rules (no LLM)
+- Boost frequently accessed memories in search results
+- Maintain backward compatibility with existing memories and config
+
+**Out of Scope (Phase 2+):**
+- LLM-based categorization or summarization
+- Automatic memory deletion or archival
+- User-facing UI for memory management
+- Cross-collection memory relationships
+- Memory consolidation or deduplication
+
+## Decisions
+
+### 1. Memory Relevance Decay
+
+**What:** Add `access_count INTEGER DEFAULT 0` and `last_accessed_at TEXT` columns to the `documents` table. Track access on every search result returned to the user. Apply exponential decay to search scores based on time since last access.
+
+**Why:** Memories that haven't been accessed in months are less likely to be relevant now. Exponential decay with a configurable half-life (default 30 days) provides intuitive control: memory is "half as relevant" after N days of no access. This is gentler than LRU eviction (which deletes) and more flexible than fixed TTL (which is binary).
+
+**How:**
+- Schema migration: `ALTER TABLE documents ADD COLUMN access_count INTEGER DEFAULT 0; ALTER TABLE documents ADD COLUMN last_accessed_at TEXT;`
+- On search result return (in `hybridSearch` after final scoring), increment `access_count` and update `last_accessed_at` for each result shown to the user
+- Decay function: `decayScore = 1 / (1 + daysSinceAccess / halfLife)` where `daysSinceAccess = (now - last_accessed_at) / 86400000`
+- Applied as a multiplier in the scoring pipeline after RRF fusion but before position-aware blending
+- New config section in `config.yml`:
+  ```yaml
+  decay:
+    enabled: true
+    halfLife: "30d"  # parsed to days
+    boostWeight: 0.15  # how much decay affects final score
+  ```
+- Backward compatible: existing memories get `access_count=0`, `last_accessed_at=NULL`; decay treats NULL as "never accessed" (maximum decay)
+
+**Alternatives considered:**
+- **LRU eviction:** Too aggressive. Deletes memories permanently. Users lose context.
+- **Fixed TTL:** Too rigid. A 90-day-old architecture decision is still valuable; a 7-day-old typo fix is not.
+- **No decay (status quo):** Loses signal. Old noise drowns out recent signal as memory grows.
+
+**Trade-offs:**
+- Adds 2 columns to `documents` table (minimal storage overhead: ~16 bytes per doc)
+- Adds 1 UPDATE per search result returned (negligible for typical result counts of 5-20)
+- Decay calculation is pure math (no I/O, no blocking)
+
+### 2. Auto-Categorization on Write
+
+**What:** When `memory_write` is called, classify content into predefined categories using keyword/pattern heuristics. Populate the existing `document_tags` table with auto-generated tags prefixed with `auto:`.
+
+**Why:** Manual tagging is tedious and inconsistent. Heuristic categorization is instant, deterministic, and requires no external dependencies. Categories help users filter searches (e.g., "show me architecture decisions") and provide structure for future features (e.g., category-specific retention policies).
+
+**How:**
+- Categories: `architecture-decision`, `debugging-insight`, `tool-config`, `pattern`, `preference`, `context`, `workflow`
+- Detection rules (keyword matching, case-insensitive):
+  - `architecture-decision`: "decided", "chose", "architecture", "design decision", "trade-off", "approach"
+  - `debugging-insight`: "error", "fix", "bug", "stack trace", "crash", "exception", "workaround"
+  - `tool-config`: "config", "setup", "install", "environment", "settings", "configuration"
+  - `pattern`: "pattern", "convention", "idiom", "best practice", "anti-pattern"
+  - `preference`: "prefer", "avoid", "like", "dislike", "style", "opinion"
+  - `context`: "context", "background", "overview", "summary", "explanation"
+  - `workflow`: "workflow", "process", "steps", "procedure", "checklist"
+- Applied in `store.insertDocument` after content insertion
+- Tags are prefixed with `auto:` (e.g., `auto:architecture-decision`) to distinguish from user-provided tags
+- Additive: does not remove user-provided tags
+- Multiple categories can apply to a single memory
+
+**Alternatives considered:**
+- **LLM-based categorization:** Too slow (100-500ms per write), costs money, requires API keys. Deferred to Phase 2.
+- **No categorization (status quo):** Memories remain unstructured. Harder to filter or prioritize.
+- **User-only tagging:** Requires manual effort. Users forget or skip tagging.
+
+**Trade-offs:**
+- Heuristics are imperfect. Some memories will be miscategorized or miss categories.
+- Keyword matching is language-dependent (assumes English). Non-English memories may not categorize well.
+- Adds ~5-10ms to write latency (negligible for background MCP server)
+
+### 3. Usage-Based Search Boosting
+
+**What:** Integrate `access_count` and `last_accessed_at` into the hybrid search scoring pipeline. Frequently accessed memories get a configurable boost.
+
+**Why:** Memories that are accessed repeatedly are more likely to be relevant in the future. This is a form of implicit feedback: the user's past behavior signals importance. Combined with decay, this creates a "hot/cold" memory system where frequently accessed recent memories rank highest.
+
+**How:**
+- New function `applyUsageBoost(results, config)` similar to `applyCentralityBoost`
+- Formula: `usageBoost = log2(1 + access_count) * decayScore * boostWeight`
+  - `log2(1 + access_count)` provides diminishing returns (10 accesses is not 10x better than 1 access)
+  - `decayScore` is the decay multiplier from Feature 1 (so old memories don't get boosted)
+  - `boostWeight` is configurable (default 0.15)
+- Applied in the scoring pipeline after `applyCentralityBoost`, before `applySupersedeDemotion`
+- New config field in `SearchConfig` type (`types.ts`):
+  ```typescript
+  usage_boost_weight: number; // default 0.15
+  ```
+- Backward compatible: memories with `access_count=0` get no boost (log2(1) = 0)
+
+**Alternatives considered:**
+- **Replace RRF entirely with usage-based ranking:** Too risky. RRF is proven. Usage is a signal, not the only signal.
+- **Separate boost index:** Over-engineered. Usage data is already in `documents` table.
+- **Linear boost (not log):** Amplifies outliers too much. A memory accessed 100 times would dominate results.
+
+**Trade-offs:**
+- Adds 1 JOIN to search query (negligible: `documents` table is already joined)
+- Boost calculation is pure math (no I/O, no blocking)
+- Cold start problem: new memories have `access_count=0` and rank lower. Mitigated by decay (new memories have no decay penalty).
+
+## Risks and Trade-offs
+
+### Performance
+- **Risk:** Access tracking adds 1 UPDATE per search result. For 20 results, that's 20 UPDATEs.
+- **Mitigation:** SQLite handles small UPDATEs efficiently. Batch UPDATEs in a single transaction. Measure latency in testing.
+- **Fallback:** If latency is unacceptable, make access tracking async (fire-and-forget).
+
+### Accuracy
+- **Risk:** Heuristic categorization is imperfect. Memories may be miscategorized.
+- **Mitigation:** Use `auto:` prefix so users can distinguish auto-tags from manual tags. Users can remove incorrect auto-tags.
+- **Fallback:** If categorization is too noisy, add a config flag to disable it.
+
+### Cold Start
+- **Risk:** New memories have `access_count=0` and rank lower than old frequently accessed memories.
+- **Mitigation:** Decay penalizes old memories. New memories have no decay penalty, so they start with a neutral score.
+- **Fallback:** Add a "recency boost" in Phase 2 to explicitly favor new memories.
+
+### Backward Compatibility
+- **Risk:** Existing memories have `access_count=0` and `last_accessed_at=NULL`.
+- **Mitigation:** Decay treats NULL as "never accessed" (maximum decay). This is correct: old memories that were never accessed should rank lower.
+- **Fallback:** Provide a migration script to backfill `last_accessed_at` with `created_at` for existing memories.
+
+### Configuration Complexity
+- **Risk:** Adding `decay` and `usage_boost_weight` config fields increases surface area.
+- **Mitigation:** Provide sensible defaults (enabled, 30d half-life, 0.15 boost weight). Document in README.
+- **Fallback:** If users find config overwhelming, hide advanced options behind a `--advanced` flag.
+
+## Implementation Notes
+
+### Schema Migration
+```sql
+ALTER TABLE documents ADD COLUMN access_count INTEGER DEFAULT 0;
+ALTER TABLE documents ADD COLUMN last_accessed_at TEXT;
+CREATE INDEX IF NOT EXISTS idx_documents_access ON documents(last_accessed_at);
+```
+
+### Scoring Pipeline Order
+1. `rrfFuse` — combine BM25 + vector
+2. `applyTopRankBoost` (if enabled)
+3. `applyCentralityBoost` (existing)
+4. **`applyUsageBoost` (new)** — boost frequently accessed memories
+5. `applySupersedeDemotion` (existing)
+6. `positionAwareBlend` — blend RRF + rerank scores
+7. **Track access** (new) — increment `access_count`, update `last_accessed_at`
+
+### Config Schema
+```yaml
+decay:
+  enabled: true
+  halfLife: "30d"  # supports "7d", "30d", "90d", etc.
+  boostWeight: 0.15
+
+search:
+  usage_boost_weight: 0.15
+  # ... existing fields
+```
+
+### Auto-Categorization Rules
+Implemented as a simple keyword matcher in `store.ts`:
+```typescript
+function autoCategorizeTags(content: string): string[] {
+  const tags: string[] = [];
+  const lower = content.toLowerCase();
+  
+  if (/\b(decided|chose|architecture|design decision|trade-?off|approach)\b/.test(lower)) {
+    tags.push('auto:architecture-decision');
+  }
+  if (/\b(error|fix|bug|stack trace|crash|exception|workaround)\b/.test(lower)) {
+    tags.push('auto:debugging-insight');
+  }
+  // ... more rules
+  
+  return tags;
+}
+```
+
+### Testing Strategy
+- Unit tests for decay function (edge cases: NULL, 0, negative)
+- Unit tests for usage boost (edge cases: 0 access_count, high access_count)
+- Unit tests for auto-categorization (each category, multi-category, no match)
+- Integration test: write memory → search → verify access tracking
+- Integration test: search with decay enabled vs disabled
+- Performance test: measure search latency with 10k memories, 20 results

package/openspec/changes/nano-brain-phase1-memory-intelligence/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+nano-brain stores memories indefinitely with equal weight — a 6-month-old unused debugging note ranks the same as yesterday's critical architecture decision. There is no automatic organization, no relevance scoring, and no way to distinguish signal from noise as memory accumulates over time. Competitive memory systems (Mem0, memU) achieve 26-74% higher accuracy on benchmarks partly through intelligent memory lifecycle management. Phase 1 addresses the three lowest-effort, highest-impact gaps: relevance decay, automatic categorization, and usage-based ranking.
+
+## What Changes
+
+- **Memory relevance decay**: Add `access_count` and `last_accessed_at` tracking to documents. Introduce a configurable decay function that deprioritizes stale, unused memories in search results. Memories accessed frequently stay prominent; neglected ones fade gracefully without deletion.
+- **Auto-categorization on write**: When `memory_write` is called, classify the content into predefined categories (architecture-decision, debugging-insight, tool-config, pattern, preference, context) using lightweight keyword/heuristic matching. Populate the existing `tags` field automatically. No LLM dependency for Phase 1 — keep it fast and local.
+- **Usage-based search boosting**: Integrate access frequency and recency into the hybrid search scoring pipeline. Frequently retrieved memories get a configurable boost in RRF fusion, complementing the existing BM25 + vector + rerank pipeline.
+
+## Capabilities
+
+### New Capabilities
+- `memory-relevance-decay`: Track memory access patterns and apply time-based relevance decay to search scoring
+- `auto-categorization`: Automatically classify and tag memories on write using heuristic rules
+- `usage-based-boosting`: Boost frequently accessed memories in hybrid search results
+
+### Modified Capabilities
+- `search-pipeline`: Search scoring now incorporates access frequency and recency as additional ranking signals
+- `storage-limits`: Decay metadata (access_count, last_accessed_at) added to document schema; retention eviction can optionally prioritize low-access documents
+
+## Impact
+
+- **Schema**: New columns on `documents` table (`access_count INTEGER DEFAULT 0`, `last_accessed_at TEXT`)
+- **Search pipeline** (`search.ts`): Additional scoring factor in RRF fusion for access-based boosting
+- **Store** (`store.ts`): Track access on every search result retrieval; auto-tag on document insert
+- **MCP server** (`server.ts`): `memory_write` gains auto-categorization; search tools update access tracking
+- **Config** (`config.yml`): New `decay` section with `halfLife`, `boostWeight`, `enabled` fields
+- **No new dependencies**: Heuristic categorization avoids LLM calls; decay is pure math
+- **Backward compatible**: Existing memories get `access_count=0`, `last_accessed_at=NULL`; decay defaults to disabled until configured

package/openspec/changes/nano-brain-phase1-memory-intelligence/specs/auto-categorization/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: Automatic tag assignment on write
+
+When `memory_write` is called, the system SHALL analyze the content and assign category tags based on keyword/pattern heuristics. Auto-generated tags SHALL be prefixed with `auto:` (e.g., `auto:architecture-decision`).
+
+#### Scenario: Content contains architecture decision keywords
+
+- **WHEN** content contains "decided to use PostgreSQL"
+- **THEN** the document is tagged with `auto:architecture-decision`
+
+#### Scenario: Content contains debugging keywords
+
+- **WHEN** content contains "fixed bug" and "stack trace"
+- **THEN** the document is tagged with `auto:debugging-insight`
+
+#### Scenario: Content with no matching patterns
+
+- **WHEN** content does not match any category patterns
+- **THEN** no auto tags are added to the document
+
+### Requirement: Category definitions
+
+The system SHALL recognize these categories: `architecture-decision` (keywords: decided, chose, architecture, design, tradeoff, approach), `debugging-insight` (keywords: error, fix, bug, stack trace, debug, workaround), `tool-config` (keywords: config, setup, install, environment, .env), `pattern` (keywords: pattern, convention, always, never, rule), `preference` (keywords: prefer, like, dislike, favorite, default), `context` (keywords: context, background, note, remember), `workflow` (keywords: workflow, process, step, pipeline, deploy).
+
+#### Scenario: Architecture decision content
+
+- **WHEN** content is "We chose React over Vue for the frontend"
+- **THEN** the document is tagged with `auto:architecture-decision`
+
+#### Scenario: Debugging insight content
+
+- **WHEN** content is "npm install failed, fixed by clearing cache"
+- **THEN** the document is tagged with `auto:debugging-insight`
+
+#### Scenario: Content matching multiple categories
+
+- **WHEN** content matches patterns for both `architecture-decision` and `workflow`
+- **THEN** all matching auto tags are applied to the document
+
+### Requirement: Additive tagging
+
+Auto-categorization SHALL NOT remove or replace user-provided tags. Auto tags are added alongside any tags the user explicitly provides.
+
+#### Scenario: User provides explicit tags
+
+- **WHEN** user provides tags=["important"] and content matches debugging patterns
+- **THEN** the final tags are ["important", "auto:debugging-insight"]
+
+#### Scenario: User provides no tags
+
+- **WHEN** user provides no tags and content matches categorization patterns
+- **THEN** only auto tags are applied to the document
+
+### Requirement: Deterministic and fast
+
+Auto-categorization SHALL NOT use LLM calls. It SHALL complete in under 5ms for typical content (under 10KB). The heuristic engine SHALL be pure keyword/regex matching.
+
+#### Scenario: Small document categorization
+
+- **WHEN** a 5KB markdown document is written
+- **THEN** auto-categorization completes in under 5ms
+
+#### Scenario: Large document categorization
+
+- **WHEN** a 100KB document is written
+- **THEN** auto-categorization completes in under 50ms

package/openspec/changes/nano-brain-phase1-memory-intelligence/specs/memory-relevance-decay/spec.md

@@ -0,0 +1,85 @@
+## ADDED Requirements
+
+### Requirement: Access tracking on search results
+
+The system SHALL increment `access_count` and update `last_accessed_at` for every document returned in search results to the user. Internal pipeline queries (expansion, reranking) SHALL NOT trigger access tracking.
+
+#### Scenario: Search returns multiple results
+
+- **WHEN** a search returns 5 results to the user
+- **THEN** all 5 documents have their `access_count` incremented by 1
+- **THEN** all 5 documents have their `last_accessed_at` updated to the current timestamp
+
+#### Scenario: Same document returned in separate searches
+
+- **WHEN** the same document is returned in two separate user searches
+- **THEN** the document's `access_count` is 2
+- **THEN** the document's `last_accessed_at` reflects the most recent search timestamp
+
+#### Scenario: Internal pipeline query does not trigger tracking
+
+- **WHEN** a vector-only internal search occurs during the hybrid pipeline
+- **THEN** no `access_count` increments occur for those intermediate results
+- **THEN** only the final results returned to the user trigger access tracking
+
+### Requirement: Decay score computation
+
+The system SHALL compute a decay score using the formula `1 / (1 + daysSinceAccess / halfLife)` where `daysSinceAccess` is the number of days since `last_accessed_at` and `halfLife` is configurable. Documents with NULL `last_accessed_at` SHALL use `created_at` as fallback.
+
+#### Scenario: Document accessed today
+
+- **WHEN** a document was accessed today (daysSinceAccess = 0)
+- **THEN** the decay score is approximately 1.0
+
+#### Scenario: Document not accessed for 30 days with 30-day half-life
+
+- **WHEN** a document has not been accessed for 30 days and `halfLife` is 30 days
+- **THEN** the decay score is approximately 0.5
+
+#### Scenario: Document never accessed
+
+- **WHEN** a document has NULL `last_accessed_at`
+- **THEN** the system uses `created_at` for the `daysSinceAccess` calculation
+- **THEN** the decay score is computed based on the document's age
+
+### Requirement: Schema migration
+
+The system SHALL add `access_count INTEGER DEFAULT 0` and `last_accessed_at TEXT DEFAULT NULL` columns to the `documents` table. Existing documents SHALL retain default values. Migration SHALL be backward compatible (no data loss).
+
+#### Scenario: Fresh database initialization
+
+- **WHEN** a new database is created
+- **THEN** the `documents` table includes `access_count` and `last_accessed_at` columns from creation
+
+#### Scenario: Existing database without decay columns
+
+- **WHEN** an existing database does not have `access_count` or `last_accessed_at` columns
+- **THEN** an ALTER TABLE migration adds both columns with default values
+- **THEN** no existing data is lost
+
+#### Scenario: Existing documents after migration
+
+- **WHEN** the migration completes on a database with existing documents
+- **THEN** all existing documents have `access_count` set to 0
+- **THEN** all existing documents have `last_accessed_at` set to NULL
+
+### Requirement: Decay configuration
+
+The system SHALL support a `decay` section in config.yml with `enabled` (boolean, default false), `halfLife` (duration string, default "30d"), and `boostWeight` (number 0-1, default 0.15). Invalid values SHALL log a warning and use defaults.
+
+#### Scenario: Decay not configured
+
+- **WHEN** config.yml has no `decay` section
+- **THEN** decay is disabled by default
+- **THEN** no decay scoring is applied to search results
+
+#### Scenario: Decay enabled with custom half-life
+
+- **WHEN** config.yml contains `decay: { enabled: true, halfLife: "7d" }`
+- **THEN** the system uses a 7-day half-life for decay calculations
+
+#### Scenario: Invalid half-life value
+
+- **WHEN** config.yml contains `decay: { halfLife: "banana" }`
+- **THEN** a warning is logged indicating the invalid value
+- **THEN** the default half-life of 30 days is used

package/openspec/changes/nano-brain-phase1-memory-intelligence/specs/search-pipeline/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Usage-aware scoring in hybrid pipeline
+
+The `memory_query` hybrid search pipeline SHALL incorporate usage-based scoring as an additional ranking signal. The scoring pipeline order SHALL be: RRF fusion → top-rank bonus → centrality boost → usage boost → supersede demotion → position-aware blend (if reranking enabled).
+
+#### Scenario: Hybrid search with usage boost enabled
+
+- **WHEN** a hybrid search is performed with usage boost enabled
+- **THEN** search results reflect access patterns in their ranking
+- **THEN** frequently accessed documents rank higher than identical documents with lower access counts
+
+#### Scenario: Hybrid search with usage boost disabled
+
+- **WHEN** a hybrid search is performed with `usage_boost_weight` set to 0
+- **THEN** the search results are identical to the current behavior without usage boosting
+- **THEN** no usage-based score adjustments are applied
+
+#### Scenario: BM25-only search does not apply usage boost
+
+- **WHEN** a BM25-only search is performed using `memory_search`
+- **THEN** no usage boost is applied to the results
+- **THEN** only the hybrid pipeline (`memory_query`) incorporates usage-based scoring

package/openspec/changes/nano-brain-phase1-memory-intelligence/specs/storage-limits/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Access-aware retention eviction
+
+When performing size-based eviction (storage exceeds maxSize), the system SHALL optionally consider access_count when selecting documents to evict. Documents with lower access_count SHALL be evicted before documents with higher access_count, within the same age tier. This behavior SHALL be enabled when `decay.enabled` is true in config.
+
+#### Scenario: Two documents same age with different access counts
+
+- **WHEN** two documents have the same age, one with `access_count` of 10 and one with `access_count` of 0
+- **THEN** the document with `access_count` of 0 is evicted first
+- **THEN** the document with `access_count` of 10 is retained
+
+#### Scenario: Decay disabled uses age-only eviction
+
+- **WHEN** `decay.enabled` is false in config
+- **THEN** eviction uses age-only ordering (current behavior)
+- **THEN** `access_count` is not considered in eviction decisions
+
+#### Scenario: All documents have zero access count
+
+- **WHEN** all documents have `access_count` of 0
+- **THEN** the system falls back to age-based eviction
+- **THEN** the oldest documents are evicted first

package/openspec/changes/nano-brain-phase1-memory-intelligence/specs/usage-based-boosting/spec.md

@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: Usage boost in search scoring
+
+The hybrid search pipeline SHALL apply a usage-based boost to results using the formula `usageBoost = log2(1 + access_count) * decayScore * boostWeight`. The boost SHALL be applied as an additive score adjustment.
+
+#### Scenario: Document with no access history
+
+- **WHEN** a document has `access_count` of 0
+- **THEN** the usage boost is 0 (since log2(1) = 0)
+- **THEN** the document's score is not affected by usage boosting
+
+#### Scenario: Document with moderate access and recent activity
+
+- **WHEN** a document has `access_count` of 7 and was recently accessed
+- **THEN** a moderate usage boost is applied (log2(8) * decayScore * boostWeight)
+- **THEN** the document ranks higher than identical documents with lower access counts
+
+#### Scenario: Document with high access but stale
+
+- **WHEN** a document has `access_count` of 100 but has not been accessed recently
+- **THEN** the usage boost is reduced by the decay score
+- **THEN** the boost is lower than a recently accessed document with the same access count
+
+### Requirement: Boost pipeline position
+
+The usage boost SHALL be applied after centrality boost and before supersede demotion in the search scoring pipeline.
+
+#### Scenario: Result with high centrality and high usage
+
+- **WHEN** a document has both high centrality and high usage scores
+- **THEN** both the centrality boost and usage boost are applied
+- **THEN** the boosts compound to increase the document's final score
+
+#### Scenario: Superseded document with high usage
+
+- **WHEN** a superseded document has high usage
+- **THEN** the usage boost is applied first
+- **THEN** the supersede demotion is applied afterward, reducing the final score
+
+### Requirement: Configuration
+
+The SearchConfig SHALL include `usage_boost_weight` (number, default 0.15). Setting to 0 effectively disables usage boosting without disabling access tracking.
+
+#### Scenario: Usage boost disabled
+
+- **WHEN** `usage_boost_weight` is set to 0
+- **THEN** no usage boost is applied to search results
+- **THEN** access tracking still occurs for all returned documents
+
+#### Scenario: Stronger usage signal
+
+- **WHEN** `usage_boost_weight` is set to 0.3
+- **THEN** usage-based boosting has a stronger effect on search rankings
+
+#### Scenario: Negative boost weight
+
+- **WHEN** `usage_boost_weight` is set to a negative value
+- **THEN** a warning is logged indicating the invalid value
+- **THEN** the default value of 0.15 is used

package/openspec/changes/nano-brain-phase1-memory-intelligence/tasks.md

@@ -0,0 +1,49 @@
+# Tasks: Memory Intelligence Phase 1
+
+## 1. Schema & Migration
+- [ ] 1.1 Add `access_count INTEGER DEFAULT 0` and `last_accessed_at TEXT` columns to documents table CREATE TABLE in `src/store.ts`
+- [ ] 1.2 Add migration logic to detect and ALTER TABLE for existing databases (follow existing migration pattern in store.ts around line 196-230)
+- [ ] 1.3 Add `access_count` and `lastAccessedAt` fields to `Document` interface and `SearchResult` interface in `src/types.ts`
+- [ ] 1.4 Add index on `last_accessed_at` column: `CREATE INDEX IF NOT EXISTS idx_documents_access ON documents(last_accessed_at)`
+
+## 2. Decay Configuration
+- [ ] 2.1 Add `decay` section to `CollectionConfig` interface in `src/types.ts`: `{ enabled: boolean, halfLife: string, boostWeight: number }`
+- [ ] 2.2 Add decay config parsing with duration string support and validation (reuse existing parseDuration pattern from storage.ts if available, or add new)
+- [ ] 2.3 Add `usage_boost_weight` field to `SearchConfig` interface and `DEFAULT_SEARCH_CONFIG` in `src/types.ts` (default 0.15)
+- [ ] 2.4 Add config validation for `boostWeight` (0-1 range) and `usage_boost_weight` (warn on negative, use default)
+
+## 3. Auto-Categorization Engine
+- [ ] 3.1 Create new file `src/categorizer.ts` with `categorize(content: string): string[]` function — pure keyword/regex matching, returns array of category strings
+- [ ] 3.2 Implement category rules: architecture-decision, debugging-insight, tool-config, pattern, preference, context, workflow with keyword lists per the spec
+- [ ] 3.3 Add `auto:` prefix to all auto-generated tags
+- [ ] 3.4 Wire categorizer into `memory_write` handler in `src/server.ts` — merge auto tags with user-provided tags before inserting into document_tags
+- [ ] 3.5 Add unit tests for categorizer: test each category detection, multi-category, no-match, and performance (<5ms for 10KB)
+
+## 4. Access Tracking
+- [ ] 4.1 Add `trackAccess(docIds: number[])` method to Store interface and implement in `src/store.ts` — batch UPDATE access_count = access_count + 1, last_accessed_at = datetime('now')
+- [ ] 4.2 Wire access tracking into MCP search tool handlers in `src/server.ts` — call trackAccess after returning results for memory_search, memory_vsearch, memory_query
+- [ ] 4.3 Ensure internal pipeline queries (expansion, reranking) do NOT trigger access tracking
+- [ ] 4.4 Add tests for access tracking (verify increment, verify internal queries don't track)
+
+## 5. Decay Score Computation
+- [ ] 5.1 Add `computeDecayScore(lastAccessedAt: string | null, createdAt: string, halfLifeDays: number): number` function in `src/search.ts`
+- [ ] 5.2 Implement decay formula: `1 / (1 + daysSinceAccess / halfLife)` where daysSinceAccess uses `lastAccessedAt` or falls back to `createdAt` if NULL
+- [ ] 5.3 Add tests for decay score computation (edge cases: NULL last_accessed_at, zero days, large daysSinceAccess)
+
+## 6. Usage-Based Search Boosting
+- [ ] 6.1 Add `applyUsageBoost(results: SearchResult[], config: { usageBoostWeight: number, decayHalfLifeDays: number }): SearchResult[]` function in `src/search.ts`
+- [ ] 6.2 Implement boost formula: `log2(1 + access_count) * decayScore * boostWeight` where decayScore = `1 / (1 + daysSinceAccess / halfLife)`
+- [ ] 6.3 Ensure access_count and last_accessed_at are loaded in search result queries (update SQL in store.ts searchFTS and searchVec)
+- [ ] 6.4 Wire applyUsageBoost into hybrid search pipeline in `src/search.ts` in the correct position: after applyCentralityBoost, before applySupersedeDemotion
+- [ ] 6.5 Add tests for usage boost integration in search pipeline (verify pipeline order, verify weight=0 disables boost)
+
+## 7. Storage Integration
+- [ ] 7.1 Update size-based eviction in `src/storage.ts` to sort by access_count (ascending) within same age tier when decay.enabled is true
+- [ ] 7.2 Ensure eviction falls back to age-only ordering when decay.enabled is false or all access_counts are 0
+- [ ] 7.3 Add tests for access-aware eviction (same age different access counts, decay disabled, all zero access counts)
+
+## 8. Testing & Validation
+- [ ] 8.1 Add tests for schema migration (fresh DB, existing DB without columns)
+- [ ] 8.2 Run full test suite and verify no regressions
+- [ ] 8.3 Manual smoke test: write a memory, search for it multiple times, verify access_count increments and boost affects ranking
+- [ ] 8.4 Performance test: measure search latency with 10k memories, 20 results (verify access tracking overhead is acceptable)

package/openspec/changes/nano-brain-phase2-llm-memory-consolidation/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-07