feat: multi-path retrieval with RRF fusion (v2.3)

Search now runs 3 retrieval paths in parallel and merges with Reciprocal
Rank Fusion — dramatically improving recall for exact names, technical
terms, and entity-connected memories.

New retrieval paths:
- BM25 keyword search (Postgres tsvector/GIN or SQLite FTS5)
- BFS spreading activation through entity relationship graph
- Results merged with RRF: score(d) = sum(1/(k+rank)) across paths

New files:
- api/src/services/rrf.js — RRF fusion algorithm (13 unit tests)
- api/src/services/keyword-search.js — BM25/FTS keyword search service
- api/src/services/graph-search.js — BFS entity graph retrieval
- api/scripts/backfill-keyword-index.js — migration for existing memories
- api/tests/rrf.test.js — comprehensive RRF test suite

Modified:
- GET /memory/search runs all 3 paths via Promise.all, fuses with RRF
- POST /memory indexes content for keyword search on write
- DELETE and supersede paths deactivate keyword index entries
- Postgres: memory_search table + tsvector trigger + co-occurrence indexes
- SQLite: FTS5 virtual table for keyword search fallback
- Qdrant: getPoints() batch retrieval for RRF payload hydration
- Stats endpoint shows retrieval path status and keyword index count
- MCP brain_search description updated, format=full shows retrieval_sources

Feature-flagged: MULTI_PATH_SEARCH=true (default on)
Configurable: RRF_K, GRAPH_SEARCH_MAX_DEPTH, GRAPH_SEARCH_DECAY

Inspired by vectorize-io/hindsight's 4-way parallel search architecture.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Skiipy11

.env.example

@@ -74,6 +74,15 @@ DECAY_FACTOR=0.98
 # WEBHOOK_URLS=https://n8n.example.com/webhook/brain  # Comma-separated webhook URLs for memory events
 # WEBHOOK_EVENTS=store,supersede,delete               # Which events trigger notifications (default: all)
 
+# --- Multi-Path Retrieval ---
+# Enables parallel vector + keyword (BM25) + graph (entity BFS) search, merged with Reciprocal Rank Fusion.
+# Requires: structured store (postgres recommended for full BM25, sqlite for FTS5 fallback)
+# MULTI_PATH_SEARCH=true           # Enable/disable multi-path retrieval (default: true)
+# RRF_K=60                         # RRF smoothing constant. Range 50-100. Higher = more equal weighting (default: 60)
+# GRAPH_SEARCH_MAX_DEPTH=2         # Max BFS hops through entity graph (default: 2)
+# GRAPH_SEARCH_DECAY=0.8           # Activation decay per hop (default: 0.8)
+# GRAPH_SEARCH_CAUSAL_BOOST=2.0    # Boost for typed entity relationships (uses, works_on, etc.) vs co_occurrence (default: 2.0)
+
 # --- MCP Server Timeouts ---
 # BRAIN_MCP_TIMEOUT=15000          # Default timeout for MCP→API calls in ms (default: 15000)
 # BRAIN_MCP_CONSOLIDATION_TIMEOUT=120000  # Timeout for sync consolidation calls in ms (default: 120000)

README.md

