claude-recall 0.37.1 → 0.38.0

package/README.md

@@ -464,6 +464,7 @@ Defaults work out of the box; tune via environment variables as needed.
 | `CLAUDE_RECALL_LLM_TIMEOUT_MS`           | `5000`  | Timeout for hook-context LLM calls (classification, hindsight hints). Hooks fall back to regex when it fires. |
 | `CLAUDE_RECALL_STOP_DEBOUNCE_MS`         | `300000` | Debounce for the heavy Stop-hook pipeline (episodes, session extraction, promotion). `0` disables. |
 | `CLAUDE_RECALL_PROJECT_ID`               | *(cwd)*  | Pin the project scope to a fixed id, overriding working-directory detection. |
+| `CLAUDE_RECALL_RETRIEVAL`                | `like`  | Lexical retrieval engine: `fts` uses SQLite FTS5 / BM25 ranking for better paraphrase recall; `like` (default) uses the legacy substring filter. Opt-in; falls back to `like` automatically if the SQLite build lacks FTS5. See [docs/design-hybrid-retrieval-fts5.md](docs/design-hybrid-retrieval-fts5.md). |
 
 ---
 

package/dist/cli/claude-recall-cli.js

@@ -1096,6 +1096,15 @@ class ClaudeRecallCLI {
             const stats = fs.statSync(dbPath);
             console.log(`  Path: ${dbPath}`);
             console.log(`  Size: ${(stats.size / 1024 / 1024).toFixed(2)} MB`);
+            // Surface the write-ahead log size. A WAL that has grown to a large
+            // fraction of the DB usually means a long-lived connection isn't
+            // checkpointing; it's truncated on the next clean shutdown (close()).
+            const walPath = `${dbPath}-wal`;
+            if (fs.existsSync(walPath)) {
+                const walMb = fs.statSync(walPath).size / 1024 / 1024;
+                const warn = walMb > 16 ? '  ⚠️  large — will truncate on next clean shutdown' : '';
+                console.log(`  WAL:  ${walMb.toFixed(2)} MB${warn}`);
+            }
         }
         // Memory stats
         const memStats = this.memoryService.getStats();

package/dist/core/retrieval.js

