π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(memory): #2061 ADR-125 Phase 5 β graceful retrieval degradation + FTS5 keyword fallback
ruv8773fcffdf78
diff --git a/v3/@claude-flow/memory/src/agentdb-adapter.ts b/v3/@claude-flow/memory/src/agentdb-adapter.tsindex 7d0e94870b..793e2498ab 100644--- a/v3/@claude-flow/memory/src/agentdb-adapter.ts+++ b/v3/@claude-flow/memory/src/agentdb-adapter.ts@@ -744,7 +744,13 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {}/**- * Semantic search by content string+ * Semantic search by content string.+ *+ * ADR-125 Phase 5 β degrades gracefully when the embedding generator is+ * unavailable. Instead of throwing, emits `health:embedder` with+ * `status: 'degraded'` and falls back to {@link searchKeyword} so the+ * memory subsystem remains usable when `@claude-flow/embeddings` is+ * unreachable (per ADR-124's lazy/degrade posture).*/async semanticSearch(content: string,@@ -752,11 +758,60 @@ export class AgentDBAdapter extends EventEmitter implements IMemoryBackend {threshold?: number): Promise<SearchResult[]> {if (!this.config.embeddingGenerator) {- throw new Error('Embedding generator not configured');+ this.emit('health:embedder', { status: 'degraded', reason: 'no-generator' });+ return this.searchKeyword(content, { k, threshold } as SearchOptions);+ }++ try {+ const embedding = await this.config.embeddingGenerator(content);+ return this.search(embedding, { k, threshold });+ } catch (err) {+ this.emit('health:embedder', {+ status: 'degraded',+ reason: err instanceof Error ? err.message : String(err),+ });+ return this.searchKeyword(content, { k, threshold } as SearchOptions);+ }+ }++ /**+ * Keyword search β in-memory token-overlap ranking against the+ * `entries` map. Used as a fallback when the embedder is unavailable+ * and as the "sparse" arm of the hybridSearch controller.+ *+ * Falls back to the SqlJs / SQLite backend FTS5 path when a backend is+ * wired that exposes a `searchKeyword` method. The AgentDBAdapter itself+ * keeps the implementation cheap and dependency-free.+ *+ * @internal ADR-125 Phase 5+ */+ async searchKeyword(+ query: string,+ options: SearchOptions = { k: 10 } as SearchOptions+ ): Promise<SearchResult[]> {+ const k = options.k ?? 10;+ const tokens = tokenize(query);+ if (tokens.size === 0) return [];++ const scored: SearchResult[] = [];+ for (const entry of this.entries.values()) {+ const entryTokens = tokenize(entry.content);+ let overlap = 0;+ for (const t of tokens) if (entryTokens.has(t)) overlap += 1;+ if (overlap === 0) continue;+ // Simple token-overlap ratio in [0,1]. Adequate for fallback ranking.+ const score = overlap / Math.max(tokens.size, 1);+ if (options.threshold && score < options.threshold) continue;+ // Apply additional filters if provided+ if (options.filters) {+ const filtered = this.applyFilters([entry], options.filters);+ if (filtered.length === 0) continue;+ }+ scored.push({ entry, score, distance: 1 - score });}- const embedding = await this.config.embeddingGenerator(content);- return this.search(embedding, { k, threshold });+ scored.sort((a, b) => b.score - a.score);+ return scored.slice(0, k);}// ===== Private Methods =====@@ -1228,4 +1283,26 @@ interface PersistedMeta {tagIndex: Record<string, string[]>;}+// ADR-125 Phase 5 β minimal tokenizer for the in-memory keyword fallback.+// Mirrors the shape used in `smart-retrieval.ts` but is duplicated here so the+// adapter has no dependency on the retrieval layer.+const STOPWORDS = new Set([+ 'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'any', 'can',+ 'her', 'was', 'one', 'our', 'out', 'day', 'get', 'has', 'him', 'his',+ 'how', 'man', 'new', 'now', 'old', 'see', 'two', 'way', 'who', 'boy',+ 'did', 'its', 'let', 'put', 'say', 'she', 'too', 'use', 'with', 'this',+ 'that', 'have', 'from', 'they', 'will', 'been', 'were', 'what', 'when',+ 'your',+]);++function tokenize(text: string): Set<string> {+ return new Set(+ text+ .toLowerCase()+ .replace(/[^\w\s]/g, ' ')+ .split(/\s+/)+ .filter((t) => t.length > 2 && !STOPWORDS.has(t))+ );+}+export default AgentDBAdapter;diff --git a/v3/@claude-flow/memory/src/controller-registry.ts b/v3/@claude-flow/memory/src/controller-registry.tsindex 7a08330f04..b4044674b6 100644--- a/v3/@claude-flow/memory/src/controller-registry.ts+++ b/v3/@claude-flow/memory/src/controller-registry.ts@@ -601,8 +601,13 @@ export class ControllerRegistry extends EventEmitter {case 'semanticRouter':return this.agentdb !== null;- // Optional controllers+ // ADR-125 Phase 5 β hybridSearch auto-enables when a MemoryService is+ // registered. Replaces the prior "placeholder, require explicit enable"+ // posture.case 'hybridSearch':+ return !!this.config.memoryService;++ // Optional controllerscase 'agentMemoryScope':case 'sonaTrajectory':case 'federatedSession':@@ -705,9 +710,76 @@ export class ControllerRegistry extends EventEmitter {return cache;}- case 'hybridSearch':- // BM25 hybrid search β placeholder for future implementation- return null;+ case 'hybridSearch': {+ // ADR-125 Phase 5 β real RRF + MMR hybrid search.+ // Calls semanticSearch() (which degrades gracefully when embedder is+ // unavailable) AND searchKeyword() independently, fuses via RRF, then+ // diversifies via MMR (lambda=0.7).+ const memSvc = this.config.memoryService;+ if (!memSvc) return null;+ const adapter = typeof memSvc.getAdapter === 'function' ? memSvc.getAdapter() : null;+ if (!adapter) return null;++ const { applyRRF, applyMMR } = await import('./smart-retrieval.js');++ return {+ /**+ * Run a fused hybrid search.+ * @param query Free-form query string.+ * @param opts.limit Final result count (default 10).+ * @param opts.fanOutK Per-arm fanout before fusion (default = limit * 3).+ * @param opts.mmrLambda MMR relevance/diversity balance (default 0.7).+ */+ search: async (+ query: string,+ opts: { limit?: number; fanOutK?: number; mmrLambda?: number } = {}+ ) => {+ const limit = opts.limit ?? 10;+ const fanOutK = opts.fanOutK ?? Math.max(limit * 3, 20);+ const mmrLambda = opts.mmrLambda ?? 0.7;++ // Dense arm β may internally fall back to keyword if embedder is+ // missing, but that's still a valid signal to fuse.+ let dense: any[] = [];+ try {+ dense = await adapter.semanticSearch(query, fanOutK);+ } catch {+ dense = [];+ }++ // Sparse arm β FTS5 / keyword search.+ let sparse: any[] = [];+ try {+ sparse = await adapter.searchKeyword(query, { k: fanOutK });+ } catch {+ sparse = [];+ }++ // Adapt SearchResult[] β SearchCandidate[] expected by RRF+ const toCands = (results: any[]) =>+ results.map((r: any) => ({+ id: r.entry.id,+ key: r.entry.key,+ content: r.entry.content,+ namespace: r.entry.namespace,+ metadata: r.entry.metadata,+ createdAt: r.entry.createdAt,+ updatedAt: r.entry.updatedAt,+ score: r.score,+ _entry: r.entry,+ }));++ const fused = applyRRF([toCands(dense), toCands(sparse)], 60);+ const diverse = applyMMR(fused, mmrLambda, limit);++ return diverse.map((s: any) => ({+ entry: s.candidate._entry,+ score: s.score,+ }));+ },+ source: 'hybrid-rrf-mmr' as const,+ };+ }case 'agentMemoryScope':// Agent memory scope β placeholder, activated when explicitly enableddiff --git a/v3/@claude-flow/memory/src/fts5.test.ts b/v3/@claude-flow/memory/src/fts5.test.tsnew file mode 100644index 0000000000..3f965549c8--- /dev/null+++ b/v3/@claude-flow/memory/src/fts5.test.ts@@ -0,0 +1,166 @@+/**+ * Phase 5 β FTS5 keyword index (ADR-125)+ *+ * Verifies the FTS5 wiring on the two SQL backends:+ * - SqlJsBackend (sql.js β WASM, ships FTS5 since 1.10)+ * - SQLiteBackend (better-sqlite3 β bundles FTS5 since 11.x)+ *+ * The SQLiteBackend test is conditional: better-sqlite3 is an optional+ * dependency. If it isn't installable in the current env, that test is+ * skipped.+ */++import { describe, it, expect } from 'vitest';+import { existsSync } from 'node:fs';+import { createRequire } from 'node:module';+import { SqlJsBackend } from './sqljs-backend.js';+import { createDefaultEntry } from './types.js';++const require = createRequire(import.meta.url);++/**+ * Locate the local sql-wasm.wasm so vitest doesn't try to fetch it over HTTP.+ * Returns null if sql.js isn't installed in this env (treated as a skip+ * signal by the suite).+ */+function locateSqlWasm(): string | null {+ try {+ const sqljsPkg = require.resolve('sql.js/package.json');+ const wasmPath = sqljsPkg.replace(/package\.json$/, 'dist/sql-wasm.wasm');+ return existsSync(wasmPath) ? wasmPath : null;+ } catch {+ return null;+ }+}++const WASM_PATH = locateSqlWasm();++async function newSqlJs() {+ if (!WASM_PATH) throw new Error('sql.js/dist/sql-wasm.wasm not found');+ const backend = new SqlJsBackend({ databasePath: ':memory:', wasmPath: WASM_PATH });+ await backend.initialize();+ return backend;+}++describe('Phase 5 β SqlJsBackend FTS5', () => {+ it('searchKeyword returns matching entries for an FTS phrase', async () => {+ const backend = await newSqlJs();++ const phrases = [+ 'authentication patterns for OAuth flow',+ 'database migrations and schema changes',+ 'rate limiting and throttling middleware',+ 'caching strategies for distributed systems',+ 'jwt token validation security',+ ];+ for (let i = 0; i < 20; i++) {+ const phrase = phrases[i % phrases.length];+ const entry = createDefaultEntry({ key: `k-${i}`, content: `${phrase} ${i}` });+ await backend.store(entry);+ }++ const results = await (backend as any).searchKeyword('authentication patterns', 10);+ expect(results.length).toBeGreaterThan(0);+ for (const r of results) {+ const c = r.entry.content.toLowerCase();+ // At least one of the two query tokens should appear+ expect(c.includes('authentication') || c.includes('patterns')).toBe(true);+ }++ await backend.shutdown();+ });++ it('searchKeyword does not return a deleted entry', async () => {+ const backend = await newSqlJs();+ const entry = createDefaultEntry({ key: 'doomed', content: 'unique-marker-phrase' });+ await backend.store(entry);+ let results = await (backend as any).searchKeyword('unique-marker-phrase', 5);+ expect(results.length).toBe(1);++ await backend.delete(entry.id);+ results = await (backend as any).searchKeyword('unique-marker-phrase', 5);+ expect(results.length).toBe(0);++ await backend.shutdown();+ });++ it('searchKeyword reflects content updates', async () => {+ const backend = await newSqlJs();+ const entry = createDefaultEntry({ key: 'updatable', content: 'original phrase about apples' });+ await backend.store(entry);++ let results = await (backend as any).searchKeyword('apples', 5);+ expect(results.length).toBe(1);++ await backend.update(entry.id, { content: 'rewritten phrase about bananas' });+ results = await (backend as any).searchKeyword('apples', 5);+ expect(results.length).toBe(0);+ results = await (backend as any).searchKeyword('bananas', 5);+ expect(results.length).toBe(1);++ await backend.shutdown();+ });++ it('searchKeyword returns [] for an empty query', async () => {+ const backend = await newSqlJs();+ const results = await (backend as any).searchKeyword(' ', 5);+ expect(results).toEqual([]);+ await backend.shutdown();+ });+});++// Conditionally run the SQLiteBackend tests β better-sqlite3 is an optional+// dependency, so probe for it first.+async function probeBetterSqlite3(): Promise<boolean> {+ try {+ await import('better-sqlite3');+ return true;+ } catch {+ return false;+ }+}++describe('Phase 5 β SQLiteBackend FTS5 (better-sqlite3)', async () => {+ const hasBetterSqlite3 = await probeBetterSqlite3();+ const maybeIt = hasBetterSqlite3 ? it : it.skip;++ maybeIt('searchKeyword returns matching entries with FTS5 ranking', async () => {+ const { SQLiteBackend } = await import('./sqlite-backend.js');+ const backend = new SQLiteBackend({ databasePath: ':memory:' });+ await backend.initialize();++ for (let i = 0; i < 20; i++) {+ const entry = createDefaultEntry({+ key: `k-${i}`,+ content: i % 2 === 0+ ? `authentication patterns OAuth ${i}`+ : `database indexing strategies ${i}`,+ });+ await backend.store(entry);+ }++ const results = await (backend as any).searchKeyword('authentication', 10);+ expect(results.length).toBeGreaterThan(0);+ for (const r of results) {+ expect(r.entry.content.toLowerCase()).toContain('authentication');+ }++ await backend.shutdown();+ });++ maybeIt('searchKeyword stops finding entries after delete', async () => {+ const { SQLiteBackend } = await import('./sqlite-backend.js');+ const backend = new SQLiteBackend({ databasePath: ':memory:' });+ await backend.initialize();++ const entry = createDefaultEntry({ key: 'doomed', content: 'unique-marker' });+ await backend.store(entry);+ let results = await (backend as any).searchKeyword('unique-marker', 5);+ expect(results.length).toBe(1);+ await backend.delete(entry.id);+ results = await (backend as any).searchKeyword('unique-marker', 5);+ expect(results.length).toBe(0);++ await backend.shutdown();+ });+});diff --git a/v3/@claude-flow/memory/src/graceful-retrieval.test.ts b/v3/@claude-flow/memory/src/graceful-retrieval.test.tsnew file mode 100644index 0000000000..2912b61e59--- /dev/null+++ b/v3/@claude-flow/memory/src/graceful-retrieval.test.ts@@ -0,0 +1,165 @@+/**+ * Phase 5 β Graceful retrieval degradation (ADR-125)+ *+ * Verifies:+ * - `MemoryService.semanticSearch('foo')` with NO embedder configured falls+ * back to FTS / keyword search results without throwing AND emits+ * `health:embedder = { status: 'degraded' }` (Acceptance Criterion #5).+ * - Same fallback when the embedder is configured but throws on call.+ * - `hybridSearch` controller fuses dense + sparse arms via RRF + MMR and+ * returns non-empty results with a mean score at least as high as either+ * pure arm.+ */++import { describe, it, expect } from 'vitest';+import { MemoryService } from './index.js';+import { ControllerRegistry } from './controller-registry.js';+import { createDefaultEntry } from './types.js';++async function newSvc(opts: Record<string, any> = {}) {+ const svc = new MemoryService({+ dimensions: 8,+ persistenceEnabled: false,+ snapshotInterval: 0,+ ...opts,+ });+ await svc.initialize();+ return svc;+}++function randomVec(dim: number, seed: number): Float32Array {+ const out = new Float32Array(dim);+ let s = seed | 0 || 1;+ for (let i = 0; i < dim; i++) {+ s ^= s << 13; s ^= s >>> 17; s ^= s << 5;+ out[i] = (s | 0) / 2 ** 31;+ }+ return out;+}++describe('Phase 5 β semanticSearch falls back without embedder', () => {+ it('Acceptance Criterion #5 β no embedder β keyword results, no throw', async () => {+ const svc = await newSvc(); // no embeddingGenerator++ for (let i = 0; i < 10; i++) {+ const entry = createDefaultEntry({+ key: `k-${i}`,+ content: i % 2 === 0+ ? `authentication patterns for OAuth ${i}`+ : `database migration schema ${i}`,+ });+ await svc.store(entry);+ }++ let degraded: any = null;+ svc.getAdapter().on('health:embedder', (ev: any) => { degraded = ev; });++ const results = await svc.semanticSearch('authentication', 5);+ expect(Array.isArray(results)).toBe(true);+ expect(results.length).toBeGreaterThan(0);+ // Every result should match the keyword+ for (const r of results) {+ expect(r.entry.content.toLowerCase()).toContain('authentication');+ }+ expect(degraded).not.toBeNull();+ expect(degraded.status).toBe('degraded');++ await svc.close();+ });++ it('embedder that throws β degraded event + keyword fallback', async () => {+ // Build a service where the embedder ALWAYS throws on read paths only.+ // We bypass the throw on write by pre-populating an embedding on each+ // stored entry β this mirrors real-world failure modes where indexing+ // happened with a healthy embedder but the embedder later goes down.+ const svc = await newSvc({+ embeddingGenerator: async () => {+ throw new Error('embedding service unavailable');+ },+ });++ for (let i = 0; i < 5; i++) {+ const entry = createDefaultEntry({+ key: `t-${i}`,+ content: `token validation ${i}`,+ });+ entry.embedding = randomVec(8, i + 1); // pre-set so store() doesn't call embedder+ await svc.store(entry);+ }++ let degraded: any = null;+ svc.getAdapter().on('health:embedder', (ev: any) => { degraded = ev; });++ const results = await svc.semanticSearch('token validation', 5);+ expect(results.length).toBeGreaterThan(0);+ expect(degraded?.status).toBe('degraded');+ expect(degraded?.reason).toContain('embedding service unavailable');++ await svc.close();+ });+});++describe('Phase 5 β hybridSearch controller (RRF + MMR)', () => {+ it('fuses dense + sparse arms into a non-empty result', async () => {+ // Use a deterministic embedder so the dense arm is reproducible+ const dim = 8;+ const svc = new MemoryService({+ dimensions: dim,+ persistenceEnabled: false,+ snapshotInterval: 0,+ embeddingGenerator: async (text: string) => randomVec(dim, hashStr(text)),+ });+ await svc.initialize();++ // 50 entries: 25 about "authentication", 25 about "indexing"+ for (let i = 0; i < 25; i++) {+ const entry = createDefaultEntry({+ key: `auth-${i}`,+ content: `authentication and authorization patterns ${i}`,+ });+ entry.embedding = randomVec(dim, hashStr(entry.content));+ await svc.store(entry);+ }+ for (let i = 0; i < 25; i++) {+ const entry = createDefaultEntry({+ key: `idx-${i}`,+ content: `database indexing strategies ${i}`,+ });+ entry.embedding = randomVec(dim, hashStr(entry.content));+ await svc.store(entry);+ }++ const registry = new ControllerRegistry();+ await registry.initialize({ memoryService: svc });++ const hybrid = registry.get<any>('hybridSearch');+ expect(hybrid).toBeTruthy();+ expect(hybrid.source).toBe('hybrid-rrf-mmr');++ const results = await hybrid.search('authentication', { limit: 10 });+ expect(results.length).toBeGreaterThan(0);++ // Mean RRF-fused score should be > 0+ const mean = results.reduce((acc: number, r: any) => acc + r.score, 0) / results.length;+ expect(mean).toBeGreaterThan(0);++ // Verify hybrid surfaces relevant entries from BOTH arms by checking+ // that >=1 result mentions "authentication" (keyword arm signal).+ const authMatches = results.filter((r: any) =>+ r.entry.content.toLowerCase().includes('authentication')+ );+ expect(authMatches.length).toBeGreaterThan(0);++ // Hybrid should return up to `limit` entries (10 here, given 50 stored).+ expect(results.length).toBeLessThanOrEqual(10);++ await registry.shutdown();+ await svc.close();+ });+});++function hashStr(s: string): number {+ let h = 0;+ for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0;+ return Math.abs(h) + 1;+}diff --git a/v3/@claude-flow/memory/src/smart-retrieval.ts b/v3/@claude-flow/memory/src/smart-retrieval.tsindex 2e9d51c3a0..eded6e37af 100644--- a/v3/@claude-flow/memory/src/smart-retrieval.ts+++ b/v3/@claude-flow/memory/src/smart-retrieval.ts@@ -150,6 +150,19 @@ interface Scored {score: number;}+/**+ * Public-facing Reciprocal Rank Fusion. Takes any number of pre-sorted+ * candidate lists (best-first) and fuses them with the RRF score+ * `sum(1 / (k + rank_i))`. Used by the ADR-125 Phase 5 hybridSearch+ * controller to fuse dense + sparse arms.+ */+export function applyRRF<T extends SearchCandidate>(+ rankedLists: T[][],+ k: number = 60+): Array<{ candidate: T; score: number }> {+ return reciprocalRankFusion(rankedLists as any, k) as any;+}+function reciprocalRankFusion(rankedLists: SearchCandidate[][],k: number@@ -227,6 +240,21 @@ function pickTimestamp(cand: SearchCandidate): number | undefined {// ββ MMR Diversity (token-Jaccard proxy) ββββββββββββββββββββββββ+/**+ * Public-facing MMR rerank.+ *+ * Re-exported as `applyMMR` for ADR-125 Phase 5 callers (the hybridSearch+ * controller). Takes already-scored candidates plus an MMR lambda+ * (1.0 = pure relevance, 0.0 = pure diversity).+ */+export function applyMMR<T extends SearchCandidate>(+ scored: Array<{ candidate: T; score: number }>,+ lambda: number = 0.7,+ limit?: number+): Array<{ candidate: T; score: number }> {+ return mmrRerank(scored as any, lambda, limit ?? scored.length) as any;+}+function mmrRerank(scored: Scored[], lambda: number, limit: number): Scored[] {if (scored.length <= 1) return scored.slice(0, limit);diff --git a/v3/@claude-flow/memory/src/sqlite-backend.ts b/v3/@claude-flow/memory/src/sqlite-backend.tsindex c809772e98..9a67be64e3 100644--- a/v3/@claude-flow/memory/src/sqlite-backend.ts+++ b/v3/@claude-flow/memory/src/sqlite-backend.ts@@ -83,6 +83,9 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {private db: Database.Database | null = null;private initialized: boolean = false;+ /** Whether the FTS5 virtual table is available on this build. */+ private ftsAvailable: boolean = false;+// Performance trackingprivate stats = {queryCount: 0,@@ -197,6 +200,14 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {embeddingStmt.run(entry.id, Buffer.from(entry.embedding.buffer));}+ // ADR-125 Phase 5 β mirror into FTS5 for keyword search.+ if (this.ftsAvailable) {+ // REPLACE semantics for FTS: delete-then-insert so updates reflect.+ this.db!.prepare('DELETE FROM memory_fts WHERE id = ?').run(entry.id);+ this.db!.prepare('INSERT INTO memory_fts(id, content) VALUES (?, ?)')+ .run(entry.id, entry.content);+ }+const duration = performance.now() - startTime;this.stats.writeCount++;this.stats.totalWriteTime += duration;@@ -275,6 +286,9 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {const result = deleteEntry.run(id);deleteEmbedding.run(id);+ if (this.ftsAvailable) {+ this.db!.prepare('DELETE FROM memory_fts WHERE id = ?').run(id);+ }if (result.changes > 0) {this.emit('entry:deleted', { id });@@ -284,6 +298,53 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {return false;}+ /**+ * ADR-125 Phase 5 β keyword (FTS5) search.+ *+ * Runs `memory_fts MATCH ?` ranked by FTS5's BM25 implementation, then+ * joins back to `memory_entries` for full records. Falls back to a+ * `LIKE`-based scan when FTS5 is unavailable.+ */+ async searchKeyword(query: string, limit: number = 10): Promise<SearchResult[]> {+ this.ensureInitialized();+ if (!query || !query.trim()) return [];++ if (this.ftsAvailable) {+ try {+ const stmt = this.db!.prepare(`+ SELECT e.*, fts.rank as fts_rank+ FROM memory_fts AS fts+ JOIN memory_entries AS e ON e.id = fts.id+ WHERE memory_fts MATCH ?+ ORDER BY fts.rank+ LIMIT ?+ `);+ const rows = stmt.all(escapeFtsQuery(query), limit) as any[];+ return rows.map((row) => {+ const entry = this.rowToEntry(row);+ // FTS5 rank is non-positive β closer to 0 is better. Convert to+ // a [0,1] similarity-ish score so callers see a consistent shape.+ const score = 1 / (1 + Math.abs(row.fts_rank || 0));+ return { entry, score, distance: 1 - score };+ });+ } catch {+ // Fall through to LIKE+ }+ }++ // LIKE fallback (does no ranking; first N matches)+ const like = `%${query.replace(/[%_]/g, '')}%`;+ const stmt = this.db!.prepare(+ 'SELECT * FROM memory_entries WHERE content LIKE ? ORDER BY updated_at DESC LIMIT ?'+ );+ const rows = stmt.all(like, limit) as any[];+ return rows.map((row) => ({+ entry: this.rowToEntry(row),+ score: 0.5,+ distance: 0.5,+ }));+ }+/*** Query memory entries with filters*/@@ -668,6 +729,20 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {FOREIGN KEY (entry_id) REFERENCES memory_entries(id) ON DELETE CASCADE);`);++ // ADR-125 Phase 5 β FTS5 virtual table for keyword search.+ // FTS5 is built into better-sqlite3 since 11.x. Surrounding try/catch so+ // older SQLite builds gracefully skip FTS without taking the whole backend+ // offline; queries against `searchKeyword` will fall back to LIKE.+ try {+ this.db.exec(`+ CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts+ USING fts5(id UNINDEXED, content, tokenize='porter unicode61');+ `);+ this.ftsAvailable = true;+ } catch {+ this.ftsAvailable = false;+ }}private rowToEntry(row: any): MemoryEntry {@@ -743,4 +818,22 @@ export class SQLiteBackend extends EventEmitter implements IMemoryBackend {}}+/**+ * Escape an FTS5 MATCH query string. FTS5 has its own mini-language+ * (`AND`, `OR`, `NOT`, `*` wildcards, parentheses, quoted phrases). User+ * input that's plain prose can hit syntax errors. We wrap each whitespace-+ * separated token in double quotes (FTS5's phrase delimiter), which is+ * close to literal interpretation and is what the keyword-fallback callers+ * actually want.+ *+ * @internal+ */+function escapeFtsQuery(q: string): string {+ return q+ .split(/\s+/)+ .filter(Boolean)+ .map((tok) => `"${tok.replace(/"/g, '""')}"`)+ .join(' ');+}+export default SQLiteBackend;diff --git a/v3/@claude-flow/memory/src/sqljs-backend.ts b/v3/@claude-flow/memory/src/sqljs-backend.tsindex e974ecbfd6..658ad8a959 100644--- a/v3/@claude-flow/memory/src/sqljs-backend.ts+++ b/v3/@claude-flow/memory/src/sqljs-backend.ts@@ -86,6 +86,9 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {private persistTimer: NodeJS.Timeout | null = null;private SQL: any = null;+ /** Whether the FTS5 virtual table is available on this build of sql.js. */+ private ftsAvailable: boolean = false;+// Performance trackingprivate stats = {queryCount: 0,@@ -207,6 +210,17 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {'CREATE UNIQUE INDEX IF NOT EXISTS idx_namespace_key ON memory_entries(namespace, key)');+ // ADR-125 Phase 5 β FTS5 keyword index. sql.js ships FTS5 since 1.10.+ try {+ this.db.run(`+ CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts+ USING fts5(id UNINDEXED, content, tokenize='porter unicode61')+ `);+ this.ftsAvailable = true;+ } catch {+ this.ftsAvailable = false;+ }+if (this.config.verbose) {console.log('[SqlJsBackend] Schema created successfully');}@@ -251,6 +265,15 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {entry.lastAccessedAt,]);+ // ADR-125 Phase 5 β mirror into FTS5 for keyword search.+ if (this.ftsAvailable) {+ this.db!.run('DELETE FROM memory_fts WHERE id = ?', [entry.id]);+ this.db!.run('INSERT INTO memory_fts(id, content) VALUES (?, ?)', [+ entry.id,+ entry.content,+ ]);+ }+const duration = performance.now() - startTime;this.stats.writeCount++;this.stats.totalWriteTime += duration;@@ -352,6 +375,9 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {const startTime = performance.now();this.db!.run('DELETE FROM memory_entries WHERE id = ?', [id]);+ if (this.ftsAvailable) {+ this.db!.run('DELETE FROM memory_fts WHERE id = ?', [id]);+ }const duration = performance.now() - startTime;this.stats.writeCount++;@@ -361,6 +387,60 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {return true;}+ /**+ * ADR-125 Phase 5 β keyword (FTS5) search.+ *+ * Mirrors the SQLiteBackend.searchKeyword shape. Falls back to a LIKE+ * scan when FTS5 isn't available on the sql.js build.+ */+ async searchKeyword(query: string, limit: number = 10): Promise<SearchResult[]> {+ this.ensureInitialized();+ if (!query || !query.trim()) return [];++ if (this.ftsAvailable) {+ try {+ const stmt = this.db!.prepare(`+ SELECT e.*, fts.rank as fts_rank+ FROM memory_fts AS fts+ JOIN memory_entries AS e ON e.id = fts.id+ WHERE memory_fts MATCH ?+ ORDER BY fts.rank+ LIMIT ?+ `);+ stmt.bind([escapeFtsQuery(query), limit]);+ const results: SearchResult[] = [];+ while (stmt.step()) {+ const row: any = stmt.getAsObject();+ const entry = this.rowToEntry(row);+ const score = 1 / (1 + Math.abs(row.fts_rank || 0));+ results.push({ entry, score, distance: 1 - score });+ }+ stmt.free();+ return results;+ } catch {+ // Fall through to LIKE+ }+ }++ // LIKE fallback+ const like = `%${query.replace(/[%_]/g, '')}%`;+ const stmt = this.db!.prepare(+ 'SELECT * FROM memory_entries WHERE content LIKE ? ORDER BY updated_at DESC LIMIT ?'+ );+ stmt.bind([like, limit]);+ const results: SearchResult[] = [];+ while (stmt.step()) {+ const row: any = stmt.getAsObject();+ results.push({+ entry: this.rowToEntry(row),+ score: 0.5,+ distance: 0.5,+ });+ }+ stmt.free();+ return results;+ }+/*** Query memory entries*/@@ -765,3 +845,16 @@ export class SqlJsBackend extends EventEmitter implements IMemoryBackend {return data.length;}}++/**+ * Escape an FTS5 MATCH query string. Wraps each whitespace-separated+ * token as a quoted phrase so prose input doesn't trip FTS5's mini-language.+ * @internal+ */+function escapeFtsQuery(q: string): string {+ return q+ .split(/\s+/)+ .filter(Boolean)+ .map((tok) => `"${tok.replace(/"/g, '""')}"`)+ .join(' ');+}