π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(memory): OAS operator selector β budget-aware consolidation picker (#2763)
ruv6568bedae611
diff --git a/v3/@claude-flow/cli/__tests__/oas-operator-selector-2763.test.ts b/v3/@claude-flow/cli/__tests__/oas-operator-selector-2763.test.tsnew file mode 100644index 0000000000..a787cab822--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/oas-operator-selector-2763.test.ts@@ -0,0 +1,65 @@+/**+ * Regression guard for #2763 dream-cycle OAS memory-operator selector.+ *+ * Rules the selector must obey:+ * 1. Hint-driven pick when the hinted operator fits.+ * 2. Otherwise, most-expensive-that-still-fits (spend the budget on+ * the best-fidelity operator we can afford).+ * 3. When no operator fits, fall back to merge with needsSplit + a+ * batch size β€ what the budget can pay for.+ */++import { describe, it, expect } from 'vitest';+import { selectOperator, OPERATORS } from '../src/memory/oas-operator-selector.js';++describe('#2763 OAS operator selector', () => {+ it('picks distill on a small set with a rich budget', () => {+ const r = selectOperator({ budget: 500, entries: 50 });+ expect(r.operator).toBe('distill');+ expect(r.estimatedCost).toBe(OPERATORS.distill.costPerEntry * 50);+ expect(r.needsSplit).toBe(false);+ });++ it('picks merge on a huge set with a tiny budget (Rule 3 fallback + needsSplit)', () => {+ const r = selectOperator({ budget: 2, entries: 5000 });+ expect(r.operator).toBe('merge');+ expect(r.needsSplit).toBe(true);+ // Budget 2 / merge cost 0.02 β batch size 100+ expect(r.suggestedBatchSize).toBe(100);+ });++ it('honors a "duplicates" hint by preferring merge even when a fancier operator would fit', () => {+ const r = selectOperator({ budget: 500, entries: 100, hint: 'duplicates' });+ expect(r.operator).toBe('merge');+ expect(r.reason).toMatch(/Hint "duplicates"/);+ });++ it('honors a "patterns" hint by preferring distill when it fits', () => {+ const r = selectOperator({ budget: 300, entries: 50, hint: 'patterns' });+ expect(r.operator).toBe('distill');+ });++ it('ignores a hint when the hinted operator does not fit', () => {+ // Distill at 100 entries costs 300; give budget 50 (can afford summarize but not distill).+ const r = selectOperator({ budget: 50, entries: 100, hint: 'patterns' });+ expect(r.operator).not.toBe('distill');+ // Should pick the best fitting alternative β summarize (100 Γ 0.5 = 50) fits exactly.+ expect(r.operator).toBe('summarize');+ });++ it('returns all four operators in the considered list, ranked by cost ascending', () => {+ const r = selectOperator({ budget: 1000, entries: 100 });+ const ids = r.considered.map((c) => c.id);+ expect(new Set(ids)).toEqual(new Set(['merge', 'summarize', 'compress', 'distill']));+ for (let i = 1; i < r.considered.length; i++) {+ expect(r.considered[i].cost).toBeGreaterThanOrEqual(r.considered[i - 1].cost);+ }+ });++ it('needsSplit=true when entries exceed the chosen operator\'s maxEntries', () => {+ // distill.maxEntries = 100; ask for 200 with a rich budget so distill is picked+ const r = selectOperator({ budget: 500, entries: 200 });+ expect(r.needsSplit).toBe(true);+ expect(r.suggestedBatchSize).toBe(OPERATORS[r.operator].maxEntries);+ });+});diff --git a/v3/@claude-flow/cli/src/commands/memory.ts b/v3/@claude-flow/cli/src/commands/memory.tsindex 41edbbf572..e17cd27151 100644--- a/v3/@claude-flow/cli/src/commands/memory.ts+++ b/v3/@claude-flow/cli/src/commands/memory.ts@@ -1852,6 +1852,74 @@ const initMemoryCommand: Command = {}};+// #2763 dream-cycle β OAS memory-operator selector. Standalone+// subcommand that returns the highest-value consolidation operator+// that fits the given budget for the given entry count. Advisory β+// the caller decides whether to invoke that operator.+const selectOperatorCommand: Command = {+ name: 'select-operator',+ description: 'Pick the highest-value consolidation operator that fits a budget (OAS, dream-cycle #2763)',+ options: [+ { name: 'budget', short: 'b', type: 'number', required: true, description: 'Budget in abstract operator points (1 point β 1 Haiku call)' },+ { name: 'entries', short: 'e', type: 'number', required: true, description: 'Number of entries to consolidate' },+ { name: 'hint', type: 'string', choices: ['duplicates', 'verbose', 'patterns', 'general'], default: 'general', description: 'Entry-shape hint' },+ ],+ examples: [+ { command: 'claude-flow memory select-operator -b 50 -e 200', description: 'Pick operator for 200 entries within 50 points' },+ { command: 'claude-flow memory select-operator -b 5 -e 100 --hint duplicates --format json', description: 'JSON for pipelines' },+ ],+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const budget = ctx.flags.budget as number;+ const entries = ctx.flags.entries as number;+ const hint = (ctx.flags.hint as string) || 'general';++ if (budget === undefined || entries === undefined) {+ output.printError('Both --budget and --entries are required.');+ return { success: false, exitCode: 1 };+ }+ if (budget < 0 || entries < 0) {+ output.printError('Budget and entries must be non-negative.');+ return { success: false, exitCode: 1 };+ }++ const { selectOperator, OPERATORS } = await import('../memory/oas-operator-selector.js');+ const selection = selectOperator({ budget, entries, hint: hint as 'duplicates' | 'verbose' | 'patterns' | 'general' });++ if (ctx.flags.format === 'json') {+ output.printJson(selection);+ return { success: true, data: selection };+ }++ const chosen = OPERATORS[selection.operator];+ output.writeln();+ output.printBox(+ `Budget: ${budget} points Β· Entries: ${entries}\n` ++ `Operator: ${selection.operator}\n` ++ `Description: ${chosen.description}\n` ++ `Estimated cost: ${selection.estimatedCost.toFixed(2)} points\n` ++ `Needs split: ${selection.needsSplit ? `YES β batch size ${selection.suggestedBatchSize}` : 'no'}`,+ 'OAS Operator Selection (#2763)'+ );+ output.writeln();+ output.writeln(output.dim(selection.reason));++ if (selection.considered.length > 0) {+ output.writeln();+ output.writeln(output.bold('All operators considered'));+ output.printTable({+ columns: [+ { key: 'id', header: 'Operator', width: 15 },+ { key: 'cost', header: 'Est. Cost', width: 12, align: 'right', format: (v) => Number(v).toFixed(2) },+ { key: 'fits', header: 'Fits Budget', width: 12, align: 'center', format: (v) => v ? 'β' : 'β' },+ ],+ data: selection.considered,+ });+ }++ return { success: true, data: selection };+ },+};+// #2760 dream-cycle β SCM query classifier. Standalone subcommand so// users can inspect what intent a query maps to and pipe the mapped// namespaces into other tools (e.g. `memory search --namespace ...`).@@ -1901,7 +1969,7 @@ const classifyCommand: Command = {export const memoryCommand: Command = {name: 'memory',description: 'Memory management commands',- subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand],+ subcommands: [initMemoryCommand, storeCommand, retrieveCommand, searchCommand, listCommand, deleteCommand, purgeCommand, statsCommand, configureCommand, cleanupCommand, compressCommand, exportCommand, importCommand, distillCommand, backupCommand, classifyCommand, selectOperatorCommand],options: [],examples: [{ command: 'claude-flow memory store -k "key" -v "value"', description: 'Store data' },diff --git a/v3/@claude-flow/cli/src/memory/oas-operator-selector.ts b/v3/@claude-flow/cli/src/memory/oas-operator-selector.tsnew file mode 100644index 0000000000..d58d924072--- /dev/null+++ b/v3/@claude-flow/cli/src/memory/oas-operator-selector.ts@@ -0,0 +1,164 @@+/**+ * OAS (Operator-Aware Selection) memory-consolidation operator picker+ * (#2763 dream-cycle).+ *+ * Findings from the OAS paper referenced in dream-cycle #2763: memory-+ * consolidation performance improves by +48% when the caller picks the+ * RIGHT operator for the current budget + workload, instead of always+ * applying the most-expensive one. Ruflo already has multiple+ * consolidation operators (merge / summarize / compress / distill),+ * but has no cost-aware selector β every `memory consolidate` call+ * uses the same path.+ *+ * v1 MVP: rule-based selector. Cost-per-entry estimates are informed+ * by ruflo's own measured performance targets in v3/@claude-flow/cli/+ * CLAUDE.md β no external benchmark call needed. v2 will refine costs+ * from routing-outcomes trajectories.+ */++/** The four consolidation operators ruflo can apply. */+export type OperatorId = 'merge' | 'summarize' | 'compress' | 'distill';++export interface OperatorSpec {+ id: OperatorId;+ /** Estimated cost per entry, in abstract "operator points" (1 point β 1 Haiku call). */+ costPerEntry: number;+ /** Maximum recommended entry count per invocation (higher counts split). */+ maxEntries: number;+ /** What the operator does β human-readable. */+ description: string;+ /** Best when the entry set has this shape. */+ bestWhen: string;+}++export const OPERATORS: Record<OperatorId, OperatorSpec> = {+ merge: {+ id: 'merge',+ costPerEntry: 0.02, // near-free β deterministic near-duplicate merge+ maxEntries: 5000,+ description: 'Near-duplicate merge (deterministic, cosine β₯ 0.95)',+ bestWhen: 'Many near-identical entries (e.g. duplicated command traces)',+ },+ summarize: {+ id: 'summarize',+ costPerEntry: 0.5, // one Haiku call per ~2 entries+ maxEntries: 500,+ description: 'Short-to-long consolidation via Haiku (1 call per ~2 entries)',+ bestWhen: 'Verbose logs / trajectory steps that share a theme',+ },+ compress: {+ id: 'compress',+ costPerEntry: 1.5, // LoRA-style compression pass β heavier+ maxEntries: 200,+ description: 'LoRA/EWC-style compression preserving semantic embeddings',+ bestWhen: 'High-fidelity pattern preservation across many entries',+ },+ distill: {+ id: 'distill',+ costPerEntry: 3, // full distillation β heaviest+ maxEntries: 100,+ description: 'Full pattern distillation (extracts high-value patterns for ReasoningBank)',+ bestWhen: 'Extracting durable learnings from a small high-signal set',+ },+};++export interface OperatorSelection {+ operator: OperatorId;+ reason: string;+ /** Estimated cost = costPerEntry Γ min(entries, maxEntries). */+ estimatedCost: number;+ /** True if entries > operator.maxEntries and caller should split into multiple invocations. */+ needsSplit: boolean;+ suggestedBatchSize: number;+ /** All operators considered, in ranked order (best first). */+ considered: Array<{ id: OperatorId; cost: number; fits: boolean }>;+}++export interface SelectOptions {+ /** Budget in abstract operator points. */+ budget: number;+ /** Number of entries to consolidate. */+ entries: number;+ /**+ * Optional hint about entry shape:+ * 'duplicates' β strongly prefer merge (cheap wins first)+ * 'verbose' β prefer summarize+ * 'patterns' β prefer distill (small, high-signal)+ * 'general' β let cost-fit decide (default)+ */+ hint?: 'duplicates' | 'verbose' | 'patterns' | 'general';+}++/**+ * Select the highest-value operator that fits the budget.+ *+ * Selection rule (v1):+ * 1. If a hint is provided AND the hinted operator fits the budget,+ * pick it (hint is a strong signal about entry shape).+ * 2. Else, rank operators by cost ascending; pick the most expensive+ * operator that still fits budget Γ 1.0 (no over-spend). Idea:+ * spend the whole budget on the most-fidelity operator we can afford.+ * 3. If nothing fits, return merge (guaranteed cheapest) with+ * needsSplit=true so caller batches.+ */+export function selectOperator(opts: SelectOptions): OperatorSelection {+ const { budget, entries, hint } = opts;++ const considered = (Object.keys(OPERATORS) as OperatorId[]).map((id) => {+ const spec = OPERATORS[id];+ const effectiveEntries = Math.min(entries, spec.maxEntries);+ const cost = spec.costPerEntry * effectiveEntries;+ return { id, cost, fits: cost <= budget };+ }).sort((a, b) => a.cost - b.cost);++ // Rule 1: honor a shape hint if the hinted operator fits.+ const hintMap: Record<NonNullable<SelectOptions['hint']>, OperatorId> = {+ duplicates: 'merge',+ verbose: 'summarize',+ patterns: 'distill',+ general: 'compress',+ };+ if (hint && hint !== 'general') {+ const preferred = hintMap[hint];+ const match = considered.find((c) => c.id === preferred);+ if (match?.fits) {+ const spec = OPERATORS[match.id];+ return {+ operator: match.id,+ reason: `Hint "${hint}" β ${match.id} (cost ${match.cost.toFixed(2)} β€ budget ${budget})`,+ estimatedCost: match.cost,+ needsSplit: entries > spec.maxEntries,+ suggestedBatchSize: spec.maxEntries,+ considered,+ };+ }+ }++ // Rule 2: pick the most-expensive operator that still fits.+ const fitting = considered.filter((c) => c.fits);+ if (fitting.length > 0) {+ const best = fitting[fitting.length - 1]; // most expensive fitting+ const spec = OPERATORS[best.id];+ return {+ operator: best.id,+ reason: `Best-fit within budget: ${best.id} at cost ${best.cost.toFixed(2)} (budget ${budget}, entries ${entries})`,+ estimatedCost: best.cost,+ needsSplit: entries > spec.maxEntries,+ suggestedBatchSize: spec.maxEntries,+ considered,+ };+ }++ // Rule 3: budget too small for any operator on the full entry set.+ // Split via merge (cheapest) with the merge batch size.+ const mergeSpec = OPERATORS.merge;+ const batchSize = Math.max(1, Math.floor(budget / mergeSpec.costPerEntry));+ return {+ operator: 'merge',+ reason: `Budget ${budget} too small for any operator across ${entries} entries β split via merge in batches of ${batchSize}`,+ estimatedCost: budget,+ needsSplit: true,+ suggestedBatchSize: batchSize,+ considered,+ };+}