@@ -30,7 +30,11 @@
 
 Born from a production setup where [OpenClaw](https://github.com/openclaw/openclaw) agents, Claude Code, and n8n workflows needed to share memory across separate machines. Nothing existed that did this well, so we built it.
 
-### What's New in v2.2
+### What's New in v2.3
+
+- **Multi-Path Retrieval with RRF Fusion** — Search now runs three retrieval paths in parallel: vector (semantic similarity), keyword (BM25 full-text via Postgres tsvector or SQLite FTS5), and graph (BFS spreading activation through entity relationships). Results are merged using Reciprocal Rank Fusion (RRF). Exact names and technical terms now surface reliably even when embeddings miss them. Entity relationships that were previously stored but unused are now a first-class retrieval signal. Feature-flagged via `MULTI_PATH_SEARCH=true` (default on). Use `format=full` in `brain_search` to see which paths contributed to each result. Includes a backfill script (`scripts/backfill-keyword-index.js`) for existing memories.
+
+### What Was New in v2.2
 
 - **Noise-Free Entity Extraction** — v2.2 filters out CSS properties, code identifiers, shell commands, sentence fragments, French prose, and generic phrases. Pattern-based filtering with 50+ generic noun/adjective blocklists. Includes a retroactive cleanup script (`scripts/cleanup-garbage-entities.js`) to purge existing noise.
 - **Per-Client Knowledge Base** — Fingerprint-based client identification with accent normalization. One tool call (`brain_client`) returns everything known about a client: brand, strategy, meetings, content, technical details, relationships. Fuzzy name resolution ("JL" resolves to "jetloans").

api/scripts/backfill-keyword-index.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Backfill keyword search index from existing Qdrant memories.
+ * Scrolls all active points and inserts their text into the memory_search table
+ * for BM25/full-text keyword retrieval.
+ *
+ * Usage: node api/scripts/backfill-keyword-index.js
+ * Requires: .env configured with QDRANT_URL, STRUCTURED_STORE (postgres|sqlite)
+ */
+
+try { await import('dotenv/config'); } catch (e) { /* dotenv not needed in Docker */ }
+import { initQdrant, scrollPoints } from '../src/services/qdrant.js';
+import { initStore, _getStoreInstance, getBackendType } from '../src/services/stores/interface.js';
+import { initKeywordSearch, indexMemory, isKeywordSearchAvailable } from '../src/services/keyword-search.js';
+import { initEmbeddings } from '../src/services/embedders/interface.js';
+
+async function backfill() {
+  console.log('[backfill] Starting keyword index backfill...');
+
+  // Initialize services
+  await initEmbeddings();
+  await initQdrant();
+  await initStore();
+  initKeywordSearch(_getStoreInstance(), getBackendType());
+
+  if (!isKeywordSearchAvailable()) {
+    console.error('[backfill] Keyword search not available. Need postgres or sqlite backend.');
+    process.exit(1);
+  }
+
+  let processed = 0;
+  let indexed = 0;
+  let skipped = 0;
+  let errors = 0;
+  let offset = null;
+
+  while (true) {
+    const result = await scrollPoints({ active: true }, 100, offset);
+    const points = result.points || [];
+
+    if (points.length === 0) break;
+
+    for (const point of points) {
+      processed++;
+      const p = point.payload;
+
+      if (!p || !p.text) {
+        skipped++;
+        continue;
+      }
+
+      try {
+        await indexMemory(point.id, p.text, {
+          client_id: p.client_id || 'global',
+          source_agent: p.source_agent || null,
+          type: p.type || null,
+        });
+        indexed++;
+      } catch (e) {
+        errors++;
+        if (errors <= 5) {
+          console.error(`[backfill] Error indexing ${point.id}: ${e.message}`);
+        }
+      }
+
+      if (processed % 100 === 0) {
+        console.log(`[backfill] Progress: ${processed} processed, ${indexed} indexed, ${skipped} skipped, ${errors} errors`);
+      }
+    }
+
+    offset = result.next_page_offset;
+    if (!offset) break;
+  }
+
+  console.log(`[backfill] Complete: ${processed} processed, ${indexed} indexed, ${skipped} skipped, ${errors} errors`);
+  process.exit(0);
+}
+
+backfill().catch(err => {
+  console.error('[backfill] Fatal error:', err);
+  process.exit(1);
+});

api/src/index.js

@@ -13,7 +13,8 @@ import { exportRouter } from './routes/export.js';
 import { graphRouter } from './routes/graph.js';
 import { initQdrant, ensureEntityIndex } from './services/qdrant.js';
 import { initEmbeddings } from './services/embedders/interface.js';
-import { initStore, isEntityStoreAvailable, loadAllAliases } from './services/stores/interface.js';
+import { initStore, isEntityStoreAvailable, loadAllAliases, _getStoreInstance, getBackendType } from './services/stores/interface.js';
+import { initKeywordSearch } from './services/keyword-search.js';
 import { initClientResolver } from './services/client-resolver.js';
 import { initLLM } from './services/llm/interface.js';
 import { runConsolidation } from './services/consolidation.js';
@@ -69,6 +70,9 @@ async function start() {
     // Initialize structured storage backend
     await initStore();
 
+    // Initialize keyword search (BM25 via Postgres tsvector or SQLite FTS5)
+    initKeywordSearch(_getStoreInstance(), getBackendType());
+
     // Initialize client fingerprint resolver (Baserow → fuzzy matcher)
     await initClientResolver();
 

api/src/routes/memory.js

@@ -3,7 +3,7 @@ import crypto from 'crypto';
 import { embed } from '../services/embedders/interface.js';
 import {
   upsertPoint, searchPoints, updatePointPayload,
-  findByPayload, computeEffectiveConfidence, getPoint,
+  findByPayload, computeEffectiveConfidence, getPoint, getPoints,
 } from '../services/qdrant.js';
 import {
   createEvent, upsertFact, upsertStatus, listEvents, listFacts, listStatuses, isStoreAvailable,
@@ -13,6 +13,11 @@ import { scrubCredentials, scrubObject } from '../services/scrub.js';
 import { extractEntities, linkExtractedEntities } from '../services/entities.js';
 import { validateMemoryInput, MAX_OBSERVED_BY } from '../middleware/validate.js';
 import { dispatchNotification } from '../services/notifications.js';
+import { isKeywordSearchAvailable, indexMemory, deactivateMemory, keywordSearch } from '../services/keyword-search.js';
+import { isGraphSearchAvailable, graphSearch } from '../services/graph-search.js';
+import { reciprocalRankFusion } from '../services/rrf.js';
+
+const MULTI_PATH_SEARCH = process.env.MULTI_PATH_SEARCH !== 'false'; // default: true
 import { getClientResolver } from '../services/client-resolver.js';
 
 export const memoryRouter = Router();
@@ -127,6 +132,7 @@ memoryRouter.post('/', async (req, res) => {
           superseded_by: pointId,
           superseded_at: now,
         });
+        deactivateMemory(matches[0].id).catch(() => {});
         dispatchNotification('memory_superseded', { id: matches[0].id, ...matches[0].payload });
       }
     } else if (type === 'status' && req.body.subject) {
@@ -139,6 +145,7 @@ memoryRouter.post('/', async (req, res) => {
           superseded_by: pointId,
           superseded_at: now,
         });
+        deactivateMemory(matches[0].id).catch(() => {});
         dispatchNotification('memory_superseded', { id: matches[0].id, ...matches[0].payload });
       }
     }
@@ -183,6 +190,15 @@ memoryRouter.post('/', async (req, res) => {
     const vector = await embed(cleanContent, 'store');
     await upsertPoint(pointId, vector, payload);
 
+    // Index in keyword search (fire-and-forget)
+    if (isKeywordSearchAvailable()) {
+      indexMemory(pointId, cleanContent, {
+        client_id: client_id || 'global',
+        source_agent,
+        type,
+      }).catch(e => console.error('[memory:keyword-index]', e.message));
+    }
+
     // Dispatch webhook notification for new memory
     dispatchNotification('memory_stored', { id: pointId, ...payload });
 
@@ -248,24 +264,24 @@ memoryRouter.post('/', async (req, res) => {
   }
 });
 
-// GET /memory/search — Semantic search via Qdrant
+// GET /memory/search — Multi-path retrieval with RRF fusion
+// Paths: vector (semantic), keyword (BM25), graph (entity BFS)
 memoryRouter.get('/search', async (req, res) => {
   try {
     const { q, type, source_agent, client_id, category, limit, include_superseded, entity, format } = req.query;
     const isCompact = format === 'compact';
+    const isFull = format === 'full';
+    const maxResults = Math.min(parseInt(limit) || 10, 100);
 
     if (!q) {
       return res.status(400).json({ error: 'Missing required query parameter: q' });
     }
 
-    const vector = await embed(q, 'search');
-
     const filter = {};
     if (type) filter.type = type;
     if (source_agent) filter.source_agent = source_agent;
     if (client_id) filter.client_id = client_id;
     if (category) filter.category = category;
-    // By default, only return active memories (not superseded)
     if (include_superseded !== 'true') filter.active = true;
 
     // Entity filter — resolve alias to canonical name, then filter via Qdrant payload
@@ -281,25 +297,99 @@ memoryRouter.get('/search', async (req, res) => {
       nestedFilters.push({ arrayField: 'entities', key: 'name', value: entityName });
     }
 
-    const rawResults = await searchPoints(vector, filter, Math.min(parseInt(limit) || 10, 100), nestedFilters);
+    // --- Multi-path retrieval ---
+    const useMultiPath = MULTI_PATH_SEARCH && !entity; // entity filter is Qdrant-only
+    const fetchLimit = useMultiPath ? Math.min(maxResults * 2, 50) : maxResults;
+
+    // Always run vector search
+    const vectorPromise = embed(q, 'search').then(vector =>
+      searchPoints(vector, filter, fetchLimit, nestedFilters)
+    );
+
+    // Run keyword + graph in parallel (only if multi-path enabled)
+    const keywordPromise = (useMultiPath && isKeywordSearchAvailable())
+      ? keywordSearch(q, filter, fetchLimit).catch(e => {
+          console.error('[memory:keyword-search]', e.message);
+          return [];
+        })
+      : Promise.resolve([]);
+
+    const graphPromise = (useMultiPath && isGraphSearchAvailable())
+      ? graphSearch(q, filter, Math.min(maxResults, 20)).catch(e => {
+          console.error('[memory:graph-search]', e.message);
+          return [];
+        })
+      : Promise.resolve([]);
+
+    const [vectorResults, keywordResults, graphResults] = await Promise.all([
+      vectorPromise, keywordPromise, graphPromise,
+    ]);
+
+    // --- Build result set ---
+    let finalResults;
+    const retrievalSources = {};
+
+    if (useMultiPath && (keywordResults.length > 0 || graphResults.length > 0)) {
+      // Build ranked lists for RRF
+      const rankedLists = [
+        vectorResults.map(r => ({ id: r.id, source: 'vector' })),
+      ];
+      if (keywordResults.length > 0) {
+        rankedLists.push(keywordResults.map(r => ({ id: r.memory_id, source: 'keyword' })));
+      }
+      if (graphResults.length > 0) {
+        rankedLists.push(graphResults.map(r => ({ id: r.memory_id, source: 'graph' })));
+      }
+
+      const fused = reciprocalRankFusion(rankedLists);
+      const topFused = fused.slice(0, maxResults);
+
+      // Track which sources contributed to each result
+      for (const f of topFused) {
+        retrievalSources[f.id] = f.sources;
+      }
+
+      // Build payload map from vector results (already have full payloads)
+      const payloadMap = new Map();
+      for (const r of vectorResults) {
+        payloadMap.set(r.id, { id: r.id, score: r.score, payload: r.payload });
+      }
+
+      // Fetch payloads for keyword/graph hits not in vector results
+      const missingIds = topFused.map(f => f.id).filter(id => !payloadMap.has(id));
+      if (missingIds.length > 0) {
+        try {
+          const fetched = await getPoints(missingIds);
+          for (const pt of fetched) {
+            payloadMap.set(pt.id, { id: pt.id, score: 0, payload: pt.payload });
+          }
+        } catch (e) {
+          console.error('[memory:search] Batch fetch failed:', e.message);
+        }
+      }
+
+      // Assemble results in RRF order
+      finalResults = topFused
+        .map(f => payloadMap.get(f.id))
+        .filter(Boolean);
+    } else {
+      // Single-path: vector only
+      finalResults = vectorResults.slice(0, maxResults);
+    }
 
     // Apply confidence decay + access-weighted ranking
-    // Memories that get used more are more valuable — self-curating brain
     const COMPACT_MAX = 200;
-    const results = rawResults.map(r => {
+    const results = finalResults.map(r => {
       const effectiveConfidence = computeEffectiveConfidence(r.payload);
       const p = r.payload;
-
-      // Access boost: log(access_count + 1) gives diminishing returns
-      // 0 accesses = 1.0x, 1 = 1.3x, 5 = 1.8x, 20 = 2.3x, 100 = 2.7x
       const accessBoost = 1 + (0.3 * Math.log2((p.access_count || 0) + 1));
-      const effectiveScore = +(r.score * effectiveConfidence * accessBoost).toFixed(4);
+      const effectiveScore = +(((r.score || 0.5) * effectiveConfidence * accessBoost)).toFixed(4);
 
       if (isCompact) {
         const text = p.text || '';
         return {
           id: r.id,
-          score: +r.score.toFixed(4),
+          score: +(r.score || 0).toFixed(4),
           effective_score: effectiveScore,
           type: p.type,
           content: text.length > COMPACT_MAX ? text.slice(0, COMPACT_MAX) + '...' : text,
@@ -310,22 +400,28 @@ memoryRouter.get('/search', async (req, res) => {
         };
       }
 
-      return {
+      const base = {
         id: r.id,
-        score: r.score,
+        score: r.score || 0,
         confidence: effectiveConfidence,
         effective_score: effectiveScore,
         ...p,
       };
+
+      // In full format, show which retrieval paths contributed
+      if (isFull && retrievalSources[r.id]) {
+        base.retrieval_sources = retrievalSources[r.id];
+      }
+
+      return base;
     });
 
-    // Re-sort by effective_score (now includes access weight)
+    // Re-sort by effective_score
     results.sort((a, b) => b.effective_score - a.effective_score);
 
     // Async: increment access_count and update last_accessed_at for returned results
     const pointIds = results.map(r => r.id);
     if (pointIds.length > 0) {
-      // Fire and forget — don't slow down the response
       Promise.resolve().then(async () => {
         try {
           const now = new Date().toISOString();
@@ -341,11 +437,25 @@ memoryRouter.get('/search', async (req, res) => {
       });
     }
 
-    res.json({
+    const response = {
       query: q,
       count: results.length,
       results,
-    });
+    };
+
+    // In full format, add retrieval metadata
+    if (isFull && useMultiPath) {
+      response.retrieval = {
+        multi_path: true,
+        paths: {
+          vector: vectorResults.length,
+          keyword: keywordResults.length,
+          graph: graphResults.length,
+        },
+      };
+    }
+
+    res.json(response);
   } catch (err) {
     console.error('[memory:search] Error:', err.message);
     res.status(500).json({ error: err.message });
@@ -426,6 +536,7 @@ memoryRouter.delete('/:id', async (req, res) => {
       deletion_reason: reason || null,
     });
 
+    deactivateMemory(id).catch(() => {});
     dispatchNotification('memory_deleted', { id, ...point.payload });
 
     console.log(`[memory:delete] Memory ${id} soft-deleted by ${req.authenticatedAgent || 'admin'}${reason ? ': ' + reason : ''}`);