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

fix(memory): make the embedder rescue reachable and stop silent NULL embeddings (#3375, #3325) (#3407)

rUv44883dbd1fd1
diff --git a/v3/@claude-flow/cli/__tests__/issue-3325-pattern-embedding-fallback.test.ts b/v3/@claude-flow/cli/__tests__/issue-3325-pattern-embedding-fallback.test.ts
new file mode 100644
index 0000000000..49a1a131a4
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-3325-pattern-embedding-fallback.test.ts
@@ -0,0 +1,200 @@
+/**
+ * Regression for #3325 β€” patterns written through the `bridge-fallback` path
+ * (ReasoningBank unusable, key shape `pattern_<ts>_<hex>`) were persisted with
+ * embedding=NULL, so Tier-1 (semantic) pattern search could never match them.
+ *
+ * `bridgeStoreEntry` embedded only through `ctx.agentdb.embedder`:
+ *
+ * if (embedder) { emb = await embedder.embed(value) ... } catch { /* store without *\/ }
+ *
+ * so BOTH an absent embedder and a throwing `embed()` silently wrote a NULL
+ * vector and returned success with nothing to say so. The query side of
+ * `bridgeSearchEntries` had the same shape, so even a vector-bearing row could
+ * not be matched semantically when the agentdb embedder was down.
+ *
+ * Fix: fall back to the LOCAL chain (`generateLocalEmbedding`, never the
+ * bridge-first `generateEmbedding` β€” #2312) on both sides; when no real vector
+ * can be produced, report `hasEmbedding: false` + `embeddingError` instead of
+ * staying silent. Also: `bridgeGetEntry` reported `hasEmbedding: false` on
+ * every TieredCache hit, which is one way a `memory_retrieve` can show
+ * `hasEmbedding: false` for a row that does have a vector.
+ *
+ * The local chain is a mocked ruvector ONNX embedder whose vectors are
+ * CONCEPT-keyed, so the search below can only succeed semantically: the query
+ * shares no words with the stored pattern. No network, no real model.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import Database from 'better-sqlite3';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const local = vi.hoisted(() => ({
+ ruvectorAvailable: true,
+ // Two orthogonal "concepts"; any text about retrying-with-delay maps to A.
+ vec(text: string): number[] {
+ const a = /backoff|retry|retries|reconnect|wait/i.test(text);
+ return Array.from({ length: 384 }, (_, i) => (a ? (i % 2 === 0 ? 1 : 0) : (i % 2 === 0 ? 0 : 1)));
+ },
+}));
+
+vi.mock('@huggingface/transformers', () => ({ pipeline: undefined }));
+vi.mock('@xenova/transformers', () => ({ pipeline: undefined }));
+vi.mock('agentic-flow/reasoningbank', () => ({ computeEmbedding: undefined }));
+vi.mock('agentic-flow', () => ({ embeddings: undefined }));
+vi.mock('ruvector', () => ({
+ get initOnnxEmbedder() {
+ return local.ruvectorAvailable ? async () => {} : undefined;
+ },
+ getOptimizedOnnxEmbedder: () => ({ embed: async (t: string) => local.vec(t) }),
+}));
+
+const PATTERN = 'use exponential backoff for flaky network retries';
+// No token of length > 1 in common with PATTERN (or its JSON envelope).
+const QUERY = 'wait longer between reconnect attempts';
+
+let root: string;
+let dbPath: string;
+let db: Database.Database;
+
+type AgentdbEmbedder = { pipeline?: unknown; embed: (t: string) => Promise<Float32Array> } | null;
+
+async function setup(embedder: AgentdbEmbedder, cache?: Map<string, unknown>) {
+ vi.resetModules();
+ // Load memory-initializer up front. When the bridge's fire-and-forget rescue
+ // and the write path dynamic-import modules at the same moment, vitest's
+ // module runner was observed to hand one caller a partially-evaluated
+ // memory-initializer (TDZ error) or the real, un-mocked `ruvector`. Native
+ // ESM awaits one evaluation for both, so this removes a test-runner
+ // artifact. The cases below also keep the rescue out of the picture (either
+ // no embedder, or `pipeline` set) so they test the write path alone.
+ await import('../src/memory/memory-initializer.js');
+ const bridge = await import('../src/memory/memory-bridge.js');
+ bridge.__setMemoryBridgeRegistryForTests({
+ getAgentDB: () => ({ database: db, embedder }),
+ // reasoningBank β†’ null forces bridgeStorePattern into `bridge-fallback`.
+ get: (name: string) => (name === 'tieredCache' && cache ? cache : null),
+ });
+ const tools = await import('../src/mcp-tools/agentdb-tools.js');
+ return { bridge, tools };
+}
+
+function storedEmbedding(patternId: string): string | null {
+ const row = db.prepare('SELECT embedding FROM memory_entries WHERE key = ?').get(patternId) as
+ | { embedding: string | null }
+ | undefined;
+ return row ? row.embedding : null;
+}
+
+beforeEach(() => {
+ delete process.env.CLAUDE_FLOW_DISABLE_BRIDGE;
+ delete process.env.RUFLO_REQUIRE_REAL_EMBEDDINGS;
+ local.ruvectorAvailable = true;
+ root = mkdtempSync(join(tmpdir(), 'ruflo-3325-'));
+ dbPath = join(root, 'memory.db');
+ db = new Database(dbPath);
+});
+
+afterEach(async () => {
+ const { __setMemoryBridgeRegistryForTests } = await import('../src/memory/memory-bridge.js');
+ __setMemoryBridgeRegistryForTests(null);
+ db.close();
+ rmSync(root, { recursive: true, force: true });
+});
+
+describe('#3325 bridge-fallback pattern writes get an embedding', () => {
+ it.each([
+ ['agentdb embedder absent', null],
+ // transformers.js loaded (pipeline set, so the rescue stays out of it) but
+ // inference throws β€” the realistic way agentdb's embed() fails.
+ ['agentdb embed() throws', { pipeline: {}, embed: async () => { throw new Error('onnx session failed'); } }],
+ ] as Array<[string, AgentdbEmbedder]>)('%s -> falls back to the local chain', async (_label, embedder) => {
+ const { bridge } = await setup(embedder);
+
+ const stored = await bridge.bridgeStorePattern({ pattern: PATTERN, type: 'error-recovery', confidence: 0.9, dbPath });
+
+ expect(stored?.controller).toBe('bridge-fallback');
+ // Pre-fix: embedding column NULL, and no field saying so.
+ expect(storedEmbedding(stored!.patternId)).not.toBeNull();
+ expect(stored!.hasEmbedding).toBe(true);
+ expect(stored!.embeddingError).toBeUndefined();
+ });
+
+ it('when no real vector is available anywhere, the write says so', async () => {
+ local.ruvectorAvailable = false;
+ const { bridge } = await setup(null);
+
+ const stored = await bridge.bridgeStorePattern({ pattern: PATTERN, type: 'error-recovery', confidence: 0.9, dbPath });
+
+ expect(stored?.success).toBe(true);
+ expect(storedEmbedding(stored!.patternId)).toBeNull();
+ // Pre-fix: neither field existed β€” a vector-less write was indistinguishable
+ // from a healthy one.
+ expect(stored!.hasEmbedding).toBe(false);
+ expect(stored!.embeddingError).toMatch(/agentdb embedder unavailable/);
+ expect(stored!.embeddingError).toMatch(/backend=mock/);
+ });
+
+ it('does not store agentdb mock vectors as if they were real', async () => {
+ local.ruvectorAvailable = false;
+ // What the rescue leaves behind when it cannot replace a degraded embedder.
+ const mock = { pipeline: {}, backend: 'mock', embed: async () => new Float32Array(384).fill(0.25) };
+ const { bridge } = await setup(mock as AgentdbEmbedder);
+
+ const stored = await bridge.bridgeStorePattern({ pattern: PATTERN, type: 'error-recovery', confidence: 0.9, dbPath });
+
+ expect(storedEmbedding(stored!.patternId)).toBeNull();
+ expect(stored!.hasEmbedding).toBe(false);
+ expect(stored!.embeddingError).toMatch(/serving mock vectors/);
+ });
+
+ it('agentdb_pattern-store surfaces the missing embedding on the degraded response', async () => {
+ local.ruvectorAvailable = false;
+ const { tools } = await setup(null);
+
+ const r = (await tools.agentdbPatternStore.handler({ pattern: PATTERN, type: 'error-recovery' })) as Record<string, unknown>;
+ expect(r.degraded).toBe(true);
+ expect(r.hasEmbedding).toBe(false);
+ expect(String(r.embeddingError)).toMatch(/agentdb embedder unavailable/);
+ });
+});
+
+describe('#3325 a bridge-fallback pattern is found semantically', () => {
+ it('agentdb_pattern-search finds it with a query that shares no words with it', async () => {
+ const { tools } = await setup(null);
+
+ const stored = (await tools.agentdbPatternStore.handler({ pattern: PATTERN, type: 'error-recovery', confidence: 0.9 })) as {
+ patternId: string;
+ };
+ const found = (await tools.agentdbPatternSearch.handler({ query: QUERY, topK: 5 })) as {
+ results: Array<{ id?: string; patternId?: string; content?: string; pattern?: string }>;
+ };
+
+ // Pre-fix: row embedding NULL and query embedding null -> BM25 only -> 0
+ // hits -> tier 2 substring -> no match -> [].
+ const ids = found.results.map(r => r.patternId ?? r.id);
+ const texts = found.results.map(r => String(r.pattern ?? r.content ?? ''));
+ expect(found.results.length).toBeGreaterThan(0);
+ expect(texts.some(t => t.includes('exponential backoff')) || ids.includes(stored.patternId)).toBe(true);
+ });
+});
+
+describe('#3325 bridgeGetEntry reports hasEmbedding truthfully on a cache hit', () => {
+ it('second (cached) read of an embedded row still says hasEmbedding: true', async () => {
+ const cache = new Map<string, unknown>();
+ // A healthy agentdb embedder, so this case isolates the cache read.
+ const healthy = { pipeline: {}, embed: async (t: string) => new Float32Array(local.vec(t)) };
+ const { bridge } = await setup(healthy, cache);
+ const stored = await bridge.bridgeStorePattern({ pattern: PATTERN, type: 'error-recovery', confidence: 0.9, dbPath });
+ expect(storedEmbedding(stored!.patternId)).not.toBeNull();
+
+ const first = await bridge.bridgeGetEntry({ key: stored!.patternId, namespace: 'pattern', dbPath });
+ const second = await bridge.bridgeGetEntry({ key: stored!.patternId, namespace: 'pattern', dbPath });
+
+ expect(first?.cacheHit).toBe(false);
+ expect(first?.entry?.hasEmbedding).toBe(true);
+ expect(second?.cacheHit).toBe(true);
+ // Pre-fix: `!!cached.embedding` β€” the cached entry has no `embedding` field.
+ expect(second?.entry?.hasEmbedding).toBe(true);
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/issue-3375-rescue-local-embedder.test.ts b/v3/@claude-flow/cli/__tests__/issue-3375-rescue-local-embedder.test.ts
new file mode 100644
index 0000000000..9b19ae3a34
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-3375-rescue-local-embedder.test.ts
@@ -0,0 +1,171 @@
+/**
+ * Regression for #3375: `rescueAgentdbEmbedder()` could never fire.
+ *
+ * The rescue exists for one situation: agentdb's EmbeddingService failed to
+ * load transformers.js (`embedder.pipeline === null`) and is serving mock
+ * vectors. It probes `generateLocalEmbedding()` and only patches agentdb's
+ * embedder when the probe reports `backend === 'onnx'`.
+ *
+ * `generateLocalEmbedding()` is documented as "ONLY the local model chain β€”
+ * never the AgentDB bridge", but it lazily loaded its model through
+ * `loadEmbeddingModel()`, which is bridge-first. Whenever the bridge was up
+ * (always, since the rescue is only ever called from inside the bridge),
+ * `bridgeLoadEmbeddingModel()` succeeded against agentdb's MOCK embedder and
+ * the local state was recorded as `{ loaded: true, model: null }`. `null` can
+ * never pass `typeof state.model === 'function'`, so every call took the hash
+ * branch and reported `backend: 'mock'`, and the rescue always bailed.
+ *
+ * The scenario is reproduced here with a real memory-bridge + memory-initializer,
+ * a real better-sqlite3 database behind the documented registry seam, agentdb's
+ * embedder in its degraded (pipeline=null, mock vectors) state, and a mocked
+ * ruvector ONNX embedder standing in for a working local chain. No network.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import Database from 'better-sqlite3';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const local = vi.hoisted(() => ({
+ ruvectorAvailable: true,
+ // Deterministic, non-zero, text-dependent 384-d "ONNX" vector.
+ vec(text: string): number[] {
+ let h = 0;
+ for (let i = 0; i < text.length; i++) h = (h * 31 + text.charCodeAt(i)) | 0;
+ return Array.from({ length: 384 }, (_, i) => Math.sin(h + i * 7) + 1.5);
+ },
+}));
+
+// Every local-chain branch ahead of ruvector is made unavailable so the test
+// is deterministic and never touches the network or a real model.
+// (Explicit `undefined` exports: vitest throws on reading an export a mock
+// factory did not define.)
+vi.mock('@huggingface/transformers', () => ({ pipeline: undefined }));
+vi.mock('@xenova/transformers', () => ({ pipeline: undefined }));
+vi.mock('agentic-flow/reasoningbank', () => ({ computeEmbedding: undefined }));
+vi.mock('agentic-flow', () => ({ embeddings: undefined }));
+vi.mock('ruvector', () => ({
+ get initOnnxEmbedder() {
+ return local.ruvectorAvailable ? async () => {} : undefined;
+ },
+ getOptimizedOnnxEmbedder: () => ({ embed: async (t: string) => local.vec(t) }),
+}));
+
+let root: string;
+let db: Database.Database;
+let mockEmbedCalls: number;
+
+/** agentdb's EmbeddingService after transformers.js failed to load. */
+function degradedAgentdbEmbedder() {
+ return {
+ pipeline: null as unknown,
+ backend: undefined as string | undefined,
+ __ruvectorRescued: undefined as boolean | undefined,
+ embed: async (_t: string) => {
+ mockEmbedCalls++;
+ return new Float32Array(384).fill(0.25);
+ },
+ };
+}
+
+async function freshModules(embedder: ReturnType<typeof degradedAgentdbEmbedder>) {
+ vi.resetModules();
+ const bridge = await import('../src/memory/memory-bridge.js');
+ const init = await import('../src/memory/memory-initializer.js');
+ bridge.__setMemoryBridgeRegistryForTests({
+ getAgentDB: () => ({ database: db, embedder }),
+ get: () => null,
+ });
+ return { bridge, init };
+}
+
+async function waitFor(pred: () => boolean, ms = 2000): Promise<boolean> {
+ const end = Date.now() + ms;
+ while (Date.now() < end) {
+ if (pred()) return true;
+ await new Promise(r => setTimeout(r, 5));
+ }
+ return pred();
+}
+
+beforeEach(() => {
+ delete process.env.CLAUDE_FLOW_DISABLE_BRIDGE;
+ delete process.env.RUFLO_REQUIRE_REAL_EMBEDDINGS;
+ local.ruvectorAvailable = true;
+ mockEmbedCalls = 0;
+ root = mkdtempSync(join(tmpdir(), 'ruflo-3375-'));
+ db = new Database(join(root, 'memory.db'));
+});
+
+afterEach(async () => {
+ const { __setMemoryBridgeRegistryForTests } = await import('../src/memory/memory-bridge.js');
+ __setMemoryBridgeRegistryForTests(null);
+ db.close();
+ rmSync(root, { recursive: true, force: true });
+});
+
+describe('#3375 generateLocalEmbedding stays on the local chain', () => {
+ it('reports onnx after loadEmbeddingModel() took the bridge branch', async () => {
+ const emb = degradedAgentdbEmbedder();
+ const { init } = await freshModules(emb);
+
+ // The bridge branch is what poisoned the local state before the fix.
+ const loaded = await init.loadEmbeddingModel();
+ expect(loaded.success).toBe(true);
+
+ const out = await init.generateLocalEmbedding('hello world');
+ // Pre-fix: backend 'mock', model 'hash-fallback' (state.model === null).
+ expect(out.backend).toBe('onnx');
+ expect(out.embedding).toEqual(local.vec('hello world'));
+ });
+
+ it('never consults the agentdb embedder (the #2312 no-recursion contract)', async () => {
+ const emb = degradedAgentdbEmbedder();
+ const { init } = await freshModules(emb);
+
+ await init.generateLocalEmbedding('probe');
+ // Pre-fix, generateLocalEmbedding -> loadEmbeddingModel ->
+ // bridgeLoadEmbeddingModel -> embedder.embed('test').
+ expect(mockEmbedCalls).toBe(0);
+ });
+
+ it('still reports mock (no false positive) when no local embedder exists either', async () => {
+ local.ruvectorAvailable = false;
+ const emb = degradedAgentdbEmbedder();
+ const { init } = await freshModules(emb);
+
+ const out = await init.generateLocalEmbedding('hello world');
+ expect(out.backend).toBe('mock');
+ });
+});
+
+describe('#3375 rescueAgentdbEmbedder can fire', () => {
+ it('patches a degraded agentdb embedder to the working local chain', async () => {
+ const emb = degradedAgentdbEmbedder();
+ const { bridge } = await freshModules(emb);
+
+ // Any bridge operation runs getDb(), which kicks off the rescue.
+ await bridge.bridgeGetEntry({ key: 'nothing', namespace: 'default' });
+ const rescued = await waitFor(() => emb.__ruvectorRescued === true || emb.backend === 'mock');
+
+ expect(rescued).toBe(true);
+ // Pre-fix: the probe came back 'mock', so the rescue tagged the embedder
+ // backend='mock' and left agentdb's mock embed() in place.
+ expect(emb.backend).toBeUndefined();
+ expect(emb.__ruvectorRescued).toBe(true);
+ const v = await emb.embed('rescued text');
+ expect(Array.from(v)).toEqual(local.vec('rescued text').map(x => Math.fround(x)));
+ });
+
+ it('declines the rescue and tags backend=mock when the local chain is degraded too', async () => {
+ local.ruvectorAvailable = false;
+ const emb = degradedAgentdbEmbedder();
+ const { bridge } = await freshModules(emb);
+
+ await bridge.bridgeGetEntry({ key: 'nothing', namespace: 'default' });
+ await waitFor(() => emb.__ruvectorRescued === true || emb.backend === 'mock');
+
+ expect(emb.__ruvectorRescued).not.toBe(true);
+ expect(emb.backend).toBe('mock');
+ });
+});
diff --git a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
index 2ca7fae315..9930cd5305 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
@@ -513,6 +513,8 @@ export const memoryTools: MCPTool[] = [
backend: await describeBackend(),
storeTime: `${duration.toFixed(2)}ms`,
error: result.error,
+ // #3325: why hasEmbedding is false, when the bridge could not embed.
+ ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
};
} catch (error) {
return {
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 37f5033c6b..948ef83b11 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -830,6 +830,53 @@ async function rescueAgentdbEmbedder(agentdb: { embedder?: { pipeline?: unknown;
_embedderPatched = true;
}
+/**
+ * #3325: embed text for a bridge row or query.
+ *
+ * AgentDB's embedder is tried first. If it is absent or throws, fall back to
+ * the LOCAL chain β€” `generateLocalEmbedding`, never the bridge-first
+ * `generateEmbedding`, which would re-enter this bridge (#2312). Only a real
+ * ONNX vector is accepted from the local chain; a hash vector would make the
+ * row look embedded while carrying no meaning. Previously both failure modes
+ * were a bare `catch {}` that stored embedding=NULL and reported nothing.
+ */
+async function embedForBridge(
+ agentdb: { embedder?: { embed?: (t: string) => Promise<ArrayLike<number> | null | undefined>; isMock?: boolean; backend?: string } } | null | undefined,
+ text: string,
+): Promise<{ vector: number[]; model: string } | { vector: null; reason: string }> {
+ let agentdbProblem: string;
+ const embedder = agentdb?.embedder;
+ // Same mock signal bridgeGenerateEmbedding honours (AUDIT #3): the rescue
+ // tags a degraded embedder backend='mock' when it cannot replace it.
+ const agentdbIsMock = embedder?.isMock === true || embedder?.backend === 'mock';
+ if (agentdbIsMock) {
+ agentdbProblem = 'agentdb embedder is serving mock vectors';
+ } else if (embedder && typeof embedder.embed === 'function') {
+ try {
+ const emb = await embedder.embed(text);
+ if (emb && emb.length > 0) {
+ return { vector: Array.from(emb), model: 'Xenova/all-MiniLM-L6-v2' };
+ }
+ agentdbProblem = 'agentdb embedder returned no vector';
+ } catch (err) {
+ agentdbProblem = `agentdb embedder threw: ${err instanceof Error ? err.message : String(err)}`;
+ }
+ } else {
+ agentdbProblem = 'agentdb embedder unavailable';
+ }
+
+ try {
+ const { generateLocalEmbedding } = await import('./memory-initializer.js');
+ const local = await generateLocalEmbedding(text);
+ if (local.backend === 'onnx' && local.embedding.length > 0) {
+ return { vector: Array.from(local.embedding), model: local.model };
+ }
+ return { vector: null, reason: `${agentdbProblem}; local embedding chain has no real model (backend=${local.backend})` };
+ } catch (err) {
+ return { vector: null, reason: `${agentdbProblem}; local embedding chain failed: ${err instanceof Error ? err.message : String(err)}` };
+ }
+}
+
// ===== Bridge functions β€” match memory-initializer.ts signatures =====
/**
@@ -864,6 +911,10 @@ export async function bridgeStoreEntry(options: {
* still true β€” this is advisory, not a failure β€” but callers should
* surface it instead of only printing an unconditional success message. */
persistWarning?: string;
+ /** #3325: set when an embedding was requested but none could be produced
+ * (agentdb embedder absent/threw AND no real local model). The row was
+ * written without a vector, so semantic search cannot find it. */
+ embeddingError?: string;
} | null> {
// ADR-323 β€” validated once in storeEntry() before this is reached on that
// path, but bridgeStoreEntry() also has direct internal callers, so check
@@ -912,26 +963,24 @@ export async function bridgeStoreEntry(options: {
return { success: false, id, error: `MutationGuard rejected: ${guardResult.reason}` };
}
- // Generate embedding via AgentDB's embedder
+ // Generate embedding via AgentDB's embedder, falling back to the local
+ // chain (#3325). If neither can produce one, the row is still written but
+ // the result says why instead of silently storing embedding=NULL.
let embeddingJson: string | null = null;
let embeddingArr: number[] | null = null;
let dimensions = 0;
let model = 'local';
+ let embeddingError: string | undefined;
if (options.generateEmbeddingFlag !== false && value.length > 0) {
- try {
- const embedder = ctx.agentdb.embedder;
- if (embedder) {
- const emb = await embedder.embed(value);
- if (emb) {
- embeddingArr = Array.from(emb) as number[];
- embeddingJson = JSON.stringify(embeddingArr);
- dimensions = emb.length;
- model = 'Xenova/all-MiniLM-L6-v2';
- }
- }
- } catch {
- // Embedding failed β€” store without
+ const emb = await embedForBridge(ctx.agentdb, value);
+ if (emb.vector) {
+ embeddingArr = emb.vector;
+ embeddingJson = JSON.stringify(embeddingArr);
+ dimensions = embeddingArr.length;
+ model = emb.model;
+ } else {
+ embeddingError = emb.reason;
}
}
@@ -1089,6 +1138,7 @@ export async function bridgeStoreEntry(options: {
cached: true,
attested: true,
...(persistWarning ? { persistWarning } : {}),
+ ...(embeddingError ? { embeddingError } : {}),
};
} catch (err) {
// #2775: distinguish a data-level UNIQUE constraint violation (key
@@ -1165,17 +1215,10 @@ export async function bridgeSearchEntries(options: {
const effectiveNamespace = namespace || 'all';
const startTime = Date.now();
- // Generate query embedding
- let queryEmbedding: number[] | null = null;
- try {
- const embedder = ctx.agentdb.embedder;
- if (embedder) {
- const emb = await embedder.embed(queryStr);
- queryEmbedding = Array.from(emb);
- }
- } catch {
- // Fall back to keyword search
- }
+ // Generate query embedding β€” same agentdb-then-local chain as the write
+ // path (#3325), so rows embedded by the local fallback are searchable.
+ // No vector β†’ keyword (BM25) search only.
+ const queryEmbedding: number[] | null = (await embedForBridge(ctx.agentdb, queryStr)).vector;
// better-sqlite3: .prepare().all() returns array of objects
// ADR-323: compose namespace + provenance filters into one WHERE clause.
@@ -1465,7 +1508,10 @@ export async function bridgeGetEntry(options: {
accessCount: cached.accessCount ?? 0,
createdAt: cached.createdAt || new Date().toISOString(),
updatedAt: cached.updatedAt || new Date().toISOString(),
- hasEmbedding: !!cached.embedding,
+ // #3325: the cache holds the `entry` object built below, which has
+ // `hasEmbedding` but no `embedding` field β€” so `!!cached.embedding`
+ // reported false on every cache hit, even for embedded rows.
+ hasEmbedding: typeof cached.hasEmbedding === 'boolean' ? cached.hasEmbedding : !!cached.embedding,
tags: cached.tags || [],
},
};
@@ -2086,7 +2132,7 @@ export async function bridgeStorePattern(options: {
confidence: number;
metadata?: Record<string, unknown>;
dbPath?: string;
-}): Promise<{ success: boolean; patternId: string; controller: string } | null> {
+}): Promise<{ success: boolean; patternId: string; controller: string; hasEmbedding?: boolean; embeddingError?: string } | null> {
const registry = await getRegistry(options.dbPath);
if (!registry) return null;
@@ -2154,7 +2200,15 @@ export async function bridgeStorePattern(options: {
// was actually stored under. getEntry/memory_retrieve look up by `key`,
// so returning result.id here handed the caller a handle that can never
// be read back β€” return `patternId` (the real key) instead.
- return { success: true, patternId, controller: 'bridge-fallback' };
+ // #3325: say whether the row got a vector. Without one, Tier-1 (semantic)
+ // pattern search cannot find it β€” report that here, at write time.
+ return {
+ success: true,
+ patternId,
+ controller: 'bridge-fallback',
+ hasEmbedding: !!result.embedding,
+ ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
+ };
} catch (err) {
// #3327 Finding A β€” this catch is what hid the defect for months. When
// ReasoningBank threw `embedPassage is not a function`, the error was
diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
index a66248e0c8..b0d82635da 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -2204,7 +2204,17 @@ interface EmbeddingModel {
dimensions: number;
}
+/**
+ * State of the LOCAL embedding chain only (transformers.js / agentic-flow /
+ * ruvector ONNX / hash). #3375: the AgentDB bridge's result is cached
+ * separately in `bridgeEmbeddingInfo` and must never be written here β€” it used
+ * to be recorded as `{ loaded: true, model: null }`, which made
+ * generateLocalEmbedding() skip loading any local model and always return the
+ * hash fallback, so rescueAgentdbEmbedder()'s `backend === 'onnx'` probe could
+ * never pass.
+ */
let embeddingModelState: EmbeddingModel | null = null;
+let bridgeEmbeddingInfo: { dimensions: number } | null = null;
/**
* Lazy load ONNX embedding model
@@ -2224,10 +2234,11 @@ export async function loadEmbeddingModel(options?: {
const startTime = Date.now();
// Already loaded
- if (embeddingModelState?.loaded) {
+ const cached = bridgeEmbeddingInfo ?? (embeddingModelState?.loaded ? embeddingModelState : null);
+ if (cached) {
return {
success: true,
- dimensions: embeddingModelState.dimensions,
+ dimensions: cached.dimensions,
modelName: 'cached',
loadTime: 0
};
@@ -2238,17 +2249,33 @@ export async function loadEmbeddingModel(options?: {
if (bridge) {
const bridgeResult = await bridge.bridgeLoadEmbeddingModel();
if (bridgeResult && bridgeResult.success) {
- // Mark local state as loaded too so subsequent calls use cache
- embeddingModelState = {
- loaded: true,
- model: null, // Bridge handles embedding
- tokenizer: null,
- dimensions: bridgeResult.dimensions
- };
+ // #3375: cache the bridge result on its own. Do NOT mark the local
+ // chain as loaded β€” the bridge's model is not callable from here.
+ bridgeEmbeddingInfo = { dimensions: bridgeResult.dimensions };
return bridgeResult;
}
}
+ return loadLocalEmbeddingChain(verbose, startTime);
+}
+
+/**
+ * Load the LOCAL embedding chain into `embeddingModelState`, never consulting
+ * the AgentDB bridge. Used by loadEmbeddingModel() after the bridge declines,
+ * and directly by generateLocalEmbedding() so the "bridge-free" contract the
+ * #2312 comment on that function describes actually holds (#3375).
+ */
+async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now()): Promise<{
+ success: boolean;
+ dimensions: number;
+ modelName: string;
+ loadTime?: number;
+ error?: string;
+}> {
+ if (embeddingModelState?.loaded) {
+ return { success: true, dimensions: embeddingModelState.dimensions, modelName: 'cached', loadTime: 0 };
+ }
+
try {
// ADR-094: prefer @huggingface/transformers (clears protobufjs <7.5.5
// critical RCE chain), fall back to legacy @xenova/transformers.
@@ -2480,9 +2507,12 @@ export async function generateLocalEmbedding(text: string): Promise<{
model: string;
backend: 'onnx' | 'mock';
}> {
- // Ensure model is loaded
+ // Ensure the LOCAL model is loaded. #3375: this must not go through
+ // loadEmbeddingModel(), which is bridge-first β€” when the bridge answered
+ // there, no local model was ever loaded and this function always returned
+ // the hash fallback.
if (!embeddingModelState?.loaded) {
- await loadEmbeddingModel();
+ await loadLocalEmbeddingChain();
}
// #2461: loadEmbeddingModel() can leave embeddingModelState null when an
@@ -2851,6 +2881,9 @@ export async function storeEntry(options: {
/** #2968: set when the bridge's checkpoint failed in a way indicating
* this write may not be durably persisted (sql.js fallback driver). */
persistWarning?: string;
+ /** #3325: set by the bridge when an embedding was requested but none could
+ * be produced β€” the row is stored without a vector. */
+ embeddingError?: string;
}> {
// ADR-323: validate before touching either backend so an invalid value
// gets one clear error instead of a raw SQLite CHECK-constraint failure