Overview
This issue tracks the complete performance and cache optimization sprint for lossless-claw, covering 5 PRs across 4 issues. The work addresses database lock races, unnecessary cache-busting compaction, SQLite tuning, compaction read/write path optimization, and search quality improvements.
PRs (in merge order)
PR
Issue
What
Status
CI
#288 #287 DB lock race fix — eager-first init with deferred fallback on SQLite lockReady
✅
#289 #282 Cache-aware compaction — skip guards + budget pressure priority + tuning guideReady
✅
#294 #291 SQLite PRAGMAs + indexes — 64MB cache, sync=NORMAL, missing indexesReady
✅
#295 #291 Core DB optimization — context cache, bulk ordinals, delta trackingReady
Pending fork CI
#296 #293 Search quality — configurable BM25 sort, phrase matching fixReady
Pending fork CI
Total Impact Across All PRs
Metric
Before
After
Startup "database is locked" loop on macOS reboot
Fixed — eager-first, defer on lock
Unnecessary compactions Every turn on high-traffic conversations
Skipped when gain < 5% or under budget ceiling
DB operations per compaction sweep 120-160
~30-40 (75% reduction)
Write lock per compaction pass ~30ms (2×N individual UPDATEs)
~1.5ms (2 bulk UPDATEs)
SQLite page cache 2MB (default)
64MB (demand-allocated)
Write sync FULL (fsync every commit)
NORMAL (~50% faster writes)
Search results Recency only
Configurable: recency / relevance / hybrid
Phrase matching Broken (`"error handling"` → two terms)
Fixed (preserved as phrase)
Expansion model docs Not documented
Full guide with per-tier configs + cost analysis
Cache miss cost awareness None
Skip guards prevent wasteful cache-busting
Architecture Decisions
Cache-aware compaction (PR #289 )
Three-tier decision logic: basic threshold → budget headroom → cache-aware reduction. Budget pressure always overrides cache concerns (prevents starvation). Per-pass chunk estimation. Configurable via `leafSkipReductionThreshold` and `leafBudgetHeadroomFactor`.
DB optimization (PRs #294 + #295 )
Context cache : per-phase Map with reference counting for concurrent safety. Invalidated after each write.Delta tracking : `tokensAfter = tokensBefore - removedTokens + addedTokens`. Mathematically proven equivalent. leafPass/condensedPass return deltas.Ordinal resequencing : rank-based correlated subquery handles gaps. 2 bulk UPDATEs instead of 2×N.PRAGMAs : cache_size=64MB, synchronous=NORMAL, temp_store=MEMORY, optimize on close.
Search quality (PR #296 )
Configurable `sort` parameter on `lcm_grep`: recency (default) / relevance (FTS5 BM25) / hybrid. Preserves LCM's design intent (DAG = relevance filter, recency = routing default) while enabling relevance for long-history users.
Documentation Delivered
Compaction Tuning Guide Architecture updates — cache-aware guards, Mermaid diagrams, prompt cache impactConfiguration updates — all new settings documented with env varsExpansion model cost — documented the hidden `lcm_expand_query` sub-agent token costModel comparison table — 10 models with exact per-call costs and context windowsReferences section — LCM paper, CMV paper, demand-paging paper, cache docs
Issues
Recommended Merge Order
fix: defer DB init to gateway_start hook to prevent database lock race #288 perf: optimize SQLite PRAGMAs and add missing indexes #294 feat: cache-aware compaction guards with budget-pressure priority and per-tier tuning #289 perf: context cache, delta tracking, and bulk ordinal resequencing #295 feat: cache-aware compaction guards with budget-pressure priority and per-tier tuning #289 feat: configurable search sort (recency/relevance/hybrid) + phrase matching fix #296
PRs #295 and #289 may have merge conflicts in `compaction.ts` since both modify `evaluateLeafTrigger`. Resolve by keeping both sets of changes — #289 adds skip guards, #295 adds caching.
Test Coverage
PR
New Tests
Total Pass
#289 21 (16 skip logic + 5 config)
239/239
#294 0 (config-only)
561/561
#295 0 (perf-only, existing tests cover correctness)
169/169
#296 0 (small scope, existing search tests cover)
202/202
Review History
Each PR went through multiple adversarial review rounds:
Overview
This issue tracks the complete performance and cache optimization sprint for lossless-claw, covering 5 PRs across 4 issues. The work addresses database lock races, unnecessary cache-busting compaction, SQLite tuning, compaction read/write path optimization, and search quality improvements.
PRs (in merge order)
Total Impact Across All PRs
Architecture Decisions
Cache-aware compaction (PR #289)
Three-tier decision logic: basic threshold → budget headroom → cache-aware reduction. Budget pressure always overrides cache concerns (prevents starvation). Per-pass chunk estimation. Configurable via `leafSkipReductionThreshold` and `leafBudgetHeadroomFactor`.
DB optimization (PRs #294 + #295)
Search quality (PR #296)
Configurable `sort` parameter on `lcm_grep`: recency (default) / relevance (FTS5 BM25) / hybrid. Preserves LCM's design intent (DAG = relevance filter, recency = routing default) while enabling relevance for long-history users.
Documentation Delivered
Issues
Recommended Merge Order
PRs #295 and #289 may have merge conflicts in `compaction.ts` since both modify `evaluateLeafTrigger`. Resolve by keeping both sets of changes — #289 adds skip guards, #295 adds caching.
Test Coverage
Review History
Each PR went through multiple adversarial review rounds: