🌊 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(ruflo-console): recorded recalls, real vectors on the memory map, log-based stale (ADR-472)
ruv0d94fdb4ddab
diff --git a/plugins/ruflo-console/hooks/data/memmap.ts b/plugins/ruflo-console/hooks/data/memmap.tsindex 0783b4c171..1755e1482c 100644--- a/plugins/ruflo-console/hooks/data/memmap.ts+++ b/plugins/ruflo-console/hooks/data/memmap.ts@@ -13,9 +13,60 @@ export const MAP_LIMIT = 500/** A stored embedding longer than this is ignored (the map then says hash): bounds the work per frame on a corrupt list. */const MAX_DIMS = 4096+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'+const B64_INDEX = new Map([...B64].map((char, index) => [char, index] as const))++/** Base64 to bytes by hand (the engine's module host is promised no built-ins); null on any character outside the alphabet. */+function bytesOf(b64: string): Uint8Array | null {+ const clean = b64.replace(/=+$/, '')++ if (clean.length % 4 === 1) return null++ const out = new Uint8Array(Math.floor((clean.length * 3) / 4))+ let acc = 0+ let bits = 0+ let at = 0++ for (const char of clean) {+ const index = B64_INDEX.get(char)++ if (index === undefined) return null++ acc = (acc << 6) | index+ bits += 6++ if (bits >= 8) {+ bits -= 8+ out[at++] = (acc >> bits) & 0xff+ }+ }++ return out+}++/** `embeddingQ8` ({dims, scale, b64}: int8 values, each times scale) as floats; undefined unless the shape, the byte count and the scale all check out. */+export function decodeQ8(value: unknown): number[] | undefined {+ const record = recordOf(value)+ const dims = numberOf(record?.dims)+ const scale = numberOf(record?.scale)++ if (record === null || typeof record.b64 !== 'string' || dims === undefined || scale === undefined || !Number.isInteger(dims) || dims < 2 || dims > MAX_DIMS || !(scale > 0) || !Number.isFinite(scale)) return undefined++ const bytes = bytesOf(record.b64)++ if (bytes === null || bytes.length !== dims) return undefined++ const out = new Array<number>(dims)++ for (let i = 0; i < dims; i++) out[i] = ((bytes[i] as number) << 24 >> 24) * scale++ return out+}+/**- * `memory list` JSON as map entries. `vector` is set only if a row carries an `embedding` array (the CLI's list does not- * today, so the map says 'hash layout'); never invented.+ * `memory list` JSON as map entries. `vector` is set only if a row carries what the CLI printed for it: an `embeddingQ8`+ * (`memory list --embeddings`, ADR-472: int8 values times a scale, base64) or a plain `embedding` array. An older CLI ignores the+ * flag and prints neither, so the map says 'hash layout'; a vector is never invented.*/export function mapEntriesOf(stdout: string): MapEntry[] | null {const value = jsonAfter(stdout)@@ -30,16 +81,16 @@ export function mapEntriesOf(stdout: string): MapEntry[] | null {const accessCount = numberOf(record?.accessCount)const raw = Array.isArray(record?.embedding) ? record.embedding : null- const vector = raw !== null && raw.length > 1 && raw.length <= MAX_DIMS && raw.every(item => typeof item === 'number' && Number.isFinite(item)) ? (raw as number[]) : undefined+ const vector = raw !== null && raw.length > 1 && raw.length <= MAX_DIMS && raw.every(item => typeof item === 'number' && Number.isFinite(item)) ? (raw as number[]) : decodeQ8(record?.embeddingQ8)return [{ key, namespace: stringOf(record?.namespace, 40) ?? '(none)', hasVector: record?.hasEmbedding === true, ...(accessCount !== undefined && { accessCount }), ...(vector !== undefined && { vector }) }]})}-/** Same call as the Namespaces probe, kept apart because the map needs the access count that probe drops. */+/** The Namespaces probe's call plus the access count that probe drops and, with `--embeddings` (ADR-472), each entry's vector as int8 + scale: about 0.2 MB at 500 x 384, under the 1 MB `jsonAfter` reads. */export const memmapProbe: Probe<MapEntry[]> = {id: 'memmap',- args: ['memory', 'list', '--format', 'json', '--limit', String(MAP_LIMIT)],+ args: ['memory', 'list', '--format', 'json', '--limit', String(MAP_LIMIT), '--embeddings'],views: ['memory'],everyMs: 60_000,timeoutMs: 30_000,diff --git a/plugins/ruflo-console/hooks/data/memory-health.ts b/plugins/ruflo-console/hooks/data/memory-health.tsindex 125185964f..b740860d35 100644--- a/plugins/ruflo-console/hooks/data/memory-health.ts+++ b/plugins/ruflo-console/hooks/data/memory-health.ts@@ -2,6 +2,9 @@* 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.*+ * ADR-472 adds two inputs, both optional: the hook's recall log (when present, "stale" can mean "the hook did not surface it in N days" for+ * the entries the hook can recall at all) and stored vectors (similar-by-meaning clusters, only when the map's probe read them).+ ** 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@@ -13,6 +16,9 @@*/import { type Probe, jsonAfter } from './cli'import { msOf, numberOf, recordOf, stringOf } from './parse'+import { logWindowMs, surfacedCounts, type RecallFacts } from './recall'++import type { MapEntry } from '../gfx/memmap'/** Entries read from the store, newest first: the cap the view shows beside every figure. */export const HEALTH_CAP = 1000@@ -109,6 +115,9 @@ export function pairKind(a: HealthEntry, b: HealthEntry, tokensA: ReadonlySet<stexport type Cluster = { kind: 'exact' | 'near'; size: number; members: { namespace: string; key: string; size: number }[] }+/** Which rule made an entry stale: the hook's recall log (surfaced in the window?) or the access count (never retrieved). */+export type StaleEntry = HealthEntry & { by: 'log' | 'count' }+export type NamespaceHealth = { name: string; count: number; recalled: number; stale: number; isNeverRecalled: boolean }export type HealthReport = {@@ -123,13 +132,45 @@ export type HealthReport = {clusterCount: number/** Entries that sit in some cluster, counting every member (a cluster of 3 is 3). */duplicateEntries: number- stale: HealthEntry[]+ stale: StaleEntry[]staleCount: number+ /** Per rule: how many stale entries each one named, and how many entries the log could judge at all (the hook can only surface what is in its ranked file). */+ staleByLog: number+ staleByCount: number+ logChecked: number+ /** The log's span in days and its record count; null with no usable log (the access-count rule alone applies). */+ log: { days: number; records: number } | nullneverRecalledEntries: numbernamespaces: NamespaceHealth[]neverRecalledNamespaces: string[]}+/** What the hook's recall log says about memory entries: the last time each id or category was surfaced, which names the hook can recall at all, and how far back the log reaches. */+export type RecallEvidence = { lastAtMs: ReadonlyMap<string, number>; recallable: ReadonlySet<string>; windowMs: number; records: number }++/**+ * The evidence of a recall facts value, or null with no log or no ranked file. A memory entry joins by an exact key match against a+ * ranked id or its category (the names the log records); entries that do not match are not judged by the log.+ */+export function recallEvidenceOf(facts: RecallFacts | null | undefined, nowMs: number): RecallEvidence | null {+ if (facts === null || facts === undefined || facts.log.length === 0 || facts.ranked === null) return null++ const lastAtMs = new Map<string, number>()++ for (const item of surfacedCounts(facts.log).values()) {+ for (const name of [item.id, item.category]) if (name !== '') lastAtMs.set(name, Math.max(lastAtMs.get(name) ?? 0, item.lastAtMs))+ }++ const recallable = new Set<string>()++ for (const entry of facts.ranked.entries) {+ recallable.add(entry.id)+ if (entry.category !== '') recallable.add(entry.category)+ }++ return { lastAtMs, recallable, windowMs: logWindowMs(facts.log, nowMs), records: facts.log.length }+}+/** 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@@ -206,14 +247,31 @@ function findClusters(entries: readonly HealthEntry[], pairCap: number): { clust}/** 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 {+export function analyseHealth(sample: HealthSample, nowMs: number, options: { staleDays?: number; pairCap?: number; evidence?: RecallEvidence | null } = {}): HealthReport {const staleDays = options.staleDays ?? STALE_DAYSconst entries = [...sample.entries].sort((a, b) => (b.updatedAtMs ?? 0) - (a.updatedAtMs ?? 0))const cutoff = nowMs - staleDays * 86_400_000const found = findClusters(entries, options.pairCap ?? PAIR_CAP)+ // The log can speak only if it reaches back as far as the stale window, and only for names the hook can recall.+ const evidence = options.evidence ?? null+ const logSpeaks = evidence !== null && evidence.windowMs >= staleDays * 86_400_000+ const isLogChecked = (entry: HealthEntry): boolean => logSpeaks && evidence.recallable.has(entry.key)// 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))+ // Log rule: not surfaced by the hook inside the window and not updated inside it (accessCount has no time, so it does not vote).+ // Count rule: never retrieved (accessCount 0) and not updated inside the window.+ const staleBy = (entry: HealthEntry): 'log' | 'count' | null => {+ if (entry.updatedAtMs === undefined || entry.updatedAtMs >= cutoff) return null++ if (isLogChecked(entry)) return (evidence?.lastAtMs.get(entry.key) ?? 0) < cutoff ? 'log' : null++ return entry.accessCount === 0 ? 'count' : null+ }+ const isStale = (entry: HealthEntry): boolean => staleBy(entry) !== null+ const stale = entries.flatMap((entry): StaleEntry[] => {+ const by = staleBy(entry)++ return by === null ? [] : [{ ...entry, by }]+ }).sort((a, b) => (a.updatedAtMs ?? 0) - (b.updatedAtMs ?? 0))const byName = new Map<string, NamespaceHealth>()for (const entry of entries) {@@ -238,8 +296,115 @@ export function analyseHealth(sample: HealthSample, nowMs: number, options: { stduplicateEntries: found.clusters.reduce((sum, cluster) => sum + cluster.size, 0),stale: stale.slice(0, 10),staleCount: stale.length,+ staleByLog: stale.filter(entry => entry.by === 'log').length,+ staleByCount: stale.filter(entry => entry.by === 'count').length,+ logChecked: entries.filter(isLogChecked).length,+ log: evidence === null ? null : { days: evidence.windowMs / 86_400_000, records: evidence.records },neverRecalledEntries: entries.filter(entry => entry.accessCount === 0).length,namespaces,neverRecalledNamespaces: namespaces.filter(space => space.isNeverRecalled).map(space => space.name),}}++/** Cosine at or above this makes two stored vectors a similar-by-meaning pair; high on purpose, so the list is short and the pairs are real. */+export const SIMILAR_COSINE = 0.97+/** Entries with a vector compared at most: the pair work is O(n^2 * dims), about 50 ms at 500 x 384. */+export const SEMANTIC_CAP = 500++export type SimilarCluster = { size: number; minCosine: number; members: { namespace: string; key: string }[] }++export type SemanticReport = {+ /** Entries with a stored vector that were compared, of those the list carried and of all it listed; the cap is what bounded them. */+ compared: number+ withVector: number+ listed: number+ cap: number+ pairs: number+ clusters: SimilarCluster[]+ clusterCount: number+ /** Entries in some cluster, counting every member. */+ entries: number+}++/**+ * Similar-by-meaning clusters among entries that carry a stored vector (the map's probe reads them: `memory list --embeddings`).+ * Null when none carries one, so the caller never reports a check that did not run. Union of every pair at or above `threshold`.+ */+export function semanticDuplicates(listed: readonly MapEntry[], threshold: number = SIMILAR_COSINE): SemanticReport | null {+ const withVector = listed.filter(entry => entry.vector !== undefined && entry.vector.length > 1)++ if (withVector.length < 2) return null++ const pool = withVector.slice(0, SEMANTIC_CAP)+ const dims = Math.max(...pool.map(entry => entry.vector?.length ?? 0))+ const unit = pool.map(entry => {+ const out = new Float64Array(dims)+ let norm = 0++ for (let i = 0; i < (entry.vector?.length ?? 0); i++) {+ const value = entry.vector?.[i] ?? 0++ out[i] = value+ norm += value * value+ }++ const scale = norm > 0 ? 1 / Math.sqrt(norm) : 0++ for (let i = 0; i < dims; i++) out[i] = (out[i] as number) * scale++ return out+ })+ const parent = pool.map((_, index) => index)+ const find = (index: number): number => {+ let root = index++ while (parent[root] !== root) root = parent[root] ?? root++ parent[index] = root++ return root+ }+ const worst = new Map<number, number>()+ const links: { a: number; b: number; cosine: number }[] = []++ for (let j = 1; j < pool.length; j += 1) {+ const vj = unit[j] as Float64Array++ for (let i = 0; i < j; i += 1) {+ const vi = unit[i] as Float64Array+ let dot = 0++ for (let d = 0; d < dims; d += 1) dot += (vi[d] as number) * (vj[d] as number)++ if (dot >= threshold) links.push({ a: i, b: j, cosine: dot })+ }+ }++ for (const { a, b } of links) parent[find(a)] = find(b)++ for (const { a, cosine } of links) {+ const root = find(a)++ worst.set(root, Math.min(worst.get(root) ?? 1, cosine))+ }++ const groups = new Map<number, number[]>()++ for (let index = 0; index < pool.length; index += 1) {+ const root = find(index)++ if (worst.has(root)) groups.set(root, [...(groups.get(root) ?? []), index])+ }++ const clusters = [...groups].map(([root, indexes]): SimilarCluster => ({+ size: indexes.length,+ minCosine: worst.get(root) ?? threshold,+ members: indexes.slice(0, CLUSTER_MEMBERS).flatMap(index => {+ const entry = pool[index]++ return entry === undefined ? [] : [{ namespace: entry.namespace, key: entry.key }]+ }),+ })).sort((a, b) => b.size - a.size || b.minCosine - a.minCosine)++ return { compared: pool.length, withVector: withVector.length, listed: listed.length, cap: SEMANTIC_CAP, pairs: (pool.length * (pool.length - 1)) / 2, clusters: clusters.slice(0, CLUSTERS_KEPT), clusterCount: clusters.length, entries: clusters.reduce((sum, cluster) => sum + cluster.size, 0) }+}diff --git a/plugins/ruflo-console/hooks/data/recall.ts b/plugins/ruflo-console/hooks/data/recall.tsindex 6af378fcba..9aaa6cf73e 100644--- a/plugins/ruflo-console/hooks/data/recall.ts+++ b/plugins/ruflo-console/hooks/data/recall.ts@@ -8,12 +8,14 @@* - `.claude-flow/routing-outcomes.json` task texts the router judged (the only prompts any hook file keeps)* - `.claude-flow/neural/models.json` the store `neural_patterns delete` and `neural_compress prune` act on*- * The hook never logs a prompt or the scores it surfaced, so a "past prompt" is re-scored against today's ranked file+ * Since ADR-472 the hook also appends `.claude-flow/data/recall-log.jsonl` (a digest of the prompt, the ids/scores/ranks it surfaced,+ * the router's pick). When a record exists it is shown as recorded. Older projects have no log, so a "past prompt" is re-scored against today's ranked file* with the hook's own formula (copied from .claude/helpers/intelligence.cjs getContext: tokenize, trigrams, jaccard,* 0.6 * match + 0.4 * pageRank, threshold 0.05, top 5) and is labelled a recomputation. `.claude-flow/neural/patterns.json`* (the ReasoningBank) is usually over READ_MAX and is not read; `reads.bank` says so.*/import { looksSecret } from './automate'+import { sha256 } from './ap-envelope'import { jsonObject, msOf, numberOf, plain, recordOf } from './parse'import { PROJECT, READ_MAX, readBounded, under, type ReaderFs, type ReadCache } from './files'@@ -21,6 +23,12 @@ export const RANKED = '.claude-flow/data/ranked-context.json'export const SESSIONS = '.claude-flow/sessions'export const MODELS = '.claude-flow/neural/models.json'export const BANK = '.claude-flow/neural/patterns.json'+/** ADR-472: what the intelligence hook logs per surfaced recall (ids, scores, ranks; a digest of the prompt, never its text). */+export const RECALL_LOG = '.claude-flow/data/recall-log.jsonl'+/** Records kept from the log, newest first: the log itself is capped at 1000 by the hook. */+export const LOG_KEPT = 1000+/** Recorded recalls the Learning Lab lists. */+export const LOGGED_SHOWN = 6/** The hook's constants (intelligence.cjs getContext). */export const ALPHA = 0.6@@ -146,7 +154,7 @@ export function parseSessionRecall(file: string, text: string | null): SessionRereturn { file: plain(file, 60), startedAtMs: msOf(value.startedAt) ?? null, updatedAtMs: msOf(value.updatedAt) ?? null, ids: ids.filter((id): id is string => typeof id === 'string').slice(0, 20).map(id => plain(id, 80)) }}-export type PastPrompt = { task: string; agent: string; ok: boolean; atMs: number }+export type PastPrompt = { task: string; agent: string; ok: boolean; atMs: number; /** The hook's digest of this text (sha256 prefix, 16 hex): a recorded recall whose digest matches names this task. */ digest: string }/** The distinct task texts the router judged, newest first: the only prompts a hook file keeps. */export function parsePrompts(text: string | null): PastPrompt[] {@@ -158,7 +166,7 @@ export function parsePrompts(text: string | null): PastPrompt[] {const row = recordOf(raw)const atMs = msOf(row?.timestamp)- return row === null || atMs === undefined || typeof row.task !== 'string' || row.task.trim() === '' ? [] : [{ task: shown(row.task, 160), agent: plain(typeof row.agent === 'string' ? row.agent : '?', 30), ok: row.success === true, atMs }]+ return row === null || atMs === undefined || typeof row.task !== 'string' || row.task.trim() === '' ? [] : [{ task: shown(row.task, 160), agent: plain(typeof row.agent === 'string' ? row.agent : '?', 30), ok: row.success === true, atMs, digest: digestOf(row.task) }]})const seen = new Set<string>()const out: PastPrompt[] = []@@ -174,6 +182,78 @@ export function parsePrompts(text: string | null): PastPrompt[] {return out}+/** The hook's digest of a prompt: first 16 hex characters of sha256 of the trimmed text (intelligence.cjs promptDigest). */+export const digestOf = (prompt: string): string => sha256(prompt.trim()).slice(0, 16)++export type LoggedItem = { id: string; score: number; rank: number; category: string }+/** One recall the hook recorded. No prompt text exists in the log; `digest` is the only handle on it. */+export type LoggedRecall = { atMs: number; sessionId: string | null; digest: string; surfaced: LoggedItem[]; router: { agent: string; confidence: number | null } | null }++/** The records of a recall-log.jsonl, newest first; lines that are not a valid record are skipped, never guessed at. */+export function parseRecallLog(text: string | null): LoggedRecall[] {+ if (text === null) return []++ const out: LoggedRecall[] = []++ for (const line of text.split('\n')) {+ if (line === '' || line.length > 20_000) continue++ let value: unknown++ try {+ value = JSON.parse(line)+ } catch {+ continue+ }++ const row = recordOf(value)+ const atMs = numberOf(row?.at)+ const digest = typeof row?.digest === 'string' && /^[0-9a-f]{8,64}$/.test(row.digest) ? row.digest : null++ if (row === null || atMs === undefined || atMs <= 0 || digest === null || !Array.isArray(row.surfaced)) continue++ const surfaced = row.surfaced.slice(0, 10).flatMap((raw): LoggedItem[] => {+ const item = recordOf(raw)+ const score = numberOf(item?.score)+ const rank = numberOf(item?.rank)++ return item === null || typeof item.id !== 'string' || item.id === '' || score === undefined || rank === undefined ? [] : [{ id: plain(item.id, 80), score, rank, category: plain(typeof item.cat === 'string' ? item.cat : '', 40) }]+ })++ if (surfaced.length === 0) continue++ const router = recordOf(row.router)++ out.push({ atMs, sessionId: typeof row.sid === 'string' ? plain(row.sid, 64) : null, digest, surfaced, router: router === null ? null : { agent: plain(typeof router.agent === 'string' ? router.agent : '?', 30), confidence: numberOf(router.confidence) ?? null } })+ }++ return out.sort((a, b) => b.atMs - a.atMs).slice(0, LOG_KEPT)+}++export type SurfacedCount = { id: string; category: string; count: number; lastAtMs: number }++/** How often each id was surfaced, and when last, over the recorded recalls: the real count a pattern's lifecycle row can show. */+export function surfacedCounts(log: readonly LoggedRecall[]): Map<string, SurfacedCount> {+ const out = new Map<string, SurfacedCount>()++ for (const recall of log) {+ for (const item of recall.surfaced) {+ const known = out.get(item.id)++ if (known === undefined) out.set(item.id, { id: item.id, category: item.category, count: 1, lastAtMs: recall.atMs })+ else {+ known.count += 1+ known.lastAtMs = Math.max(known.lastAtMs, recall.atMs)+ }+ }+ }++ return out+}++/** The span the log covers, oldest record to `nowMs`: an id absent from the log proves "not surfaced" only over this span. */+export const logWindowMs = (log: readonly LoggedRecall[], nowMs: number): number => (log.length === 0 ? 0 : Math.max(0, nowMs - (log[log.length - 1]?.atMs ?? nowMs)))+/** One pattern of `.claude-flow/neural/models.json`: only what the file records (no rank, no last-used time). */export type NeuralPattern = { id: string; name: string; type: string; content: string; createdAtMs: number | null; usageCount: number; verdict: string | null }@@ -207,8 +287,10 @@ export type RecallFacts = {sessions: SessionRecall[]prompts: PastPrompt[]neural: NeuralPattern[] | null+ /** ADR-472: the hook's recall log, newest first; empty when the hook has not written one (an older helper, or RUFLO_RECALL_LOG=0). */+ log: LoggedRecall[]/** Per source: ok, missing, or too-large (the ReasoningBank patterns.json is read only for its size). */- reads: { ranked: ReadStatus; sessions: ReadStatus; prompts: ReadStatus; neural: ReadStatus; bank: ReadStatus }+ reads: { ranked: ReadStatus; sessions: ReadStatus; prompts: ReadStatus; neural: ReadStatus; bank: ReadStatus; log: ReadStatus }}/** The recall facts of a snapshot that carries them, else null: the view's one accessor. */@@ -219,13 +301,15 @@ const status = (read: { text: string | null; reason?: string }): ReadStatus => (let lastRanked: { text: string; parsed: Ranked | null } | null = nulllet lastModels: { text: string; parsed: NeuralPattern[] | null } | null = nulllet lastOutcomes: { text: string; parsed: PastPrompt[] } | null = null+let lastLog: { text: string; parsed: LoggedRecall[] } | null = null/** Reads the four files (and stats the bank); never rejects. `fs.read` of a file over its cap is refused by readBounded. */export async function readRecall(fs: ReaderFs, cache: ReadCache, cwd: string): Promise<RecallFacts> {- const [ranked, models, outcomes, bankStat, listed] = await Promise.all([+ const [ranked, models, outcomes, logRead, bankStat, listed] = await Promise.all([readBounded(fs, cache, under(cwd, RANKED)),readBounded(fs, cache, under(cwd, MODELS)),readBounded(fs, cache, under(cwd, PROJECT.outcomes)),+ readBounded(fs, cache, under(cwd, RECALL_LOG), READ_MAX, true),fs.stat(under(cwd, BANK)).catch(() => undefined),fs.list(under(cwd, SESSIONS)).catch(() => null),])@@ -242,12 +326,14 @@ export async function readRecall(fs: ReaderFs, cache: ReadCache, cwd: string): Pif (models.text !== null && lastModels?.text !== models.text) lastModels = { text: models.text, parsed: parseNeuralStore(models.text) }if (outcomes.text !== null && lastOutcomes?.text !== outcomes.text) lastOutcomes = { text: outcomes.text, parsed: parsePrompts(outcomes.text) }+ if (logRead.text !== null && lastLog?.text !== logRead.text) lastLog = { text: logRead.text, parsed: parseRecallLog(logRead.text) }return {ranked: ranked.text === null ? null : (lastRanked?.parsed ?? null),sessions,prompts: outcomes.text === null ? [] : (lastOutcomes?.parsed ?? []),neural: models.text === null ? null : (lastModels?.parsed ?? null),- reads: { ranked: status(ranked), sessions: listed === null ? 'missing' : 'ok', prompts: status(outcomes), neural: status(models), bank: bankStat === undefined ? 'missing' : (bankStat.size ?? 0) > READ_MAX ? 'too-large' : 'ok' },+ log: logRead.text === null ? [] : (lastLog?.parsed ?? []),+ reads: { ranked: status(ranked), sessions: listed === null ? 'missing' : 'ok', prompts: status(outcomes), neural: status(models), bank: bankStat === undefined ? 'missing' : (bankStat.size ?? 0) > READ_MAX ? 'too-large' : 'ok', log: status(logRead) },}}diff --git a/plugins/ruflo-console/hooks/gfx/memmap.ts b/plugins/ruflo-console/hooks/gfx/memmap.tsindex d3e4d460cb..10c10f02d1 100644--- a/plugins/ruflo-console/hooks/gfx/memmap.ts+++ b/plugins/ruflo-console/hooks/gfx/memmap.ts@@ -74,6 +74,26 @@ export function projectVector(vector: readonly number[]): { x: number; y: number/** Every entry is embedded and carries its vector: the only case the map may call 'embedding'. */export const modeOf = (entries: readonly MapEntry[]): MapMode => (entries.length > 0 && entries.every(entry => entry.vector !== undefined && entry.vector.length > 1) ? 'embedding' : 'hash')+const subsets = new WeakMap<readonly MapEntry[], { entries: readonly MapEntry[]; omitted: number }>()++/**+ * What is drawn. A store usually has some entries with no vector (an entry stored with embeddings off). If at least half have one, the+ * map draws only those, in the embedding layout, and says how many it left out; below half it keeps every entry in the hash layout. One+ * answer per entries array, so the picture and the rows of a frame agree and the layout cache still hits.+ */+export function drawable(entries: readonly MapEntry[]): { entries: readonly MapEntry[]; omitted: number } {+ const known = subsets.get(entries)++ if (known !== undefined) return known++ const withVector = entries.filter(entry => entry.vector !== undefined && entry.vector.length > 1)+ const answer = withVector.length > 0 && withVector.length < entries.length && withVector.length * 2 >= entries.length ? { entries: withVector, omitted: entries.length - withVector.length } : { entries, omitted: 0 }++ subsets.set(entries, answer)++ return answer+}+const laidOut = new WeakMap<readonly MapEntry[], { mode: MapMode; points: MapPoint[] }>()/**diff --git a/plugins/ruflo-console/hooks/views/memmap.ts b/plugins/ruflo-console/hooks/views/memmap.tsindex 763ead1c49..b8074a25b0 100644--- a/plugins/ruflo-console/hooks/views/memmap.ts+++ b/plugins/ruflo-console/hooks/views/memmap.ts@@ -2,7 +2,7 @@ import type { RenderElement } from 'claude-code'import type { Namespaces } from '../data/cli'import { hitsOf, isHit } from '../data/memmap'-import { layout, MAP_ROWS, memmapPicture, SPACE_COLORS, spacesOf, type MapEntry, type MapPoint } from '../gfx/memmap'+import { drawable, layout, MAP_ROWS, memmapPicture, SPACE_COLORS, spacesOf, type MapEntry, type MapPoint } from '../gfx/memmap'import type { Grid } from '../gfx/raster'import type { State } from '../state'import { clip, count, live, row, rule, text, type Ctx } from './common'@@ -35,11 +35,12 @@ function litOf(state: State, points: readonly MapPoint[]): { lit: Set<string>; n/** The map for one frame, by Raster key; none while there is nothing to draw (the view then says so). */export function memmapPictures(state: State, columns: number): Map<string, Grid> {- const { entries } = mapEntriesFrom(state)+ const listed = mapEntriesFrom(state).entriesconst pictures = new Map<string, Grid>()- if (entries.length === 0) return pictures+ if (listed.length === 0) return pictures+ const { entries } = drawable(listed)const { points } = layout(entries)pictures.set('memmap', memmapPicture(points, spacesOf(entries), litOf(state, points).lit, Math.max(20, Math.min(columns, 100)), MAP_ROWS))@@ -57,19 +58,20 @@ function mapPicture(ctx: Ctx, entries: number, spaces: number): RenderElement {/** The memory map section: the picture, what its places mean (said plainly), the namespace colours and what the last search lit. */export function memmapRows(ctx: Ctx): RenderElement[] {const { state, nowMs } = ctx- const { entries, hasCounts } = mapEntriesFrom(state)+ const { entries: listed, hasCounts } = mapEntriesFrom(state)- if (entries.length === 0) {+ if (listed.length === 0) {return [rule(ctx, 'Memory map'), text(ctx, sourceFallback(state, nowMs), { dimColor: true })]}+ const { entries, omitted } = drawable(listed)const { mode, points } = layout(entries)const spaces = spacesOf(entries)const { lit, named } = litOf(state, points)const result = state.lab.resultconst searched = result !== null && (result.id === 'mem-search' || result.id === 'mem-unified')const rows: RenderElement[] = [- rule(ctx, 'Memory map', `${entries.length} entries · ${spaces.length} namespace${spaces.length === 1 ? '' : 's'} · ${mode === 'embedding' ? 'embedding layout' : 'hash layout'}`),+ rule(ctx, 'Memory map', `${entries.length} entries · ${spaces.length} namespace${spaces.length === 1 ? '' : 's'} · ${mode === 'embedding' ? 'embedding layout' : 'hash layout'}${omitted > 0 ? ` · ${omitted} without a vector not drawn` : ''}`),mapPicture(ctx, entries.length, spaces.length),]@@ -107,8 +109,8 @@ export function memmapRows(ctx: Ctx): RenderElement[] {note(ctx,mode === 'embedding'- ? 'layout: each entry’s stored embedding projected to 2D by a fixed random projection; near means similar, but a 2D projection loses most of the distance'- : 'layout: NOT similarity. `memory list` does not print vectors, so each namespace has a fixed place and each entry a hash of its key scatters it inside; near means the same namespace only',+ ? `layout: each entry’s stored embedding projected to 2D by a fixed random projection (read from the store, not recomputed); near means similar, but a 2D projection loses most of the distance${omitted > 0 ? `; ${omitted} listed entr${omitted === 1 ? 'y has' : 'ies have'} no stored vector and ${omitted === 1 ? 'is' : 'are'} left off the map` : ''}`+ : 'layout: NOT similarity. No stored vectors were read for most entries (an older CLI does not print them, or most entries have none), so each namespace has a fixed place and each entry a hash of its key scatters it inside; near means the same namespace only',),)diff --git a/plugins/ruflo-console/hooks/views/memory-health.ts b/plugins/ruflo-console/hooks/views/memory-health.tsindex d733195e51..4433b8039f 100644--- a/plugins/ruflo-console/hooks/views/memory-health.ts+++ b/plugins/ruflo-console/hooks/views/memory-health.ts@@ -1,6 +1,8 @@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 type { MapEntry } from '../gfx/memmap'+import { analyseHealth, HEALTH_CAP, type HealthReport, type HealthSample, NEAR_JACCARD, PAIR_CAP, recallEvidenceOf, type SemanticReport, semanticDuplicates, SIMILAR_COSINE, STALE_DAYS } from '../data/memory-health'+import { recallOf, type RecallFacts } from '../data/recall'import { gauge } from '../memory-lines'import { ago, button, clip, confirmHere, count, kv, live, row, sourceLine, text, THEME, type Ctx } from './common'@@ -26,11 +28,30 @@ function summaryRows(ctx: Ctx, report: HealthReport, total: number | undefined):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'}`),+ kv(ctx, 'stale', `${gauge(report.staleCount, report.analysed, width)} ${report.staleCount} ${staleMeaning(report)} (${share(report.staleCount, report.analysed)})`, report.staleCount === 0 ? THEME.ok : THEME.warn),+ text(ctx, ` ${staleRule(report)}`, { dimColor: true }),+ kv(ctx, 'never retrieved', `${report.neverRecalledEntries} of ${report.analysed} entries have an access count of 0 (retrievals by memory retrieve or search, not the hook) · ${report.neverRecalledNamespaces.length} whole namespace${report.neverRecalledNamespaces.length === 1 ? '' : 's'}`),]}+/** What "stale" counts, said by the rules that actually fired. */+function staleMeaning(report: HealthReport): string {+ if (report.log === null) return `never retrieved and not updated for ${STALE_DAYS}d`++ return `not surfaced by the hook (log) or never retrieved (access count), and not updated for ${STALE_DAYS}d`+}++/** Which rule judged how many entries, and why the log is or is not used. Never omitted. */+export function staleRule(report: HealthReport): string {+ if (report.log === null) return 'rule: access count only (no recall log read: it needs the hook’s recall-log.jsonl and the ranked file). The count has no time, so this is “never retrieved”, not “not retrieved lately”.'++ const span = report.log.days < 1 ? 'under a day' : `${report.log.days.toFixed(1)} days`++ if (report.logChecked === 0) return `rule: access count (the recall log covers ${span} of ${report.log.records} recalls but is not used: ${report.log.days < STALE_DAYS ? `it is shorter than ${STALE_DAYS}d` : 'no entry key matches a name the hook recalls'})`++ return `rule: log for ${report.logChecked} entr${report.logChecked === 1 ? 'y' : 'ies'} whose key the hook can recall (not surfaced in ${STALE_DAYS}d of a ${span} log; ${report.staleByLog} stale), access count for the rest (${report.staleByCount} stale)`+}+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 })]@@ -49,10 +70,10 @@ function clusterRows(ctx: Ctx, report: HealthReport): RenderElement[] {}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 }))+ const rows = report.stale.slice(0, SHOW_STALE).map(entry => text(ctx, ` ${clip(`${entry.namespace}/${entry.key}`, Math.max(10, ctx.columns - 38))} updated ${ago(entry.updatedAtMs, ctx.nowMs)} · by ${entry.by === 'log' ? 'recall log' : 'access count'}`, { 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 }))+ if (rows.length === 0) rows.push(text(ctx, ` no entry is both unrecalled (by the rule above) and ${STALE_DAYS}+ days untouched`, { color: THEME.ok }))return rows}@@ -95,21 +116,50 @@ function consolidateRows(ctx: Ctx): RenderElement[] {* The analysis is O(pairs) (up to PAIR_CAP, ~100 ms at the cap) and the view renders every frame, so it is computed once per* probe result and per minute (the stale cutoff is the only thing the clock changes), never per frame.*/-const reports = new WeakMap<HealthSample, { minute: number; report: HealthReport }>()+const reports = new WeakMap<HealthSample, { minute: number; facts: RecallFacts | null; report: HealthReport }>()-export function reportFor(sample: HealthSample, nowMs: number): HealthReport {+export function reportFor(sample: HealthSample, nowMs: number, facts: RecallFacts | null = null): HealthReport {const minute = Math.floor(nowMs / 60_000)const cached = reports.get(sample)- if (cached !== undefined && cached.minute === minute) return cached.report+ if (cached !== undefined && cached.minute === minute && cached.facts === facts) return cached.report- const report = analyseHealth(sample, nowMs)+ const report = analyseHealth(sample, nowMs, { evidence: recallEvidenceOf(facts, nowMs) })- reports.set(sample, { minute, report })+ reports.set(sample, { minute, facts, report })return report}+const semantics = new WeakMap<readonly MapEntry[], SemanticReport | null>()++/** Similar-by-meaning clusters of the map's listed entries, computed once per probe result (about 50 ms at 500 x 384, never per frame). */+export function semanticFor(entries: readonly MapEntry[]): SemanticReport | null {+ if (!semantics.has(entries)) semantics.set(entries, semanticDuplicates(entries))++ return semantics.get(entries) ?? null+}++function semanticRows(ctx: Ctx, entries: readonly MapEntry[] | null): RenderElement[] {+ const report = entries === null ? null : semanticFor(entries)++ if (report === null) return [text(ctx, ' similar by meaning: not checked. It needs stored vectors, which memory list prints only with --embeddings (a CLI that has it, and entries stored with embeddings)', { dimColor: true })]++ const rows: RenderElement[] = [text(ctx, ` ${report.compared} of ${report.listed} listed entries with a stored vector compared${report.withVector > report.compared ? ` (the newest ${report.cap} of ${report.withVector}; the rest are not)` : ''} · ${count(report.pairs)} pairs · cosine ≥ ${SIMILAR_COSINE}`, { dimColor: true })]++ if (report.clusterCount === 0) return [...rows, text(ctx, ' no two stored vectors are that close', { color: THEME.ok })]++ for (const cluster of report.clusters.slice(0, SHOW_CLUSTERS)) {+ const names = cluster.members.slice(0, 3).map(member => `${member.namespace}/${member.key}`).join(' · ')++ rows.push(row(ctx, [ctx.kit.Text({ bold: true, color: THEME.warn, children: ` like ×${cluster.size} ` }), text(ctx, clip(`${names}${cluster.size > 3 ? ` +${cluster.size - 3}` : ''} (min cos ${cluster.minCosine.toFixed(3)})`, 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 (${report.entries} entries in ${report.clusterCount} clusters in all)`, { dimColor: true }))++ return rows+}+/** 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)@@ -119,13 +169,17 @@ export function healthRows(ctx: Ctx, now: () => number = () => ctx.nowMs): Rendeif (sample.entries.length === 0) return [text(ctx, ' no entries to analyse: store one, or import your Claude memories (IMPORT CLAUDE)', { dimColor: true })]- const report = reportFor(sample, now())+ const facts = recallOf(ctx.state.snapshot)+ const report = reportFor(sample, now(), facts)+ const mapped = live<MapEntry[]>(ctx.state.probes.get('memmap'))const total = live<{ total?: number }>(ctx.state.probes.get('memory'))?.totalreturn [...summaryRows(ctx, report, total),text(ctx, ' duplicate clusters', { bold: true, color: THEME.head }),...clusterRows(ctx, report),+ text(ctx, ' similar by meaning (stored vectors)', { bold: true, color: THEME.head }),+ ...semanticRows(ctx, mapped),text(ctx, ' stale entries', { bold: true, color: THEME.head }),...staleRows(ctx, report),text(ctx, ' recall by namespace', { bold: true, color: THEME.head }),diff --git a/plugins/ruflo-console/hooks/views/recall-rows.ts b/plugins/ruflo-console/hooks/views/recall-rows.tsindex dab796c7eb..32d4c0b3ae 100644--- a/plugins/ruflo-console/hooks/views/recall-rows.ts+++ b/plugins/ruflo-console/hooks/views/recall-rows.ts@@ -1,6 +1,6 @@import type { RenderElement } from 'claude-code'-import { compositeRank, explainPrompt, lifecycleOrder, recallOf, shown, wouldPrune, type RecallFacts, type SessionRecall } from '../data/recall'+import { compositeRank, digestOf, explainPrompt, LOGGED_SHOWN, lifecycleOrder, logWindowMs, recallOf, shown, surfacedCounts, wouldPrune, type LoggedRecall, type RecallFacts, type SessionRecall } from '../data/recall'import { ago, button, clip, kv, row, text, THEME, type Ctx } from './common'/** Rows of a table drawn at most; the rest are counted, not hidden silently. */@@ -16,6 +16,15 @@ export const pickPrompt = (value: string | null): void => {export const pickedPrompt = (): string | null => picked+/** The recorded recall being shown (`<atMs>:<digest>`); null shows the newest. View-local like the prompt above. */+let pickedLog: string | null = null++export const pickLogged = (recall: LoggedRecall | null): void => {+ pickedLog = recall === null ? null : `${recall.atMs}:${recall.digest}`+}++const loggedKey = (recall: LoggedRecall): string => `${recall.atMs}:${recall.digest}`+const bar = (value: number, max = 1): string => {const filled = Math.max(0, Math.min(BAR, Math.round((value / max) * BAR)))@@ -34,6 +43,46 @@ function sessionRows(ctx: Ctx, facts: RecallFacts, session: SessionRecall): Rend})}++/** One recorded recall: every surfaced id with the hook's own score and rank, resolved to today's ranked summary where it still exists. Nothing is recomputed. */+function loggedItemRows(ctx: Ctx, facts: RecallFacts, recall: LoggedRecall): RenderElement[] {+ const byId = new Map((facts.ranked?.entries ?? []).map(entry => [entry.id, entry]))+ const top = recall.surfaced[0]?.score ?? 1++ return recall.surfaced.map(item => {+ const entry = byId.get(item.id)++ return text(ctx, ` ${item.rank}. ${bar(item.score, top)} ${n3(item.score)} ${entry === undefined ? `${clip(item.id, 48)} (no longer in the ranked file)` : entry.summary}`, entry === undefined ? { dimColor: true } : {})+ })+}++/** The recorded recalls (ADR-472): pick one by time and digest; what it surfaced is read from the log, with the hook's scores. */+function loggedRows(ctx: Ctx, facts: RecallFacts): RenderElement[] {+ const { nowMs } = ctx+ const log = facts.log+ const rows: RenderElement[] = []+ const days = logWindowMs(log, nowMs) / 86_400_000+ const shownRecall = log.find(recall => loggedKey(recall) === pickedLog) ?? log[0]++ rows.push(text(ctx, ` recorded recalls: ${log.length} in recall-log.jsonl, ${days < 1 ? 'under a day' : `${days.toFixed(1)} days`} back. The prompt text is not kept; each is a digest.`, { bold: true, color: THEME.head }))+ log.slice(0, LOGGED_SHOWN).forEach((recall, index) => {+ const task = facts.prompts.find(prompt => prompt.digest === recall.digest)+ const label = `${ago(recall.atMs, nowMs)} · ${recall.digest.slice(0, 8)} · ${recall.surfaced.length} surfaced${recall.router === null ? '' : ` · router ${recall.router.agent}`}${task === undefined ? '' : ` · "${clip(task.task, 40)}"`}`++ rows.push(row(ctx, [ctx.kit.Button({ key: `recall-log-${index}`, label: `${recall === shownRecall ? '▾' : '▸'} ${clip(label, Math.max(20, ctx.columns - 8))}`, plain: true, onPress: () => { pickLogged(recall); ctx.act.refresh() } })], `recall-log-row-${index}`))+ if (recall === shownRecall) rows.push(...loggedItemRows(ctx, facts, recall))+ })+ if (log.length > LOGGED_SHOWN) rows.push(text(ctx, ` + ${log.length - LOGGED_SHOWN} older recorded recalls`, { dimColor: true }))++ const counts = [...surfacedCounts(log).values()].sort((a, b) => b.count - a.count || b.lastAtMs - a.lastAtMs).slice(0, 5)+ const byId = new Map((facts.ranked?.entries ?? []).map(entry => [entry.id, entry]))++ if (counts.length > 0) rows.push(text(ctx, ' most surfaced (counts over the recorded recalls)', { bold: true, color: THEME.head }))+ for (const item of counts) rows.push(text(ctx, ` ${String(item.count).padStart(4)}x last ${ago(item.lastAtMs, nowMs).padEnd(8)} ${byId.get(item.id)?.summary ?? clip(item.id, 48)}`))++ return rows+}+/*** What the hook recalled. The one RECORDED fact is each session's last recall (ids only: the hook keeps neither the prompt* nor the scores); the explain field re-scores a prompt with the hook's own formula against today's ranked file.@@ -50,16 +99,19 @@ export function recallRows(ctx: Ctx): RenderElement[] {}rows.push(kv(ctx, 'ranked file', `${facts.ranked.entries.length} entries · ranked ${ago(facts.ranked.computedAtMs, nowMs)}`))- rows.push(text(ctx, ' The hook logs neither the prompt nor its scores. Recorded: each session’s last recall (ids). Below that, a re-score.', { dimColor: true }))+ const logged = facts.log.length > 0++ if (logged) rows.push(...loggedRows(ctx, facts))+ else rows.push(text(ctx, facts.reads.log === 'too-large' ? ' recall-log.jsonl is over the read cap: not read. Showing each session’s last recall (ids only), then a re-score.' : ' No recall log (recall-log.jsonl; an older helper, or RUFLO_RECALL_LOG=0): the hook logs neither the prompt nor its scores. Recorded: each session’s last recall (ids only). Below that, a re-score.', { dimColor: true }))- if (facts.sessions.length === 0) rows.push(text(ctx, ' no session file has a lastMatchedPatterns: no recall is recorded yet', { dimColor: true }))+ if (!logged && facts.sessions.length === 0) rows.push(text(ctx, ' no session file has a lastMatchedPatterns: no recall is recorded yet', { dimColor: true }))- facts.sessions.slice(0, 4).forEach((session, index) => {+ if (!logged) facts.sessions.slice(0, 4).forEach((session, index) => {rows.push(text(ctx, ` recorded recall · session ${ago(session.updatedAtMs, nowMs)} · ${session.ids.length} pattern${session.ids.length === 1 ? '' : 's'}${index === 0 ? '' : ' (ids only)'}`, { bold: index === 0, color: THEME.head }))if (index === 0) rows.push(...sessionRows(ctx, facts, session))})- rows.push(text(ctx, ' explain a prompt (what would surface now: recomputed, not what surfaced then)', { bold: true, color: THEME.head }))+ rows.push(text(ctx, logged ? ' explain a prompt (a prompt the hook recorded shows its recorded recall; any other is recomputed against today’s ranked file)' : ' explain a prompt (what would surface now: recomputed, not what surfaced then)', { bold: true, color: THEME.head }))if (facts.prompts.length === 0) rows.push(text(ctx, ` no past prompts: ${facts.reads.prompts === 'ok' ? 'routing-outcomes.json holds no task text' : `.claude-flow/routing-outcomes.json is ${facts.reads.prompts}`}; type one below`, { dimColor: true }))@@ -73,9 +125,21 @@ export function recallRows(ctx: Ctx): RenderElement[] {if (prompt === null) return rows- const scored = explainPrompt(prompt, facts.ranked.entries)+ const recorded = logged ? facts.log.find(recall => recall.digest === digestOf(prompt)) : undefinedrows.push(text(ctx, ` "${clip(prompt, Math.max(20, ctx.columns - 8))}"`, { bold: true }))++ if (recorded !== undefined) {+ rows.push(text(ctx, ` recorded ${ago(recorded.atMs, nowMs)} (digest ${recorded.digest.slice(0, 8)}): what the hook surfaced then, with its scores; not recomputed`, { color: THEME.ok }))+ rows.push(...loggedItemRows(ctx, facts, recorded))+ rows.push(button(ctx, 'recall-clear', 'clear', () => { pickPrompt(null); ctx.act.refresh() }))++ return rows+ }++ const scored = explainPrompt(prompt, facts.ranked.entries)++ if (logged) rows.push(text(ctx, ' no recorded recall has this prompt’s digest: recomputed against today’s ranked file, not what surfaced then', { dimColor: true }))if (scored.length === 0) rows.push(text(ctx, ' nothing clears the hook’s 0.05 threshold: it would surface no memory for this prompt', { color: THEME.warn }))scored.forEach((item, index) => {@@ -101,20 +165,26 @@ export function lifecycleRows(ctx: Ctx): RenderElement[] {const sorted = lifecycleOrder(patterns)const idle = wouldPrune(patterns, 1).length+ const counts = surfacedCounts(facts?.log ?? [])+ const joined = patterns.filter(pattern => counts.has(pattern.id)).length+ const hasLog = (facts?.log.length ?? 0) > 0+rows.push(text(ctx, ' columns: only what models.json records (age, uses, verdict at creation); rank and last-used time are not recorded there', { dimColor: true }))+ if (hasLog) rows.push(text(ctx, ` seen: times the hook surfaced the id; ${joined} of ${patterns.length} rows appear in the recall log (it recalls from ranked-context.json, not models.json)`, { dimColor: true }))// Column widths follow the width: the wide table (id 26 + type 14 + age 8 + uses 5 + verdict 8, then the name) needs 86 columns plus the two buttons; narrower, the columns shrink and the name goes.const wide = ctx.columns >= 120const [wId, wType, wAge, wUses, wVerdict] = wide ? [26, 14, 8, 5, 8] : [16, 12, 6, 4, 7]- const wName = wide ? Math.max(10, ctx.columns - 86 - 20) : 0+ const wSeen = hasLog ? 5 : 0+ const wName = wide ? Math.max(10, ctx.columns - 86 - 20 - wSeen) : 0- rows.push(text(ctx, ` ${'pattern'.padEnd(wId)} ${'type'.padEnd(wType)} ${'age'.padEnd(wAge)} ${'uses'.padEnd(wUses)} ${'verdict'.padEnd(wVerdict)}${wide ? ' name' : ''}`, { dimColor: true }))+ rows.push(text(ctx, ` ${'pattern'.padEnd(wId)} ${'type'.padEnd(wType)} ${'age'.padEnd(wAge)} ${'uses'.padEnd(wUses)} ${'verdict'.padEnd(wVerdict)}${hasLog ? ` ${'seen'.padEnd(wSeen - 1)}` : ''}${wide ? ' name' : ''}`, { dimColor: true }))sorted.slice(0, SHOWN).forEach((pattern, index) => {rows.push(row(ctx,[- ctx.kit.Text({ children: ` ${clip(pattern.id, wId).padEnd(wId)} ${clip(pattern.type, wType).padEnd(wType)} ${clip(pattern.createdAtMs === null ? 'n/a' : ago(pattern.createdAtMs, nowMs).replace(' ago', ''), wAge).padEnd(wAge)} ${String(pattern.usageCount).padEnd(wUses)} ${clip(pattern.verdict ?? 'n/a', wVerdict).padEnd(wVerdict)}${wide ? ` ${clip(pattern.name, wName)}` : ''} ` }),+ ctx.kit.Text({ children: ` ${clip(pattern.id, wId).padEnd(wId)} ${clip(pattern.type, wType).padEnd(wType)} ${clip(pattern.createdAtMs === null ? 'n/a' : ago(pattern.createdAtMs, nowMs).replace(' ago', ''), wAge).padEnd(wAge)} ${String(pattern.usageCount).padEnd(wUses)} ${clip(pattern.verdict ?? 'n/a', wVerdict).padEnd(wVerdict)}${hasLog ? ` ${String(counts.get(pattern.id)?.count ?? 0).padEnd(wSeen - 1)}` : ''}${wide ? ` ${clip(pattern.name, wName)}` : ''} ` }),ctx.kit.Button({ key: `recall-promote-${index}`, label: '▲ promote', plain: true, onPress: () => void ctx.act.run('nn-recall-promote', pattern.id) }),ctx.kit.Button({ key: `recall-prune-${index}`, label: ' ✂ prune', plain: true, onPress: () => void ctx.act.run('nn-recall-prune', pattern.id) }),],diff --git a/plugins/ruflo-console/scripts/bench-memmap.mjs b/plugins/ruflo-console/scripts/bench-memmap.mjsindex 27c51fad89..52471f5284 100644--- a/plugins/ruflo-console/scripts/bench-memmap.mjs+++ b/plugins/ruflo-console/scripts/bench-memmap.mjs@@ -3,9 +3,12 @@* Memory map cost: the data reader (`memory list` JSON -> entries), the layout, the picture and the whole section render, at 1k and* 10k entries (the real probe caps at MAP_LIMIT = 500; the larger sizes show what an uncapped caller would pay). Median and p99* wall time per call, approximate bytes allocated per call (heapUsed delta after gc(); run with --expose-gc, else n/a).- * Embedding rows are synthetic 384-dim vectors: the CLI's list does not print vectors today, so that column is the worst case.+ * Embedding rows are synthetic 384-dim vectors, printed the way `memory list --embeddings` prints them (int8 + scale, base64; ADR-472),+ * so the parse row includes the decode. 500 is the real probe's size (MAP_LIMIT); the larger sizes show what an uncapped caller would pay.* NODE_OPTIONS=--expose-gc npx -y tsx plugins/ruflo-console/scripts/bench-memmap.mjs [iterations]*/+import { encodeEmbeddingQ8 } from '../../../v3/@claude-flow/cli/src/memory/embedding-q8.ts'+import { semanticDuplicates } from '../hooks/data/memory-health.ts'import { mapEntriesOf } from '../hooks/data/memmap.ts'import { layout, memmapPicture, spacesOf } from '../hooks/gfx/memmap.ts'import { newState } from '../hooks/state.ts'@@ -57,13 +60,13 @@ const time = (/** @type {() => unknown} */ fn) => {const row = (/** @type {string} */ name, /** @type {() => unknown} */ fn) => console.log(` ${name.padEnd(34)} ${time(fn)}`)-for (const size of [1000, 10_000]) {+for (const size of [500, 1000, 10_000]) {console.log(`\n${size} entries (${N} runs each)`)for (const embedded of [false, true]) {const mode = embedded ? 'embedding' : 'hash'const entries = entriesOf(size, embedded)- const json = JSON.stringify(entries.map(e => ({ key: e.key, namespace: e.namespace, hasEmbedding: true, accessCount: e.accessCount, ...(e.vector && { embedding: e.vector }) })))+ const json = JSON.stringify(entries.map(e => ({ key: e.key, namespace: e.namespace, hasEmbedding: true, accessCount: e.accessCount, ...(e.vector && { embeddingQ8: encodeEmbeddingQ8(e.vector) }) })))const { points } = layout(entries)const spaces = spacesOf(entries)const hits = new Set(points.slice(0, 20).map(p => `${p.namespace}/${p.key}`))@@ -73,7 +76,9 @@ for (const size of [1000, 10_000]) {const ctx = /** @type {never} */ ({ kit, state, act, columns: 100, nowMs: 5_000, pictures: new Map() })+ console.log(` [${mode}] stdout ${(json.length / 1000).toFixed(0)} KB`)row(`[${mode}] mapEntriesOf (parse)`, () => mapEntriesOf(json))+ if (embedded) row(`[${mode}] similar-by-meaning (health)`, () => semanticDuplicates([...entries]))// Cold rows hand a fresh array each call (layout is remembered per array); the copy is ~0.1 ms at 10k and is inside the figure.row(`[${mode}] layout (cold)`, () => layout([...entries]))row(`[${mode}] memmapPicture`, () => memmapPicture(points, spaces, hits, 100))diff --git a/plugins/ruflo-console/tests/memmap-vectors.spec.ts b/plugins/ruflo-console/tests/memmap-vectors.spec.tsnew file mode 100644index 0000000000..50d230da87--- /dev/null+++ b/plugins/ruflo-console/tests/memmap-vectors.spec.ts@@ -0,0 +1,165 @@+/**+ * The memory map with real vectors (ADR-472): `memory list --embeddings` rows (int8 + scale) decoded, the layout that follows, and the+ * label that is dropped only when stored vectors drove it. Run with+ * npx vitest run plugins/ruflo-console/tests/memmap-vectors.spec.ts+ */+import { describe, expect, it } from 'vitest'++import { encodeEmbeddingQ8 } from '../../../v3/@claude-flow/cli/src/memory/embedding-q8'+import { decodeQ8, mapEntriesOf, memmapProbe } from '../hooks/data/memmap'+import { drawable, layout, modeOf, type MapEntry } from '../hooks/gfx/memmap'+import { newState } from '../hooks/state'+import type { Ctx } from '../hooks/views/common'+import { memmapRows } from '../hooks/views/memmap'++const unit = (n: number, seed: number): number[] => {+ const v = Array.from({ length: n }, (_, i) => Math.sin(seed * 12.9898 + i * 78.233))+ const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0))++ return v.map(x => x / norm)+}+const cosine = (a: readonly number[], b: readonly number[]): number => {+ let dot = 0+ let na = 0+ let nb = 0++ for (let i = 0; i < a.length; i++) {+ dot += (a[i] as number) * (b[i] as number)+ na += (a[i] as number) ** 2+ nb += (b[i] as number) ** 2+ }++ return dot / Math.sqrt(na * nb)+}+const row = (key: string, namespace: string, vector?: number[]) => ({ key, namespace, hasEmbedding: vector !== undefined, accessCount: 1, ...(vector !== undefined && { embeddingQ8: encodeEmbeddingQ8(JSON.stringify(vector)) }) })++describe('decoding what the CLI prints', () => {+ it('reads int8 + scale back to within quantisation error of the stored vector, using the CLI’s own encoder', () => {+ const v = unit(384, 5)+ const back = decodeQ8(encodeEmbeddingQ8(JSON.stringify(v)))++ expect(back).toHaveLength(384)+ expect(cosine(back ?? [], v)).toBeGreaterThan(0.9999)+ })++ it('refuses a shape that does not check out rather than drawing a guess', () => {+ const good = encodeEmbeddingQ8([0.5, -0.25, 0.1, 0.9]) as { dims: number; scale: number; b64: string }++ expect(decodeQ8(good)).toHaveLength(4)+ for (const bad of [null, 'x', {}, { ...good, dims: 5 }, { ...good, dims: 3 }, { ...good, scale: 0 }, { ...good, scale: -1 }, { ...good, scale: Infinity }, { ...good, b64: '!!!!' }, { ...good, b64: 3 }, { ...good, dims: 1.5 }, { dims: 5000, scale: 1, b64: 'AAAA' }]) {+ expect(decodeQ8(bad), JSON.stringify(bad)).toBeUndefined()+ }+ })++ it('puts a decoded vector on each listed entry, and none on a row without one', () => {+ const entries = mapEntriesOf(JSON.stringify([row('a', 'n', unit(8, 1)), row('b', 'n')]))++ expect(entries?.[0]?.vector).toHaveLength(8)+ expect(entries?.[0]?.hasVector).toBe(true)+ expect(entries?.[1]?.vector).toBeUndefined()+ })++ it('asks for the vectors, and an older CLI that ignores the flag leaves the hash layout (no vectors, no claim)', () => {+ expect(memmapProbe.args).toContain('--embeddings')++ const older = mapEntriesOf(JSON.stringify(Array.from({ length: 6 }, (_, i) => ({ key: `k${i}`, namespace: 'n', hasEmbedding: true, accessCount: 0 }))))++ expect(older).toHaveLength(6)+ expect(modeOf(older ?? [])).toBe('hash')+ })++ it('fits the 500 x 384 case inside the 1,000,000 characters the reader parses, and decodes all of it', () => {+ const stdout = JSON.stringify(Array.from({ length: 500 }, (_, i) => row(`entry-${i}`, `ns-${i % 6}`, unit(384, i))), null, 2)+ const started = performance.now()+ const entries = mapEntriesOf(stdout)+ const ms = performance.now() - started++ console.log(`memmap vectors: 500 x 384 stdout ${stdout.length} chars, parsed and decoded in ${ms.toFixed(1)} ms`)+ expect(stdout.length).toBeLessThan(1_000_000)+ expect(entries).toHaveLength(500)+ expect(entries?.every(entry => entry.vector?.length === 384)).toBe(true)+ expect(modeOf(entries ?? [])).toBe('embedding')+ })+})++describe('what is drawn', () => {+ const mixed = (withVector: number, without: number): MapEntry[] => [+ ...Array.from({ length: withVector }, (_, i) => ({ key: `v${i}`, namespace: 'a', hasVector: true, vector: unit(16, i) })),+ ...Array.from({ length: without }, (_, i) => ({ key: `n${i}`, namespace: 'b', hasVector: false })),+ ]++ it('draws only the entries that have a vector when at least half do, and counts the rest', () => {+ const list = mixed(6, 2)+ const got = drawable(list)++ expect(got.entries).toHaveLength(6)+ expect(got.omitted).toBe(2)+ expect(layout(got.entries).mode).toBe('embedding')+ expect(drawable(list)).toBe(got)+ })++ it('keeps every entry in the hash layout when fewer than half have a vector, or when all do or none do', () => {+ const few = mixed(2, 6)++ expect(drawable(few)).toEqual({ entries: few, omitted: 0 })+ expect(layout(drawable(few).entries).mode).toBe('hash')+ expect(drawable(mixed(0, 5)).omitted).toBe(0)+ expect(drawable(mixed(5, 0)).omitted).toBe(0)+ expect(drawable([])).toEqual({ entries: [], omitted: 0 })+ })++ it('places similar stored vectors nearer than unrelated ones', () => {+ const base = unit(64, 3)+ const near = base.map((x, i) => x + 0.02 * Math.sin(i))+ const far = unit(64, 99)+ const placed = layout([{ key: 'base', namespace: 'a', hasVector: true, vector: base }, { key: 'near', namespace: 'a', hasVector: true, vector: near }, { key: 'far', namespace: 'a', hasVector: true, vector: far }]).points+ const dist = (p: { x: number; y: number }, q: { x: number; y: number }) => Math.hypot(p.x - q.x, p.y - q.y)++ expect(dist(placed[0] as never, placed[1] as never)).toBeLessThan(dist(placed[0] as never, placed[2] as never))+ })+})++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'), Raster: make('Raster') }+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 shownOf = (value: MapEntry[]): string => {+ const state = newState({ boot: false })++ state.probes.set('memmap', { value, error: null, okAtMs: 4_000 } as never)++ const ctx = { kit, state, nowMs: 5_000, columns: 200, pictures: new Map(), act: new Proxy({}, { get: () => () => undefined }) } as unknown as Ctx++ return flat(memmapRows(ctx)).filter(el => el.kind === 'Text').map(el => String(el.props.children)).join('\n')+}++describe('the labels', () => {+ const vec = (i: number): MapEntry => ({ key: `v${i}`, namespace: 'a', hasVector: true, vector: unit(16, i) })+ const bare = (i: number): MapEntry => ({ key: `n${i}`, namespace: 'b', hasVector: false })++ it('drops "NOT similarity" only when stored vectors drove the layout, and says how many entries were left off', () => {+ const shown = shownOf([...[1, 2, 3, 4, 5].map(vec), bare(1)])++ expect(shown).toContain('embedding layout')+ expect(shown).toContain('1 without a vector not drawn')+ expect(shown).toContain('read from the store, not recomputed')+ expect(shown).not.toContain('NOT similarity')+ })++ it('keeps the hash label when vectors were not read, or are too few to draw from', () => {+ for (const list of [[1, 2, 3].map(bare), [vec(1), bare(1), bare(2), bare(3)]]) {+ const shown = shownOf(list)++ expect(shown).toContain('hash layout')+ expect(shown).toContain('NOT similarity')+ expect(shown).not.toContain('embedding layout')+ }+ })+})diff --git a/plugins/ruflo-console/tests/memmap.spec.ts b/plugins/ruflo-console/tests/memmap.spec.tsindex 0226ec30f5..26234ccf68 100644--- a/plugins/ruflo-console/tests/memmap.spec.ts+++ b/plugins/ruflo-console/tests/memmap.spec.ts@@ -107,7 +107,7 @@ describe('the readers', () => {})it('asks for the same bounded list as the Namespaces sample, on the memory view only', () => {- expect(memmapProbe.args).toEqual(['memory', 'list', '--format', 'json', '--limit', '500'])+ expect(memmapProbe.args).toEqual(['memory', 'list', '--format', 'json', '--limit', '500', '--embeddings'])expect(memmapProbe.views).toEqual(['memory'])})diff --git a/plugins/ruflo-console/tests/memory-health-recall.spec.ts b/plugins/ruflo-console/tests/memory-health-recall.spec.tsnew file mode 100644index 0000000000..254da0cbbf--- /dev/null+++ b/plugins/ruflo-console/tests/memory-health-recall.spec.ts@@ -0,0 +1,140 @@+/**+ * Memory health with the hook's recall log and stored vectors (ADR-472): "stale" judged by the log where it can speak, and the+ * accessCount rule everywhere else; similar-by-meaning clusters only when vectors were read. Run with+ * npx vitest run plugins/ruflo-console/tests/memory-health-recall.spec.ts+ */+import { describe, expect, it } from 'vitest'++import { analyseHealth, recallEvidenceOf, SEMANTIC_CAP, semanticDuplicates, SIMILAR_COSINE, type HealthEntry } from '../hooks/data/memory-health'+import { parseRanked, parseRecallLog, type RecallFacts } from '../hooks/data/recall'+import type { MapEntry } from '../hooks/gfx/memmap'+import { newState } from '../hooks/state'+import type { Ctx } from '../hooks/views/common'+import { healthRows, staleRule } from '../hooks/views/memory-health'++const DAY = 86_400_000+const NOW = 1_800_000_000_000+const e = (namespace: string, key: string, accessCount: number, updatedDaysAgo: number): HealthEntry => ({ namespace, key, size: 100, accessCount, updatedAtMs: NOW - updatedDaysAgo * DAY })+const ranked = JSON.stringify({ computedAt: 1, entries: [{ id: 'mem_old', category: 'project_old', summary: 's', words: [], pageRank: 0.1 }, { id: 'mem_hot', category: 'project_hot', summary: 's', words: [], pageRank: 0.1 }] })+const rec = (daysAgo: number, id: string, cat = 'auto-memory') => JSON.stringify({ at: NOW - daysAgo * DAY, digest: 'abcdabcdabcdabcd', surfaced: [{ id, score: 0.2, rank: 1, cat }] })+const factsOf = (lines: string[]): RecallFacts => ({ ranked: parseRanked(ranked), sessions: [], prompts: [], neural: null, log: parseRecallLog(lines.join('\n')), reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'missing', bank: 'ok', log: 'ok' } })++describe('stale by the recall log', () => {+ // A 60-day log: the hook surfaced project_hot 3 days ago and nothing else lately.+ const facts = factsOf([rec(60, 'mem_old', 'project_old'), rec(3, 'mem_hot', 'project_hot'), rec(1, 'other', 'x')])+ const sample = { listed: 4, entries: [e('claude-memories', 'project_old', 5, 90), e('claude-memories', 'project_hot', 0, 90), e('notes', 'plain', 0, 90), e('notes', 'plain-used', 2, 90)] }++ it('judges an entry the hook can recall by the log (not surfaced in the window), whatever its access count says', () => {+ const report = analyseHealth(sample, NOW, { evidence: recallEvidenceOf(facts, NOW) })+ const byKey = new Map(report.stale.map(entry => [entry.key, entry.by]))++ expect(byKey.get('project_old')).toBe('log') // accessCount 5, but the hook last surfaced it 60 days ago+ expect(byKey.has('project_hot')).toBe(false) // accessCount 0, but surfaced 3 days ago+ expect(byKey.get('plain')).toBe('count') // the hook cannot recall it: the access-count rule+ expect(byKey.has('plain-used')).toBe(false)+ expect(report).toMatchObject({ staleCount: 2, staleByLog: 1, staleByCount: 1, logChecked: 2 })+ expect(report.log?.records).toBe(3)+ })++ it('never calls an entry updated inside the window stale, even if the hook has not surfaced it', () => {+ const report = analyseHealth({ listed: 1, entries: [e('claude-memories', 'project_old', 0, 2)] }, NOW, { evidence: recallEvidenceOf(facts, NOW) })++ expect(report.staleCount).toBe(0)+ })++ it('does not let a log shorter than the window speak: the access-count rule applies and the report says the log was not used', () => {+ const short = factsOf([rec(5, 'other', 'x')])+ const report = analyseHealth(sample, NOW, { evidence: recallEvidenceOf(short, NOW) })++ expect(report.logChecked).toBe(0)+ expect(report.staleByLog).toBe(0)+ expect(report.stale.every(entry => entry.by === 'count')).toBe(true)+ expect(report.stale.map(entry => entry.key).sort()).toEqual(['plain', 'project_hot'])+ expect(staleRule(report)).toMatch(/shorter than 30d/)+ })++ it('has no evidence without a log or without the ranked file, and then matches the old rule exactly', () => {+ expect(recallEvidenceOf(null, NOW)).toBeNull()+ expect(recallEvidenceOf(factsOf([]), NOW)).toBeNull()+ expect(recallEvidenceOf({ ...facts, ranked: null }, NOW)).toBeNull()++ const plain = analyseHealth(sample, NOW)++ expect(plain.log).toBeNull()+ expect(plain.stale.map(entry => [entry.key, entry.by]).sort()).toEqual([['plain', 'count'], ['project_hot', 'count']])+ expect(staleRule(plain)).toMatch(/access count only/)+ })++ it('names both rules in the rule line and in the view', () => {+ const report = analyseHealth(sample, NOW, { evidence: recallEvidenceOf(facts, NOW) })++ expect(staleRule(report)).toMatch(/log for 2 entries whose key the hook can recall/)+ expect(staleRule(report)).toMatch(/access count for the rest/)++ const state = newState({ boot: false })+ const kit = { Box: (props: object) => ({ kind: 'Box', props }), Text: (props: object) => ({ kind: 'Text', props }), Button: (props: object) => ({ kind: 'Button', props }) }++ state.snapshot = { recall: facts } as never+ state.probes.set('memory-health', { value: sample, okAtMs: NOW, error: null, errorAtMs: null } as never)++ const nodes = healthRows({ kit, state, act: new Proxy({}, { get: () => new Proxy({}, { get: () => () => undefined }) }), columns: 200, nowMs: NOW, pictures: new Map() } as unknown as Ctx)+ const flat = (node: unknown): { kind: string; props: Record<string, unknown> }[] => (Array.isArray(node) ? node.flatMap(flat) : typeof node === 'object' && node !== null ? [node as never, ...flat((node as { props: { children?: unknown } }).props.children)] : [])+ const shown = flat(nodes).filter(el => el.kind === 'Text').map(el => String(el.props.children)).join('\n')++ expect(shown).toContain('by recall log')+ expect(shown).toContain('by access count')+ expect(shown).toContain('(retrievals by memory retrieve or search, not the hook)')+ })+})++const unit = (n: number, seed: number): number[] => {+ const v = Array.from({ length: n }, (_, i) => Math.sin(seed * 12.9898 + i * 78.233))+ const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0))++ return v.map(x => x / norm)+}+const vec = (key: string, vector: number[] | undefined, namespace = 'a'): MapEntry => ({ key, namespace, hasVector: vector !== undefined, ...(vector !== undefined && { vector }) })++describe('similar by meaning', () => {+ it('clusters stored vectors at or above the cosine threshold, and only those', () => {+ const base = unit(64, 1)+ const twin = base.map((x, i) => x + 0.001 * Math.cos(i))+ const report = semanticDuplicates([vec('base', base), vec('twin', twin, 'b'), vec('other', unit(64, 50)), vec('none', undefined)])++ expect(report).toMatchObject({ compared: 3, withVector: 3, listed: 4, clusterCount: 1, entries: 2, cap: SEMANTIC_CAP })+ expect(report?.clusters[0]?.members.map(member => `${member.namespace}/${member.key}`).sort()).toEqual(['a/base', 'b/twin'])+ expect(report?.clusters[0]?.minCosine).toBeGreaterThanOrEqual(SIMILAR_COSINE)+ })++ it('does not run, and says so, when no or one entry carries a vector', () => {+ expect(semanticDuplicates([vec('a', undefined), vec('b', undefined)])).toBeNull()+ expect(semanticDuplicates([vec('a', unit(8, 1))])).toBeNull()+ expect(semanticDuplicates([])).toBeNull()+ })++ it('compares at most the cap and reports how many it left out', () => {+ const many = Array.from({ length: SEMANTIC_CAP + 25 }, (_, i) => vec(`k${i}`, unit(8, i)))+ const report = semanticDuplicates(many)++ expect(report?.compared).toBe(SEMANTIC_CAP)+ expect(report?.withVector).toBe(SEMANTIC_CAP + 25)+ expect(report?.pairs).toBe((SEMANTIC_CAP * (SEMANTIC_CAP - 1)) / 2)+ })++ it('handles vectors of unequal length and an all-zero vector without throwing or inventing a match', () => {+ const report = semanticDuplicates([vec('a', [1, 0, 0]), vec('b', [1, 0]), vec('z', [0, 0, 0])])++ expect(report?.clusterCount).toBe(1) // [1,0,0] and [1,0] are the same direction once padded; the zero vector matches nothing+ expect(report?.clusters[0]?.members.map(member => member.key).sort()).toEqual(['a', 'b'])+ })++ it('costs a bounded amount at 500 x 384', () => {+ const entries = Array.from({ length: SEMANTIC_CAP }, (_, i) => vec(`k${i}`, unit(384, i)))+ const started = performance.now()+ const report = semanticDuplicates(entries)+ const ms = performance.now() - started++ console.log(`similar by meaning: ${SEMANTIC_CAP} x 384, ${report?.pairs} pairs in ${ms.toFixed(0)} ms`)+ expect(ms).toBeLessThan(3000)+ })+})diff --git a/plugins/ruflo-console/tests/memory-health.spec.ts b/plugins/ruflo-console/tests/memory-health.spec.tsindex e814377aa7..262802c0d9 100644--- a/plugins/ruflo-console/tests/memory-health.spec.ts+++ b/plugins/ruflo-console/tests/memory-health.spec.ts@@ -170,7 +170,7 @@ describe('the health view', () => {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(out).toMatch(/2 never retrieved and not updated for 30d/)expect(buttons).toContain('mem-health-consolidate')})})diff --git a/plugins/ruflo-console/tests/recall-log.spec.ts b/plugins/ruflo-console/tests/recall-log.spec.tsnew file mode 100644index 0000000000..a7d1f4c679--- /dev/null+++ b/plugins/ruflo-console/tests/recall-log.spec.ts@@ -0,0 +1,198 @@+/**+ * The hook's recall log in the console (ADR-472): the reader, the digest parity with the real helper, the recorded-recall rows, and+ * the lifecycle's surfaced counts. Run with+ * npx vitest run plugins/ruflo-console/tests/recall-log.spec.ts+ */+import { execFileSync } from 'node:child_process'+import { createHash } from 'node:crypto'+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'+import { tmpdir } from 'node:os'+import { join, resolve } from 'node:path'++import { describe, expect, it } from 'vitest'++import { digestOf, logWindowMs, parseNeuralStore, parsePrompts, parseRanked, parseRecallLog, readRecall, surfacedCounts, tokenize, type RecallFacts } from '../hooks/data/recall'+import { newState } from '../hooks/state'+import type { Ctx } from '../hooks/views/common'+import { lifecycleRows, pickLogged, pickPrompt, recallRows } from '../hooks/views/recall-rows'++const NOW = 1_791_250_000_000+const HOUR = 3_600_000+const line = (at: number, digest: string, surfaced: { id: string; score: number; rank: number; cat?: string }[], router?: { agent: string; confidence: number }) => JSON.stringify({ v: 1, at, sid: 's1', digest, surfaced: surfaced.map(item => ({ ...item, cat: item.cat ?? 'auto-memory' })), ...(router !== undefined && { router }) })+const entry = (id: string, summary: string, pageRank: number) => ({ id, summary, content: summary, category: 'auto-memory', confidence: 0.5, pageRank, accessCount: 0, words: tokenize(summary) })+const RANKED = JSON.stringify({ computedAt: 1, entries: [entry('mem_a', 'authentication token refresh for the login service', 0.04), entry('mem_b', 'deploy the cloud run gateway', 0.02)] })+const MODELS = JSON.stringify({ patterns: { 'pattern-1': { id: 'pattern-1', name: 'p1', type: 't', content: 'c', createdAt: '2026-09-27T00:00:00Z', usageCount: 0 }, mem_a: { id: 'mem_a', name: 'joined', type: 't', content: 'c2', createdAt: '2026-09-27T00:00:00Z', usageCount: 1 } } })+const PROMPT = 'please explain the authentication token refresh flow'+const LOG = [+ line(NOW - 5 * HOUR, 'aaaaaaaaaaaaaaaa', [{ id: 'mem_b', score: 0.21, rank: 1 }]),+ line(NOW - 2 * HOUR, digestOf(PROMPT), [{ id: 'mem_a', score: 0.4321, rank: 1 }, { id: 'mem_gone', score: 0.1234, rank: 2 }], { agent: 'coder', confidence: 0.9 }),+ 'not json',+ JSON.stringify({ at: NOW, digest: 'zz', surfaced: [] }),+ JSON.stringify({ at: NOW, digest: 'bbbbbbbbbbbbbbbb', surfaced: [{ id: 'x', score: 'high', rank: 1 }] }),+].join('\n')++describe('the digest', () => {+ it('is the helper’s: sha256 of the trimmed prompt, 16 hex characters, in plain TypeScript', () => {+ for (const prompt of ['hello', ' padded ', 'unicode ✓ ünï', PROMPT]) {+ expect(digestOf(prompt)).toBe(createHash('sha256').update(prompt.trim()).digest('hex').slice(0, 16))+ }+ })++ it('matches a record the real helper wrote for the same prompt', () => {+ const root = mkdtempSync(join(tmpdir(), 'ruflo-console-472-'))++ try {+ mkdirSync(join(root, '.claude-flow', 'data'), { recursive: true })+ writeFileSync(join(root, '.claude-flow', 'data', 'ranked-context.json'), JSON.stringify({ entries: [{ id: 'mem_a', summary: 'authentication token refresh', category: 'auto-memory', confidence: 0.5, pageRank: 0.04, words: ['authentication', 'token', 'refresh'] }] }))+ const helper = resolve(__dirname, '../../../.claude/helpers/intelligence.cjs')++ execFileSync(process.execPath, ['-e', `const i=require(${JSON.stringify(helper)});i.appendRecall(i.getContextDetailed(${JSON.stringify(PROMPT)}),{sessionId:'s9'})`], { cwd: root, env: { ...process.env, CLAUDE_PROJECT_DIR: root, RUFLO_RECALL_LOG: '' } })++ const [record] = parseRecallLog(readFileSync(join(root, '.claude-flow', 'data', 'recall-log.jsonl'), 'utf8'))++ expect(record?.digest).toBe(digestOf(PROMPT))+ expect(record?.surfaced[0]).toMatchObject({ id: 'mem_a', rank: 1 })+ expect(record?.sessionId).toBe('s9')+ } finally {+ rmSync(root, { recursive: true, force: true })+ }+ })+})++describe('the reader', () => {+ it('keeps valid records newest first and skips the rest', () => {+ const log = parseRecallLog(LOG)++ expect(log.map(record => record.digest)).toEqual([digestOf(PROMPT), 'aaaaaaaaaaaaaaaa'])+ expect(log[0]).toMatchObject({ sessionId: 's1', router: { agent: 'coder', confidence: 0.9 } })+ expect(log[0]?.surfaced.map(item => [item.id, item.score, item.rank])).toEqual([['mem_a', 0.4321, 1], ['mem_gone', 0.1234, 2]])+ expect(parseRecallLog(null)).toEqual([])+ expect(parseRecallLog('')).toEqual([])+ })++ it('counts what was surfaced and how far back the log reaches', () => {+ const log = parseRecallLog(`${LOG}\n${line(NOW - HOUR, 'cccccccccccccccc', [{ id: 'mem_a', score: 0.3, rank: 1 }])}`)+ const counts = surfacedCounts(log)++ expect(counts.get('mem_a')).toMatchObject({ count: 2, lastAtMs: NOW - HOUR })+ expect(counts.get('mem_b')?.count).toBe(1)+ expect(logWindowMs(log, NOW)).toBe(5 * HOUR)+ expect(logWindowMs([], NOW)).toBe(0)+ })++ it('reads the log as a regular file through the bounded reader, and a missing or too-large log is a status, not an error', async () => {+ const files = new Map([['/p/.claude-flow/data/ranked-context.json', RANKED], ['/p/.claude-flow/data/recall-log.jsonl', LOG]])+ const fs = {+ read: async (path: string) => files.get(path) ?? Promise.reject(new Error('ENOENT')),+ stat: async (path: string) => (files.has(path) ? { mtimeMs: 1, size: files.get(path)?.length ?? 0, kind: 'file' } : Promise.reject(new Error('ENOENT'))),+ list: async () => Promise.reject(new Error('ENOENT')),+ }+ const got = await readRecall(fs as never, new Map(), '/p')++ expect(got.log).toHaveLength(2)+ expect(got.reads.log).toBe('ok')++ const none = await readRecall({ ...fs, read: async () => Promise.reject(new Error('x')), stat: async () => Promise.reject(new Error('x')) } as never, new Map(), '/none')++ expect(none.log).toEqual([])+ expect(none.reads.log).toBe('missing')++ const big = await readRecall({ ...fs, stat: async (path: string) => ({ mtimeMs: 1, size: path.endsWith('recall-log.jsonl') ? 3_000_000 : 10, kind: 'file' }) } as never, new Map(), '/p')++ expect(big.reads.log).toBe('too-large')+ expect(big.log).toEqual([])+ })++ it('gives each router task the digest the hook would give that prompt', () => {+ const [task] = parsePrompts(JSON.stringify({ outcomes: [{ task: PROMPT, agent: 'coder', success: true, timestamp: new Date(NOW).toISOString() }] }))++ expect(task?.digest).toBe(digestOf(PROMPT))+ })+})++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 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 words = (nodes: unknown): string => flat(nodes).filter(el => el.kind === 'Text' || el.kind === 'Button').map(el => String(el.props.children ?? el.props.label ?? '')).join('\n')+const factsOf = (log: string | null): RecallFacts => ({ ranked: parseRanked(RANKED), sessions: [], prompts: [{ task: PROMPT, agent: 'coder', ok: true, atMs: NOW - 2 * HOUR, digest: digestOf(PROMPT) }], neural: parseNeuralStore(MODELS), log: parseRecallLog(log), reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'ok', log: log === null ? 'missing' : 'ok' } })+const ctxOf = (facts: RecallFacts): Ctx => {+ const state = newState({ boot: false })++ state.snapshot = { recall: facts } as never++ return { kit, state, nowMs: NOW, columns: 140, pictures: new Map(), act: new Proxy({}, { get: () => () => undefined }) as unknown as Ctx['act'] } as unknown as Ctx+}++describe('the recorded recalls in the Learning Lab', () => {+ it('lists the records and shows the newest one’s surfaced ids with the hook’s own scores, no recomputation label', () => {+ pickPrompt(null)+ pickLogged(null)++ const shown = words(recallRows(ctxOf(factsOf(LOG))))++ expect(shown).toContain('recorded recalls: 2 in recall-log.jsonl')+ expect(shown).toContain('The prompt text is not kept')+ expect(shown).toContain('0.432')+ expect(shown).toContain('authentication token refresh for the login service')+ expect(shown).toContain('mem_gone (no longer in the ranked file)')+ expect(shown).toContain('router coder')+ expect(shown).toContain('"please explain the authentication')+ expect(shown).not.toContain('recomputed, not what surfaced then')+ expect(shown).toContain('most surfaced')+ })++ it('picking another record shows that one', () => {+ pickPrompt(null)+ pickLogged(parseRecallLog(LOG)[1] ?? null)++ const shown = words(recallRows(ctxOf(factsOf(LOG))))++ expect(shown).toContain('0.210')+ expect(shown).not.toContain('0.432')+ pickLogged(null)+ })++ it('shows a prompt whose digest was recorded as recorded, and any other as recomputed with its label', () => {+ pickPrompt(PROMPT)+ const recorded = words(recallRows(ctxOf(factsOf(LOG))))++ expect(recorded).toContain('what the hook surfaced then, with its scores; not recomputed')+ expect(recorded).toContain('0.432')++ pickPrompt('deploy the cloud run gateway now')++ const recomputed = words(recallRows(ctxOf(factsOf(LOG))))++ expect(recomputed).toContain('no recorded recall has this prompt’s digest: recomputed against today’s ranked file, not what surfaced then')+ pickPrompt(null)+ })++ it('without a log keeps the old honest note and the labelled recomputation', () => {+ pickPrompt('authentication token refresh')++ const shown = words(recallRows(ctxOf(factsOf(null))))++ expect(shown).toContain('No recall log')+ expect(shown).toContain('RUFLO_RECALL_LOG=0')+ expect(shown).toContain('recomputed, not what surfaced then')+ expect(shown).not.toContain('recorded recalls:')+ pickPrompt(null)+ })++ it('the lifecycle shows real surfaced counts and says how few rows join the log', () => {+ const shown = words(lifecycleRows(ctxOf(factsOf(LOG))))++ expect(shown).toContain('seen')+ expect(shown).toContain('1 of 2 rows appear in the recall log')+ expect(shown).toContain('ranked-context.json, not models.json')+ expect(words(lifecycleRows(ctxOf(factsOf(null))))).not.toContain('rows appear in the recall log')+ })+})diff --git a/plugins/ruflo-console/tests/recall.spec.ts b/plugins/ruflo-console/tests/recall.spec.tsindex d77547dfa5..4647e53606 100644--- a/plugins/ruflo-console/tests/recall.spec.ts+++ b/plugins/ruflo-console/tests/recall.spec.ts@@ -6,7 +6,7 @@ import { join, resolve } from 'node:path'import { describe, expect, it } from 'vitest'-import { compositeRank, explainPrompt, jaccard, lifecycleOrder, parseNeuralStore, parsePrompts, parseRanked, parseSessionRecall, readRecall, tokenize, trigrams, wouldPrune, type RecallFacts } from '../hooks/data/recall'+import { compositeRank, digestOf, explainPrompt, jaccard, lifecycleOrder, parseNeuralStore, parsePrompts, parseRanked, parseSessionRecall, readRecall, tokenize, trigrams, wouldPrune, type RecallFacts } from '../hooks/data/recall'import { promoteSpec, pruneSpec, pruneUnusedSpec, recallEntries } from '../hooks/recall'import { readSnapshot } from '../hooks/data/snapshot'import { paletteEntries } from '../hooks/palette'@@ -106,7 +106,7 @@ describe('parsers read only what is recorded', () => {})describe('the commands', () => {- const facts: RecallFacts = { ranked: parseRanked(RANKED), sessions: [], prompts: [], neural: parseNeuralStore(MODELS), reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'too-large' } }+ const facts: RecallFacts = { ranked: parseRanked(RANKED), sessions: [], prompts: [], neural: parseNeuralStore(MODELS), log: [], reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'too-large', log: 'missing' } }const state = newState({ boot: false })state.snapshot = { recall: facts } as never@@ -167,9 +167,10 @@ describe('the rows', () => {const facts: RecallFacts = {ranked: parseRanked(RANKED),sessions: [{ file: 'session-1.json', startedAtMs: 1, updatedAtMs: 1_791_249_000_000, ids: ['mem_a', 'mem_gone'] }],- prompts: [{ task: 'authentication token refresh', agent: 'coder', ok: true, atMs: 1_791_000_000_000 }],+ prompts: [{ task: 'authentication token refresh', agent: 'coder', ok: true, atMs: 1_791_000_000_000, digest: digestOf('authentication token refresh') }],neural: parseNeuralStore(MODELS),- reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'too-large' },+ log: [],+ reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'too-large', log: 'missing' },}it('shows the recorded recall as ids resolved, and says what is not recorded', () => {@@ -325,7 +326,7 @@ describe('what the scoring and the table promise', () => {expect(bare?.confidence).toBeNull()pickPrompt(`explain ${key}`)- const facts: RecallFacts = { ranked: { computedAtMs: 1, entries: bare === undefined ? [] : [bare] }, sessions: [{ file: 's', startedAtMs: 1, updatedAtMs: 1, ids: ['x'] }], prompts: [], neural: null, reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'missing', bank: 'missing' } }+ const facts: RecallFacts = { ranked: { computedAtMs: 1, entries: bare === undefined ? [] : [bare] }, sessions: [{ file: 's', startedAtMs: 1, updatedAtMs: 1, ids: ['x'] }], prompts: [], neural: null, log: [], reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'missing', bank: 'missing', log: 'missing' } }const text = words(recallRows(ctxOf(facts)))pickPrompt(null)@@ -335,7 +336,7 @@ describe('what the scoring and the table promise', () => {it('fits the lifecycle table in 80, 120 and 160 columns, and shows only SHOWN rows with the rest counted', () => {const patterns = Object.fromEntries(Array.from({ length: 15 }, (_, index) => [`pattern-1791244689589-${index}-abcdefg`, { id: `pattern-1791244689589-${index}-abcdefg`, name: 'fix: wire recordTrajectory into the hooks tools handler for everything', type: 'history-commit', content: 'c', metadata: { verdict: 'success' }, createdAt: '2026-09-27T17:34:15.801Z', usageCount: index }]))- const facts: RecallFacts = { ranked: null, sessions: [], prompts: [], neural: parseNeuralStore(JSON.stringify({ patterns })), reads: { ranked: 'missing', sessions: 'ok', prompts: 'missing', neural: 'ok', bank: 'ok' } }+ const facts: RecallFacts = { ranked: null, sessions: [], prompts: [], neural: parseNeuralStore(JSON.stringify({ patterns })), log: [], reads: { ranked: 'missing', sessions: 'ok', prompts: 'missing', neural: 'ok', bank: 'ok', log: 'missing' } }for (const columns of [80, 120, 160]) {const ctx = { ...ctxOf(facts), columns } as Ctxdiff --git a/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts b/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.tsindex 7b14891fd3..f8e9c3d60e 100644--- a/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts+++ b/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts@@ -13,6 +13,7 @@ const HELPERS = resolve(__dirname, '../.claude/helpers');const INTEL = join(HELPERS, 'intelligence.cjs');const HANDLER = join(HELPERS, 'hook-handler.cjs');const PROMPT = 'please refactor the swarm coordination planner for the zebra topology';+const SHORT_SECRET_ID = 'mem-ghp_abcdefghijkl-notes';const SECRET_ID = 'mem-sk-abcdefghijklmnopqrstuvwxyz0123456789ABCDEF-token';let root: string;@@ -31,6 +32,7 @@ beforeEach(() => {entries: [entry('mem-swarm-planner-1', 'Swarm coordination planner notes', ['swarm', 'coordination', 'planner', 'zebra', 'topology'], 0.4),entry(SECRET_ID, 'Secret-looking id', ['swarm', 'planner', 'refactor', 'zebra'], 0.3),+ entry(SHORT_SECRET_ID, 'Short secret id', ['swarm', 'planner', 'zebra'], 0.2),entry('mem-unrelated-3', 'Cooking notes', ['pasta', 'tomato'], 0.0),],}),@@ -54,7 +56,7 @@ describe('ADR-472 recall log', () => {expect(record?.v).toBe(1)expect(record?.sid).toBe('sess-1')expect(record?.digest).toBe(createHash('sha256').update(PROMPT).digest('hex').slice(0, 16))- expect(record?.surfaced.map((s: any) => s.rank)).toEqual([1, 2])+ expect(record?.surfaced.map((s: any) => s.rank)).toEqual([1, 2, 3])expect(record?.surfaced[0].id).toBe('mem-swarm-planner-1')expect(record?.surfaced[0].score).toBeGreaterThan(0.05)expect(record?.router).toEqual({ agent: 'coder', confidence: 0.812 })@@ -70,6 +72,7 @@ describe('ADR-472 recall log', () => {const raw = readFileSync(logPath(), 'utf-8');expect(raw).not.toContain('sk-abcdefghijklmnop');+ expect(raw).not.toContain('ghp_abcdefghijkl');expect(raw).toContain('[masked]');expect(records()[0]?.sid).toBeNull();expect(records()[0]?.router).toBeUndefined();diff --git a/v3/docs/adr/ADR-472-recall-log-and-memory-vectors.md b/v3/docs/adr/ADR-472-recall-log-and-memory-vectors.mdnew file mode 100644index 0000000000..30fdebadfe--- /dev/null+++ b/v3/docs/adr/ADR-472-recall-log-and-memory-vectors.md@@ -0,0 +1,94 @@+# ADR-472: Recall log and stored vectors for the Learning Lab and the memory map++- Status: Accepted+- Date: 2026-10-06+- Builds on: ADR-454 (memory map), ADR-456 (explain a recall, pattern lifecycle), ADR-457 (memory health)+- Touches shipped code: `.claude/helpers/{intelligence,hook-handler}.cjs` (both copies), `v3/@claude-flow/cli/src/{commands/memory.ts,memory/*}`; console: `plugins/ruflo-console`++## 1. Context++Two limits remained after ADR-454..457.++1. The intelligence hook never logged which entries it surfaced for a prompt. The Learning Lab could show only each session's last recall (ids) and a labelled recomputation against today's ranked file.+2. `memory list` did not print vectors, so the memory map used a hash layout and said "NOT similarity".++## 2. Decision: the recall log++`intelligence.cjs` gains `getContextDetailed(prompt)` (the old `getContext` is now a thin wrapper that returns the same text), `appendRecall(detailed, meta)`, `recallLogEnabled()` and `promptDigest()`. `hook-handler.cjs route` prints the context exactly as before, runs the router, then appends one record, each step in its own try (the printed context is never suppressed by a logging failure, and logging never blocks).++File: `.claude-flow/data/recall-log.jsonl`, one JSON object per line, mode 0600:++```json+{"v":1,"at":1791325954383,"sid":"<claude session id|null>","digest":"<16 hex>",+ "surfaced":[{"id":"mem_ab..","score":0.4321,"rank":1,"cat":"project_notes"}],+ "router":{"agent":"coder","confidence":0.812}}+```++- `digest` = first 16 hex of sha256 of the trimmed prompt. The prompt text is never written. It is a join key: the console hashes the router's recorded task texts (and a typed prompt) the same way, so a record can be matched to a prompt the person still has.+- `surfaced` = the ids, the hook's own score, rank (1-based) and category of what it printed (at most 10; the hook prints 5). No summary, no content, no paths. `cat` is the memory file stem for imported memories.+- `router` is present only when the router answered. `sid` comes from the hook's stdin JSON (`session_id`), `null` when absent (never the string "undefined").+- Masking: ids, categories, session id and agent pass through a mask that replaces credential-shaped tokens (`sk-`, `ghp_`, `gho_`, `xox*-`, `AKIA`, `eyJ` prefixes, and any 40+ character base64-ish run) with `[masked]`, and strips control characters.+- Bounded and rotating: capped at 1000 records or 1 MiB, whichever is hit first. Past the cap the newest half is kept, rewritten through a temp file and renamed so a reader never sees a half file. The 1 MiB cap (not 2 MB) is deliberate: the console's `READ_MAX` is 2,000,000 bytes, and a log that is unreadable exactly when it is fullest is worse than one that rotates earlier. Lines are only counted once the file passes 100 KiB (a record is at least ~140 bytes, so below that the record cap cannot be exceeded): the common append is one `stat` and one `appendFileSync`.+- Fail-open: every step is in try/catch and returns false on failure.++### Privacy decision: default ON++Default **on**, off with `RUFLO_RECALL_LOG=0` (also `false`, `off`, `no`) or `{"recallLog":{"enabled":false}}` in `claude-flow.config.json`. The env var wins when set (an explicit `1` re-enables over the file). Justification, checked against the code: the log is local, mode 0600, holds no prompt text and no values; the repo already keeps strictly more sensitive material by default (`.claude-flow/routing-outcomes.json` stores raw task text via `hooks post-task` / `model-outcome`, `pending-insights.jsonl` stores edited file paths, `sessions/*.json` store the matched ids). A digest-only log is less sensitive than all of those. Two honest caveats, stated here rather than hidden:++- ranked ids are slugified memory headings (`mem-project_x-swarm-execution-is-a-no-op---r-4`), so "ids only" still reveals the titles of the user's own memory notes, on the user's own disk;+- a 16-hex digest of a short or predictable prompt can be confirmed by anyone who can guess the prompt (a dictionary check). It cannot be reversed, and anyone who can read the log can already read `routing-outcomes.json`.++Not logged when the `route` event is owned by a mod (`RUFLO_MODS_OWNS=route`): the script does not run then, and the mod's own route does not call `getContext`. Not logged when nothing surfaced.++### Shipped-file and signing note++Both copies of `intelligence.cjs` and `hook-handler.cjs` are byte-identical (the parity test passes). They are covered by `helpers.manifest.json`, which is signed with a key this change does not hold. **The manifest is not re-signed here**; until the integrator signs at release, `__tests__/helper-signing.test.ts` "its hashes match the actual shipped helper files" fails by design (it is the gate that proves the helpers were signed after the last edit). The `semver.gte` downgrade guard in `helper-refresh.ts` is untouched: a project's older helpers are refreshed from the package only when the package version is not older, so the log appears after a release that carries these helpers. The generated fallback helpers in `helpers-generator.ts` are not changed (the log is a feature of the shipped helpers only).++## 3. Decision: the console++- `data/recall.ts` reads the log through the bounded reader as a regular file (never a link), parses it newest first (malformed lines and records with no valid surfaced item are skipped), and reports a status (`ok`, `missing`, `too-large`). The digest function is a plain-TypeScript sha256 (the engine's module host is not promised `node:crypto`); a spec runs the real helper and requires the same digest and the same fields.+- Learning Lab, **Explain a recall**: with a log, the section lists recorded recalls (time, digest prefix, count, router agent, and the router's task text when its digest matches). Picking one shows exactly what it surfaced with the hook's own scores, resolved to today's ranked summary where the id still exists. A prompt (typed or a past router task) whose digest was recorded is shown as recorded ("not recomputed"). Any other prompt keeps the recomputation with its label. With no log the old text and label are unchanged.+- **Pattern lifecycle**: a `seen` column and a "most surfaced" list use real counts from the log. The lifecycle table is `models.json` (ADR-456 section 1) and the hook recalls from `ranked-context.json`, which has different ids, so most rows read 0. The view says how many rows appear in the log (`N of M`) rather than implying a join that does not exist.+- **Memory health**: "stale" can now mean "not surfaced by the hook for N days", with these rules, each stated in the view:+ - the log speaks for an entry only if the log reaches back at least `STALE_DAYS` (30) and the entry's key equals a ranked id or its category (the names the hook can recall at all); such an entry is stale if the hook has not surfaced it inside the window and it was not updated inside it (`accessCount` has no time, so it does not vote);+ - every other entry keeps the documented rule (accessCount 0 and not updated for 30 days);+ - each stale row says which rule judged it (`by recall log` or `by access count`), and the rule line gives the counts per rule and how many entries the log could judge.+ - Two different "recall" notions are named: `accessCount` counts retrievals by `memory retrieve`/search, the log counts hook surfacing.+ - The join is by exact key; if no memory key matches a ranked name, `logChecked` is 0 and the access-count rule applies to all (the view says the log is not used).++## 4. Decision: vectors++Path: `memory list --format json --embeddings`. `listEntries` / `bridgeListEntries` (both backends already `SELECT embedding`) gain `includeEmbedding`. Each row then carries `embeddingQ8: {dims, scale, b64}`: the stored vector as int8 with one per-vector scale (`scale = max|v|/127`), base64. Read-only: no write, no content (the `content` field is still absent). Bounded: at most 500 rows (`MAX_LIST_EMBEDDINGS`) per call and 4096 dimensions per vector; a malformed, non-finite, constant-zero or over-long vector yields no field (never a guess). `--embeddings` has no effect without `--format json`.++Why int8 and not floats: the console reads CLI stdout through `jsonAfter`, which parses at most 1,000,000 characters. 500 x 384 as 4-decimal JSON floats is about 1.3 MB; as base64 float32 about 1.07 MB; both would silently truncate and the map would fall back to hash with no error. As int8 it is 326 KB (measured) and the reconstruction cosine is above 0.9999, far more than a 2D random projection needs. A spec asserts the 500 x 384 output fits under the cap.++Console: `memmapProbe` adds `--embeddings`; `mapEntriesOf` decodes `embeddingQ8` (and still accepts a plain `embedding` array). An older CLI ignores the unknown flag (`commandParser` allows unknown flags), prints no vectors, and the map stays in the hash layout with its label: graceful, tested. `drawable()` makes the map useful when a store has some un-embedded entries: if at least half have a vector it draws only those in the embedding layout and the title says "N without a vector not drawn"; below half it keeps every entry in the hash layout. The "NOT similarity" label is dropped only when stored vectors drove the layout; the embedding label says the vectors are read from the store and that a 2D projection loses most of the distance.++Memory health adds **similar by meaning**: clusters of entries whose stored vectors have cosine >= 0.97 (union of pairs, at most 500 entries with a vector, cap and counts shown), computed only when the map's probe actually returned vectors; otherwise one line says it was not checked and why. It never runs on the 1000-entry health list (that probe does not ask for vectors).++### Performance (`scripts/bench-memmap.mjs`, 500 entries x 384 dims, median of 10)++| step | cost |+|---|---|+| parse + decode 326 KB of stdout (per probe result, 60 s cadence) | 6.8 ms |+| layout (cold, per probe result) | 0.26 ms |+| picture, whole frame warm | 0.17 ms / 0.32 ms |+| similar-by-meaning (124,750 pairs, once per probe result) | 33 ms median, 80 ms p99 |++Per-frame cost is unchanged (layouts and the cluster report are cached by the probe result's array identity). Per-refresh cost is bounded by the 500-row cap on the CLI side and the console side.++## 5. What remains unavailable++- Log entries before this change do not exist; sessions and routing outcomes are still the only history for older recalls.+- The log carries ranked-context ids only; neural `models.json` rows (and the ReasoningBank `patterns.json`) are different stores and are not in it.+- Memory-health's log rule applies only to entries whose key equals a ranked id or category; other namespaces have no recall history at all, and stay on the access-count rule.+- Mod-owned `route` does not log.+- The map shows at most 500 entries (unchanged), and similar-by-meaning at most 500 of those.++## 6. Tests++`v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts` (8, runs the real shipped helpers, including `hook-handler route` end to end), `adr-472-memory-list-embeddings.test.ts` (4: encoder, `listEntries` on a fixture store with real ONNX vectors, bounds, read-only, the `list` command with and without `--embeddings`); console `recall-log.spec.ts` (11), `memmap-vectors.spec.ts` (10), `memory-health-recall.spec.ts` (10) plus the amended existing specs. Mutation checks performed: masking regex, opt-out guard, digest, rotation floor, q8 sign extension, log window guard, log rule, half-drawable threshold, digest match; each is caught.++## 7. Rollback++Console: revert the commit's `plugins/ruflo-console` changes; the probe then stops passing `--embeddings` and nothing else depends on the log. CLI: `--embeddings` and `includeEmbedding` are additive (no flag, no change). Helpers: set `RUFLO_RECALL_LOG=0` to stop logging immediately without a release, delete `.claude-flow/data/recall-log.jsonl` to drop the data; reverting `intelligence.cjs` / `hook-handler.cjs` restores the old behaviour (`getContext` is unchanged for every other caller).