🌊 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(console): memory health in the Memory Lab (ADR-457)
ruvc15bf29cbec9
diff --git a/plugins/ruflo-console/hooks/data/memory-health.ts b/plugins/ruflo-console/hooks/data/memory-health.tsnew file mode 100644index 0000000000..a27411189a--- /dev/null+++ b/plugins/ruflo-console/hooks/data/memory-health.ts@@ -0,0 +1,243 @@+/**+ * Memory health (ADR-457): duplicate and near-duplicate clusters, stale entries and never-recalled namespaces, read from+ * what `memory list --format json` already prints. Pure and read-only: nothing here runs a command or touches a store.+ *+ * What the list carries is key, namespace, size, accessCount, createdAt, updatedAt and whether a vector exists, and NOT+ * the value, so this reads no memory content at all. Three consequences, each stated in the UI rather than hidden:+ * - a duplicate is judged on the key and the size (exact: same normalised key and same size; near: similar key tokens+ * and a close size), never on the value;+ * - "recalled" means accessCount > 0, the count the CLI bumps when an entry is retrieved; there is no last-recalled+ * timestamp, so "stale" means never recalled AND not updated for STALE_DAYS, and a recalled entry is never called stale;+ * - the list is the newest HEALTH_CAP entries, and the pairwise comparison has a budget (PAIR_CAP). Both limits are+ * returned in the result so the view prints them: nothing is truncated silently.+ */+import { type Probe, jsonAfter } from './cli'+import { msOf, numberOf, recordOf, stringOf } from './parse'++/** Entries read from the store, newest first: the cap the view shows beside every figure. */+export const HEALTH_CAP = 1000+/** Pairwise key comparisons allowed per analysis; the newest entries are compared first and the rest are reported skipped. */+export const PAIR_CAP = 500_000+/** An entry nobody recalled and nobody updated for this long is stale. */+export const STALE_DAYS = 30+/** Key-token Jaccard at or above this, with sizes within SIZE_RATIO of each other, makes two entries near-duplicates. */+export const NEAR_JACCARD = 0.75+export const SIZE_RATIO = 0.2+/** Members kept per cluster and clusters kept in total: the counts above them are exact, the lists are bounded. */+export const CLUSTER_MEMBERS = 8+export const CLUSTERS_KEPT = 12++export type HealthEntry = { key: string; namespace: string; size: number; accessCount: number; updatedAtMs?: number; createdAtMs?: number }+export type HealthSample = { listed: number; entries: HealthEntry[] }++/** The array a list printed: log lines such as `[INFO] …` before it open with `[` too, so the array is the one that opens with `[{`, `[]` or a bare `[`. */+function listJson(stdout: string): unknown {+ const start = /^[ \t]*\[(?=\s*(?:[{\]]|$))/m.exec(stdout)++ return start === null ? jsonAfter(stdout) : jsonAfter(stdout.slice(start.index))+}++/** `memory list` over the newest HEALTH_CAP entries, read as a health sample. */+export const memoryHealthProbe: Probe<HealthSample> = {+ id: 'memory-health',+ args: ['memory', 'list', '--format', 'json', '--limit', String(HEALTH_CAP)],+ views: ['memory'],+ everyMs: 120_000,+ timeoutMs: 45_000,+ parse: stdout => {+ const value = listJson(stdout)++ if (!Array.isArray(value)) return null++ const entries: HealthEntry[] = []++ for (const item of value.slice(0, HEALTH_CAP)) {+ const record = recordOf(item)+ const key = stringOf(record?.key, 128)++ if (record === null || key === undefined) continue++ const updatedAtMs = msOf(record.updatedAt)+ const createdAtMs = msOf(record.createdAt)++ entries.push({+ key,+ namespace: stringOf(record.namespace, 40) ?? '(none)',+ size: Math.max(0, numberOf(record.size) ?? 0),+ accessCount: Math.max(0, numberOf(record.accessCount) ?? 0),+ ...(updatedAtMs !== undefined && { updatedAtMs }),+ ...(createdAtMs !== undefined && { createdAtMs }),+ })+ }++ return { listed: Math.min(value.length, HEALTH_CAP), entries }+ },+}++/** A key with case and separators removed, so `Api/Auth`, `api-auth` and `api_auth` compare equal. */+export const normaliseKey = (key: string): string => key.toLowerCase().replace(/[^a-z0-9]+/g, '')++/** The words of a key: split on separators and case humps, lowercased, single characters dropped. */+export function keyTokens(key: string): Set<string> {+ const words = key.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/)++ return new Set(words.filter(word => word.length > 1))+}++export function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number {+ if (a.size === 0 && b.size === 0) return 0++ let shared = 0++ for (const word of a) if (b.has(word)) shared += 1++ return shared / (a.size + b.size - shared)+}++const sizeClose = (a: number, b: number): boolean => Math.abs(a - b) <= SIZE_RATIO * Math.max(a, b, 1)++export type PairKind = 'exact' | 'near' | null++/** How two entries relate: the same normalised key and size (exact), similar key words and a close size (near), or not. */+export function pairKind(a: HealthEntry, b: HealthEntry, tokensA: ReadonlySet<string>, tokensB: ReadonlySet<string>): PairKind {+ if (a.namespace === b.namespace && a.key === b.key) return null++ if (normaliseKey(a.key) === normaliseKey(b.key) && normaliseKey(a.key) !== '') return a.size === b.size ? 'exact' : 'near'++ return sizeClose(a.size, b.size) && jaccard(tokensA, tokensB) >= NEAR_JACCARD ? 'near' : null+}++export type Cluster = { kind: 'exact' | 'near'; size: number; members: { namespace: string; key: string; size: number }[] }++export type NamespaceHealth = { name: string; count: number; recalled: number; stale: number; isNeverRecalled: boolean }++export type HealthReport = {+ /** Entries analysed, and how many the store listed in total (equal unless the list itself was cut). */+ analysed: number+ /** Duplicate analysis: pairs compared of pairs possible; `isTruncated` when the budget cut the older entries out. */+ pairsCompared: number+ pairsPossible: number+ isTruncated: boolean+ entriesCompared: number+ clusters: Cluster[]+ clusterCount: number+ /** Entries that sit in some cluster, counting every member (a cluster of 3 is 3). */+ duplicateEntries: number+ stale: HealthEntry[]+ staleCount: number+ neverRecalledEntries: number+ namespaces: NamespaceHealth[]+ neverRecalledNamespaces: string[]+}++/** Find the clusters: union of every exact/near pair among the newest entries the pair budget reaches. */+function findClusters(entries: readonly HealthEntry[], pairCap: number): { clusters: Cluster[]; compared: number; entriesCompared: number; isTruncated: boolean; possible: number } {+ const n = entries.length+ const possible = (n * (n - 1)) / 2+ const parent = entries.map((_, index) => index)+ const kinds = new Map<number, Set<'exact' | 'near'>>()+ const find = (index: number): number => {+ let root = index++ while (parent[root] !== root) root = parent[root] ?? root++ parent[index] = root++ return root+ }+ const tokens = entries.map(entry => keyTokens(entry.key))+ let compared = 0+ let reached = n+ const pairKinds: { a: number; b: number; kind: 'exact' | 'near' }[] = []++ // Entry j is compared against every older-in-list entry before it, so the budget drops the oldest entries first.+ outer: for (let j = 1; j < n; j += 1) {+ for (let i = 0; i < j; i += 1) {+ if (compared >= pairCap) {+ reached = j++ break outer+ }++ compared += 1++ const entryA = entries[i]+ const entryB = entries[j]+ const kind = entryA === undefined || entryB === undefined ? null : pairKind(entryA, entryB, tokens[i] ?? new Set(), tokens[j] ?? new Set())++ if (kind !== null) pairKinds.push({ a: i, b: j, kind })+ }+ }++ for (const { a, b } of pairKinds) parent[find(a)] = find(b)++ for (const { a, kind } of pairKinds) {+ const root = find(a)+ const set = kinds.get(root) ?? new Set<'exact' | 'near'>()++ set.add(kind)+ kinds.set(root, set)+ }++ const groups = new Map<number, number[]>()++ for (let index = 0; index < n; index += 1) {+ const root = find(index)++ if (kinds.has(root)) groups.set(root, [...(groups.get(root) ?? []), index])+ }++ const clusters: Cluster[] = [...groups].map(([root, indexes]) => ({+ // A cluster is exact only when every link inside it is exact.+ kind: kinds.get(root)?.has('near') === true ? 'near' : 'exact',+ size: indexes.length,+ members: indexes.slice(0, CLUSTER_MEMBERS).flatMap(index => {+ const entry = entries[index]++ return entry === undefined ? [] : [{ namespace: entry.namespace, key: entry.key, size: entry.size }]+ }),+ }))++ clusters.sort((a, b) => (a.kind === b.kind ? b.size - a.size : a.kind === 'exact' ? -1 : 1))++ return { clusters, compared, entriesCompared: reached, isTruncated: reached < n, possible }+}++/** The whole report for a sample at `nowMs`; all limits are arguments so a test can shrink them. */+export function analyseHealth(sample: HealthSample, nowMs: number, options: { staleDays?: number; pairCap?: number } = {}): HealthReport {+ const staleDays = options.staleDays ?? STALE_DAYS+ const entries = [...sample.entries].sort((a, b) => (b.updatedAtMs ?? 0) - (a.updatedAtMs ?? 0))+ const cutoff = nowMs - staleDays * 86_400_000+ const found = findClusters(entries, options.pairCap ?? PAIR_CAP)+ // An entry with no timestamp is never called stale: its age is unknown, not old.+ const isStale = (entry: HealthEntry): boolean => entry.accessCount === 0 && entry.updatedAtMs !== undefined && entry.updatedAtMs < cutoff+ const stale = entries.filter(isStale).sort((a, b) => (a.updatedAtMs ?? 0) - (b.updatedAtMs ?? 0))+ const byName = new Map<string, NamespaceHealth>()++ for (const entry of entries) {+ const space = byName.get(entry.namespace) ?? { name: entry.namespace, count: 0, recalled: 0, stale: 0, isNeverRecalled: false }++ space.count += 1+ if (entry.accessCount > 0) space.recalled += 1+ if (isStale(entry)) space.stale += 1+ byName.set(entry.namespace, space)+ }++ const namespaces = [...byName.values()].map(space => ({ ...space, isNeverRecalled: space.count > 0 && space.recalled === 0 })).sort((a, b) => b.count - a.count)++ return {+ analysed: entries.length,+ pairsCompared: found.compared,+ pairsPossible: found.possible,+ isTruncated: found.isTruncated,+ entriesCompared: found.entriesCompared,+ clusters: found.clusters.slice(0, CLUSTERS_KEPT),+ clusterCount: found.clusters.length,+ duplicateEntries: found.clusters.reduce((sum, cluster) => sum + cluster.size, 0),+ stale: stale.slice(0, 10),+ staleCount: stale.length,+ neverRecalledEntries: entries.filter(entry => entry.accessCount === 0).length,+ namespaces,+ neverRecalledNamespaces: namespaces.filter(space => space.isNeverRecalled).map(space => space.name),+ }+}diff --git a/plugins/ruflo-console/hooks/views/memory-health.ts b/plugins/ruflo-console/hooks/views/memory-health.tsnew file mode 100644index 0000000000..97d61265b5--- /dev/null+++ b/plugins/ruflo-console/hooks/views/memory-health.ts@@ -0,0 +1,116 @@+import type { RenderElement } from 'claude-code'++import { analyseHealth, HEALTH_CAP, type HealthReport, type HealthSample, NEAR_JACCARD, PAIR_CAP, STALE_DAYS } from '../data/memory-health'+import { gauge } from '../memory-lines'+import { ago, button, clip, confirmHere, count, kv, live, row, sourceLine, text, THEME, type Ctx } from './common'++/** The probe id the integrator registers (data/memory-health.ts memoryHealthProbe). */+export const HEALTH_PROBE = 'memory-health'+/** Clusters and stale entries drawn at once; the counts above are exact, the lists are bounded and say so. */+const SHOW_CLUSTERS = 5+const SHOW_STALE = 5++const share = (part: number, whole: number): string => (whole <= 0 ? 'n/a' : `${Math.round((part / whole) * 100)}%`)++/** What limits the figures, in one line: the list cap, the pair budget, and what was left out. Never omitted. */+export function limitsLine(report: HealthReport, total: number | undefined): string {+ const listCut = total !== undefined && total > report.analysed ? ` of ${count(total)} stored (the newest ${HEALTH_CAP} are read)` : ''+ const pairs = report.isTruncated ? `pair budget ${count(PAIR_CAP)} reached: only the newest ${report.entriesCompared} entries were compared` : `${count(report.pairsCompared)} of ${count(report.pairsPossible)} pairs compared`++ return `${report.analysed} entries${listCut} · ${pairs} · from key and size only, no values read`+}++function summaryRows(ctx: Ctx, report: HealthReport, total: number | undefined): RenderElement[] {+ const width = Math.max(8, Math.min(24, ctx.columns - 50))++ return [+ text(ctx, ` ${limitsLine(report, total)}`, report.isTruncated ? { color: THEME.warn } : { dimColor: true }),+ kv(ctx, 'duplicates', `${gauge(report.duplicateEntries, report.analysed, width)} ${report.duplicateEntries} entries in ${report.clusterCount} cluster${report.clusterCount === 1 ? '' : 's'} (${share(report.duplicateEntries, report.analysed)})`, report.clusterCount === 0 ? THEME.ok : THEME.warn),+ kv(ctx, 'stale', `${gauge(report.staleCount, report.analysed, width)} ${report.staleCount} never recalled and not updated for ${STALE_DAYS}d (${share(report.staleCount, report.analysed)})`, report.staleCount === 0 ? THEME.ok : THEME.warn),+ kv(ctx, 'never recalled', `${report.neverRecalledEntries} of ${report.analysed} entries have an access count of 0 · ${report.neverRecalledNamespaces.length} whole namespace${report.neverRecalledNamespaces.length === 1 ? '' : 's'}`),+ ]+}++function clusterRows(ctx: Ctx, report: HealthReport): RenderElement[] {+ if (report.clusterCount === 0) return [text(ctx, ` no duplicate or near-duplicate keys among these entries (near = key words ≥ ${Math.round(NEAR_JACCARD * 100)}% alike and a close size)`, { color: THEME.ok })]++ const rows: RenderElement[] = []++ for (const cluster of report.clusters.slice(0, SHOW_CLUSTERS)) {+ const names = cluster.members.slice(0, 3).map(member => `${member.namespace}/${member.key}`).join(' · ')+ const more = cluster.size > 3 ? ` +${cluster.size - 3}` : ''++ rows.push(row(ctx, [ctx.kit.Text({ bold: true, color: cluster.kind === 'exact' ? THEME.bad : THEME.warn, children: ` ${cluster.kind === 'exact' ? 'same ' : 'near '}×${cluster.size} ` }), text(ctx, clip(`${names}${more}`, Math.max(10, ctx.columns - 14)), { color: THEME.info })]))+ }++ if (report.clusterCount > SHOW_CLUSTERS) rows.push(text(ctx, ` +${report.clusterCount - SHOW_CLUSTERS} more cluster${report.clusterCount - SHOW_CLUSTERS === 1 ? '' : 's'} not drawn (the counts above include them)`, { dimColor: true }))++ return rows+}++function staleRows(ctx: Ctx, report: HealthReport): RenderElement[] {+ const rows = report.stale.slice(0, SHOW_STALE).map(entry => text(ctx, ` ${clip(`${entry.namespace}/${entry.key}`, Math.max(10, ctx.columns - 24))} updated ${ago(entry.updatedAtMs, ctx.nowMs)}`, { color: THEME.warn }))++ if (report.staleCount > SHOW_STALE) rows.push(text(ctx, ` +${report.staleCount - SHOW_STALE} more, oldest shown first`, { dimColor: true }))+ if (rows.length === 0) rows.push(text(ctx, ` no entry is both unrecalled and ${STALE_DAYS}+ days untouched`, { color: THEME.ok }))++ return rows+}++function namespaceRows(ctx: Ctx, report: HealthReport): RenderElement[] {+ const width = Math.max(6, Math.min(20, ctx.columns - 60))+ const rows = report.namespaces.slice(0, 8).map(space =>+ row(ctx, [+ ctx.kit.Text({ color: space.isNeverRecalled ? THEME.warn : THEME.info, children: ` ${clip(space.name, 18).padEnd(19)}` }),+ ctx.kit.Text({ dimColor: true, children: `${gauge(space.recalled, space.count, width)} ${space.recalled}/${space.count} recalled${space.stale > 0 ? ` · ${space.stale} stale` : ''}${space.isNeverRecalled ? ' · never recalled' : ''}` }),+ ]),+ )++ if (report.namespaces.length > 8) rows.push(text(ctx, ` +${report.namespaces.length - 8} smaller namespaces not drawn`, { dimColor: true }))++ return rows+}++/**+ * Consolidate runs the existing AgentDB consolidate (mem-consolidate) behind the lab's confirm card. Its answer is drawn+ * here, so the person who pressed it sees it: the run is raised under the AgentDB group and re-homed to this section.+ */+function consolidateRows(ctx: Ctx): RenderElement[] {+ const lab = ctx.state.memoryLab+ const press = () => {+ ctx.act.memory.run('mem-consolidate')+ lab.origin = 'health'+ }++ return [+ row(ctx, [+ button(ctx, 'mem-health-consolidate', '▸ consolidate', press, { primary: true }),+ text(ctx, ' AgentDB consolidate: merges and promotes across tiers; asks first. It does not delete the keys listed above, delete those one by one (DELETE).', { dimColor: true }),+ ]),+ ...(lab.origin === 'health' ? confirmHere(ctx, 'mem:agentdb') : []),+ ]+}++/** The health section's rows, or one honest line when the probe has not answered. */+export function healthRows(ctx: Ctx, now: () => number = () => ctx.nowMs): RenderElement[] {+ const result = ctx.state.probes.get(HEALTH_PROBE)+ const sample = live<HealthSample>(result)++ if (sample === null) return [text(ctx, ` ${sourceLine(result, ctx.nowMs, 'memory health (memory list)').text}${result === undefined ? ' (the health probe is not registered in this build)' : ''}`, { dimColor: true })]++ if (sample.entries.length === 0) return [text(ctx, ' no entries to analyse: store one, or import your Claude memories (IMPORT CLAUDE)', { dimColor: true })]++ const report = analyseHealth(sample, now())+ const total = live<{ total?: number }>(ctx.state.probes.get('memory'))?.total++ return [+ ...summaryRows(ctx, report, total),+ text(ctx, ' duplicate clusters', { bold: true, color: THEME.head }),+ ...clusterRows(ctx, report),+ text(ctx, ' stale entries', { bold: true, color: THEME.head }),+ ...staleRows(ctx, report),+ text(ctx, ' recall by namespace', { bold: true, color: THEME.head }),+ ...namespaceRows(ctx, report),+ ...consolidateRows(ctx),+ ]+}diff --git a/plugins/ruflo-console/hooks/views/memory-lab.ts b/plugins/ruflo-console/hooks/views/memory-lab.tsindex 20e81b4155..547b94cde8 100644--- a/plugins/ruflo-console/hooks/views/memory-lab.ts+++ b/plugins/ruflo-console/hooks/views/memory-lab.ts@@ -2,6 +2,7 @@ import type { RenderElement } from 'claude-code'import { MEM_GROUPS, MEM_LAB, memSpecOf, textOfFields, type MemCost, type MemEntry, type MemField } from '../memory-lab'import { ago, button, clip, confirmHere, type Ctx, row, rule, section, tagChip, text, THEME } from './common'+import { healthRows } from './memory-health'import { frameResult } from './status-card'/** Result lines in view at once; j/k scroll the rest. */@@ -142,7 +143,7 @@ function resultRows(ctx: Ctx): RenderElement[] {*/export function memoryLabRows(ctx: Ctx): RenderElement[] {const lead = Math.max(15, Math.min(18, ctx.columns - 40))- const rows: RenderElement[] = [...searchRows(ctx), ...areaPanel(ctx, 'search'), ...entryRows(ctx), ...areaPanel(ctx, 'entry')]+ const rows: RenderElement[] = [...section(ctx, 'mem-g-health', 'Memory health', 'duplicates, stale, never recalled · read-only', [...healthRows(ctx), ...areaPanel(ctx, 'health')], true), ...searchRows(ctx), ...areaPanel(ctx, 'search'), ...entryRows(ctx), ...areaPanel(ctx, 'entry')]rows.push(rule(ctx, 'Lab text', 'the input for the rows below that take text'))rows.push(field(ctx, 'text', 'text', 'a query or pattern · a node id · a | b to compare · source relation target', 'keep', value => ctx.act.memory.draft('text', value)))diff --git a/plugins/ruflo-console/tests/memory-health.spec.ts b/plugins/ruflo-console/tests/memory-health.spec.tsnew file mode 100644index 0000000000..1c565ae8b9--- /dev/null+++ b/plugins/ruflo-console/tests/memory-health.spec.ts@@ -0,0 +1,159 @@+/**+ * Memory health (ADR-457): the pure analysis, the probe's reader, and the view's honest states. Run with+ * npx vitest run plugins/ruflo-console/tests/memory-health.spec.ts+ */+import { describe, expect, it } from 'vitest'++import { analyseHealth, HEALTH_CAP, jaccard, keyTokens, memoryHealthProbe, normaliseKey, type HealthEntry } from '../hooks/data/memory-health'+import { newState } from '../hooks/state'+import type { Ctx } from '../hooks/views/common'+import { healthRows, limitsLine } from '../hooks/views/memory-health'++const DAY = 86_400_000+const NOW = 1_800_000_000_000+const e = (namespace: string, key: string, size: number, accessCount: number, ageDays: number): HealthEntry => ({ namespace, key, size, accessCount, updatedAtMs: NOW - ageDays * DAY })++describe('memory health analysis', () => {+ it('normalises keys across case and separators and tokenises humps', () => {+ expect(normaliseKey('Api/Auth_Token')).toBe('apiauthtoken')+ expect([...keyTokens('authTokenRefresh')]).toEqual(['auth', 'token', 'refresh'])+ expect(jaccard(new Set(['a', 'b']), new Set(['b', 'c']))).toBeCloseTo(1 / 3)+ expect(jaccard(new Set(), new Set())).toBe(0)+ })++ it('clusters exact duplicates (same normalised key and size) and near ones (similar words, close size)', () => {+ const report = analyseHealth(+ { listed: 5, entries: [e('a', 'api/auth', 100, 1, 1), e('b', 'api-auth', 100, 1, 2), e('a', 'jwt-refresh-token-rotation', 200, 1, 3), e('a', 'jwt-refresh-token-rotation-v2', 210, 1, 4), e('a', 'unrelated', 50, 1, 5)] },+ NOW,+ )++ expect(report.clusterCount).toBe(2)+ expect(report.clusters[0]).toMatchObject({ kind: 'exact', size: 2 })+ expect(report.clusters[1]).toMatchObject({ kind: 'near', size: 2 })+ expect(report.duplicateEntries).toBe(4)+ })++ it('does not call far-apart sizes near, and a single entry is never a cluster', () => {+ const report = analyseHealth({ listed: 2, entries: [e('a', 'jwt-refresh-token-rotation', 100, 1, 1), e('a', 'jwt-refresh-token-rotation-v2', 900, 1, 2)] }, NOW)++ expect(report.clusterCount).toBe(0)+ })++ it('stale means never recalled and not updated for the window; a recalled or undated entry is never stale', () => {+ const undated: HealthEntry = { namespace: 'a', key: 'undated', size: 1, accessCount: 0 }+ const report = analyseHealth({ listed: 4, entries: [e('a', 'old-unread', 1, 0, 90), e('a', 'old-read', 1, 3, 90), e('a', 'new-unread', 1, 0, 2), undated] }, NOW)++ expect(report.stale.map(entry => entry.key)).toEqual(['old-unread'])+ expect(report.staleCount).toBe(1)+ expect(report.neverRecalledEntries).toBe(3)+ })++ it('reports namespaces where nothing was ever recalled', () => {+ const report = analyseHealth({ listed: 3, entries: [e('cold', 'x1', 1, 0, 1), e('cold', 'x2', 1, 0, 1), e('warm', 'y1', 1, 2, 1)] }, NOW)++ expect(report.neverRecalledNamespaces).toEqual(['cold'])+ expect(report.namespaces.find(space => space.name === 'warm')).toMatchObject({ recalled: 1, isNeverRecalled: false })+ })++ it('stops at the pair budget, compares the newest first, and says so', () => {+ const entries = Array.from({ length: 40 }, (_, index) => e('a', `entry-number-${index}-${index % 2 === 0 ? 'even' : 'odd'}`, 10, 1, index))+ const full = analyseHealth({ listed: 40, entries }, NOW)+ const cut = analyseHealth({ listed: 40, entries }, NOW, { pairCap: 100 })++ expect(full.isTruncated).toBe(false)+ expect(full.pairsCompared).toBe(780)+ expect(cut.isTruncated).toBe(true)+ expect(cut.pairsCompared).toBe(100)+ expect(cut.entriesCompared).toBeLessThan(40)+ expect(limitsLine(cut, 5000)).toMatch(/pair budget .* reached: only the newest \d+ entries were compared/)+ expect(limitsLine(cut, 5000)).toMatch(/of 5000 stored \(the newest 1000 are read\)/)+ })++ it('an empty sample yields an empty report, not a crash', () => {+ const report = analyseHealth({ listed: 0, entries: [] }, NOW)++ expect(report).toMatchObject({ analysed: 0, clusterCount: 0, staleCount: 0, isTruncated: false })+ })+})++describe('the health probe reader', () => {+ const stdout = JSON.stringify([+ { key: 'api/auth', namespace: 'default', size: 12, accessCount: 2, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-02-01T00:00:00Z', hasEmbedding: true, content: 'must-not-be-kept' },+ { namespace: 'default', size: 1 },+ { key: 'k2', size: 'x' },+ ])++ it('keeps key, namespace, size, access count and times, drops rows without a key, and never carries a value', () => {+ const sample = memoryHealthProbe.parse(`[INFO] noise\n${stdout}`)++ expect(sample?.listed).toBe(3)+ expect(sample?.entries).toHaveLength(2)+ expect(sample?.entries[0]).toMatchObject({ key: 'api/auth', namespace: 'default', size: 12, accessCount: 2 })+ expect(JSON.stringify(sample)).not.toContain('must-not-be-kept')+ expect(sample?.entries[1]).toMatchObject({ key: 'k2', namespace: '(none)', size: 0, accessCount: 0 })+ expect(memoryHealthProbe.parse('not json')).toBeNull()+ })++ it('asks for exactly the cap, read-only, through the fixed memory list argv', () => {+ expect(memoryHealthProbe.args).toEqual(['memory', 'list', '--format', 'json', '--limit', String(HEALTH_CAP)])+ })+})++type El = { kind: string; props: Record<string, unknown> }+const make = (kind: string) => (props: Record<string, unknown>): El => ({ kind, props })+const kit = { Box: make('Box'), Text: make('Text'), Button: make('Button'), Input: make('Input') }+const act = new Proxy({}, { get: () => new Proxy({}, { get: () => () => undefined }) }) as unknown as Ctx['act']+const flat = (node: unknown): El[] => {+ if (Array.isArray(node)) return node.flatMap(flat)+ if (typeof node !== 'object' || node === null) return []+ const el = node as El+ const children = el.props.children++ return [el, ...(Array.isArray(children) ? children.flatMap(flat) : flat(children))]+}+const textOf = (nodes: unknown): string => flat(nodes).filter(el => el.kind === 'Text').map(el => String(el.props.children)).join('\n')++function draw(probes: [string, unknown][]): { out: string; buttons: string[] } {+ const state = newState({ boot: false })++ for (const [id, result] of probes) state.probes.set(id, result as never)++ const nodes = healthRows({ kit, state, act, columns: 120, nowMs: NOW, pictures: new Map() } as unknown as Ctx)++ return { out: textOf(nodes), buttons: flat(nodes).filter(el => el.kind === 'Button').map(el => String(el.props.key)) }+}++describe('the health view', () => {+ it('shows an honest line, no invented numbers, when the probe has not answered', () => {+ expect(draw([]).out).toMatch(/not registered in this build/)+ expect(draw([['memory-health', { value: null, okAtMs: null, error: 'boom', errorAtMs: NOW, isRunning: false }]]).out).toMatch(/boom/)+ })++ it('shows an empty-store line for an empty sample', () => {+ expect(draw([['memory-health', { value: { listed: 0, entries: [] }, okAtMs: NOW, error: null, errorAtMs: null }]]).out).toMatch(/no entries to analyse/)+ })++ it('draws the figures, the limits line and the consolidate button from a real sample', () => {+ const sample = { listed: 3, entries: [e('a', 'api/auth', 100, 0, 90), e('b', 'api-auth', 100, 0, 91), e('c', 'solo', 5, 4, 1)] }+ const { out, buttons } = draw([['memory-health', { value: sample, okAtMs: NOW, error: null, errorAtMs: null }]])++ expect(out).toMatch(/3 entries · 3 of 3 pairs compared · from key and size only, no values read/)+ expect(out).toMatch(/2 entries in 1 cluster/)+ expect(out).toMatch(/same ×2/)+ expect(out).toMatch(/2 never recalled and not updated for 30d/)+ expect(buttons).toContain('mem-health-consolidate')+ })+})++describe('the analysis cost at the cap', () => {+ it('analyses HEALTH_CAP entries inside the pair budget quickly (generous bound, the measured time is printed)', () => {+ const entries = Array.from({ length: HEALTH_CAP }, (_, index) => e(`ns${index % 7}`, `topic-${index % 90}-item-${index}`, 50 + (index % 40), index % 3, index % 120))+ const started = performance.now()+ const report = analyseHealth({ listed: HEALTH_CAP, entries }, NOW)+ const ms = performance.now() - started++ console.log(`memory health: ${HEALTH_CAP} entries, ${report.pairsCompared} pairs, ${report.clusterCount} clusters in ${ms.toFixed(0)} ms`)+ expect(report.analysed).toBe(HEALTH_CAP)+ expect(ms).toBeLessThan(5000)+ })+})diff --git a/v3/docs/adr/ADR-457-memory-health.md b/v3/docs/adr/ADR-457-memory-health.mdnew file mode 100644index 0000000000..0d7c9e8879--- /dev/null+++ b/v3/docs/adr/ADR-457-memory-health.md@@ -0,0 +1,32 @@+# ADR-457: Memory health in the console's Memory Lab++- Status: Accepted+- Date: 2026-10-05+- Plugin: `plugins/ruflo-console` (`hooks/data/memory-health.ts`, `hooks/views/memory-health.ts`, `hooks/views/memory-lab.ts`)++## Context++The Memory view shows counts, namespaces and a browse list, but not whether the store is healthy: whether the same fact was stored twice, whether entries nobody ever recalls pile up, or whether a whole namespace is dead weight. Everything needed is already printed by `memory list --format json` (key, namespace, size, accessCount, createdAt, updatedAt, hasEmbedding). That list carries no value, so a health view can be built without reading any memory content.++## Decision++1. `data/memory-health.ts` holds the pure analysis (`analyseHealth`) and one read-only probe (`memoryHealthProbe`: `memory list --format json --limit 1000`, 120 s cadence, only while the memory view is in front).+2. Duplicates are judged on key and size only. Exact: same normalised key (case and separators removed) and same size, in different places. Near: key-word Jaccard >= 0.75 with sizes within 20 %, or the same normalised key with a different size. Clusters are the connected components of those pairs.+3. "Recalled" means `accessCount > 0`, the counter the CLI bumps on retrieval. There is no last-recalled timestamp, so stale means never recalled AND not updated for 30 days. A recalled or undated entry is never called stale. A never-recalled namespace is one where every listed entry has accessCount 0.+4. Documented caps, always printed in the section's first line, never silent: HEALTH_CAP 1000 newest entries read (with "of N stored" when the store is bigger), PAIR_CAP 500 000 key comparisons (newest entries are compared first; when the budget stops the run the line says how many entries were compared), 5 clusters / 5 stale rows drawn with "+N more" while the counts above stay exact.+5. The view (`views/memory-health.ts`, mounted as the first section of `memoryLabRows`) draws summary gauges, clusters, stale entries and recall per namespace. Absent or failed probe: a single honest line (the probe's own error, or "not registered in this build"). Empty store: an empty-state line. No number is invented.+6. Consolidate is the existing `mem-consolidate` lab entry (`agentdb_consolidate`, a write) behind the lab's confirm card; the button re-homes the answer to the health section. It merges and promotes across tiers; it does not delete the listed keys, and the UI says so. Deleting stays the existing per-entry DELETE.++## Consequences++- Two stores exist (`.swarm/memory.db` read by the CLI, `.swarm/agentdb-memory.db` written by MCP); health reads the first only, like the browse list. When the CLI refuses an unsafe sql.js read (active WAL), the probe error is shown instead of a stale figure.+- Key/size similarity misses duplicates stored under different keys and flags look-alike keys with different content. This is the price of reading no values; the line "from key and size only, no values read" says it.+- Integrator wiring is required (below); without it the section shows "not registered".++## Test and benchmark plan++`tests/memory-health.spec.ts`: key normalising, exact and near clustering, size guard, stale rules (recalled and undated never stale), never-recalled namespaces, pair-budget truncation message, probe reader (drops rows without a key, never carries a value, fixed argv), view states (no probe, failed probe, empty, real sample with consolidate button), and a 1000-entry timing test (measured about 0.1-0.2 s on the dev host; bound 5 s).++## Rollback++Delete the section line in `views/memory-lab.ts`, the two new files and the probe registration; nothing persists and no schema changes.