Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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,
+ };
+}