claude-flow 3.19.0 → 3.21.0

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',
@@ -121,6 +48,7 @@ export const agenticowTools = [
                 branchPath: { type: 'string', description: 'Path to write the branch file' },
                 label: { type: 'string', description: 'Human-readable label for the branch (alnum + _.-:/@ only)' },
                 dimension: { type: 'integer', description: 'Vector dimension (required only when basePath does not exist yet)' },
+                nativeAnn: { type: 'boolean', description: 'Use the native Rust COW dual-graph ANN path (recall@10=1.0, query spans the COW boundary in one Rust call). Default false (exact JS chain-walk). Set true when the branch will be queried.', default: false },
             },
             required: ['basePath', 'branchPath', 'label'],
         },
@@ -132,9 +60,10 @@ export const agenticowTools = [
             const basePath = resolveMemoryPath(String(input.basePath));
             const branchPath = resolveMemoryPath(String(input.branchPath));
             const dim = input.dimension;
+            const nativeAnn = input.nativeAnn === true;
             const base = await openWithLineage(api, basePath, dim);
             try {
-                const branch = await base.fork(label, branchPath);
+                const branch = await base.fork(label, branchPath, { nativeAnn });
                 // Persist lineage manifests so the branch (and base) reopen with
                 // their COW chain intact. Without this, fork is in-memory only.
                 await branch.save?.(manifestFor(branchPath));
@@ -145,6 +74,7 @@ export const agenticowTools = [
                     basePath,
                     branchPath,
                     label,
+                    nativeAnn,
                 };
             }
             finally {
@@ -152,6 +82,181 @@ 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 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: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file (branch or base)' },
+                records: {
+                    type: 'array',
+                    description: 'Vectors to ingest: [{id?: number, vector: number[], text?: string}]',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'integer', description: 'Explicit id (auto-assigned when omitted)' },
+                            vector: { type: 'array', items: { type: 'number' }, description: 'Embedding vector (length must equal the memory dimension)' },
+                            text: { type: 'string', description: 'Optional payload surfaced on query hits' },
+                        },
+                        required: ['vector'],
+                    },
+                },
+                dimension: { type: 'integer', description: 'Vector dimension (required only when path does not exist yet)' },
+            },
+            required: ['path', 'records'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const records = input.records;
+            if (!Array.isArray(records) || records.length === 0) {
+                throw new Error('records must be a non-empty array of {id?, vector, text?}');
+            }
+            for (const r of records) {
+                if (!Array.isArray(r.vector) || r.vector.length === 0) {
+                    throw new Error('each record requires a non-empty numeric vector');
+                }
+            }
+            const dim = input.dimension ?? records[0].vector.length;
+            const mem = await openWithLineage(api, path, dim);
+            try {
+                const result = await mem.ingest(records.map((r) => ({
+                    ...(typeof r.id === 'number' ? { id: r.id } : {}),
+                    vector: r.vector,
+                    ...(r.text !== undefined ? { text: r.text } : {}),
+                })));
+                await mem.save?.(manifestFor(path));
+                return { success: true, path, ingested: result };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        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 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: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+                vector: { type: 'array', items: { type: 'number' }, description: 'Query embedding vector' },
+                k: { type: 'integer', description: 'Number of nearest neighbors to return', default: 10 },
+                efSearch: { type: 'integer', description: 'HNSW efSearch per lineage store (higher = better recall, slower)' },
+            },
+            required: ['path', 'vector'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const vector = input.vector;
+            if (!Array.isArray(vector) || vector.length === 0) {
+                throw new Error('vector must be a non-empty numeric array');
+            }
+            const k = typeof input.k === 'number' ? input.k : 10;
+            const opts = {};
+            if (typeof input.efSearch === 'number')
+                opts.efSearch = input.efSearch;
+            const mem = await openWithLineage(api, path);
+            try {
+                const hits = await mem.query(vector, k, opts);
+                return { success: true, path, k, hits };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_diff',
+        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: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to branch .rvf file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const diff = await mem.diff();
+                return { success: true, path, diff };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        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 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: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const lineage = await mem.lineage();
+                return { success: true, path, lineage };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
+    {
+        name: 'agenticow_status',
+        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: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Path to .rvf memory file' },
+            },
+            required: ['path'],
+        },
+        handler: async (input) => {
+            const api = await loadAgenticow();
+            if (!api)
+                return degradedResult('agenticow-not-found');
+            const path = resolveMemoryPath(String(input.path));
+            const mem = await openWithLineage(api, path);
+            try {
+                const status = await mem.status();
+                return { success: true, path, status };
+            }
+            finally {
+                await mem.close?.();
+            }
+        },
+    },
     {
         name: 'agenticow_checkpoint',
         description: 'agenticow — freeze a labelled restore point on an .rvf memory file. Subsequent edits stay in a fresh COW child; rollback returns here. Use when you are about to run an experimental Darwin tick or speculative agent edit that may need to be discarded. Relying on the working node alone is wrong because there is no "undo last N writes" semantics — without a checkpoint, a bad ingest contaminates the base. Persists via .agenticow.json lineage manifest so it survives close+reopen.',
@@ -191,6 +296,7 @@ export const agenticowTools = [
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'Path to .rvf memory file' },
+                checkpointId: { type: 'string', description: 'Target checkpoint id from agenticow_lineage (omit to roll back to the most recent checkpoint)' },
             },
             required: ['path'],
         },
@@ -199,9 +305,10 @@ export const agenticowTools = [
             if (!api)
                 return degradedResult('agenticow-not-found');
             const path = resolveMemoryPath(String(input.path));
+            const checkpointId = input.checkpointId ? String(input.checkpointId) : undefined;
             const mem = await openWithLineage(api, path);
             try {
-                const r = await mem.rollback();
+                const r = checkpointId ? await mem.rollback(checkpointId) : await mem.rollback();
                 await mem.save?.(manifestFor(path));
                 return { success: true, path, rolledBack: true, result: r };
             }

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