@claude-flow/cli 3.66.2 → 3.68.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.66.2",
+    "version": "3.68.0",
     "files": {
       "auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",
       "hook-handler.cjs": "0ce70981aa33f76d008b6f49626effaf4269918c4094f1a28c1ef6fceb097d6f",
@@ -10,6 +10,6 @@
       "learning-loop.cjs": "d046cd6f8efb7dd40e1d2451516c181fc8b26477aefb1124c0df5f52a23f9190"
     }
   },
-  "signature": "if1ToBugZK6ce9z+01Bfo3otxr+WTji2wwDw5u13NQjm0g2pKboaTUOQ9t/LRV1Gq52NPX9abgU3/KEQn6AeAw==",
+  "signature": "hlbaMRRdeS+x8RDQSG0gdJuZhV7d1pJKr+ut6Gy3w4y72vxS2tbe/R1G+zs5WUtCfX5/bkzh/U9YBDqsMiovCA==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -245,6 +245,8 @@ This adds slash commands and agent definitions. `ruflo-core` (installed above) d
 | [**ruflo-jujutsu**](plugins/ruflo-jujutsu/README.md) | Analyze git diffs, score risk, suggest reviewers |
 | [**ruflo-docs**](plugins/ruflo-docs/README.md) | Generate and maintain documentation automatically |
 | [**agentic-qe-fleet**](https://github.com/proffesor-for-testing/agentic-qe/tree/v3.15.17/plugins/agentic-qe-fleet) | External, maintained by [Agentic QE](https://github.com/proffesor-for-testing/agentic-qe): 11 QE agents, test generation, coverage, chaos and TDD skills, the `agentic-qe` MCP server, and a guard for AQE learning data (`/plugin install agentic-qe-fleet@ruflo`). Install it from one marketplace only, `agentic-qe` or `ruflo`: enabled from both, its mod and commands load twice |
+| [**agentdb**](https://github.com/ruvnet/agentdb/tree/plugin-v3.2.0/plugins/agentdb) | External, maintained in [ruvnet/agentdb](https://github.com/ruvnet/agentdb): agentdb's own MCP server (pinned `agentdb@3.2.0`: hybrid keyword + vector search, opt-in cross-encoder rerank), a memory-specialist agent, vector-memory / learning / diagnostics skills, `/agentdb-status`, and a guard that keeps secrets out of memory and refuses delete/reset unless allowed (`/plugin install agentdb@ruflo`). Use `ruflo-agentdb` instead if you want AgentDB through ruflo's server; the two can coexist. Install it from one marketplace only, `agentdb` or `ruflo` |
+| [**agentic-flow**](https://github.com/ruvnet/agentic-flow/tree/plugin-v3.1.0/plugins/agentic-flow) | External, maintained in [ruvnet/agentic-flow](https://github.com/ruvnet/agentic-flow): the agentic-flow MCP server (pinned `agentic-flow@3.1.0`, `readonly` profile by default, nothing pre-approved), ReasoningBank and model-router agents, routing / learning / autopilot skills, `/agentic-flow-status`, and a guard on `agentic_flow_agent` (`/plugin install agentic-flow@ruflo`). Install it from one marketplace only, `agentic-flow` or `ruflo` |
 
 #### Security & Compliance
 

package/catalog-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-31T18:12:16.494Z",
-  "gitSha": "bd77bced",
+  "generatedAt": "2026-11-01T04:34:21.063Z",
+  "gitSha": "2b1a3927",
   "catalog": {
     "agents": 177,
-    "tools": 445,
+    "tools": 446,
     "skills": 34
   },
   "benchmark": null

package/dist/src/init/executor.js

@@ -2022,7 +2022,7 @@ npx @claude-flow/cli@latest hive-mind consensus --propose "task"
 ### Integrated Packages
 | Package | Version | Purpose |
 |---------|---------|---------|
-| agentic-flow | 3.0.0-alpha.1 | Core coordination + ReasoningBank + Router |
+| agentic-flow | 3.0.0 | Core coordination + ReasoningBank + Router |
 | agentdb | 3.0.0-alpha.10 | Vector database + 8 controllers |
 | @ruvector/attention | 0.1.3 | Flash attention |
 | @ruvector/sona | 0.1.5 | Neural learning |

package/dist/src/mcp-tools/agentdb-tools.d.ts

@@ -20,6 +20,7 @@ export declare const agentdbCausalEdge: MCPTool;
 export declare const agentdbRoute: MCPTool;
 export declare const agentdbSessionStart: MCPTool;
 export declare const agentdbSessionEnd: MCPTool;
+export declare const agentdbEpisodeRecall: MCPTool;
 export declare const agentdbHierarchicalStore: MCPTool;
 export declare const agentdbHierarchicalRecall: MCPTool;
 export declare const agentdbConsolidate: MCPTool;

package/dist/src/mcp-tools/agentdb-tools.js

@@ -633,12 +633,16 @@ export const agentdbRoute = {
 // ===== agentdb_session_start — Session with ReflexionMemory =====
 export const agentdbSessionStart = {
     name: 'agentdb_session-start',
-    description: 'Start a session with ReflexionMemory episodic replay Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
+    description: 'Start a session with ReflexionMemory episodic replay. Set recall=true with a context to get back past session episodes relevant to it (keyword + vector search; rerank=true adds a local cross-encoder, ~200 ms). Use when generic memory_* tools are wrong because you need AgentDB-specific controllers (HNSW vector search, hierarchical tiers, causal-graph links, pattern store/recall, RaBitQ quantization). For simple key-value persistence, memory_store/memory_retrieve are simpler. For unrelated file work, native Read/Write are fine.',
     inputSchema: {
         type: 'object',
         properties: {
             sessionId: { type: 'string', description: 'Session identifier' },
             context: { type: 'string', description: 'Session context for pattern retrieval' },
+            recall: { type: 'boolean', description: 'Also return past session episodes relevant to context', default: false },
+            k: { type: 'number', description: 'Episodes to recall (1-50)', default: 5 },
+            hybrid: { type: 'boolean', description: 'Keyword + vector search; false = vector only', default: true },
+            rerank: { type: 'boolean', description: 'Rerank with a local cross-encoder (~200 ms, 23 MB model on first use)', default: false },
         },
         required: ['sessionId'],
     },
@@ -659,6 +663,10 @@ export const agentdbSessionStart = {
             const result = await bridge.bridgeSessionStart({
                 sessionId,
                 context: validateString(params.context, 'context', 10_000) ?? undefined,
+                recall: params.recall === true,
+                k: validatePositiveInt(params.k, 5, 50),
+                hybrid: params.hybrid !== false,
+                rerank: params.rerank === true,
             });
             return result ?? { success: false, error: 'AgentDB bridge not available. Use memory_store/memory_search instead.' };
         }
@@ -706,6 +714,53 @@ export const agentdbSessionEnd = {
         }
     },
 };
+// ===== agentdb_episode-recall — agentdb 3.2 hybrid episode retrieval (ADR-519) =====
+export const agentdbEpisodeRecall = {
+    name: 'agentdb_episode-recall',
+    description: 'Recall past episodes (session summaries, distilled trajectories) relevant to a task, ranked by keyword + vector search. rerank=true adds a local cross-encoder for better ordering at ~200 ms per call. Use when you want what happened last time on similar work; for key-value entries use memory_search.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: { type: 'string', description: 'What you are about to work on' },
+            k: { type: 'number', description: 'Episodes to return (1-50)', default: 5 },
+            hybrid: { type: 'boolean', description: 'Keyword + vector search; false = vector only', default: true },
+            rerank: { type: 'boolean', description: 'Rerank with a local cross-encoder (~200 ms, 23 MB model on first use)', default: false },
+            onlySuccesses: { type: 'boolean', description: 'Only episodes recorded as successes' },
+            onlyFailures: { type: 'boolean', description: 'Only episodes recorded as failures' },
+            minReward: { type: 'number', description: 'Minimum reward (0-1)' },
+            timeWindowDays: { type: 'number', description: 'Only episodes from the last N days' },
+        },
+        required: ['query'],
+    },
+    handler: async (params) => {
+        try {
+            const vQuery = validateText(params.query, 'query', 10_000);
+            if (!vQuery.valid)
+                return { success: false, error: vQuery.error };
+            const query = validateString(params.query, 'query', 10_000);
+            if (!query || !query.trim())
+                return { success: false, error: 'query is required (non-empty string)' };
+            if (params.onlySuccesses === true && params.onlyFailures === true) {
+                return { success: false, error: 'onlySuccesses and onlyFailures are mutually exclusive' };
+            }
+            const bridge = await getBridge();
+            const result = await bridge.bridgeRecallEpisodes({
+                task: query,
+                k: validatePositiveInt(params.k, 5, 50),
+                hybrid: params.hybrid !== false,
+                rerank: params.rerank === true,
+                onlySuccesses: params.onlySuccesses === true,
+                onlyFailures: params.onlyFailures === true,
+                ...(typeof params.minReward === 'number' && Number.isFinite(params.minReward) ? { minReward: validateScore(params.minReward, 0) } : {}),
+                ...(params.timeWindowDays !== undefined ? { timeWindowDays: validatePositiveInt(params.timeWindowDays, 30, 3650) } : {}),
+            });
+            return result ?? { success: false, error: 'AgentDB ReflexionMemory not available. Use memory_search instead.' };
+        }
+        catch (error) {
+            return { success: false, error: sanitizeError(error) };
+        }
+    },
+};
 // ===== agentdb_hierarchical_store — Store to hierarchical memory =====
 export const agentdbHierarchicalStore = {
     name: 'agentdb_hierarchical-store',
@@ -1547,6 +1602,7 @@ export const agentdbTools = [
     agentdbRoute,
     agentdbSessionStart,
     agentdbSessionEnd,
+    agentdbEpisodeRecall, // ADR-519
     agentdbHierarchicalStore,
     agentdbHierarchicalRecall,
     agentdbHierarchicalDelete,

package/dist/src/mcp-tools/neural-tools.js

@@ -145,7 +145,9 @@ function ensureEmbeddings() {
             if (!realEmbeddings) {
                 const rb = await import('agentic-flow/reasoningbank').catch(() => null);
                 if (rb?.computeEmbedding) {
-                    realEmbeddings = { embed: (text) => rb.computeEmbedding(text) };
+                    // computeEmbedding returns a Float32Array; JSON.stringify writes that as
+                    // {"0":…,"1":…}, so convert before it reaches the neural store.
+                    realEmbeddings = { embed: async (text) => Array.from(await rb.computeEmbedding(text)) };
                     embeddingServiceName = 'agentic-flow/reasoningbank';
                 }
             }

package/dist/src/memory/memory-bridge.d.ts

@@ -507,6 +507,43 @@ export declare function bridgeDeleteCausalNode(options: {
     guarded?: boolean;
     error?: string;
 } | null>;
+export interface RecalledEpisode {
+    id?: number;
+    sessionId: string;
+    task: string;
+    critique?: string;
+    reward: number;
+    success: boolean;
+    similarity?: number;
+    tags?: string[];
+    ts?: number;
+}
+export interface EpisodeRecallOptions {
+    task: string;
+    k?: number;
+    /** Keyword + vector fusion. Default true (agentdb's own default). */
+    hybrid?: boolean;
+    /** Cross-encoder rerank. Default false: ~200 ms on CPU, 23 MB model on first use. */
+    rerank?: boolean;
+    onlySuccesses?: boolean;
+    onlyFailures?: boolean;
+    minReward?: number;
+    timeWindowDays?: number;
+}
+/**
+ * Recall past episodes relevant to a task. Episodes come from session ends
+ * and from `memory distill`. Ranking is agentdb's keyword + vector fusion,
+ * optionally reranked by a local cross-encoder.
+ */
+export declare function bridgeRecallEpisodes(options: EpisodeRecallOptions & {
+    dbPath?: string;
+}): Promise<{
+    success: boolean;
+    controller: string;
+    episodes: RecalledEpisode[];
+    hybrid: boolean;
+    rerank: boolean;
+} | null>;
 /**
  * Start a session with ReflexionMemory episodic replay.
  * Loads relevant past session patterns for the new session.
@@ -515,11 +552,17 @@ export declare function bridgeSessionStart(options: {
     sessionId: string;
     context?: string;
     dbPath?: string;
+    /** Recall past session episodes relevant to `context`. Default false. */
+    recall?: boolean;
+    k?: number;
+    hybrid?: boolean;
+    rerank?: boolean;
 }): Promise<{
     success: boolean;
     controller: string;
     restoredPatterns: number;
     sessionId: string;
+    episodes?: RecalledEpisode[];
 } | null>;
 /**
  * End a session and persist episodic summary to ReflexionMemory.
@@ -534,6 +577,7 @@ export declare function bridgeSessionEnd(options: {
     success: boolean;
     controller: string;
     persisted: boolean;
+    episodeId?: number;
 } | null>;
 /**
  * Route a task via AgentDB's SemanticRouter.

package/dist/src/memory/memory-bridge.js

@@ -2952,6 +2952,64 @@ export async function bridgeDeleteCausalNode(options) {
         return null;
     }
 }
+// ===== Episode recall (agentdb 3.2 hybrid retrieval, ADR-519) =====
+const EPISODE_TASK_MAX = 4_000;
+const EPISODE_TEXT_MAX = 2_000;
+const EPISODE_RECALL_MAX = 50;
+/** Null when the registry has no ReflexionMemory with retrieveRelevant. */
+async function recallEpisodesFrom(registry, options) {
+    const reflexion = registry.get('reflexion');
+    if (!reflexion || typeof reflexion.retrieveRelevant !== 'function')
+        return null;
+    const k = Math.min(Math.max(Math.trunc(options.k ?? 5), 1), EPISODE_RECALL_MAX);
+    const rows = await reflexion.retrieveRelevant({
+        task: options.task,
+        k,
+        hybrid: options.hybrid !== false,
+        rerank: options.rerank === true,
+        ...(options.onlySuccesses ? { onlySuccesses: true } : {}),
+        ...(options.onlyFailures ? { onlyFailures: true } : {}),
+        ...(typeof options.minReward === 'number' ? { minReward: options.minReward } : {}),
+        ...(typeof options.timeWindowDays === 'number' ? { timeWindowDays: options.timeWindowDays } : {}),
+    });
+    if (!Array.isArray(rows))
+        return [];
+    // Drop the embedding (1.5 KB of floats per row) and bound the text fields:
+    // this goes back over MCP.
+    return rows.slice(0, k).map(r => ({
+        ...(typeof r.id === 'number' ? { id: r.id } : {}),
+        sessionId: String(r.sessionId ?? ''),
+        task: String(r.task ?? '').slice(0, EPISODE_TEXT_MAX),
+        ...(r.critique ? { critique: String(r.critique).slice(0, EPISODE_TEXT_MAX) } : {}),
+        reward: Number(r.reward ?? 0),
+        success: !!r.success,
+        ...(typeof r.similarity === 'number' ? { similarity: Math.round(r.similarity * 1e4) / 1e4 } : {}),
+        ...(Array.isArray(r.tags) ? { tags: r.tags.slice(0, 20) } : {}),
+        ...(typeof r.ts === 'number' ? { ts: r.ts } : {}),
+    }));
+}
+/**
+ * Recall past episodes relevant to a task. Episodes come from session ends
+ * and from `memory distill`. Ranking is agentdb's keyword + vector fusion,
+ * optionally reranked by a local cross-encoder.
+ */
+export async function bridgeRecallEpisodes(options) {
+    if (!operationContext.getStore()?.active)
+        return withBridgeOperation(() => bridgeRecallEpisodes(options));
+    const registry = await getRegistry(options.dbPath);
+    if (!registry)
+        return null;
+    const episodes = await recallEpisodesFrom(registry, options);
+    if (!episodes)
+        return null;
+    return {
+        success: true,
+        controller: 'reflexion',
+        episodes,
+        hybrid: options.hybrid !== false,
+        rerank: options.rerank === true,
+    };
+}
 // ===== Phase 5: ReflexionMemory session lifecycle =====
 /**
  * Start a session with ReflexionMemory episodic replay.
@@ -2966,20 +3024,36 @@ export async function bridgeSessionStart(options) {
     try {
         let restoredPatterns = 0;
         let controller = 'none';
-        // Try ReflexionMemory for episodic session replay
-        const reflexion = registry.get('reflexion');
-        if (reflexion && typeof reflexion.startEpisode === 'function') {
-            await reflexion.startEpisode(options.sessionId, { context: options.context });
-            controller = 'reflexion';
-        }
-        // Load recent patterns from past sessions
-        const searchResult = await bridgeSearchEntries({
-            query: options.context || 'session patterns',
-            namespace: 'session',
-            limit: 10,
-            threshold: 0.2,
-            dbPath: options.dbPath,
-        });
+        // Episodic replay: past session episodes relevant to this session's
+        // context, ranked by agentdb's keyword + vector search (agentdb ADR-016).
+        // Opt-in, because a recall costs an embedding call and a generic context
+        // ("new session") matches nothing in particular.
+        let episodes;
+        if (options.recall && options.context) {
+            const recalled = await recallEpisodesFrom(registry, {
+                task: options.context, k: options.k, hybrid: options.hybrid, rerank: options.rerank,
+            });
+            if (recalled) {
+                episodes = recalled;
+                controller = 'reflexion';
+            }
+        }
+        // Load recent patterns from past sessions. A failure here must not
+        // discard episodes already recalled above.
+        let searchResult = null;
+        try {
+            searchResult = await bridgeSearchEntries({
+                query: options.context || 'session patterns',
+                namespace: 'session',
+                limit: 10,
+                threshold: 0.2,
+                dbPath: options.dbPath,
+            });
+        }
+        catch (err) {
+            if (!episodes)
+                throw err;
+        }
         if (searchResult?.results) {
             restoredPatterns = searchResult.results.length;
         }
@@ -2988,6 +3062,7 @@ export async function bridgeSessionStart(options) {
             controller: controller === 'none' ? 'bridge-search' : controller,
             restoredPatterns,
             sessionId: options.sessionId,
+            ...(episodes ? { episodes } : {}),
         };
     }
     catch {
@@ -3006,35 +3081,63 @@ export async function bridgeSessionEnd(options) {
     try {
         let controller = 'none';
         let persisted = false;
-        // End episode in ReflexionMemory
+        // Store the session summary as a ReflexionMemory episode so a later
+        // session can recall it. Only a real summary is worth recalling. The
+        // outcome is unverified, so it is stored neutral (reward 0, not a success)
+        // and can never count as evidence that an approach worked (ADR-171).
+        let episodeId;
         const reflexion = registry.get('reflexion');
-        if (reflexion && typeof reflexion.endEpisode === 'function') {
-            await reflexion.endEpisode(options.sessionId, {
-                summary: options.summary,
-                tasksCompleted: options.tasksCompleted,
-                patternsLearned: options.patternsLearned,
+        if (options.summary && reflexion && typeof reflexion.storeEpisode === 'function') {
+            try {
+                const id = await reflexion.storeEpisode({
+                    sessionId: options.sessionId,
+                    task: options.summary.slice(0, EPISODE_TASK_MAX),
+                    reward: 0,
+                    success: false,
+                    tags: ['session-end'],
+                    metadata: {
+                        source: 'session-end',
+                        provenance: 'session-summary',
+                        tasksCompleted: options.tasksCompleted ?? 0,
+                        patternsLearned: options.patternsLearned ?? 0,
+                    },
+                });
+                if (typeof id === 'number' && Number.isFinite(id)) {
+                    episodeId = id;
+                    controller = 'reflexion';
+                    persisted = true;
+                }
+            }
+            catch { /* non-fatal: the memory entry below still records the session */ }
+        }
+        // Persist session summary as memory entry. A failure here must not hide
+        // an episode that was already stored above.
+        let entryStored = false;
+        try {
+            await bridgeStoreEntry({
+                key: `session-${options.sessionId}`,
+                value: JSON.stringify({
+                    sessionId: options.sessionId,
+                    summary: options.summary || 'Session ended',
+                    tasksCompleted: options.tasksCompleted ?? 0,
+                    patternsLearned: options.patternsLearned ?? 0,
+                    endedAt: new Date().toISOString(),
+                }),
+                namespace: 'session',
+                tags: ['session-end'],
+                upsert: true,
+                dbPath: options.dbPath,
             });
-            controller = 'reflexion';
+            entryStored = true;
+        }
+        catch (err) {
+            if (episodeId === undefined)
+                throw err;
+        }
+        if (entryStored) {
+            controller = controller === 'none' ? 'bridge-store' : controller + '+bridge-store';
             persisted = true;
         }
-        // Persist session summary as memory entry
-        await bridgeStoreEntry({
-            key: `session-${options.sessionId}`,
-            value: JSON.stringify({
-                sessionId: options.sessionId,
-                summary: options.summary || 'Session ended',
-                tasksCompleted: options.tasksCompleted ?? 0,
-                patternsLearned: options.patternsLearned ?? 0,
-                endedAt: new Date().toISOString(),
-            }),
-            namespace: 'session',
-            tags: ['session-end'],
-            upsert: true,
-            dbPath: options.dbPath,
-        });
-        if (controller === 'none')
-            controller = 'bridge-store';
-        persisted = true;
         // Phase 3: Trigger NightlyLearner consolidation if available
         const nightlyLearner = registry.get('nightlyLearner');
         if (nightlyLearner && typeof nightlyLearner.consolidate === 'function') {
@@ -3044,7 +3147,7 @@ export async function bridgeSessionEnd(options) {
             }
             catch { /* non-fatal */ }
         }
-        return { success: true, controller, persisted };
+        return { success: true, controller, persisted, ...(episodeId !== undefined ? { episodeId } : {}) };
     }
     catch {
         return null;