claude-flow 3.20.0 → 3.21.1

package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js

@@ -224,6 +224,8 @@ export const agentTools = [
                     description: 'Claude model alias (haiku=fast/cheap, sonnet=balanced, opus=current Opus 4.8, opus-4.7=prior Opus pin)'
                 },
                 task: { type: 'string', description: 'Task description for intelligent model routing' },
+                memoryBase: { type: 'string', description: 'Opt-in: base .rvf memory file to fork a per-agent Copy-On-Write branch from (agenticow). When set, the agent gets an isolated ~162-byte COW branch instead of a full copy — promote on success, discard on terminate. Requires the optional `agenticow` dep; degrades to a no-op when absent or when CLAUDE_FLOW_NO_COW_MEMORY=1.' },
+                memoryDimension: { type: 'integer', description: 'Vector dimension for the COW base (required only when memoryBase does not exist yet)' },
             },
             required: ['agentType'],
         },
@@ -295,6 +297,31 @@ export const agentTools = [
                 await addNode({ id: agentId, type: 'agent', name: agentType });
             }
             catch { /* graph-node not available */ }
+            // ACOW — opt-in per-agent COW memory branch. Only when the caller
+            // supplies `memoryBase` does the agent get an isolated 162-byte branch
+            // (vs a full .rvf copy). Lazy-imported so agenticow stays off the
+            // startup path. Non-fatal: a branch failure never blocks the spawn —
+            // the agent is already registered above.
+            let memoryBranch;
+            if (input.memoryBase) {
+                try {
+                    const { SwarmMemoryBranches } = await import('../services/swarm-memory-branches.js');
+                    const svc = new SwarmMemoryBranches();
+                    const br = await svc.branchForAgent(String(input.memoryBase), agentId, {
+                        dimension: typeof input.memoryDimension === 'number' ? input.memoryDimension : undefined,
+                    });
+                    if (br.branchPath) {
+                        memoryBranch = br.branchPath;
+                        agent.memoryBranch = br.branchPath;
+                        agent.memoryBase = br.basePath;
+                        store.agents[agentId] = agent;
+                        saveAgentStore(store);
+                    }
+                    // else: degraded (agenticow missing / kill-switched) — agent stands
+                    // without an isolated branch; callers see no memoryBranch field.
+                }
+                catch { /* COW branch is best-effort; agent already registered */ }
+            }
             // Include deterministic codemod routing info if applicable
             const response = {
                 success: true,
@@ -307,6 +334,7 @@ export const agentTools = [
                 ...(routingResult.openrouterModel ? { openrouterModel: routingResult.openrouterModel } : {}),
                 status: 'registered',
                 createdAt: agent.createdAt,
+                ...(memoryBranch ? { memoryBranch, memoryBase: agent.memoryBase } : {}),
                 note: 'Agent registered for coordination. Three execution paths: ' +
                     '(1) call agent_execute(agentId, prompt) — direct LLM call via Anthropic Messages API (requires ANTHROPIC_API_KEY); ' +
                     '(2) Claude Code Task tool — spawns a real subagent; ' +
@@ -375,6 +403,7 @@ export const agentTools = [
             properties: {
                 agentId: { type: 'string', description: 'ID of agent to terminate' },
                 force: { type: 'boolean', description: 'Force immediate termination' },
+                promoteMemory: { type: 'boolean', description: 'When the agent has a per-agent COW memory branch (spawned with memoryBase), promote (merge) its edits into the shared base on terminate. Default false → discard the branch (throw its edits away). No-op when the agent has no branch.' },
             },
             required: ['agentId'],
         },
@@ -385,13 +414,30 @@ export const agentTools = [
             const store = loadAgentStore();
             const agentId = input.agentId;
             if (store.agents[agentId]) {
-                store.agents[agentId].status = 'terminated';
+                const rec = store.agents[agentId];
+                rec.status = 'terminated';
                 saveAgentStore(store);
+                // ACOW — resolve the agent's COW memory branch on teardown: promote
+                // (merge into base) when asked, else discard. Non-fatal — a failure
+                // here never blocks termination. Discard needs no agenticow (pure fs),
+                // so cleanup still works in the degraded path.
+                let memory;
+                if (rec.memoryBranch) {
+                    try {
+                        const { SwarmMemoryBranches } = await import('../services/swarm-memory-branches.js');
+                        const svc = new SwarmMemoryBranches();
+                        memory = input.promoteMemory
+                            ? (await svc.promoteAgent(agentId))
+                            : (await svc.discardAgent(agentId));
+                    }
+                    catch { /* best-effort teardown */ }
+                }
                 return {
                     success: true,
                     agentId,
                     terminated: true,
                     terminatedAt: new Date().toISOString(),
+                    ...(memory ? { memory } : {}),
                 };
             }
             return {

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-loader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Agenticow shared loader + helpers.
+ *
+ * Extracted from `agenticow-tools.ts` so both the MCP tool surface AND the
+ * `SwarmMemoryBranches` service (src/services/swarm-memory-branches.ts) share
+ * one loader, one degradation contract, and one set of path/lineage helpers —
+ * rather than duplicating the optional-dep dance in two places.
+ *
+ * Architectural constraint (ADR-150, mirrors metaharness-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — never a hard runtime dep.
+ *   - When the package is missing, callers get `null` from `loadAgenticow()`
+ *     (or a `{degraded:true}` result via `degradedResult`) and MUST fall back
+ *     gracefully — never throw a MODULE_NOT_FOUND.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-loader
+ */
+export declare const PACKAGE_NAME = "agenticow";
+export interface AgenticowApi {
+    open: (file: string, opts?: {
+        dimension?: number;
+        metric?: string;
+    }) => Promise<any>;
+    openBase?: (file: string, opts?: any) => Promise<any>;
+    AgenticMemory: any;
+}
+/**
+ * Lazily import `agenticow`. Returns the module on success, or `null` when the
+ * package is not installed (the optional-dep degraded path). Any OTHER load
+ * error (e.g. a corrupt install) is re-thrown so it is not silently masked.
+ */
+export declare function loadAgenticow(): Promise<AgenticowApi | null>;
+/** Reset the module-level load cache. Test-only seam. */
+export declare function __resetAgenticowCache(): void;
+export declare function degradedResult(reason: string): {
+    success: true;
+    degraded: true;
+    reason: string;
+};
+/**
+ * Resolve a user-supplied memory path against the project cwd, rejecting path
+ * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
+ */
+export declare function resolveMemoryPath(path: string): string;
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
+ * disappear when the AgenticMemory handle closes.
+ */
+export declare function manifestFor(file: string): string;
+/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
+export declare function validateLabel(label: string): string;
+/**
+ * Open (or create) a memory file, restoring its COW chain from the lineage
+ * manifest when one exists. When neither the `.rvf` nor the manifest exists,
+ * `dimension` is required to create a fresh base.
+ */
+export declare function openWithLineage(api: AgenticowApi, file: string, dimension?: number): Promise<any>;
+//# sourceMappingURL=agenticow-loader.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-loader.js

@@ -0,0 +1,105 @@
+/**
+ * Agenticow shared loader + helpers.
+ *
+ * Extracted from `agenticow-tools.ts` so both the MCP tool surface AND the
+ * `SwarmMemoryBranches` service (src/services/swarm-memory-branches.ts) share
+ * one loader, one degradation contract, and one set of path/lineage helpers —
+ * rather than duplicating the optional-dep dance in two places.
+ *
+ * Architectural constraint (ADR-150, mirrors metaharness-tools.ts):
+ *   - `agenticow` lives in `optionalDependencies` — never a hard runtime dep.
+ *   - When the package is missing, callers get `null` from `loadAgenticow()`
+ *     (or a `{degraded:true}` result via `degradedResult`) and MUST fall back
+ *     gracefully — never throw a MODULE_NOT_FOUND.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-loader
+ */
+import { existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { getProjectCwd } from './types.js';
+export const PACKAGE_NAME = 'agenticow';
+// Cache: module load is expensive enough to amortize across handler calls.
+// null = not yet attempted; false = attempted and unavailable; module = loaded.
+let _agenticowMod = null;
+let _loadAttempted = false;
+/**
+ * Lazily import `agenticow`. Returns the module on success, or `null` when the
+ * package is not installed (the optional-dep degraded path). Any OTHER load
+ * error (e.g. a corrupt install) is re-thrown so it is not silently masked.
+ */
+export async function loadAgenticow() {
+    if (_loadAttempted)
+        return _agenticowMod || null;
+    _loadAttempted = true;
+    try {
+        _agenticowMod = await import(PACKAGE_NAME);
+        return _agenticowMod;
+    }
+    catch (err) {
+        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
+            /Cannot find (module|package)/i.test(String(err.message)))) {
+            _agenticowMod = false;
+            return null;
+        }
+        throw err;
+    }
+}
+/** Reset the module-level load cache. Test-only seam. */
+export function __resetAgenticowCache() {
+    _agenticowMod = null;
+    _loadAttempted = false;
+}
+export function degradedResult(reason) {
+    return { success: true, degraded: true, reason };
+}
+/**
+ * Resolve a user-supplied memory path against the project cwd, rejecting path
+ * traversal and NUL bytes (D-2 style hardening — same rule the MCP verbs use).
+ */
+export function resolveMemoryPath(path) {
+    if (!path || typeof path !== 'string')
+        throw new Error('memory path is required');
+    if (/\.\.[\\/]|\0/.test(path))
+        throw new Error('memory path contains disallowed characters');
+    return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
+}
+/**
+ * Lineage manifest companion path. agenticow persists the COW chain
+ * (working → checkpoints → base) into `<file>.agenticow.json` next to the
+ * `.rvf` data file. Without it, forks/checkpoints are in-memory only and
+ * disappear when the AgenticMemory handle closes.
+ */
+export function manifestFor(file) {
+    return `${file}.agenticow.json`;
+}
+/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */
+export function validateLabel(label) {
+    if (!label || typeof label !== 'string')
+        throw new Error('label is required');
+    if (label.length > 256)
+        throw new Error('label exceeds 256 chars');
+    if (!/^[A-Za-z0-9_.\-:/@]+$/.test(label)) {
+        throw new Error('label may only contain [A-Za-z0-9_.\\-:/@]');
+    }
+    return label;
+}
+/**
+ * Open (or create) a memory file, restoring its COW chain from the lineage
+ * manifest when one exists. When neither the `.rvf` nor the manifest exists,
+ * `dimension` is required to create a fresh base.
+ */
+export async function openWithLineage(api, file, dimension) {
+    const manifest = manifestFor(file);
+    if (existsSync(manifest)) {
+        return api.AgenticMemory.load(manifest);
+    }
+    const opts = {};
+    if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {
+        opts.dimension = dimension;
+    }
+    else if (!existsSync(file)) {
+        throw new Error('dimension is required when creating a new memory file');
+    }
+    return api.open(file, opts);
+}
+//# sourceMappingURL=agenticow-loader.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-speculate-tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import type { MCPTool } from './types.js';
+export declare const agenticowSpeculateTools: MCPTool[];
+//# sourceMappingURL=agenticow-speculate-tools.d.ts.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-speculate-tools.js

@@ -0,0 +1,202 @@
+/**
+ * agenticow speculate — MCP surface for speculative branch-and-promote
+ * (agenticow step 4).
+ *
+ * Exposes the `SpeculativeExploration` module as a single MCP tool
+ * `agenticow_speculate` so agents can drive parallel A/B memory exploration:
+ * fan out N candidate ingest-sets, each on its own 162-byte COW branch of a
+ * shared base `.rvf`, score them by a probe query, PROMOTE the winner into
+ * base, and DISCARD the losers (delete their branch files).
+ *
+ * Because MCP inputs are JSON (not JS functions), candidates are DECLARATIVE:
+ * each candidate is a label + a set of vectors to ingest, and scoring is a
+ * probe query (`nearest`) or an ingest count (`count`). The generic
+ * `explore(base, {label, fn}[], score)` core does the real work.
+ *
+ * Optional-dep contract (mirrors agenticow-tools.ts): when `agenticow` is not
+ * installed the tool returns `{success:true, degraded:true,
+ * reason:'agenticow-not-found'}` and never throws for that reason.
+ *
+ * @module @claude-flow/cli/mcp-tools/agenticow-speculate
+ */
+import { loadAgenticow, degradedResult, resolveMemoryPath, openWithLineage, manifestFor, validateLabel, } from './agenticow-loader.js';
+import { explore, } from '../agenticow/speculative-exploration.js';
+/** Turn a validated label into a filesystem-safe branch filename segment. */
+function safeSegment(label) {
+    return label.replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 64) || 'branch';
+}
+export const agenticowSpeculateTools = [
+    {
+        name: 'agenticow_speculate',
+        description: "agenticow — speculative branch-and-promote for parallel A/B memory exploration. " +
+            "Forks a 162-byte COW branch per candidate off a shared base .rvf, ingests each candidate's " +
+            "vectors into its OWN isolated branch, scores every branch (probe-query 'nearest' distance or " +
+            "ingest 'count'), PROMOTES the winning branch's edits into base, and DISCARDS the losers by " +
+            "deleting their branch files. Use when you want to try N competing memory-write strategies and " +
+            "keep only the best — the memory-state analogue of worktree-per-agent code exploration. " +
+            "Copying the base per candidate is wrong (full-copy snapshots grow linearly, the 3.3 GB Darwin " +
+            "bloat); COW forks are constant-size and losers cost ~162 B to throw away. Optional dep — " +
+            "degrades to {degraded:true} when agenticow is missing.",
+        category: 'memory',
+        tags: ['agenticow', 'memory', 'cow', 'speculative', 'branch', 'promote', 'ab'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                basePath: {
+                    type: 'string',
+                    description: 'Path to base .rvf memory file (absolute or relative to cwd)',
+                },
+                dimension: {
+                    type: 'integer',
+                    description: 'Vector dimension (required only when basePath does not exist yet)',
+                },
+                candidates: {
+                    type: 'array',
+                    description: 'The A/B candidates. Each explores its own COW branch.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string', description: 'Branch label (alnum + _.-:/@ only)' },
+                            ingest: {
+                                type: 'array',
+                                description: 'Vectors to ingest into this candidate branch',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: { type: 'integer', description: 'Explicit vector id (auto when omitted)' },
+                                        vector: { type: 'array', items: { type: 'number' }, description: 'Dense vector' },
+                                        text: { type: 'string', description: 'Optional payload text' },
+                                    },
+                                    required: ['vector'],
+                                },
+                            },
+                            branchPath: {
+                                type: 'string',
+                                description: 'Optional explicit path for this branch file (default: alongside base)',
+                            },
+                        },
+                        required: ['label', 'ingest'],
+                    },
+                },
+                probe: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: "Probe vector for scoreBy='nearest' (scores each branch by best-hit similarity)",
+                },
+                k: { type: 'integer', description: 'Nearest-neighbours to fetch per probe (default 1)' },
+                scoreBy: {
+                    type: 'string',
+                    enum: ['nearest', 'count'],
+                    description: "'nearest' = closest probe distance wins; 'count' = most accepted ingests wins. Default 'nearest'.",
+                },
+                requireClearance: {
+                    type: 'boolean',
+                    description: 'ADR-171 fail-closed gate. When true, the top-scored winner is NOT promoted (base stays unchanged) and a provenance-tagged receipt is emitted — score alone cannot graduate work. Use when speculating over TASK outcomes rather than pure memory A/B. Default false (score-only promotion, tagged `unverified`).',
+                    default: false,
+                },
+            },
+            required: ['basePath', 'candidates'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const basePath = resolveMemoryPath(String(input.basePath));
+            const dimension = input.dimension;
+            const scoreBy = input.scoreBy === 'count' ? 'count' : 'nearest';
+            const k = Number.isInteger(input.k) && input.k > 0 ? input.k : 1;
+            const probe = Array.isArray(input.probe) ? input.probe : null;
+            const rawCandidates = input.candidates;
+            if (!Array.isArray(rawCandidates) || rawCandidates.length === 0) {
+                throw new Error('at least one candidate is required');
+            }
+            if (scoreBy === 'nearest' && !probe) {
+                throw new Error("scoreBy='nearest' requires a probe vector");
+            }
+            // Build the generic {label, fn} candidates. Each fn ingests into its own
+            // branch handle, then (for 'nearest') probes it so we can score.
+            const candidates = rawCandidates.map((c) => {
+                const label = validateLabel(String(c.label));
+                if (!Array.isArray(c.ingest) || c.ingest.length === 0) {
+                    throw new Error(`candidate ${label} must ingest at least one vector`);
+                }
+                const records = c.ingest.map((r) => ({
+                    ...(Number.isInteger(r.id) ? { id: r.id } : {}),
+                    vector: r.vector,
+                    ...(typeof r.text === 'string' ? { text: r.text } : {}),
+                }));
+                return {
+                    label,
+                    fn: (branch) => {
+                        const res = branch.ingest(records);
+                        const accepted = Number(res?.accepted ?? records.length);
+                        let hits = [];
+                        if (probe) {
+                            hits = (branch.query(probe, k) || []).map((h) => ({
+                                id: h.id,
+                                distance: h.distance,
+                            }));
+                        }
+                        const bestDistance = hits.length ? hits[0].distance : null;
+                        return { accepted, bestDistance, hits };
+                    },
+                };
+            });
+            const score = (r) => {
+                if (scoreBy === 'count')
+                    return r.accepted;
+                // nearest: smaller distance = better. Map to a higher-is-better score.
+                if (r.bestDistance === null)
+                    return -Infinity;
+                return 1 / (1 + Math.max(0, r.bestDistance));
+            };
+            const branchPath = (label) => {
+                const explicit = rawCandidates.find((c) => validateLabel(String(c.label)) === label)?.branchPath;
+                if (explicit)
+                    return resolveMemoryPath(String(explicit));
+                return `${basePath}.spec-${safeSegment(label)}.rvf`;
+            };
+            // ADR-171 promotion gate. For pure memory A/B the `score` IS the chosen
+            // metric (not a proxy for task correctness), so score-only promotion is
+            // legitimate and stays the default (tagged `unverified`, never
+            // masquerading as ground truth). Callers grafting this onto TASK work
+            // pass requireClearance:true to fail-closed — the winner is then
+            // ineligible unless a real clearance mechanism graduates it.
+            const requireClearance = input.requireClearance === true;
+            const exploreOpts = { branchPath, persist: true };
+            if (requireClearance)
+                exploreOpts.requireClearance = true;
+            // Open base, run the speculative exploration, persist base with the winner promoted.
+            const base = await openWithLineage(api, basePath, dimension);
+            try {
+                const result = await explore(base, candidates, score, exploreOpts);
+                base.save?.(manifestFor(basePath));
+                return {
+                    success: true,
+                    basePath,
+                    scoreBy,
+                    winner: result.winner,
+                    scores: result.scores,
+                    promoted: result.promoted,
+                    promotedBy: result.promotedBy,
+                    promotionDecision: result.promotionDecision,
+                    promoteStats: result.promoteStats,
+                    discarded: result.discarded,
+                    receipts: result.receipts,
+                    branches: result.branches.map((b) => ({
+                        label: b.label,
+                        path: b.path,
+                        score: b.score,
+                        kept: b.kept,
+                        accepted: b.result.accepted,
+                        bestDistance: b.result.bestDistance,
+                    })),
+                };
+            }
+            finally {
+                await base.close?.();
+            }
+        },
+    },
+];
+//# sourceMappingURL=agenticow-speculate-tools.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/agenticow-tools.js

