π 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
dream(memory): #3056 hybridSearch reachable via explicit opt-in (evaluated, ACCEPT-scoped) (#3057)
rUv41efca8be386
diff --git a/docs/dream-cycle/dream-gist-2026-08-18.md b/docs/dream-cycle/dream-gist-2026-08-18.mdnew file mode 100644index 0000000000..76db0fe191--- /dev/null+++ b/docs/dream-cycle/dream-gist-2026-08-18.md@@ -0,0 +1,66 @@+# Memory SOTA Report β 2026-08-18++TL;DR: Tonight's memory deep-dive found that three consecutive prior Dream Cycle nights (2026-06-08 β ADR-341, 2026-08-08, 2026-08-13) independently proposed "Ruflo needs multi-signal (dense+sparse+entity) retrieval" as if the capability didn't exist β it does. `@claude-flow/memory`'s `hybridSearch` controller (ADR-125 Phase 5 / ADR-147) is a fully built, unit-tested three-arm RRF+MMR fusion engine. The real gap is reachability, not capability: the controller's explicit opt-in (`controllers: { hybridSearch: true }`) silently no-op'd to `null` unless a caller also hand-built a full `UnifiedMemoryService` wrapper β something no production call site does. Shipped a small, additive, opt-in-only fix, and built the first real retrieval-quality benchmark this feature has ever had. Result: a genuine, disclosed, mixed picture β large recall gains on keyword-exact and entity-named queries, parity on mixed/easy queries, and a real, statistically significant regression on pure-paraphrase queries where fusion noise dilutes an already-perfect dense signal.++## What's New in 2026++| Finding | Source | Confidence |+|---|---|---|+| Dense+sparse RRF fusion roughly *matches* the stronger single signal in aggregate; its real value is per-query-type robustness where the two signals disagree | vstash, arXiv 2604.15484 (Apr 2026) β reproducible in-paper numbers (Vector NDCG@5=0.809, FTS=0.631, Hybrid=0.814) | A |+| MMR diversity reranking adds a further ~+1.8% NDCG@5 on top of RRF, mainly a diversity/coverage gain not a raw-relevance gain | vstash, arXiv 2604.15484 | A |+| Workload-adaptive cascade fusion (BM25+HNSW) "substantially outperforms" single-signal retrieval for long-term conversational memory (no clean numeric delta extracted) | AgentIR, arXiv 2605.25092 (May 2026) | B |+| No named academic anti-pattern exists for "capability built and explicitly requestable via config, but silently inert because the required object is never constructed on any production path" β the closest documented territory is feature-toggle/config-drift technical debt, which describes toggles left *on* accidentally, not capabilities left permanently unreachable | FSE'12 feature-toggle study (peer-reviewed) + arXiv 2604.15872 (Apr 2026) | A / B |+| Only Mem0 ships a comparably rich (dense+sparse+entity) fusion among surveyed competitors, and it's default-on β Ruflo's equivalent is architecturally competitive or ahead in signal richness (3 fully-fused arms + MMR vs Mem0's simpler design) but unreachable by default | Live competitor research, 2026-08-18 | B (Mem0's own benchmark numbers, vendor-reported) |++## Ruflo Current Capability++`v3/@claude-flow/memory/src/controller-registry.ts`'s `hybridSearch` controller runs `semanticSearch()` (dense), `searchKeyword()` (sparse FTS5-style), and a per-entity keyword pass (`entity-tagger.ts`, proper-noun/email/URL/quoted-phrase extraction) independently in parallel, fuses via Reciprocal Rank Fusion (`smart-retrieval.ts`), and diversifies via MMR. It's real: `graceful-retrieval.test.ts`'s existing "Phase 5 β hybridSearch controller (RRF + MMR)" tests confirm dense+sparse fusion and entity-arm boosting work correctly, and the package README documents it as a shipped 3.0.0-alpha.18 feature. But `isControllerEnabled('hybridSearch')`'s default condition requires `config.memoryService` (a full `UnifiedMemoryService` wrapper), and β until tonight β the factory (`createController`) had **no fallback** when a caller explicitly requested `hybridSearch: true` but only had a `backend` (e.g. a raw `AgentDBAdapter`, which the production CLI/MCP path in `memory-bridge.ts` always uses). The explicit override worked at the gate but not at construction β a silent no-op with no error, no warning, and no signal explaining why `registry.get('hybridSearch')` came back `null`.++## Competitor Comparison++| Framework | Hybrid dense+sparse(+entity) fusion? | Default-on or opt-in | Confidence |+|---|---|---|---|+| Mem0 | Yes β dense + BM25 + entity-linking, closest comparator to Ruflo's design | **Default-on** (core `search()`) | B (vendor benchmark, 92.5 LoCoMo/94.4 LongMemEval, Apr 2026) |+| LangGraph BaseStore | Dense-only natively; no built-in RRF fusion | Opt-in (`index` config) | B |+| CrewAI | No native fusion in core memory; fusion only via optional tools (e.g. WeaviateVectorSearchTool) | Opt-in, per-tool | C |+| AutoGen/AG2 | No native fusion; needs a Mem0 plugin bolt-on | Opt-in, third-party | C |+| OpenAI Agents SDK | None β Sessions persist raw history only | N/A | A (official docs) |+| Qdrant / Weaviate / Milvus / LanceDB | All support dense+sparse RRF/relativeScoreFusion | Opt-in β explicit hybrid API call required per query | B |++No published postmortem or GitHub issue was found (competitor-analyst search, 2026-08-18) describing another team shipping a hybrid retrieval feature that then sat unreachable in production from a default-path config gap β this appears to be a genuinely under-documented failure mode, not a known/common one.++## Hypothesis++Given a caller that explicitly opts into `controllers: { hybridSearch: true }` with a JS-side `backend` (e.g. `AgentDBAdapter`) but no hand-built `UnifiedMemoryService`, when `createController('hybridSearch')` falls back to constructing the fusion controller directly from that backend (duck-typed on `semanticSearch`+`searchKeyword`) instead of silently returning `null`, then retrieval quality (recall@10 / MRR) on a mixed keyword+semantic+entity query set should differ measurably from the vector-only baseline that explicit opt-in silently fell back to before β subject to: (1) default (non-explicit) auto-enable behavior is completely unchanged; (2) all existing hybridSearch/controller-registry tests remain green; (3) zero LLM cost.++## Benchmarks++New bespoke, deterministic, $0 benchmark (`v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs`) β no LLM calls, seeded PRNG, 300 synthetic entries / 60 queries across 4 categories (15 instances each), designed *before* any run per the vstash calibration (per-category deltas, not one misleading aggregate): **A-keyword-exact** (target has a literal rare token dense-only can't see), **B-paraphrase-semantic** (target paraphrases the query with zero literal overlap, embedded near it β dense-only's best case), **C-entity** (target names a person the query asks about, topically unrelated otherwise), **D-mixed-control** (both signals agree β expected near-ceiling for both, a sanity check not a differentiator). Both baseline and candidate resolve query embeddings through the identical `embeddingGenerator` function β the first version of this script had an unfair baseline (the candidate's internal dense arm silently degraded to keyword-only from a missing embedder while the baseline got hand-crafted embeddings directly); found and fixed before finalizing numbers, the same class of self-caught methodology bug as the 2026-08-17 paired-t stddev fix.++## Evaluation++**evaluated: accepted, scoped.** Full receipt: `v3/@claude-flow/memory/benchmarks/results/hybridsearch-quality-receipt.json`.++| Category | Baseline recall@10 | Hybrid recall@10 | Ξ | MRR Ξ (paired t) |+|---|---|---|---|---|+| A-keyword-exact | 0.000 | 0.867 | **+0.867** | +0.157 (t=4.17) |+| B-paraphrase-semantic | 1.000 | 0.867 | **-0.133** | -0.551 (t=-5.75) |+| C-entity | 0.000 | 0.333 | +0.333 | +0.333 (t=2.65) |+| D-mixed-control | 1.000 | 1.000 | 0.000 | 0.000 (t=0.00) |+| **Overall** | 0.500 | 0.767 | **+0.267** | β |++The aggregate is a real, substantial net positive β but categories B and C are the honest, disclosed nuance the aggregate hides. Category B is a genuine, statistically significant **regression**: when dense-only already nails a query perfectly, fusing in sparse/entity-arm noise can bump the correct answer out of the fused top-10 (2/15 instances) or push down its rank. Category C's recovery (33%, vs. category A's 87%) is weaker than expected β plausibly because category C's distractors share generic vocabulary overlap with the target (unlike category A's distractors, which share none), letting the sparse arm partially favor distractors too; flagged as a follow-up question, not resolved tonight. Existing test suite: 75/75 passing (7 in `graceful-retrieval.test.ts` incl. 3 new, 68 in `controller-registry.test.ts`), zero regressions; full `@claude-flow/memory` suite 458/459 (1 pre-existing environmental failure β a chmod-based read-only-file test that can't enforce under a root-owned sandbox, same documented class as 2026-08-15's finding, confirmed unrelated to this candidate).++## Darwin Results++Skipped β scope mismatch, same class as three of the last four nights. `@metaharness/darwin`'s real interface (`evolve --bench <corpus>`) mutates routing/topology/prompt/memory/tool/tier/context/coordination parameters against LLM-scored task corpora; there's no analog for a binary code-path fallback (does the fallback exist or not) β it isn't a continuous or categorical parameter to tune.++## SOTA Proof & Witness++See the linked issue and PR for the full witness stamp (session commit, report hash, witness hash) and verifier procedure.++## Recommended Next Steps++1. **Investigate category B's regression as a follow-up candidate**: a confidence-gated fusion β when the dense arm's top result already clears a high similarity threshold, skip fusing in sparse/entity arms entirely (or down-weight them) rather than always running all three. This directly targets tonight's disclosed regression without touching the default-disabled reachability fix.+2. **Wire `memory-bridge.ts` (the actual CLI/MCP production path) to hybridSearch, in a dedicated future night** β tonight's fix makes the controller reachable via explicit config, but the CLI's `memory search` command still never sets it. That's a larger, riskier change (touches the hot CLI startup path) deliberately left out of tonight's small, safe, opt-in-only scope.+3. **Re-run category C with a stronger entity-arm weighting** (currently equal RRF weight to dense/sparse) to test whether the weaker 33% recovery is a tunable weighting issue vs. an inherent limit of the regex-based entity tagger β a scoped, cheap follow-up experiment.diff --git a/v3/@claude-flow/memory/benchmarks/results/hybridsearch-quality-receipt.json b/v3/@claude-flow/memory/benchmarks/results/hybridsearch-quality-receipt.jsonnew file mode 100644index 0000000000..7c5aa056ff--- /dev/null+++ b/v3/@claude-flow/memory/benchmarks/results/hybridsearch-quality-receipt.json@@ -0,0 +1,54 @@+{+ "generatedAt": "dream-cycle-2026-08-18",+ "dim": 16,+ "topK": 10,+ "instancesPerCategory": 15,+ "categories": {+ "A-keyword-exact": {+ "n": 15,+ "baselineRecallAt10": 0,+ "hybridRecallAt10": 0.8666666666666667,+ "recallDelta": 0.8666666666666667,+ "baselineMRR": 0,+ "hybridMRR": 0.15746031746031747,+ "mrrPairedT": 4.173979607959554,+ "mrrMeanDiff": 0.15746031746031747+ },+ "B-paraphrase-semantic": {+ "n": 15,+ "baselineRecallAt10": 1,+ "hybridRecallAt10": 0.8666666666666667,+ "recallDelta": -0.1333333333333333,+ "baselineMRR": 1,+ "hybridMRR": 0.44888888888888895,+ "mrrPairedT": -5.745014696183407,+ "mrrMeanDiff": -0.5511111111111112+ },+ "C-entity": {+ "n": 15,+ "baselineRecallAt10": 0,+ "hybridRecallAt10": 0.3333333333333333,+ "recallDelta": 0.3333333333333333,+ "baselineMRR": 0,+ "hybridMRR": 0.3333333333333333,+ "mrrPairedT": 2.64575131106459,+ "mrrMeanDiff": 0.3333333333333333+ },+ "D-mixed-control": {+ "n": 15,+ "baselineRecallAt10": 1,+ "hybridRecallAt10": 1,+ "recallDelta": 0,+ "baselineMRR": 1,+ "hybridMRR": 1,+ "mrrPairedT": 0,+ "mrrMeanDiff": 0+ }+ },+ "overall": {+ "n": 60,+ "baselineRecallAt10": 0.5,+ "hybridRecallAt10": 0.7666666666666667,+ "recallDelta": 0.2666666666666667+ }+}\ No newline at end of filediff --git a/v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs b/v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjsnew file mode 100644index 0000000000..664ab0676a--- /dev/null+++ b/v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs@@ -0,0 +1,354 @@+#!/usr/bin/env node+/**+ * Dream Cycle 2026-08-18 β hybridSearch retrieval-quality benchmark+ *+ * Quantifies the actual recall@10 / MRR benefit of the already-built+ * three-arm hybridSearch controller (dense HNSW + sparse FTS5 keyword ++ * entity-linking, RRF + MMR fused) over the vector-only `semanticSearch()`+ * path every production caller gets today, now that the 2026-08-18 fix+ * (`controller-registry.ts`) makes hybridSearch reachable via explicit+ * `controllers: { hybridSearch: true }` opt-in without a hand-built+ * `UnifiedMemoryService`.+ *+ * Zero LLM calls, $0 cost, fully deterministic (seeded PRNG). Run against+ * the SAME corpus + SAME stored embeddings for both arms β only the+ * retrieval path differs (baseline: `semanticSearch()` only; candidate:+ * the hybridSearch controller).+ *+ * Per the 2026-08-18 Deep Researcher finding (vstash, arXiv 2604.15484,+ * Apr 2026): hybrid fusion roughly MATCHES the stronger single signal in+ * aggregate β its real value is per-query-type robustness where dense and+ * sparse disagree. This benchmark therefore reports FOUR separate query+ * categories rather than one aggregate number, to avoid a misleading+ * "no significant gain" read on a metric average that hides where the+ * fusion actually helps.+ *+ * Usage: node benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs+ * (run from v3/@claude-flow/memory, against the built dist/)+ */++import { UnifiedMemoryService } from '../../../dist/index.js';+import { ControllerRegistry } from '../../../dist/controller-registry.js';+import { createDefaultEntry } from '../../../dist/types.js';++const DIM = 16;+const TOP_K = 10;+const INSTANCES_PER_CATEGORY = 15;++// ---- Deterministic PRNG (xorshift32, seeded) ----+function makeRng(seed) {+ let s = seed | 0 || 1;+ return () => {+ s ^= s << 13; s ^= s >>> 17; s ^= s << 5;+ return (s >>> 0) / 0xffffffff;+ };+}++function hashStr(s) {+ let h = 0;+ for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0;+ return Math.abs(h) + 1;+}++// A "topic" embedding: deterministic base vector from a topic id, so text+// assigned the same topic id clusters in vector space regardless of its+// literal wording β simulating what a real semantic embedder does for+// paraphrases, without needing a real (costly) embedding model.+function topicVec(topicId, dim = DIM) {+ const rng = makeRng(hashStr(`topic:${topicId}`));+ const v = new Float32Array(dim);+ for (let i = 0; i < dim; i++) v[i] = rng() * 2 - 1;+ return v;+}++function withNoise(vec, rng, amount = 0.05) {+ const out = new Float32Array(vec.length);+ for (let i = 0; i < vec.length; i++) out[i] = vec[i] + (rng() * 2 - 1) * amount;+ return out;+}++// ---- Corpus + query generation (frozen design β written before any run) ----++function buildCorpus() {+ const entries = []; // { key, content, embedding, topicId }+ const queries = []; // { category, query, targetKey, queryEmbedding }+ const rng = makeRng(hashStr('dream-cycle-2026-08-18-hybridsearch-corpus'));++ // Category A β keyword-exact: target has a literal rare token the query+ // also contains, but its topic embedding is DELIBERATELY unrelated to the+ // query's topic. Distractors sit near the query's topic (semantically+ // plausible) but never mention the rare token. Dense-only should miss the+ // target; sparse/hybrid should catch it via the exact-token match.+ for (let i = 0; i < INSTANCES_PER_CATEGORY; i++) {+ const rareToken = `xreindex${7000 + i}gamma`;+ const queryTopic = `db-ops-${i}`;+ const unrelatedTopic = `weather-report-${i}`;+ const query = `find the log entry about ${rareToken} checkpoint status`;+ const targetKey = `catA-target-${i}`;+ entries.push({+ key: targetKey,+ content: `system log entry: ${rareToken} completed at checkpoint 7`,+ embedding: withNoise(topicVec(unrelatedTopic), rng),+ });+ for (let d = 0; d < 4; d++) {+ entries.push({+ key: `catA-distractor-${i}-${d}`,+ content: `notes about routine database reindexing operations and maintenance windows ${d}`,+ embedding: withNoise(topicVec(queryTopic), rng),+ });+ }+ // queryEmbeddingTopic pins the resolved query embedding to the SAME+ // topic used for the distractors above, so the dense arm genuinely+ // prefers the distractors (plausible-but-wrong) over the target β+ // without this, the query would hash to an unrelated vector and the+ // "dense should miss this" premise wouldn't hold.+ queries.push({ category: 'A-keyword-exact', query, targetKey, queryEmbeddingTopic: queryTopic });+ }++ // Category B β paraphrase-semantic: target shares almost no literal+ // tokens with the query but its topic embedding is close (paraphrase).+ // Distractors are topically unrelated. Sparse-only should largely miss+ // the target; dense/hybrid should catch it via embedding proximity.+ const paraphrasePairs = [+ ['How do I fix a database that responds slowly to lookups?',+ 'Query latency was high because the index needed a rebuild; the rebuild resolved it.'],+ ['What causes an agent to repeat the same failed tool call?',+ 'The retry loop lacked a backoff and kept re-issuing an identical request.'],+ ['Why did the deployment roll back automatically?',+ 'The health check threshold was breached so the release manager reverted the change.'],+ ];+ for (let i = 0; i < INSTANCES_PER_CATEGORY; i++) {+ const [queryBase, paraphrase] = paraphrasePairs[i % paraphrasePairs.length];+ // Each instance needs a distinct query string (else the embeddingGenerator+ // lookup below would collide across instances that reuse the same base+ // question text and resolve to the wrong instance's topic).+ const query = `${queryBase} (case ${i})`;+ const sharedTopic = `paraphrase-topic-${i}`;+ const targetKey = `catB-target-${i}`;+ entries.push({+ key: targetKey,+ content: `${paraphrase} (case ${i})`,+ embedding: withNoise(topicVec(sharedTopic), rng),+ });+ for (let d = 0; d < 4; d++) {+ entries.push({+ key: `catB-distractor-${i}-${d}`,+ content: `unrelated household gardening tip number ${d} for case ${i}`,+ embedding: withNoise(topicVec(`unrelated-${i}-${d}`), rng),+ });+ }+ // The query itself is embedded near the same shared topic β this is+ // what happens when a real embedder captures paraphrase similarity.+ queries.push({+ category: 'B-paraphrase-semantic',+ query,+ targetKey,+ queryEmbeddingTopic: sharedTopic,+ });+ }++ // Category C β entity: a distinctive named entity in the target, absent+ // from distractors; query names the entity. Target's topic embedding is+ // deliberately unrelated to the query (dense alone should miss it);+ // the entity arm (keyword search on the extracted proper noun) should+ // catch it.+ const names = ['Priya Natarajan', 'Diego Alvarez', 'Wen Zhao', 'Aisha Bello', 'Lars Eriksson'];+ for (let i = 0; i < INSTANCES_PER_CATEGORY; i++) {+ const name = names[i % names.length];+ // Unique per instance (case suffix) β avoids collisions in the+ // embeddingGenerator's query-text lookup and keeps every instance+ // independently addressable even though names repeat every 5 cases.+ const query = `what did ${name} decide about the release (case ${i})`;+ const targetKey = `catC-target-${i}`;+ const distractorTopic = `entity-distractor-${i}`;+ entries.push({+ key: targetKey,+ content: `${name} approved the release plan after the review meeting (case ${i})`,+ embedding: withNoise(topicVec(`entity-unrelated-${i}`), rng),+ });+ for (let d = 0; d < 4; d++) {+ entries.push({+ key: `catC-distractor-${i}-${d}`,+ content: `generic release notes and changelog entry ${d} for case ${i}`,+ embedding: withNoise(topicVec(distractorTopic), rng),+ });+ }+ // Pin the query embedding to the distractors' topic β same rationale+ // as category A: without this, dense wouldn't even plausibly prefer+ // the distractors, weakening the "entity arm rescues it" premise.+ queries.push({ category: 'C-entity', query, targetKey, queryEmbeddingTopic: distractorTopic });+ }++ // Category D β mixed/control: target has BOTH topic proximity AND some+ // keyword overlap with the query. Expect both baseline and candidate+ // near ceiling here β a control group, not a differentiator.+ for (let i = 0; i < INSTANCES_PER_CATEGORY; i++) {+ const sharedTopic = `mixed-topic-${i}`;+ const query = `release checklist deployment status case ${i}`;+ const targetKey = `catD-target-${i}`;+ entries.push({+ key: targetKey,+ content: `release checklist deployment status update for case ${i}`,+ embedding: withNoise(topicVec(sharedTopic), rng),+ });+ for (let d = 0; d < 4; d++) {+ entries.push({+ key: `catD-distractor-${i}-${d}`,+ content: `unrelated topic filler entry ${d} case ${i}`,+ embedding: withNoise(topicVec(`mixed-distractor-${i}-${d}`), rng),+ });+ }+ queries.push({ category: 'D-mixed-control', query, targetKey, queryEmbeddingTopic: sharedTopic });+ }++ return { entries, queries, rng };+}++// The query's OWN embedding (used by the dense arm) must be derived+// consistently: for categories where we declared a `queryEmbeddingTopic`,+// use that topic's vector (simulating a real embedder placing the query+// near its true paraphrase/topic cluster). Otherwise, hash the raw query+// text (a generic embedder would place an out-of-topic query arbitrarily β+// here, deliberately NOT matching the target's unrelated-topic vector,+// matching categories A/C's design: dense should not accidentally solve+// the query it wasn't designed to solve).+//+// CRITICAL FAIRNESS REQUIREMENT: the candidate path (hybridSearch) calls+// `adapter.semanticSearch(queryText, ...)` internally, which computes its+// OWN embedding from raw text via `config.embeddingGenerator` β it never+// sees the hand-crafted Float32Array this function returns. If the service+// has no `embeddingGenerator` configured, ADR-125's graceful-degradation+// path makes `semanticSearch()` silently fall back to keyword-only search,+// which would make the "dense arm" inside hybridSearch secretly identical+// to its sparse arm β an unfair, misleading comparison against a baseline+// that DOES get the real hand-crafted embedding via `svc.search(embedding)`.+// So this exact function is also wired as the service's `embeddingGenerator`+// (see `main()`) β both paths resolve the SAME query text to the SAME+// vector. Only the retrieval algorithm differs between baseline/candidate.+function queryEmbedding(query, queryEmbeddingTopic) {+ if (queryEmbeddingTopic) return topicVec(queryEmbeddingTopic);+ return topicVec(`query-text:${query}`);+}++function rankOf(results, targetKey) {+ const idx = results.findIndex((r) => (r.entry ? r.entry.key : r.key) === targetKey);+ return idx === -1 ? null : idx + 1;+}++function pairedTTest(a, b) {+ const n = a.length;+ const diffs = a.map((v, i) => v - b[i]);+ const mean = diffs.reduce((s, v) => s + v, 0) / n;+ const variance = diffs.reduce((s, v) => s + (v - mean) ** 2, 0) / (n - 1); // sample stddev β 08-17 bugfix precedent+ const se = Math.sqrt(variance / n);+ const t = se === 0 ? (mean === 0 ? 0 : Infinity) : mean / se;+ return { meanDiff: mean, t, n };+}++async function main() {+ const { entries, queries } = buildCorpus();++ // Same embedding function for both paths (see fairness note above).+ const svc = new UnifiedMemoryService({+ dimensions: DIM,+ persistenceEnabled: false,+ snapshotInterval: 0,+ embeddingGenerator: async (text) => {+ const q = queries.find((q) => q.query === text);+ return queryEmbedding(text, q?.queryEmbeddingTopic);+ },+ });+ await svc.initialize();++ for (const e of entries) {+ const entry = createDefaultEntry({ key: e.key, content: e.content });+ entry.embedding = e.embedding;+ await svc.store(entry);+ }++ // Candidate path: explicit opt-in, backend-only (no memoryService) β+ // exercises exactly the 2026-08-18 fix, not a hand-built memoryService.+ const registry = new ControllerRegistry();+ await registry.initialize({+ backend: svc.getAdapter(),+ controllers: { hybridSearch: true },+ });+ const hybrid = registry.get('hybridSearch');+ if (!hybrid) throw new Error('hybridSearch controller did not construct β candidate regressed');++ const byCategory = {};++ for (const q of queries) {+ const qEmb = queryEmbedding(q.query, q.queryEmbeddingTopic);++ // Baseline: what every production caller gets today (vector-only).+ const baselineResults = await svc.search(qEmb, { k: TOP_K });+ const baselineRank = rankOf(baselineResults, q.targetKey);++ // Candidate: hybridSearch (dense + sparse + entity, RRF + MMR).+ const hybridResults = await hybrid.search(q.query, { limit: TOP_K });+ const hybridRank = rankOf(hybridResults, q.targetKey);++ const bucket = (byCategory[q.category] ??= { baselineRR: [], hybridRR: [], baselineRecall: [], hybridRecall: [] });+ bucket.baselineRR.push(baselineRank ? 1 / baselineRank : 0);+ bucket.hybridRR.push(hybridRank ? 1 / hybridRank : 0);+ bucket.baselineRecall.push(baselineRank ? 1 : 0);+ bucket.hybridRecall.push(hybridRank ? 1 : 0);+ }++ const report = { generatedAt: 'dream-cycle-2026-08-18', dim: DIM, topK: TOP_K, instancesPerCategory: INSTANCES_PER_CATEGORY, categories: {} };++ console.log('\n=== hybridSearch quality benchmark β Dream Cycle 2026-08-18 ===\n');+ console.log(`corpus: ${entries.length} entries, ${queries.length} queries (${INSTANCES_PER_CATEGORY}/category)\n`);++ let overallBaselineRecall = [];+ let overallHybridRecall = [];++ for (const [category, b] of Object.entries(byCategory)) {+ const mean = (arr) => arr.reduce((s, v) => s + v, 0) / arr.length;+ const mrrTest = pairedTTest(b.hybridRR, b.baselineRR);+ const recallDelta = mean(b.hybridRecall) - mean(b.baselineRecall);++ report.categories[category] = {+ n: b.baselineRR.length,+ baselineRecallAt10: mean(b.baselineRecall),+ hybridRecallAt10: mean(b.hybridRecall),+ recallDelta,+ baselineMRR: mean(b.baselineRR),+ hybridMRR: mean(b.hybridRR),+ mrrPairedT: mrrTest.t,+ mrrMeanDiff: mrrTest.meanDiff,+ };++ console.log(`[${category}] n=${b.baselineRR.length}`);+ console.log(` recall@10 baseline=${mean(b.baselineRecall).toFixed(3)} hybrid=${mean(b.hybridRecall).toFixed(3)} Ξ=${(recallDelta >= 0 ? '+' : '') + recallDelta.toFixed(3)}`);+ console.log(` MRR baseline=${mean(b.baselineRR).toFixed(3)} hybrid=${mean(b.hybridRR).toFixed(3)} Ξ=${(mrrTest.meanDiff >= 0 ? '+' : '') + mrrTest.meanDiff.toFixed(3)} t=${mrrTest.t.toFixed(2)}`);+ console.log('');++ overallBaselineRecall = overallBaselineRecall.concat(b.baselineRecall);+ overallHybridRecall = overallHybridRecall.concat(b.hybridRecall);+ }++ const overallMean = (arr) => arr.reduce((s, v) => s + v, 0) / arr.length;+ report.overall = {+ n: overallBaselineRecall.length,+ baselineRecallAt10: overallMean(overallBaselineRecall),+ hybridRecallAt10: overallMean(overallHybridRecall),+ recallDelta: overallMean(overallHybridRecall) - overallMean(overallBaselineRecall),+ };+ console.log(`[OVERALL] n=${report.overall.n} recall@10 baseline=${report.overall.baselineRecallAt10.toFixed(3)} hybrid=${report.overall.hybridRecallAt10.toFixed(3)} Ξ=${(report.overall.recallDelta >= 0 ? '+' : '') + report.overall.recallDelta.toFixed(3)}`);++ await registry.shutdown();+ await svc.close();++ const fs = await import('node:fs');+ const path = await import('node:path');+ const outPath = path.join(import.meta.dirname, '..', 'hybridsearch-quality-receipt.json');+ fs.writeFileSync(outPath, JSON.stringify(report, null, 2));+ console.log(`\nReceipt written to ${outPath}`);+}++main().catch((err) => {+ console.error(err);+ process.exit(1);+});diff --git a/v3/@claude-flow/memory/src/controller-registry.ts b/v3/@claude-flow/memory/src/controller-registry.tsindex 060cda8440..4e872a9b08 100644--- a/v3/@claude-flow/memory/src/controller-registry.ts+++ b/v3/@claude-flow/memory/src/controller-registry.ts@@ -68,6 +68,25 @@ export type CLIControllerName =| 'mmrDiversityRanker'| 'guardedVectorBackend';+/**+ * Minimal surface the `hybridSearch` controller needs from a backend when+ * falling back to `this.backend` (no `memoryService` supplied) β the same+ * two methods `AgentDBAdapter` exposes and the only two this factory calls.+ * A named guard instead of ad-hoc `typeof` checks so a future backend that+ * happens to define same-named-but-differently-shaped methods is easier to+ * catch and reason about at one call site (Dream Cycle 2026-08-18).+ */+interface HybridCapableBackend {+ semanticSearch(query: string, k?: number, threshold?: number): Promise<unknown[]>;+ searchKeyword(query: string, options?: { k?: number }): Promise<unknown[]>;+}++function isHybridCapableBackend(backend: unknown): backend is HybridCapableBackend {+ if (!backend || typeof backend !== 'object') return false;+ const b = backend as Record<string, unknown>;+ return typeof b.semanticSearch === 'function' && typeof b.searchKeyword === 'function';+}+/*** All controller names*/@@ -757,9 +776,27 @@ export class ControllerRegistry extends EventEmitter {// independently in parallel, fuses via RRF, diversifies via MMR.// Results carry a `signals` field naming which arms surfaced each// entry (provenance for debugging + downstream rerankers).+ //+ // Dream Cycle 2026-08-18: the auto-enable gate (`isControllerEnabled`)+ // already honors an explicit `controllers: { hybridSearch: true }`+ // override, but until now this factory unconditionally required+ // `config.memoryService` regardless of that override β so explicitly+ // opting in without also hand-building a `UnifiedMemoryService`+ // silently produced a disabled controller (no error, no signal why).+ // When no `memoryService` was supplied, fall back to `this.backend`+ // if it duck-types as AgentDBAdapter-compatible (has `semanticSearch`+ // + `searchKeyword`) β the same two methods this factory already+ // calls below. Only reachable when a caller explicitly requests+ // `hybridSearch`; the default (memoryService-only) auto-enable+ // condition and its behavior are unchanged.const memSvc = this.config.memoryService;- if (!memSvc) return null;- const adapter = typeof memSvc.getAdapter === 'function' ? memSvc.getAdapter() : null;+ const directBackend =+ !memSvc && isHybridCapableBackend(this.backend) ? this.backend : null;+ const adapter = memSvc+ ? typeof memSvc.getAdapter === 'function'+ ? memSvc.getAdapter()+ : null+ : directBackend;if (!adapter) return null;const { applyRRF, applyMMR } = await import('./smart-retrieval.js');diff --git a/v3/@claude-flow/memory/src/graceful-retrieval.test.ts b/v3/@claude-flow/memory/src/graceful-retrieval.test.tsindex 37062cdd42..141b54d942 100644--- a/v3/@claude-flow/memory/src/graceful-retrieval.test.ts+++ b/v3/@claude-flow/memory/src/graceful-retrieval.test.ts@@ -213,6 +213,76 @@ describe('Phase 5 β hybridSearch controller (RRF + MMR)', () => {});});+describe('Dream Cycle 2026-08-18 β hybridSearch explicit opt-in without memoryService', () => {+ it('default behavior is unchanged: backend-only + no explicit override β disabled', async () => {+ const svc = await newSvc({+ embeddingGenerator: async (text: string) => randomVec(8, hashStr(text)),+ });+ const registry = new ControllerRegistry();+ await registry.initialize({ backend: svc.getAdapter() });++ expect(registry.isEnabled('hybridSearch')).toBe(false);+ expect(registry.get('hybridSearch')).toBeNull();++ await registry.shutdown();+ await svc.close();+ });++ it('explicit `controllers: { hybridSearch: true }` + backend (no memoryService) now constructs a working controller', async () => {+ const svc = await newSvc({+ embeddingGenerator: async (text: string) => randomVec(8, hashStr(text)),+ });++ for (let i = 0; i < 20; i++) {+ const entry = createDefaultEntry({+ key: `note-${i}`,+ content: `release process and deployment checklist ${i}`,+ });+ entry.embedding = randomVec(8, hashStr(entry.content));+ await svc.store(entry);+ }++ const registry = new ControllerRegistry();+ // Only `backend` is supplied (the AgentDBAdapter directly) β no+ // `memoryService`. Before the 2026-08-18 fix this silently returned+ // null despite the explicit `true` override.+ await registry.initialize({+ backend: svc.getAdapter(),+ controllers: { hybridSearch: true },+ });++ expect(registry.isEnabled('hybridSearch')).toBe(true);+ const hybrid = registry.get<any>('hybridSearch');+ expect(hybrid).toBeTruthy();+ expect(hybrid.source).toBe('hybrid-rrf-mmr');++ const results = await hybrid.search('deployment checklist', { limit: 5 });+ expect(results.length).toBeGreaterThan(0);+ for (const r of results) {+ expect(Array.isArray(r.signals)).toBe(true);+ expect(r.signals.length).toBeGreaterThan(0);+ }++ await registry.shutdown();+ await svc.close();+ });++ it('explicit override with an incompatible backend (no semanticSearch/searchKeyword) still degrades to null, not a throw', async () => {+ const registry = new ControllerRegistry();+ const incompatibleBackend = {+ initialize: async () => {},+ shutdown: async () => {},+ };+ await registry.initialize({+ backend: incompatibleBackend as any,+ controllers: { hybridSearch: true },+ });++ expect(registry.get('hybridSearch')).toBeNull();+ await registry.shutdown();+ });+});+function hashStr(s: string): number {let h = 0;for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) | 0;