Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
new file mode 100644
index 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.json
new file mode 100644
index 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 file
diff --git a/v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs b/v3/@claude-flow/memory/benchmarks/results/scripts/hybridsearch-quality-benchmark.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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;