🌊 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(cli): memory_stats answers from the store, not from a raw file probe (#3319)
Lukas Buck84950144f567
diff --git a/v3/@claude-flow/cli/__tests__/issue-3311-memory-stats-uses-the-bridge.test.ts b/v3/@claude-flow/cli/__tests__/issue-3311-memory-stats-uses-the-bridge.test.tsnew file mode 100644index 0000000000..e23210feac--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/issue-3311-memory-stats-uses-the-bridge.test.ts@@ -0,0 +1,166 @@+/**+ * #3311: `memory_stats` decided whether memory existed with a raw whole-image+ * sql.js probe, which cannot see live SQLite WAL frames. A store the bridge+ * read and searched perfectly well came back `initialized: false` from this+ * one tool, and a listing that failed came back as a store with no entries.+ */+import { beforeEach, describe, expect, it, vi } from 'vitest';++const checkMemoryInitialization = vi.fn();+const listEntries = vi.fn();++vi.mock('../src/memory/memory-initializer.js', () => ({+ checkMemoryInitialization: (...args: unknown[]) => checkMemoryInitialization(...args),+ listEntries: (...args: unknown[]) => listEntries(...args),+ initializeMemoryDatabase: vi.fn(async () => ({ success: true })),+ storeEntry: vi.fn(async () => ({ success: true })),+ searchEntries: vi.fn(async () => ({ results: [] })),+ getEntry: vi.fn(async () => null),+ deleteEntry: vi.fn(async () => ({ success: true })),+ getHNSWStatus: () => ({ algorithm: 'brute-force' }),+}));++const { memoryTools } = await import('../src/mcp-tools/memory-tools.js');+const stats = memoryTools.find(tool => tool.name === 'memory_stats')!;++const row = (namespace: string, hasEmbedding = false) => ({+ id: `id-${namespace}-${Math.random()}`,+ key: 'k',+ namespace,+ size: 1,+ accessCount: 0,+ createdAt: '2026-01-01T00:00:00Z',+ updatedAt: '2026-01-01T00:00:00Z',+ hasEmbedding,+});++/** One page of rows, the way the store answers a successful listing. */+const page = (entries: ReturnType<typeof row>[], total = entries.length) => ({+ success: true,+ entries,+ total,+});++beforeEach(() => {+ checkMemoryInitialization.mockReset();+ listEntries.mockReset();+ // The probe answers for a store it cannot see: this is the reported+ // failure, and the default for every case below unless a test says+ // otherwise.+ checkMemoryInitialization.mockResolvedValue({ initialized: false });+});++describe('#3311 memory_stats', () => {+ it('reports a store the bridge can list, even when the raw probe says no', async () => {+ listEntries.mockResolvedValue(page([row('default', true), row('default')]));++ const result = await stats.handler({}) as any;++ expect(result.initialized).toBe(true);+ expect(result.totalEntries).toBe(2);+ expect(result.entriesWithEmbeddings).toBe(1);+ expect(result.embeddingCoverage).toBe('50.0%');+ });++ it('does not consult the probe for whether the store is there', async () => {+ listEntries.mockResolvedValue(page([row('default')]));+ checkMemoryInitialization.mockRejectedValue(new Error('raw whole-image read refused (WAL)'));++ const result = await stats.handler({}) as any;++ // The probe is the only source of the version and feature labels, so it+ // is still read -- it just cannot veto a store that answered.+ expect(result.initialized).toBe(true);+ expect(result.totalEntries).toBe(1);+ expect(result.error).toBeUndefined();+ });++ it('reports a failed listing as unavailable, not as an empty store', async () => {+ listEntries.mockResolvedValue({+ success: false,+ entries: [],+ total: 0,+ error: 'raw WAL safety guard refused a whole-image read',+ });++ const result = await stats.handler({}) as any;++ expect(result.available).toBe(false);+ expect(result.error).toMatch(/WAL/);+ // The point of the cell: no fabricated zero for a question that was+ // never answered.+ expect(result.totalEntries).toBeUndefined();+ expect(result.initialized).not.toBe(false);+ });++ it('reports a thrown listing as unavailable too', async () => {+ listEntries.mockRejectedValue(new Error('registry unavailable'));++ const result = await stats.handler({}) as any;++ expect(result.available).toBe(false);+ expect(result.error).toMatch(/registry unavailable/);+ expect(result.totalEntries).toBeUndefined();+ });++ it('still reports an empty store as empty', async () => {+ // The accept control for the two cells above: "nothing there" and+ // "could not tell" must stay different answers.+ listEntries.mockResolvedValue(page([], 0));++ const result = await stats.handler({}) as any;++ expect(result.initialized).toBe(true);+ expect(result.available).toBeUndefined();+ expect(result.totalEntries).toBe(0);+ expect(result.embeddingCoverage).toBe('0%');+ });++ it('counts a namespace named __proto__ instead of losing it', async () => {+ listEntries.mockResolvedValue(page([row('__proto__'), row('__proto__'), row('constructor')]));++ const result = await stats.handler({}) as any;++ expect(result.namespaces.__proto__).toBe(2);+ expect(result.namespaces.constructor).toBe(1);+ expect(result.totalEntries).toBe(3);+ });++ it('pages past the old 100000 cap rather than counting a prefix', async () => {+ const total = 25000;+ listEntries.mockImplementation(async ({ offset = 0, limit = 10000 }) => ({+ success: true,+ entries: Array.from({ length: Math.max(0, Math.min(limit, total - offset)) }, () =>+ row(offset < 10000 ? 'early' : 'late')),+ total,+ }));++ const result = await stats.handler({}) as any;++ expect(result.totalEntries).toBe(total);+ expect(result.entriesCounted).toBe(total);+ expect(result.truncated).toBeUndefined();+ expect(result.namespaces.early + result.namespaces.late).toBe(total);+ // Asked for in pages, not in one 100000-row gulp.+ expect(listEntries.mock.calls.length).toBeGreaterThan(1);+ for (const [options] of listEntries.mock.calls) {+ expect(options.limit).toBeLessThanOrEqual(10000);+ }+ });++ it('says so when it could not count every row', async () => {+ // A `total` the rows never reach: the loop has to stop, and what it+ // reports then must not read as a complete breakdown.+ listEntries.mockImplementation(async () => ({+ success: true,+ entries: Array.from({ length: 10000 }, () => row('default')),+ total: 10_000_000,+ }));++ const result = await stats.handler({}) as any;++ expect(result.truncated).toBe(true);+ expect(result.totalEntries).toBe(10_000_000);+ expect(result.entriesCounted).toBeLessThan(10_000_000);+ });+});diff --git a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.tsindex 4c28d91f3c..5b2ac16e85 100644--- a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts+++ b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts@@ -280,6 +280,81 @@ async function describeBackend(): Promise<string> {}}+/** #3311: one page per round trip, so a store larger than one page is+ * counted rather than silently cut off at the old hardcoded 100000. */+const MEMORY_STATS_PAGE = 10000;++/** #3311: a hard stop so a `total` that never agrees with the rows returned+ * cannot spin forever. Reaching it is reported as a truncated count, not as+ * a complete one. */+const MEMORY_STATS_MAX_PAGES = 200;++/** The shape one page of `listEntries` comes back in, generic over the row+ * type so paging does not widen or narrow what the caller already has. */+type ListPage<E> = {+ success: boolean;+ entries: E[];+ total: number;+ error?: string;+};++/**+ * Page through the store and return every row, or the first failure.+ *+ * The old call asked for `limit: 100000` in one shot and read only+ * `entries`/`total` off the result — so a bigger store had its namespace+ * breakdown and embedding coverage computed from a prefix, and a listing+ * that reported `success: false` was read as an empty one.+ */+async function collectAllEntries<E>(+ listEntries: (options: { limit?: number; offset?: number }) => Promise<ListPage<E>>,+): Promise<ListPage<E>> {+ const entries: E[] = [];+ let total = 0;++ for (let page = 0; page < MEMORY_STATS_MAX_PAGES; page++) {+ const result = await listEntries({ limit: MEMORY_STATS_PAGE, offset: entries.length });+ if (!result.success) {+ return { success: false, entries, total: result.total ?? total, error: result.error };+ }+ total = result.total;+ entries.push(...result.entries);+ if (result.entries.length === 0 || entries.length >= total) break;+ }++ return { success: true, entries, total };+}++/** #3311: unavailable is its own answer. The zeros this replaces were+ * indistinguishable from a store that really is empty. */+function memoryStatsUnavailable(error: string): {+ initialized: null;+ available: false;+ error: string;+} {+ return { initialized: null, available: false, error };+}++/**+ * Version and feature labels from the initialization probe.+ *+ * Metadata only. The probe reads a whole-image snapshot that cannot see live+ * WAL frames, so it is allowed to fail without that meaning the store is+ * missing — which is exactly the conflation #3311 reports.+ */+async function readMemoryStatusLabels(): Promise<{+ version?: string;+ features?: { vectorEmbeddings: boolean; patternLearning: boolean; temporalDecay: boolean };+}> {+ try {+ const { checkMemoryInitialization } = await getMemoryFunctions();+ const status = await checkMemoryInitialization();+ return { version: status.version, features: status.features };+ } catch {+ return {};+ }+}+/*** Ensure memory database is initialized and migrate legacy data if needed.* #1606: Wrapped in try/catch to prevent process-level crashes that kill@@ -772,43 +847,62 @@ export const memoryTools: MCPTool[] = [},handler: async () => {await ensureInitialized();- const { checkMemoryInitialization, listEntries } = await getMemoryFunctions();+ const { listEntries } = await getMemoryFunctions();+ // #3311: the store's own listing decides whether memory is there.+ // `checkMemoryInitialization` opens a whole-image sql.js snapshot of+ // the main database file, which cannot include live SQLite WAL frames+ // — so a store the bridge reads and searches perfectly well came back+ // `initialized: false` from this tool alone. The probe is still read+ // below, for the version and feature labels it is the only source of,+ // but it no longer gets to overrule a working store.+ let listing: ListPage<{ namespace: string; hasEmbedding: boolean }>;try {- const status = await checkMemoryInitialization();- const allEntries = await listEntries({ limit: 100000 });+ listing = await collectAllEntries(listEntries);+ } catch (error) {+ return memoryStatsUnavailable(error instanceof Error ? error.message : 'Unknown error');+ }+ if (!listing.success) {+ // A failed query is not an empty store. Reporting zeros here is+ // what made a WAL refusal look like "you have no memories".+ return memoryStatsUnavailable(listing.error || 'listEntries reported failure');+ }- // Count by namespace- const namespaces: Record<string, number> = {};- let withEmbeddings = 0;+ // Object.create(null): a namespace literally named `__proto__` is a+ // legal key, and assigning it on an object literal sets the prototype+ // instead of counting anything — so that namespace's entries vanished+ // from the breakdown while still being counted in the total.+ const namespaces: Record<string, number> = Object.create(null) as Record<string, number>;+ let withEmbeddings = 0;+ for (const entry of listing.entries) {+ namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;+ if (entry.hasEmbedding) withEmbeddings++;+ }- for (const entry of allEntries.entries) {- namespaces[entry.namespace] = (namespaces[entry.namespace] || 0) + 1;- if (entry.hasEmbedding) withEmbeddings++;- }+ const counted = listing.entries.length;+ const status = await readMemoryStatusLabels();- return {- initialized: status.initialized,- totalEntries: allEntries.total,- entriesWithEmbeddings: withEmbeddings,- embeddingCoverage: allEntries.total > 0- ? `${((withEmbeddings / allEntries.total) * 100).toFixed(1)}%`- : '0%',- namespaces,- backend: await describeBackend(),- version: status.version || '3.0.0',- features: status.features || {- vectorEmbeddings: true,- hnswIndex: true,- semanticSearch: true,- },- };- } catch (error) {- return {- initialized: false,- error: error instanceof Error ? error.message : 'Unknown error',- };- }+ return {+ initialized: true,+ totalEntries: listing.total,+ entriesCounted: counted,+ // The breakdown below covers `entriesCounted` rows, which is every+ // row unless the listing was truncated; say so rather than letting+ // a partial count read as the whole store.+ ...(counted < listing.total ? { truncated: true } : {}),+ entriesWithEmbeddings: withEmbeddings,+ embeddingCoverage: counted > 0+ ? `${((withEmbeddings / counted) * 100).toFixed(1)}%`+ : '0%',+ namespaces: { ...namespaces },+ backend: await describeBackend(),+ version: status.version || '3.0.0',+ features: status.features || {+ vectorEmbeddings: true,+ hnswIndex: true,+ semanticSearch: true,+ },+ };},},{