@@ -31,83 +31,10 @@
  *
  * @module @claude-flow/cli/mcp-tools/agenticow
  */
-import { existsSync } from 'node:fs';
-import { getProjectCwd } from './types.js';
-import { resolve, isAbsolute } from 'node:path';
-const PACKAGE_NAME = 'agenticow';
-// Cache: module load is expensive enough to amortize across handler calls.
-// null = not yet attempted; false = attempted and unavailable; module = loaded.
-let _agenticowMod = null;
-let _loadAttempted = false;
-async function loadAgenticow() {
-    if (_loadAttempted)
-        return _agenticowMod;
-    _loadAttempted = true;
-    try {
-        _agenticowMod = await import(PACKAGE_NAME);
-        return _agenticowMod;
-    }
-    catch (err) {
-        if (err && (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'MODULE_NOT_FOUND' ||
-            /Cannot find (module|package)/i.test(String(err.message)))) {
-            _agenticowMod = false;
-            return null;
-        }
-        throw err;
-    }
-}
-function degradedResult(reason) {
-    return { success: true, degraded: true, reason };
-}
-function resolveMemoryPath(path) {
-    if (!path || typeof path !== 'string')
-        throw new Error('memory path is required');
-    // D-2 style: reject path traversal in user-supplied paths
-    if (/\.\.[\\/]|\0/.test(path))
-        throw new Error('memory path contains disallowed characters');
-    return isAbsolute(path) ? path : resolve(getProjectCwd(), path);
-}
-/**
- * Lineage manifest companion path. agenticow persists the COW chain
- * (working → checkpoints → base) into `<file>.agenticow.json` next to the
- * `.rvf` data file. Without this, checkpoints and forks are in-memory only
- * and disappear when the AgenticMemory handle closes. Mirrors the bin
- * CLI's `manifestFor(file)` helper.
- */
-function manifestFor(file) {
-    return `${file}.agenticow.json`;
-}
-function validateLabel(label) {
-    if (!label || typeof label !== 'string')
-        throw new Error('label is required');
-    if (label.length > 256)
-        throw new Error('label exceeds 256 chars');
-    if (!/^[A-Za-z0-9_.\-:/@]+$/.test(label)) {
-        throw new Error('label may only contain [A-Za-z0-9_.\\-:/@]');
-    }
-    return label;
-}
-/**
- * Open (or create) a base memory file. When a lineage manifest exists at
- * `<file>.agenticow.json`, we load that to restore the COW chain (checkpoints,
- * ancestors). When only the `.rvf` exists, fresh-open it. When neither exists,
- * dimension is required to create. Mirrors the bin CLI's `loadMem()` helper.
- */
-async function openWithLineage(api, file, dimension) {
-    const manifest = manifestFor(file);
-    if (existsSync(manifest)) {
-        // The class-level static method `load` reconstructs the full chain.
-        return api.AgenticMemory.load(manifest);
-    }
-    const opts = {};
-    if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {
-        opts.dimension = dimension;
-    }
-    else if (!existsSync(file)) {
-        throw new Error('dimension is required when creating a new memory file');
-    }
-    return api.open(file, opts);
-}
+// Loader + path/lineage helpers are shared with the SwarmMemoryBranches
+// service (src/services/swarm-memory-branches.ts) via one module so the
+// optional-dep dance and the COW open/fork semantics live in exactly one place.
+import { loadAgenticow, degradedResult, resolveMemoryPath, manifestFor, validateLabel, openWithLineage, } from './agenticow-loader.js';
 export const agenticowTools = [
     {
         name: 'agenticow_branch',
@@ -157,7 +84,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_ingest',
-        description: 'agenticow — write vectors (with optional text payloads) into an .rvf memory branch or base. Records: [{id?, vector, text?}] — id auto-assigns when omitted. This is the write half that makes a branch usable: agenticow_branch creates an empty COW child, but without ingest it has nothing to read back. Use after branching to populate an agent/session-local memory. Editing the base directly is wrong when the writes are speculative — ingest into a branch, then promote only if validated. Persists via .agenticow.json lineage manifest.',
+        description: 'agenticow — write vectors (with optional text payloads) into an .rvf memory branch or base. Records: [{id?, vector, text?}] — id auto-assigns when omitted. This is the write half that makes a branch usable: agenticow_branch creates an empty COW child, but without ingest it has nothing to read back. Use when you have branched and must populate the branch (agenticow_branch alone leaves it empty). Editing the base directly is wrong when the writes are speculative — ingest into a branch, then promote only if validated. Persists via .agenticow.json lineage manifest.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'ingest', 'write'],
         inputSchema: {
@@ -213,7 +140,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_query',
-        description: 'agenticow — k-NN read across an .rvf memory branch\'s full COW lineage (parent ∪ edits, child wins), returning {id, distance, branch, text}. Read-only (no manifest write). The `branch` field on each hit tells you which lineage node the result came from — the read-through semantics that make branching useful. Use to retrieve from an agent/session branch without materializing a full copy. Re-opening the base and manually merging edits is wrong: query already spans the chain (and uses the single-call Rust path when the branch was forked with nativeAnn).',
+        description: 'agenticow — k-NN read across an .rvf memory branch\'s full COW lineage (parent ∪ edits, child wins), returning {id, distance, branch, text}. Read-only (no manifest write). The `branch` field on each hit tells you which lineage node the result came from — the read-through semantics that make branching useful. Use when you need to read from an agent/session branch without materializing a full copy. Re-opening the base and manually merging edits is wrong: query already spans the chain (and uses the single-call Rust path when the branch was forked with nativeAnn).',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'query', 'read', 'search'],
         inputSchema: {
@@ -251,7 +178,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_diff',
-        description: 'agenticow — show what a branch changed relative to its lineage: {added, overridden, deleted} vector-id lists. Use before promote to preview the exact merge, or to audit what an agent/session branch actually wrote. Diffing by re-querying is wrong because deletions (tombstones) are invisible to a read — diff() surfaces them explicitly. Requires the branch was opened with edit tracking (default on).',
+        description: 'agenticow — show what a branch changed relative to its lineage: {added, overridden, deleted} vector-id lists. Use when you are about to promote and want to preview the exact merge, or when auditing what a branch actually wrote. Diffing by re-querying is wrong because deletions (tombstones) are invisible to a read — diff() surfaces them explicitly. Requires the branch was opened with edit tracking (default on).',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'diff'],
         inputSchema: {
@@ -278,7 +205,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_lineage',
-        description: 'agenticow — walk the COW chain of an .rvf memory file: an ordered list of nodes (role working|checkpoint|base, id, label, parent, createdAt, mutations, tombstones). Use to understand branch history, find checkpoint ids for a targeted rollback, or debug a promote. Guessing the chain from filenames is wrong — lineage is the authoritative structure the store maintains.',
+        description: 'agenticow — walk the COW chain of an .rvf memory file: an ordered list of nodes (role working|checkpoint|base, id, label, parent, createdAt, mutations, tombstones). Use when you need branch history — to find checkpoint ids for a targeted rollback, or to debug a promote. Guessing the chain from filenames is wrong — lineage is the authoritative structure the store maintains.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'lineage', 'history'],
         inputSchema: {
@@ -305,7 +232,7 @@ export const agenticowTools = [
     },
     {
         name: 'agenticow_status',
-        description: 'agenticow — health/geometry of an .rvf memory file: {totalVectors, totalSegments, fileSize, currentEpoch, deadSpaceRatio, readOnly, chainDepth, dimension, metric}. Use to check vector count before/after ingest, spot compaction pressure (deadSpaceRatio), or confirm the dimension before ingesting into a shared base. Pure read.',
+        description: 'agenticow — health/geometry of an .rvf memory file: {totalVectors, totalSegments, fileSize, currentEpoch, deadSpaceRatio, readOnly, chainDepth, dimension, metric}. Use when you need to check vector count before/after ingest, spot compaction pressure (deadSpaceRatio), or confirm the dimension before ingesting into a shared base. Pure read.',
         category: 'memory',
         tags: ['agenticow', 'memory', 'cow', 'status'],
         inputSchema: {

package/v3/@claude-flow/cli/dist/src/mcp-tools/index.d.ts

@@ -27,6 +27,7 @@ export { autopilotTools } from './autopilot-tools.js';
 export { metaharnessTools } from './metaharness-tools.js';
 export { testgenTools } from './testgen-tools.js';
 export { agenticowTools } from './agenticow-tools.js';
+export { agenticowSpeculateTools } from './agenticow-speculate-tools.js';
 export { agentbbsTools } from './agentbbs-tools.js';
 export { businessPodTools } from './business-pod-tools.js';
 export { httpFetchTools } from './http-fetch-tools.js';

package/v3/@claude-flow/cli/dist/src/mcp-tools/index.js

@@ -29,6 +29,8 @@ export { metaharnessTools } from './metaharness-tools.js';
 export { testgenTools } from './testgen-tools.js';
 // agenticow@~0.2.3 — Copy-On-Write memory branching (162-byte branches)
 export { agenticowTools } from './agenticow-tools.js';
+// agenticow step 4 — speculative branch-and-promote (A/B memory exploration)
+export { agenticowSpeculateTools } from './agenticow-speculate-tools.js';
 // ADR-164 — AgentBBS federated business-domain BBS rooms (Phase 1)
 export { agentbbsTools } from './agentbbs-tools.js';
 // ADR-164 Phase 2 — Business-pod template validation