🌊 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
fix(learning): report SONA trajectory scope and live count honestly
Rudy Celekli11e04bfc52ca
diff --git a/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts b/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.tsindex a1717294a4..1097dfee7b 100644--- a/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts+++ b/v3/@claude-flow/cli/__tests__/unified-stats-2245.test.ts@@ -44,7 +44,8 @@ describe('UnifiedLearningStats shape (ADR-075)', () => {expect(stats.consistency).toBeDefined();expect(Array.isArray(stats.consistency.notes)).toBe(true);- expect(typeof stats.consistency.sonaTracksGlobal).toBe('boolean');+ expect(stats.consistency.sonaTracksGlobal).toBeNull();+ expect(stats.consistency.sonaTracksGlobalDelta).toBeNull();expect(typeof stats.generatedAt).toBe('string');});});diff --git a/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.ts b/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.tsnew file mode 100644index 0000000000..728353d18c--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/unified-stats-scope-3198.test.ts@@ -0,0 +1,49 @@+import { afterAll, describe, expect, it, vi } from 'vitest';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';++const originalCwd = process.cwd();+const project = mkdtempSync(join(tmpdir(), 'ruflo-sona-scope-3198-'));+const statsDir = join(project, '.claude-flow', 'neural');+mkdirSync(statsDir, { recursive: true });+writeFileSync(join(statsDir, 'stats.json'), JSON.stringify({+ trajectoriesRecorded: 30_622,+ patternsLearned: 0,+ signalsProcessed: 0,+ lastAdaptation: null,+}));++afterAll(() => {+ process.chdir(originalCwd);+ rmSync(project, { recursive: true, force: true });+});++describe('#3198 unified learning counters have different lifetimes', () => {+ it('does not call a fresh process-local SONA count drift from persisted history', async () => {+ process.chdir(project);+ vi.resetModules();+ const intel = await import('../src/memory/intelligence.js');+ const init = await intel.initializeIntelligence();+ expect(init.success).toBe(true);++ const stats = await intel.getUnifiedLearningStats();+ expect(stats.global.trajectoriesRecorded).toBe(30_622);+ expect(stats.sona.trajectoriesTotal).toBe(0);+ expect(stats.global.scope).toBe('project-persisted');+ expect(stats.sona.scope).toBe('process-local');+ expect(stats.sona.metric).toBe('recent-buffered-trajectories');+ expect(stats.consistency.sonaTracksGlobal).toBeNull();+ expect(stats.consistency.sonaTracksGlobalDelta).toBeNull();+ expect(stats.consistency.notes.join(' ')).toMatch(/different (scopes|lifetimes)|not comparable/i);+ expect(stats.consistency.notes.join(' ')).not.toMatch(/expected to track within/i);++ // The coordinator's actual stats() key is trajectoryCount. The old+ // aggregator read nonexistent trajectoriesTotal/trajectoriesProcessed keys,+ // so this stayed 0 even after a trajectory completed in this process.+ expect(await intel.recordTrajectory([], 'failure')).toBe(true);+ const after = await intel.getUnifiedLearningStats();+ expect(after.global.trajectoriesRecorded).toBe(30_623);+ expect(after.sona.trajectoriesTotal).toBeGreaterThan(0);+ });+});diff --git a/v3/@claude-flow/cli/src/memory/intelligence.ts b/v3/@claude-flow/cli/src/memory/intelligence.tsindex 6b9af189db..7b86efef14 100644--- a/v3/@claude-flow/cli/src/memory/intelligence.ts+++ b/v3/@claude-flow/cli/src/memory/intelligence.ts@@ -869,6 +869,7 @@ export interface UnifiedLearningStats {signalsProcessed: number;lastAdaptation: number | null;source: string;+ scope: 'project-persisted';};sona: {trajectoriesTotal: number;@@ -877,6 +878,8 @@ export interface UnifiedLearningStats {avgAdaptationTimeMs: number;source: string;available: boolean;+ scope: 'process-local';+ metric: 'recent-buffered-trajectories';};memoryBridge: {totalEntries: number;@@ -891,8 +894,9 @@ export interface UnifiedLearningStats {source: string;};consistency: {- sonaTracksGlobal: boolean;- sonaTracksGlobalDelta: number;+ /** These counters measure different lifetimes and cannot be compared. */+ sonaTracksGlobal: null;+ sonaTracksGlobalDelta: null;notes: string[];};generatedAt: string;@@ -908,12 +912,15 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {let sonaStats = { trajectoriesTotal: 0, patternsLearned: 0, reasoningBankSize: 0, avgAdaptationTimeMs: 0 };if (sonaCoord) {try {- const s = (sonaCoord as unknown as { stats?: () => Record<string, number> }).stats?.() ?? {};+ const s = sonaCoord.stats();sonaStats = {- trajectoriesTotal: Number(s.trajectoriesTotal ?? s.trajectoriesProcessed ?? 0),- patternsLearned: Number(s.totalPatterns ?? s.patternsLearned ?? 0),- reasoningBankSize: (bank as unknown as { stats?: () => { patternCount?: number } })?.stats?.()?.patternCount ?? 0,- avgAdaptationTimeMs: (sonaCoord as unknown as { getAvgAdaptationTime?: () => number }).getAvgAdaptationTime?.() ?? 0,+ // LocalSonaCoordinator.stats() reports trajectoryCount, a bounded+ // recent buffer. Reading nonexistent trajectoriesTotal / processed+ // fields made this metric permanently 0, even after learning.+ trajectoriesTotal: s.trajectoryCount,+ patternsLearned: 0,+ reasoningBankSize: bank?.stats().patternCount ?? 0,+ avgAdaptationTimeMs: s.avgAdaptationMs,};} catch { /* SONA not yet initialised */ }}@@ -936,11 +943,12 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {neuralStats = nt.getNeuralStoreStats();} catch { /* neural module not loadable */ }- // Consistency notes — describe (don't enforce) the cross-store relationships- const sonaTracksGlobalDelta = sonaStats.trajectoriesTotal - intel.trajectoriesRecorded;+ // SONA's coordinator is recreated on each process start, while globalStats+ // is restored from disk. Their counts can differ by thousands after a+ // restart even when both learning paths work correctly (#3198).const notes: string[] = [];- if (sonaAvailable && Math.abs(sonaTracksGlobalDelta) > 2) {- notes.push(`sona.trajectoriesTotal (${sonaStats.trajectoriesTotal}) drifts from globalStats.trajectoriesRecorded (${intel.trajectoriesRecorded}) by ${sonaTracksGlobalDelta} — expected to track within ±1`);+ if (sonaAvailable && sonaStats.trajectoriesTotal !== intel.trajectoriesRecorded) {+ notes.push('sona.trajectoriesTotal is a process-local, bounded recent trajectory buffer; global.trajectoriesRecorded is project-persisted. These counters have different lifetimes and are not comparable.');}if (intel.patternsLearned > 0 && neuralStats.patternCount === 0) {notes.push(`globalStats reports ${intel.patternsLearned} patterns learned but neural_patterns store is empty — pretrain has not written here, or trajectory-end isn't promoting patterns to the neural store yet`);@@ -956,17 +964,20 @@ export async function getUnifiedLearningStats(): Promise<UnifiedLearningStats> {signalsProcessed: intel.signalsProcessed,lastAdaptation: intel.lastAdaptation,source: '.claude-flow/neural/stats.json (globalStats)',+ scope: 'project-persisted',},sona: {...sonaStats,source: 'sonaCoordinator (in-memory, resets per process)',available: sonaAvailable,+ scope: 'process-local',+ metric: 'recent-buffered-trajectories',},memoryBridge: bridgeStats,neuralPatterns: neuralStats,consistency: {- sonaTracksGlobal: sonaAvailable ? Math.abs(sonaTracksGlobalDelta) <= 1 : true,- sonaTracksGlobalDelta,+ sonaTracksGlobal: null,+ sonaTracksGlobalDelta: null,notes,},generatedAt: new Date().toISOString(),diff --git a/v3/docs/adr/ADR-075-unified-learning-stats.md b/v3/docs/adr/ADR-075-unified-learning-stats.mdindex 80110b3157..49d250464b 100644--- a/v3/docs/adr/ADR-075-unified-learning-stats.md+++ b/v3/docs/adr/ADR-075-unified-learning-stats.md@@ -32,15 +32,21 @@ Add a **read-only aggregator** that calls all four stores and returns them in on```tsinterface UnifiedLearningStats {- global: { patternsLearned, trajectoriesRecorded, signalsProcessed, lastAdaptation, source };- sona: { trajectoriesTotal, patternsLearned, reasoningBankSize, avgAdaptationTimeMs, source, available };+ global: { patternsLearned, trajectoriesRecorded, signalsProcessed, lastAdaptation, source, scope: 'project-persisted' };+ sona: { trajectoriesTotal, patternsLearned, reasoningBankSize, avgAdaptationTimeMs, source, available, scope: 'process-local', metric: 'recent-buffered-trajectories' };memoryBridge: { totalEntries, perNamespace, source, reachable };neuralPatterns:{ patternCount, byType, modelCount, source };- consistency: { sonaTracksGlobal, sonaTracksGlobalDelta, notes };+ consistency: { sonaTracksGlobal: null, sonaTracksGlobalDelta: null, notes };generatedAt: string;}```+The two trajectory counters are not an equality check: SONA coordinator+state resets with each process and retains only a bounded recent buffer,+while globalStats is restored from disk.+The historical comparison fields are `null` because a numeric delta or+pass/fail verdict would misreport normal restarts as drift.+### MCP surface`hooks_intelligence_unified-stats` exposes the aggregator to MCP clients. Description names every sub-view's store and the kind of question each answers, so an LLM agent can choose between this (one coherent dashboard) and the original narrow aggregators (one specific slice).diff --git a/v3/docs/learning/self-learning-usage.md b/v3/docs/learning/self-learning-usage.mdindex 09a75616a1..9cebda4698 100644--- a/v3/docs/learning/self-learning-usage.md+++ b/v3/docs/learning/self-learning-usage.md@@ -160,14 +160,20 @@ node v3/@claude-flow/cli/scripts/benchmark-pretrained-retrieval.mjs## How to read the consistency block-When `hooks_intelligence_unified-stats` returns a non-empty `consistency.notes`,-that's a real cross-store drift you should look at:+`hooks_intelligence_unified-stats` reports two trajectory counters with different+lifetimes. `global.trajectoriesRecorded` is persisted for the project;+`sona.trajectoriesTotal` counts the bounded recent trajectory buffer in this+process.+A fresh process can therefore report SONA 0 beside thousands of persisted+trajectories without a learning failure. The counters cannot be compared.+Other `consistency.notes` can still identify actionable cross-store gaps:```jsonc"consistency": {- "sonaTracksGlobal": true, // SONA matches globalStats within ±1- "sonaTracksGlobalDelta": 0,+ "sonaTracksGlobal": null, // different lifetimes; no valid comparison+ "sonaTracksGlobalDelta": null,"notes": [+ "sona.trajectoriesTotal is a process-local, bounded recent trajectory buffer; global.trajectoriesRecorded is project-persisted. These counters have different lifetimes and are not comparable.","globalStats reports 47 patterns learned but neural_patterns store is empty — pretrain has not written here, or trajectory-end isn't promoting patterns to the neural store yet"]}