@@ -102,8 +102,17 @@ class MemoryRetrieval {
     }
     calculateRelevance(memory, context, stats, evidenceCount) {
         let score = memory.relevance_score || 1.0;
-        // Boost for keyword matches in memory value
-        if (context.keywords && context.keywords.length > 0) {
+        // Lexical boost. Two sources, mutually exclusive:
+        //   (a) FTS5 path — storage attached a normalized bm25Score ∈ [0,1]; every
+        //       returned candidate already matched the query (MATCH filtered), so
+        //       there is no "no-overlap" case here.
+        //   (b) LIKE path — no bm25Score; fall back to keyword-overlap counting.
+        if (memory.bm25Score !== undefined) {
+            // Fuse BM25 multiplicatively, preserving the LIKE path's dynamic range
+            // (~1x..4x) so decay/strength/evidence boosts behave identically.
+            score *= 1 + MemoryRetrieval.W_LEXICAL * memory.bm25Score;
+        }
+        else if (context.keywords && context.keywords.length > 0) {
             const memoryStr = JSON.stringify(memory.value).toLowerCase();
             let keywordMatches = 0;
             for (const keyword of context.keywords) {
@@ -268,6 +277,13 @@ class MemoryRetrieval {
     }
 }
 exports.MemoryRetrieval = MemoryRetrieval;
+/**
+ * Fusion weight for the FTS5 BM25 lexical signal. Chosen so a top match
+ * (bm25Score=1) yields a ~4x boost, matching the LIKE path's full-match
+ * dynamic range (1 + matchRatio*3, ×1.5 all-match). Tune against the
+ * retrieval benchmark before flipping CLAUDE_RECALL_RETRIEVAL=fts to default.
+ */
+MemoryRetrieval.W_LEXICAL = 3.0;
 MemoryRetrieval.TYPE_PRIORITY = {
     'correction': 6,
     'solution': 5.5, // hard-won reusable solutions — high signal, rank just below corrections

package/dist/hooks/memory-sync-hook.js

@@ -75,12 +75,94 @@ function deriveAutoMemoryPath(cwd, homedir) {
  * Extract display value from a memory record.
  */
 function extractValue(value) {
-    if (typeof value === 'string')
-        return value;
-    if (typeof value === 'object' && value !== null) {
-        return value.content || value.value || JSON.stringify(value);
+    // Always resolve to readable text. Handles every historical shape:
+    //  - clean structured `{ title, description, content }` → prefer the title
+    //  - failure content objects → "what_failed → what_should_do"
+    //  - nested `{ content: { ... } }` / `{ content: "{...json...}" }` wrappers
+    //  - stringified-JSON stored as a plain string
+    // Without this, a failure stored as `JSON.stringify(content)` rendered its
+    // raw JSON as the file title/slug (e.g. `[{"what_failed":"Bash command...`),
+    // and clean object-content memories stringified to "[object Object]".
+    let v = value;
+    for (let depth = 0; depth < 6; depth++) {
+        if (typeof v === 'string') {
+            const t = v.trim();
+            if (t.startsWith('{') || t.startsWith('[')) {
+                try {
+                    v = JSON.parse(t);
+                    continue;
+                }
+                catch {
+                    return v;
+                }
+            }
+            return v;
+        }
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            if (typeof v.title === 'string' && v.title.trim())
+                return v.title.trim();
+            if (typeof v.what_failed === 'string') {
+                return v.what_should_do ? `${v.what_failed} → ${v.what_should_do}` : v.what_failed;
+            }
+            const next = v.content ?? v.value ?? v.text;
+            if (next === undefined)
+                return JSON.stringify(v);
+            v = next;
+            continue;
+        }
+        break;
     }
-    return String(value ?? '');
+    return typeof v === 'string' ? v : JSON.stringify(v ?? '');
+}
+/**
+ * Generic default "lessons" the failure detectors emit when no fix has been
+ * paired yet. A promoted memory whose only takeaway is one of these teaches
+ * nothing — it just costs context. We skip syncing those to the file-based
+ * memory; the specific failure still lives in the DB, so fix-pairing and
+ * evidence counting are unaffected, and once a fix enriches what_should_do
+ * (e.g. "Fix: <command>") the memory syncs normally.
+ */
+const BOILERPLATE_LESSONS = new Set([
+    'check inputs and prerequisites before retrying',
+    'check command syntax, file paths, and prerequisites before running',
+    'review error details and adjust approach',
+]);
+/** Unwrap a memory value to the object that carries the failure fields, or null. */
+function unwrapToFailureObject(value) {
+    let v = value;
+    for (let depth = 0; depth < 6; depth++) {
+        if (typeof v === 'string') {
+            const t = v.trim();
+            if (t.startsWith('{')) {
+                try {
+                    v = JSON.parse(t);
+                    continue;
+                }
+                catch {
+                    return null;
+                }
+            }
+            return null;
+        }
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            if (typeof v.what_should_do === 'string' || typeof v.what_failed === 'string')
+                return v;
+            const next = v.content ?? v.value;
+            if (next === undefined)
+                return null;
+            v = next;
+            continue;
+        }
+        return null;
+    }
+    return null;
+}
+function isBoilerplateFailure(rule) {
+    if (rule.crType !== 'failure')
+        return false;
+    const obj = unwrapToFailureObject(rule.value);
+    const wsd = obj && typeof obj.what_should_do === 'string' ? obj.what_should_do.trim().toLowerCase() : '';
+    return BOILERPLATE_LESSONS.has(wsd);
 }
 /**
  * Check if a memory key matches test data patterns.
@@ -231,12 +313,23 @@ async function handleMemorySync(input) {
         const memoryService = memory_1.MemoryService.getInstance();
         // Get top rules ranked for sync
         const rules = memoryService.getTopRulesForSync(projectId, MAX_SYNC_FILES);
-        // Filter out test data and secrets
+        // Filter out test data, secrets, and boilerplate-only failure lessons.
         const filtered = rules.filter(r => {
             if (isTestData(r.key))
                 return false;
-            const val = extractValue(r.value);
-            if (containsSecret(val))
+            // Scan the FULL raw value for secrets, not just the display gist —
+            // extractValue now returns a summary that could omit a secret buried in
+            // a non-title field.
+            let raw;
+            try {
+                raw = typeof r.value === 'string' ? r.value : JSON.stringify(r.value);
+            }
+            catch {
+                raw = String(r.value ?? '');
+            }
+            if (containsSecret(raw))
+                return false;
+            if (isBoilerplateFailure(r))
                 return false;
             return true;
         });

package/dist/hooks/precompact-preserve.js

@@ -97,29 +97,37 @@ async function handlePrecompactPreserve(input) {
         console.log(`💾 Recall: preserved ${stored} memories before context compression`);
     }
     (0, shared_1.hookLog)('precompact', `PreCompact sweep: stored ${stored} memories from ${entries.length} entries`);
-    // Reset search enforcer hook-state so Claude is forced to re-load rules
-    // after context compression. Without this, the enforcer thinks rules are
-    // still loaded even though they may have been lost during compaction.
-    resetEnforcerState(input?.session_id);
+    // Reset per-session hook-state so Claude is forced to re-load AND re-inject
+    // rules after context compression. Without this, the enforcer thinks rules
+    // are still loaded and the rule-injector thinks it already injected them —
+    // but compaction may have dropped both from context.
+    resetSessionHookState(input?.session_id);
 }
 /**
- * Delete the search enforcer's hook-state file for this session,
- * forcing a fresh load_rules gate on the next tool call.
+ * Delete this session's per-session hook-state files, forcing a fresh
+ * load_rules gate (search enforcer) and re-injection (rule-injector) on the
+ * next tool call after compaction.
  */
-function resetEnforcerState(sessionId) {
+function resetSessionHookState(sessionId) {
     if (!sessionId) {
-        (0, shared_1.hookLog)('precompact', 'No session_id — cannot reset enforcer state');
+        (0, shared_1.hookLog)('precompact', 'No session_id — cannot reset session hook-state');
         return;
     }
     const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/g, '_') || 'default';
-    const stateFile = path.join(os.homedir(), '.claude-recall', 'hook-state', `${safeId}.json`);
-    try {
-        if (fs.existsSync(stateFile)) {
-            fs.unlinkSync(stateFile);
-            (0, shared_1.hookLog)('precompact', `Reset enforcer state for session ${safeId} — rules will re-gate`);
+    const stateDir = path.join(os.homedir(), '.claude-recall', 'hook-state');
+    const stateFiles = [
+        path.join(stateDir, `${safeId}.json`), // search-enforcer gate state
+        path.join(stateDir, `rule-injector-${safeId}.json`), // rule-injector dedup set
+    ];
+    for (const stateFile of stateFiles) {
+        try {
+            if (fs.existsSync(stateFile)) {
+                fs.unlinkSync(stateFile);
+                (0, shared_1.hookLog)('precompact', `Reset hook-state ${path.basename(stateFile)} for session ${safeId}`);
+            }
+        }
+        catch (err) {
+            (0, shared_1.hookLog)('precompact', `Failed to reset ${path.basename(stateFile)}: ${err.message}`);
         }
-    }
-    catch (err) {
-        (0, shared_1.hookLog)('precompact', `Failed to reset enforcer state: ${err.message}`);
     }
 }

package/dist/hooks/rule-injector.js

@@ -24,15 +24,52 @@
  * effectiveness directly. This is the meter that replaces the broken
  * citation-detection regex.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeInjection = computeInjection;
 exports.handleRuleInjector = handleRuleInjector;
+const crypto_1 = require("crypto");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const shared_1 = require("./shared");
 const memory_1 = require("../services/memory");
 const config_1 = require("../services/config");
 const outcome_storage_1 = require("../services/outcome-storage");
 const rule_retrieval_1 = require("../services/rule-retrieval");
 const memory_tools_1 = require("../mcp/tools/memory-tools");
+const session_link_1 = require("../services/session-link");
 const TYPE_LABELS = {
     correction: 'correction',
     devops: 'devops',
@@ -81,6 +118,44 @@ function formatInjection(matches, toolName) {
         `but defer to safety and correctness if any conflict.\n${lines.join('\n')}\n` +
         `</recalled-memory>`);
 }
+/**
+ * Per-session injection dedup. The hook fires on EVERY tool call, so without
+ * this the same rule is re-injected verbatim before every Read/Bash/Edit —
+ * pure per-call token overhead, and identical repetition trains the model to
+ * tune the block out. We remember which rules were already injected this
+ * session (keyed by rule identity + a content hash, so a rule re-injects only
+ * if its content actually changed) and skip them next time.
+ */
+function injectionStateFile(sessionId) {
+    const safe = (sessionId || 'default').replace(/[^a-zA-Z0-9_-]/g, '_') || 'default';
+    return path.join((0, shared_1.hookStateDir)(), `rule-injector-${safe}.json`);
+}
+function loadInjectedSet(sessionId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(injectionStateFile(sessionId), 'utf-8'));
+        if (Array.isArray(parsed?.injected))
+            return new Set(parsed.injected);
+    }
+    catch { /* no state yet — first injection this session */ }
+    return new Set();
+}
+function saveInjectedSet(sessionId, injected) {
+    try {
+        fs.writeFileSync(injectionStateFile(sessionId), JSON.stringify({ injected: [...injected] }), 'utf-8');
+    }
+    catch { /* best-effort — dedup is an optimization, never block the call */ }
+}
+function ruleInjectionId(rule) {
+    let payload;
+    try {
+        payload = JSON.stringify(rule.value);
+    }
+    catch {
+        payload = String(rule.value);
+    }
+    const hash = (0, crypto_1.createHash)('sha1').update(payload).digest('hex').slice(0, 8);
+    return `${rule.type}:${rule.key}:${hash}`;
+}
 /**
  * Runtime-agnostic core: rank active rules against this tool call, record
  * the injections for outcome resolution, and return the formatted context
@@ -88,7 +163,7 @@ function formatInjection(matches, toolName) {
  * runtime (Claude Code wants a hookSpecificOutput JSON envelope; Kiro adds
  * raw stdout to context).
  */
-async function computeInjection(toolName, toolInput, toolUseId) {
+async function computeInjection(toolName, toolInput, toolUseId, sessionId = 'default') {
     if (!toolName)
         return null;
     // Skip the hook for our own tools so we don't recursively inject rules
@@ -99,6 +174,10 @@ async function computeInjection(toolName, toolInput, toolUseId) {
     }
     const projectId = config_1.ConfigService.getInstance().getProjectId();
     const memoryService = memory_1.MemoryService.getInstance();
+    // Record the harness session id for this project so the MCP server can
+    // correlate its own logs with hook-side state (#6). This hook runs on every
+    // tool call with the harness session_id, so the link stays fresh.
+    (0, session_link_1.writeHarnessSessionLink)(sessionId, projectId);
     // Fetch all active rules for this project. We pass them all to the ranker
     // because the ranking function is fast and we want sticky rules to surface
     // even when token overlap is low.
@@ -126,10 +205,17 @@ async function computeInjection(toolName, toolInput, toolUseId) {
         (0, shared_1.hookLog)('rule-injector', `No relevant rules for ${toolName} (scanned ${allRules.length})`);
         return null;
     }
+    // Drop rules already injected this session (unless their content changed).
+    const injected = loadInjectedSet(sessionId);
+    const freshMatches = matches.filter(m => !injected.has(ruleInjectionId(m.rule)));
+    if (freshMatches.length === 0) {
+        (0, shared_1.hookLog)('rule-injector', `All ${matches.length} matched rule(s) already injected this session (${sessionId}) — skipping`);
+        return null;
+    }
     // Record each injection so PostToolUse can resolve it with the outcome
     try {
         const outcomeStorage = outcome_storage_1.OutcomeStorage.getInstance();
-        for (const m of matches) {
+        for (const m of freshMatches) {
             outcomeStorage.recordRuleInjection({
                 rule_key: m.rule.key,
                 tool_name: toolName,
@@ -144,12 +230,16 @@ async function computeInjection(toolName, toolInput, toolUseId) {
         // Non-critical — failure to record shouldn't block the injection itself
         (0, shared_1.hookLog)('rule-injector', `Failed to record injections: ${err.message}`);
     }
-    (0, shared_1.hookLog)('rule-injector', `Injected ${matches.length} rule(s) for ${toolName} (top score=${matches[0].score.toFixed(3)})`);
-    return formatInjection(matches, toolName);
+    // Mark them injected so they don't repeat on the next tool call.
+    for (const m of freshMatches)
+        injected.add(ruleInjectionId(m.rule));
+    saveInjectedSet(sessionId, injected);
+    (0, shared_1.hookLog)('rule-injector', `Injected ${freshMatches.length} rule(s) for ${toolName} (top score=${freshMatches[0].score.toFixed(3)})`);
+    return formatInjection(freshMatches, toolName);
 }
 async function handleRuleInjector(input) {
     try {
-        const additionalContext = await computeInjection(input?.tool_name ?? '', input?.tool_input ?? {}, input?.tool_use_id ?? '');
+        const additionalContext = await computeInjection(input?.tool_name ?? '', input?.tool_input ?? {}, input?.tool_use_id ?? '', input?.session_id ?? 'default');
         if (!additionalContext) {
             // Nothing to inject — print empty JSON so CC parses it cleanly
             process.stdout.write('{}\n');

package/dist/memory/storage.js

@@ -44,11 +44,23 @@ const path = __importStar(require("path"));
 const test_pollution_1 = require("../services/test-pollution");
 class MemoryStorage {
     constructor(dbPath) {
+        /**
+         * Whether the FTS5 mirror table + triggers are present and usable. Set once
+         * during setupFts(); when false, searchByContext always uses the LIKE path
+         * regardless of retrievalMode (self-built/exotic SQLite may lack FTS5).
+         */
+        this.ftsAvailable = false;
+        this.retrievalMode = (process.env.CLAUDE_RECALL_RETRIEVAL || 'like').trim().toLowerCase();
         this.db = new better_sqlite3_1.default(dbPath);
         // Enable WAL mode for better concurrency and to ensure writes are visible
         this.db.pragma('journal_mode = WAL');
         // Ensure changes are synced to disk
         this.db.pragma('synchronous = NORMAL');
+        // Cap WAL growth: after each checkpoint SQLite truncates the -wal file
+        // back to this ceiling, so it can't balloon (a stuck reader once left it
+        // at 34MB) and linger across restarts. Paired with a TRUNCATE checkpoint
+        // in close().
+        this.db.pragma('journal_size_limit = 8388608'); // 8 MB
         this.initialize();
     }
     initialize() {
@@ -245,6 +257,85 @@ class MemoryStorage {
             console.error('⚠️  Schema migration error:', error);
             // Don't throw - let the database continue with existing schema
         }
+        // FTS5 lexical index (v0.38.0+). Separate from the try block above so a
+        // FTS5-less SQLite build degrades to the LIKE path instead of aborting the
+        // whole migration.
+        this.setupFts();
+    }
+    /**
+     * Create the FTS5 mirror of memories.value (external-content table kept in
+     * sync by triggers) and backfill it once. Feature-detected: if this SQLite
+     * build lacks FTS5, ftsAvailable stays false and retrieval uses LIKE.
+     *
+     * The table + triggers are derived, redundant data — dropping them reverts to
+     * LIKE with zero risk to `memories`. Triggers do the syncing in SQL so every
+     * writer (upsert, INSERT OR REPLACE, delete, import) stays covered without a
+     * TypeScript write-path change.
+     */
+    setupFts() {
+        try {
+            // Was the mirror already present before this startup? If so, the triggers
+            // below have been maintaining it and we must NOT re-backfill. We cannot
+            // gauge this from `count(*) FROM memories_fts`: for an external-content
+            // table that count proxies to the content table, so it reads non-zero
+            // even when the index is empty (the legacy-upgrade bug).
+            const existed = !!this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='memories_fts'").get();
+            this.db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+          value,
+          content='memories',
+          content_rowid='id'
+        );
+        CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+          INSERT INTO memories_fts(rowid, value) VALUES (new.id, new.value);
+        END;
+        CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+          INSERT INTO memories_fts(memories_fts, rowid, value) VALUES('delete', old.id, old.value);
+        END;
+        CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+          INSERT INTO memories_fts(memories_fts, rowid, value) VALUES('delete', old.id, old.value);
+          INSERT INTO memories_fts(rowid, value) VALUES (new.id, new.value);
+        END;
+      `);
+            // First time the mirror is created (fresh DB or legacy upgrade): backfill
+            // the index from existing rows via FTS5's canonical 'rebuild' command —
+            // the correct way to populate an external-content index from content. A
+            // single scan, trivial at the 10k row cap. Skipped on later startups.
+            if (!existed) {
+                this.db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+            }
+            this.ftsAvailable = true;
+        }
+        catch (error) {
+            // FTS5 unavailable (self-built SQLite without the extension) — leave the
+            // flag off; searchByContext uses the LIKE path everywhere.
+            this.ftsAvailable = false;
+        }
+    }
+    /**
+     * Turn extracted keywords into a safe FTS5 MATCH expression: each term is
+     * stripped to word characters, wrapped as a quoted prefix token, and
+     * OR-joined — e.g. `"kaggle"* OR "submission"*`. Prefix (`*`) mimics the
+     * substring reach of the old LIKE filter ("auth" still matches
+     * "authentication"). Returns '' when nothing usable remains, so the caller
+     * falls back to LIKE rather than issuing an empty MATCH.
+     *
+     * Sanitization is mandatory: bare AND/OR/NEAR, quotes, hyphens and `*` are
+     * FTS5 operators and throw SQLITE_ERROR on malformed input.
+     */
+    sanitizeFtsMatch(keywords) {
+        const terms = [];
+        for (const kw of keywords) {
+            // Keep only letters/digits/space; collapse everything else (quotes,
+            // hyphens, parens, operators) to spaces, then take the first token.
+            const cleaned = String(kw).toLowerCase().replace(/[^a-z0-9\s]/g, ' ').trim();
+            if (!cleaned)
+                continue;
+            const token = cleaned.split(/\s+/)[0];
+            if (token)
+                terms.push(`"${token}"*`);
+        }
+        return [...new Set(terms)].join(' OR ');
     }
     /**
      * Compute a SHA-256 content hash from the meaningful fields of a memory.
@@ -543,6 +634,24 @@ class MemoryStorage {
             throw new Error('searchByContext requires context.project_id or context.includeAllProjects=true. ' +
                 'Calling without either would silently return memories from all projects.');
         }
+        // FTS5 lexical path (opt-in). Only when a keyword filter would otherwise be
+        // applied — empty/stopword queries keep the LIKE branch's "return all
+        // scoped rows" behaviour so load_rules-style calls are unaffected.
+        if (this.retrievalMode === 'fts' &&
+            this.ftsAvailable &&
+            context.keywords &&
+            context.keywords.length > 0) {
+            const matchExpr = this.sanitizeFtsMatch(context.keywords);
+            if (matchExpr) {
+                try {
+                    return this.searchByContextFts(context, matchExpr);
+                }
+                catch {
+                    // Malformed MATCH or FTS error — never crash retrieval; fall through
+                    // to the LIKE path below.
+                }
+            }
+        }
         let query = 'SELECT * FROM memories WHERE 1=1';
         const params = [];
         if (context.project_id) {
@@ -590,6 +699,48 @@ class MemoryStorage {
         const rows = stmt.all(...params);
         return rows.map(row => this.rowToMemory(row));
     }
+    /**
+     * FTS5 candidate fetch: MATCH replaces the LIKE keyword filter while every
+     * other predicate (scope, file_path, type) is preserved verbatim. Attaches a
+     * normalized bm25Score ∈ [0,1] to each row (1 = best match in this set) for
+     * the retrieval-layer fusion. Throws on a malformed MATCH — the caller
+     * catches and falls back to LIKE.
+     */
+    searchByContextFts(context, matchExpr) {
+        let query = `SELECT m.*, bm25(memories_fts) AS bm25_rank
+       FROM memories_fts
+       JOIN memories m ON m.id = memories_fts.rowid
+       WHERE memories_fts MATCH ?`;
+        const params = [matchExpr];
+        if (context.project_id) {
+            query += ' AND (m.project_id = ? OR m.scope = ? OR m.project_id IS NULL)';
+            params.push(context.project_id, 'universal');
+        }
+        if (context.file_path) {
+            query += ' AND m.file_path = ?';
+            params.push(context.file_path);
+        }
+        if (context.type) {
+            query += ' AND m.type = ?';
+            params.push(context.type);
+        }
+        // SQLite bm25() is negative; more-negative = better, so ascending is best-first.
+        query += ' ORDER BY bm25_rank';
+        const rows = this.db.prepare(query).all(...params);
+        if (rows.length === 0)
+            return [];
+        // Min-max normalize -bm25 (so higher = better) across the candidate set.
+        const raws = rows.map(r => -r.bm25_rank);
+        const min = Math.min(...raws);
+        const max = Math.max(...raws);
+        const span = max - min;
+        return rows.map((row, i) => {
+            const memory = this.rowToMemory(row);
+            // Degenerate set (single row, or all equally ranked) → all are the best match.
+            memory.bm25Score = span > 0 ? (raws[i] - min) / span : 1.0;
+            return memory;
+        });
+    }
     deleteByKey(key) {
         const stmt = this.db.prepare('DELETE FROM memories WHERE key = ?');
         const result = stmt.run(key);
@@ -1055,6 +1206,16 @@ class MemoryStorage {
         return this.db;
     }
     close() {
+        // Flush the WAL into the main DB and truncate the -wal/-shm files so they
+        // don't linger at tens of MB after the process exits. Best-effort: a
+        // checkpoint can fail if another connection still holds a read lock, in
+        // which case db.close() below still runs an implicit passive checkpoint.
+        try {
+            this.db.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        catch {
+            // ignore — proceed to close regardless
+        }
         this.db.close();
     }
 }

package/dist/services/search-monitor.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchMonitor = void 0;
 const logging_1 = require("./logging");
+const config_1 = require("./config");
+const session_link_1 = require("./session-link");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -58,6 +60,20 @@ class SearchMonitor {
             fs.mkdirSync(dir, { recursive: true });
         }
     }
+    /**
+     * Best-effort lookup of the harness session_id for this process's project.
+     * A hook records it (see session-link.ts); returns undefined if none has run
+     * yet or on any error — this must never disrupt a search.
+     */
+    resolveHarnessSessionId() {
+        try {
+            const projectId = config_1.ConfigService.getInstance().getProjectId();
+            return (0, session_link_1.readHarnessSessionLink)(projectId) ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     recordSearch(query, resultCount, sessionId, source, context) {
         if (!this.monitoringEnabled)
             return;
@@ -66,6 +82,7 @@ class SearchMonitor {
             query,
             resultCount,
             sessionId,
+            harnessSessionId: this.resolveHarnessSessionId(),
             source,
             context
         };