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(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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.md
new file mode 100644
index 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.