🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(console): explain-a-recall and pattern lifecycle in the Learning Lab (ADR-456)
ruv97fb5351ff4e
diff --git a/plugins/ruflo-console/hooks/data/recall.ts b/plugins/ruflo-console/hooks/data/recall.tsnew file mode 100644index 0000000000..e49077d082--- /dev/null+++ b/plugins/ruflo-console/hooks/data/recall.ts@@ -0,0 +1,225 @@+/**+ * Explain-a-recall and the pattern lifecycle (ADR-456): what the intelligence hook recalled, and what the stores it and+ * the neural verbs act on hold. Pure parsers and scoring, plus one bounded reader. Four files, each read as the engine+ * allows (see files.ts: a file over READ_MAX is never read), and each its own fact:+ *+ * - `.claude-flow/data/ranked-context.json` what the hook recalls from (summary, confidence, pageRank, accessCount)+ * - `.claude-flow/sessions/session-*.json` `context.lastMatchedPatterns`: the ids of each session's LAST recall+ * - `.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+ * 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 { jsonObject, msOf, numberOf, plain, recordOf } from './parse'+import { PROJECT, READ_MAX, readBounded, under, type ReaderFs, type ReadCache } from './files'++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'++/** The hook's constants (intelligence.cjs getContext). */+export const ALPHA = 0.6+export const MIN_SCORE = 0.05+export const TOP_K = 5+/** How many session files are read, newest first. */+export const SESSIONS_READ = 8+export const PROMPTS_KEPT = 10++const STOP_WORDS = new Set([+ 'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',+ 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',+ 'should', 'may', 'might', 'shall', 'can', 'to', 'of', 'in', 'for',+ 'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',+ 'before', 'after', 'and', 'but', 'or', 'nor', 'not', 'so', 'yet',+ 'both', 'either', 'neither', 'each', 'every', 'all', 'any', 'few',+ 'more', 'most', 'other', 'some', 'such', 'no', 'only', 'own', 'same',+ 'than', 'too', 'very', 'just', 'because', 'if', 'when', 'which',+ 'who', 'whom', 'this', 'that', 'these', 'those', 'it', 'its',+])++export const tokenize = (text: string): string[] =>+ text+ .toLowerCase()+ .replace(/[^a-z0-9\s-]/g, ' ')+ .split(/\s+/)+ .filter(word => word.length > 2 && !STOP_WORDS.has(word))++export function trigrams(words: readonly string[]): Set<string> {+ const out = new Set<string>()++ for (const word of words) for (let i = 0; i <= word.length - 3; i++) out.add(word.slice(i, i + 3))++ return out+}++export function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number {+ if (a.size === 0 && b.size === 0) return 0++ let shared = 0++ for (const item of a) if (b.has(item)) shared++++ return shared / (a.size + b.size - shared)+}++export type RankedEntry = { id: string; summary: string; category: string; confidence: number; pageRank: number; accessCount: number; words: string[] }+export type Ranked = { computedAtMs: number | null; entries: RankedEntry[] }++/** The order the hook sorts its own entries in (intelligence.cjs: 0.6 pageRank + 0.4 confidence). */+export const compositeRank = (entry: Pick<RankedEntry, 'pageRank' | 'confidence'>): number => ALPHA * entry.pageRank + (1 - ALPHA) * entry.confidence++export function parseRanked(text: string | null): Ranked | null {+ const value = jsonObject(text)++ if (value === null || !Array.isArray(value.entries)) return null++ const entries = value.entries.flatMap((raw): RankedEntry[] => {+ const row = recordOf(raw)++ if (row === null || typeof row.id !== 'string') return []++ const words = Array.isArray(row.words) ? row.words.filter((word): word is string => typeof word === 'string') : []++ return [{ id: plain(row.id, 80), summary: plain(typeof row.summary === 'string' ? row.summary : typeof row.content === 'string' ? row.content : '', 80), category: plain(typeof row.category === 'string' ? row.category : '', 24), confidence: numberOf(row.confidence) ?? 0.5, pageRank: numberOf(row.pageRank) ?? 0, accessCount: numberOf(row.accessCount) ?? 0, words }]+ })++ return { computedAtMs: msOf(value.computedAt) ?? null, entries }+}++export type Scored = { entry: RankedEntry; match: number; score: number }++/** What the hook's getContext would surface for this prompt against these entries, best first; an empty list when nothing clears the threshold. */+export function explainPrompt(prompt: string, entries: readonly RankedEntry[]): Scored[] {+ const words = tokenize(prompt)++ if (words.length === 0) return []++ const grams = trigrams(words)+ const out: Scored[] = []++ for (const entry of entries) {+ const match = jaccard(grams, trigrams(entry.words))+ const score = ALPHA * match + (1 - ALPHA) * entry.pageRank++ if (score >= MIN_SCORE) out.push({ entry, match, score })+ }++ return out.sort((a, b) => b.score - a.score).slice(0, TOP_K)+}++/** One session's last recall: only ids are recorded (the prompt and the scores are not). */+export type SessionRecall = { file: string; startedAtMs: number | null; updatedAtMs: number | null; ids: string[] }++export function parseSessionRecall(file: string, text: string | null): SessionRecall | null {+ const value = jsonObject(text)+ const ids = recordOf(value?.context)?.lastMatchedPatterns++ if (value === null || !Array.isArray(ids)) return null++ return { 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 }++/** The distinct task texts the router judged, newest first: the only prompts a hook file keeps. */+export function parsePrompts(text: string | null): PastPrompt[] {+ const value = jsonObject(text)++ if (value === null || !Array.isArray(value.outcomes)) return []++ const rows = value.outcomes.flatMap((raw): PastPrompt[] => {+ const row = recordOf(raw)+ const atMs = msOf(row?.timestamp)++ return row === null || atMs === undefined || typeof row.task !== 'string' || row.task.trim() === '' ? [] : [{ task: plain(row.task, 160), agent: plain(typeof row.agent === 'string' ? row.agent : '?', 30), ok: row.success === true, atMs }]+ })+ const seen = new Set<string>()+ const out: PastPrompt[] = []++ for (const row of rows.sort((a, b) => b.atMs - a.atMs)) {+ if (seen.has(row.task)) continue++ seen.add(row.task)+ out.push(row)+ if (out.length >= PROMPTS_KEPT) break+ }++ return out+}++/** 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 }++export function parseNeuralStore(text: string | null): NeuralPattern[] | null {+ const value = jsonObject(text)+ const patterns = recordOf(value?.patterns)++ if (patterns === null) return null++ return Object.values(patterns).slice(0, 1000).flatMap((raw): NeuralPattern[] => {+ const row = recordOf(raw)++ if (row === null || typeof row.id !== 'string') return []++ const verdict = recordOf(row.metadata)?.verdict++ return [{ id: plain(row.id, 80), name: plain(typeof row.name === 'string' ? row.name : '', 90), type: plain(typeof row.type === 'string' ? row.type : '?', 24), content: plain(typeof row.content === 'string' ? row.content : '', 600), createdAtMs: msOf(row.createdAt) ?? null, usageCount: numberOf(row.usageCount) ?? 0, verdict: typeof verdict === 'string' ? plain(verdict, 20) : null }]+ })+}++/** Most used first, then oldest first: the order a prune is read in (the never-used, oldest ones last-but-visible together). */+export const lifecycleOrder = (rows: readonly NeuralPattern[]): NeuralPattern[] => [...rows].sort((a, b) => b.usageCount - a.usageCount || (a.createdAtMs ?? Infinity) - (b.createdAtMs ?? Infinity))++/** The ids `neural_compress prune` with this threshold would remove: usageCount below it (neural-tools.ts). */+export const wouldPrune = (rows: readonly NeuralPattern[], threshold: number): string[] => rows.filter(row => row.usageCount < threshold).map(row => row.id)++export type ReadStatus = 'ok' | 'missing' | 'too-large' | 'refused'++export type RecallFacts = {+ ranked: Ranked | null+ sessions: SessionRecall[]+ prompts: PastPrompt[]+ neural: NeuralPattern[] | null+ /** 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 }+}++/** The recall facts of a snapshot that carries them, else null: the view's one accessor. */+export const recallOf = (snapshot: object | null | undefined): RecallFacts | null => (snapshot as { recall?: RecallFacts } | null | undefined)?.recall ?? null++const status = (read: { text: string | null; reason?: string }): ReadStatus => (read.text !== null ? 'ok' : ((read.reason ?? 'missing') as ReadStatus))++let lastRanked: { text: string; parsed: Ranked | null } | 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([+ readBounded(fs, cache, under(cwd, RANKED)),+ readBounded(fs, cache, under(cwd, MODELS)),+ readBounded(fs, cache, under(cwd, PROJECT.outcomes)),+ fs.stat(under(cwd, BANK)).catch(() => undefined),+ fs.list(under(cwd, SESSIONS)).catch(() => null),+ ])+ const files = (listed ?? []).filter(entry => entry.kind !== 'dir' && /^session-\d+\.json$/.test(entry.name)).sort((a, b) => (b.mtimeMs ?? 0) - (a.mtimeMs ?? 0)).slice(0, SESSIONS_READ)+ const reads = await Promise.all(files.map(async entry => ({ name: entry.name, read: await readBounded(fs, cache, under(cwd, `${SESSIONS}/${entry.name}`), 100_000, true) })))+ const sessions = reads.flatMap(({ name, read }) => {+ const parsed = parseSessionRecall(name, read.text)++ return parsed === null ? [] : [parsed]+ })++ // The ranked file is parsed again only when its text changed: the snapshot runs on a timer.+ if (ranked.text !== null && lastRanked?.text !== ranked.text) lastRanked = { text: ranked.text, parsed: parseRanked(ranked.text) }++ return {+ ranked: ranked.text === null ? null : (lastRanked?.parsed ?? null),+ sessions,+ prompts: parsePrompts(outcomes.text),+ neural: parseNeuralStore(models.text),+ 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' },+ }+}diff --git a/plugins/ruflo-console/hooks/recall.ts b/plugins/ruflo-console/hooks/recall.tsnew file mode 100644index 0000000000..f8a22b52a8--- /dev/null+++ b/plugins/ruflo-console/hooks/recall.ts@@ -0,0 +1,59 @@+/**+ * The lifecycle commands of ADR-456, as fixed argv checked against @claude-flow/cli (mcp-tools/neural-tools.ts+ * `neural_patterns` delete and `neural_compress` prune, both on .claude-flow/neural/models.json; mcp-tools/agentdb-tools.ts+ * `agentdb_feedback`, whose bridge turns a success with quality >= 0.9 and a pattern into a reusable skill, memory-bridge.ts).+ * Every one writes, so every one asks first. There is no in-place "raise this pattern's rank" verb in ruflo: promote is+ * the documented promote-to-skill path and it ADDS a pattern and a skill; the original row is not edited. Pure: specs+ * and entries only, built from the state; the runner runs them.+ */+import type { ActionSpec } from './actions'+import { autoSpec, tool, type AutoEntry } from './automate'+import { recallOf, wouldPrune } from './data/recall'+import type { State } from './state'++/** A pattern id as ruflo mints them (`pattern-<ms>-<n>-<rand>`): letters, digits, dash and underscore only. */+export const patternIdOf = (text: string): string | null => {+ const id = text.trim()++ return /^[A-Za-z0-9_-]{1,80}$/.test(id) ? id : null+}++export const PRUNE_NOTE = 'DELETES FOR GOOD: one pattern from .claude-flow/neural/models.json; there is no undo'+export const PROMOTE_NOTE = 'writes: records a success (quality 0.95) with this pattern, which adds a pattern to the ReasoningBank and a reusable skill; the row itself is not changed'++export function pruneSpec(text: string): ActionSpec | null {+ const id = patternIdOf(text)++ return id === null ? null : autoSpec('nn-recall-prune', `prune the pattern ${id}`, 'writes', tool('neural_patterns', { action: 'delete', patternId: id }), { note: PRUNE_NOTE })+}++export function promoteSpec(state: State, text: string): ActionSpec | null {+ const id = patternIdOf(text)+ const pattern = id === null ? undefined : recallOf(state.snapshot)?.neural?.find(row => row.id === id)++ if (id === null || pattern === undefined || pattern.content === '') return null++ return autoSpec('nn-recall-promote', `promote the pattern ${id} to a skill`, 'writes', tool('agentdb_feedback', { taskId: `promote-${id}`.slice(0, 80), success: true, quality: 0.95, patterns: [pattern.content] }), { note: PROMOTE_NOTE })+}++/** `neural_compress` prune: every pattern used fewer than `uses` times. The count shown is what the file says now. */+export function pruneUnusedSpec(state: State, uses = 1): ActionSpec | null {+ const rows = recallOf(state.snapshot)?.neural++ if (rows === null || rows === undefined) return null++ const doomed = wouldPrune(rows, uses).length++ if (doomed === 0) return null++ return autoSpec('nn-recall-prune-unused', `prune ${doomed} of ${rows.length} patterns used fewer than ${uses} time${uses === 1 ? '' : 's'}`, 'writes', tool('neural_compress', { method: 'prune', targetSize: uses }), { note: `DELETES FOR GOOD: every pattern in .claude-flow/neural/models.json with usageCount below ${uses} (${doomed} now); there is no undo` })+}++/** The typed entries (`/ruflo run nn-recall-prune <pattern id>`) and the bulk one; ids are what `/ruflo run` takes. */+export function recallEntries(state: State): AutoEntry[] {+ return [+ { id: 'nn-recall-prune', group: 'neural', label: 'nn-recall-prune <pattern id>: delete one pattern from the neural store', make: pruneSpec },+ { id: 'nn-recall-promote', group: 'neural', label: 'nn-recall-promote <pattern id>: promote one neural-store pattern to a skill', make: text => promoteSpec(state, text) },+ { id: 'nn-recall-prune-unused', group: 'neural', label: 'neural_compress prune: delete every neural-store pattern that was never used', spec: pruneUnusedSpec(state), why: 'n/a: no .claude-flow/neural/models.json was read, or no pattern in it is unused' },+ ]+}diff --git a/plugins/ruflo-console/hooks/views/neural.ts b/plugins/ruflo-console/hooks/views/neural.tsindex d3f5a6102a..21b50b0d7f 100644--- a/plugins/ruflo-console/hooks/views/neural.ts+++ b/plugins/ruflo-console/hooks/views/neural.ts@@ -3,6 +3,7 @@ import type { RenderElement } from 'claude-code'import { EPOCHS, PATTERNS, sparkline } from '../data/automate'import { field, resultRows, strip } from './automate'import { spinAt } from '../spinner'+import { lifecycleRows, recallRows } from './recall-rows'import { ago, col, count, kv, row, section, text, THEME, type Ctx } from './common'const BAR = 24@@ -105,6 +106,8 @@ export const neuralActionRows = (ctx: Ctx, nested = false): RenderElement[] => {...section(ctx, 'nn-intel', 'Intelligence', neural === null ? 'no .claude-flow/neural/stats.json' : 'neural/stats.json', intelligenceRows(ctx), true),...section(ctx, 'nn-train', 'Training', `${trains.length} run${trains.length === 1 ? '' : 's'} this session${isTraining ? ' · running' : ''}`, trainingRows(ctx), nested || isTraining),...section(ctx, 'nn-self', 'Self-learning', 'bootstrap, consolidate and teach the ReasoningBank · local, no model calls', selfLearnRows(ctx), nested),+ ...section(ctx, 'nn-recall', 'Explain a recall', 'what the hook surfaced · ranked-context.json', recallRows(ctx), true),+ ...section(ctx, 'nn-life', 'Pattern lifecycle', 'neural/models.json · prune and promote ask first', lifecycleRows(ctx), nested),...section(ctx, 'nn-router', 'Router', 'which agent for this task? · $0, local', routerRows(ctx), true),]}diff --git a/plugins/ruflo-console/hooks/views/recall-rows.ts b/plugins/ruflo-console/hooks/views/recall-rows.tsnew file mode 100644index 0000000000..83998e3d70--- /dev/null+++ b/plugins/ruflo-console/hooks/views/recall-rows.ts@@ -0,0 +1,129 @@+import type { RenderElement } from 'claude-code'++import { compositeRank, explainPrompt, lifecycleOrder, recallOf, wouldPrune, 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. */+const SHOWN = 12+const BAR = 10++/** The prompt being explained: typed or picked. View-local (the integrator may move it into State); a button sets it and asks for a redraw. */+let picked: string | null = null++export const pickPrompt = (value: string | null): void => {+ picked = value === null || value.trim() === '' ? null : value.trim().slice(0, 300)+}++export const pickedPrompt = (): string | null => picked++const bar = (value: number, max = 1): string => {+ const filled = Math.max(0, Math.min(BAR, Math.round((value / max) * BAR)))++ return '█'.repeat(filled) + '░'.repeat(BAR - filled)+}++const n3 = (value: number): string => value.toFixed(3)++function sessionRows(ctx: Ctx, facts: RecallFacts, session: SessionRecall): RenderElement[] {+ const byId = new Map((facts.ranked?.entries ?? []).map(entry => [entry.id, entry]))++ return session.ids.map((id, index) => {+ const entry = byId.get(id)++ return text(ctx, entry === undefined ? ` ${index + 1}. ${clip(id, 40)} (no longer in the ranked file)` : ` ${index + 1}. rank ${n3(compositeRank(entry))} ${entry.summary} [${entry.category || 'n/a'} · conf ${entry.confidence.toFixed(2)} · pr ${n3(entry.pageRank)} · ${entry.accessCount}x]`, entry === undefined ? { dimColor: true } : {})+ })+}++/**+ * 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.+ */+export function recallRows(ctx: Ctx): RenderElement[] {+ const facts = recallOf(ctx.state.snapshot)+ const { nowMs } = ctx+ const rows: RenderElement[] = []++ if (facts === null || facts.ranked === null) {+ const why = facts === null ? 'the recall probe is not wired into this snapshot' : `.claude-flow/data/ranked-context.json is ${facts.reads.ranked}`++ return [text(ctx, ` nothing to recall from: ${why}. The hook builds that file when it consolidates (hooks intelligence).`, { dimColor: true })]+ }++ 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 }))++ if (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) => {+ 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 }))++ 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 }))++ facts.prompts.slice(0, 6).forEach((prompt, index) =>+ rows.push(row(ctx, [ctx.kit.Button({ key: `recall-pick-${index}`, label: `▸ ${clip(prompt.task, Math.max(20, ctx.columns - 24))}`, plain: true, onPress: () => { pickPrompt(prompt.task); ctx.act.refresh() } }), ctx.kit.Text({ dimColor: true, children: ` ${prompt.agent} ${prompt.ok ? '✓' : '✗'} ${ago(prompt.atMs, nowMs)}` })], `recall-pick-row-${index}`)),+ )++ if (ctx.kit.Input !== undefined) rows.push(ctx.kit.Input({ key: 'in-recall-explain', label: 'prompt', placeholder: 'any prompt, to see which memories it would pull', submitLabel: 'explain', onSubmit: value => { pickPrompt(value); ctx.act.refresh() } }))++ const prompt = pickedPrompt()++ if (prompt === null) return rows++ const scored = explainPrompt(prompt, facts.ranked.entries)++ rows.push(text(ctx, ` "${clip(prompt, Math.max(20, ctx.columns - 8))}"`, { bold: 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) => {+ rows.push(text(ctx, ` ${index + 1}. ${bar(item.score, scored[0]?.score ?? 1)} ${n3(item.score)} = 0.6·match ${n3(item.match)} + 0.4·pr ${n3(item.entry.pageRank)} ${item.entry.summary}`))+ })+ rows.push(button(ctx, 'recall-clear', 'clear', () => { pickPrompt(null); ctx.act.refresh() }))++ return rows+}++/**+ * The neural store's patterns with only what models.json records. No rank and no last-used time exist in that file, so+ * neither is drawn; usageCount is real and is 0 for patterns nothing has recalled. Prune and promote ask first.+ */+export function lifecycleRows(ctx: Ctx): RenderElement[] {+ const facts = recallOf(ctx.state.snapshot)+ const { nowMs } = ctx+ const rows: RenderElement[] = []+ const patterns = facts?.neural ?? null++ if (patterns === null) return [text(ctx, ` no pattern table: .claude-flow/neural/models.json is ${facts?.reads.neural ?? 'not read (the recall probe is not wired)'}`, { dimColor: true })]++ const sorted = lifecycleOrder(patterns)+ const idle = wouldPrune(patterns, 1).length++ 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 }))+ rows.push(text(ctx, ` ${'pattern'.padEnd(26)} ${'type'.padEnd(14)} ${'age'.padEnd(8)} ${'uses'.padEnd(5)} ${'verdict'.padEnd(8)} name`, { dimColor: true }))++ sorted.slice(0, SHOWN).forEach((pattern, index) => {+ rows.push(+ row(+ ctx,+ [+ ctx.kit.Text({ children: ` ${clip(pattern.id, 26).padEnd(26)} ${clip(pattern.type, 14).padEnd(14)} ${(pattern.createdAtMs === null ? 'n/a' : ago(pattern.createdAtMs, nowMs).replace(' ago', '')).padEnd(8)} ${String(pattern.usageCount).padEnd(5)} ${(pattern.verdict ?? 'n/a').padEnd(8)} ${clip(pattern.name, Math.max(10, ctx.columns - 96))} ` }),+ 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) }),+ ],+ `recall-pattern-${index}`,+ ),+ )+ })+ if (sorted.length > SHOWN) rows.push(text(ctx, ` + ${sorted.length - SHOWN} more in the file`, { dimColor: true }))+ if (sorted.length === 0) rows.push(text(ctx, ' the neural store holds no patterns', { dimColor: true }))++ rows.push(row(ctx, [text(ctx, ` ${idle} of ${patterns.length} never used `, { color: idle > 0 ? THEME.warn : THEME.ok }), ctx.kit.Button({ key: 'recall-prune-unused', label: '✂ prune the never-used', plain: true, onPress: () => void ctx.act.run('nn-recall-prune-unused') })], 'recall-prune-bulk'))+ rows.push(+ text(ctx, facts?.reads.bank === 'too-large' ? ' the ReasoningBank (neural/patterns.json) is over the 2 MB read cap: it is not read, and no per-pattern verb acts on it' : ' the ReasoningBank (neural/patterns.json) is a separate store; no per-pattern verb acts on it', { dimColor: true }),+ )++ return rows+}diff --git a/plugins/ruflo-console/tests/recall.spec.ts b/plugins/ruflo-console/tests/recall.spec.tsnew file mode 100644index 0000000000..f3aac59a54--- /dev/null+++ b/plugins/ruflo-console/tests/recall.spec.ts@@ -0,0 +1,257 @@+/** Explain-a-recall and the pattern lifecycle (ADR-456): parsers, the hook's own scoring, the commands' argv, and what the rows say. */+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'+import { createRequire } from 'node:module'+import { tmpdir } from 'node:os'+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 { promoteSpec, pruneSpec, pruneUnusedSpec, recallEntries } from '../hooks/recall'+import { newState } from '../hooks/state'+import type { Ctx } from '../hooks/views/common'+import { lifecycleRows, pickPrompt, recallRows } from '../hooks/views/recall-rows'++const ranked = (entries: unknown[]) => JSON.stringify({ version: 1, computedAt: 1_791_244_689_589, entries })+const entry = (id: string, summary: string, pageRank: number, confidence = 0.5, accessCount = 0) => ({ id, summary, content: summary, category: 'auto-memory', confidence, pageRank, accessCount, words: tokenize(summary) })++const RANKED = ranked([+ entry('mem_a', 'authentication token refresh for the login service', 0.04, 0.6, 3),+ entry('mem_b', 'deploy the cloud run gateway with traffic migration', 0.02),+ entry('mem_c', 'unrelated gardening notes about tomatoes', 0.001),+])++const MODELS = JSON.stringify({+ models: {},+ patterns: {+ 'pattern-1-a': { id: 'pattern-1-a', name: 'fix: wire recordTrajectory', type: 'history-commit', embedding: [0.1], content: 'paths: hooks-tools.ts:142', metadata: { verdict: 'success' }, createdAt: '2026-09-27T17:34:15.801Z', usageCount: 0 },+ 'pattern-2-b': { id: 'pattern-2-b', name: 'Dream Cycle scan', type: 'history-issue', content: 'MV-HNSW gap', metadata: { verdict: 'partial' }, createdAt: '2026-09-28T00:00:00.000Z', usageCount: 4 },+ },+ version: '3.0.0',+})++describe('the hook’s scoring, copied', () => {+ it('tokenizes, takes trigrams and compares like intelligence.cjs', () => {+ expect(tokenize('Fix the AUTH token, now!')).toEqual(['fix', 'auth', 'token', 'now'])+ expect([...trigrams(['auth'])].sort()).toEqual(['aut', 'uth'])+ expect(jaccard(new Set(['a', 'b']), new Set(['b', 'c']))).toBeCloseTo(1 / 3)+ expect(jaccard(new Set(), new Set())).toBe(0)+ })++ it('scores 0.6 * match + 0.4 * pageRank, drops what is under 0.05, best first', () => {+ const parsed = parseRanked(RANKED)+ const top = explainPrompt('authentication token refresh', parsed?.entries ?? [])++ expect(top[0]?.entry.id).toBe('mem_a')+ expect(top.map(item => item.entry.id)).not.toContain('mem_c')+ expect(top[0]?.score).toBeCloseTo(0.6 * (top[0]?.match ?? 0) + 0.4 * 0.04, 10)+ expect(explainPrompt('the of and', parsed?.entries ?? [])).toEqual([])+ })++ const helper = resolve(__dirname, '../../../.claude/helpers/intelligence.cjs')++ it.skipIf(!existsSync(helper))('gives the scores the real hook prints', () => {+ const root = mkdtempSync(join(tmpdir(), 'recall-'))++ mkdirSync(join(root, '.claude-flow', 'data'), { recursive: true })+ writeFileSync(join(root, '.claude-flow', 'data', 'ranked-context.json'), RANKED)+ process.env.CLAUDE_PROJECT_DIR = root++ try {+ const out: string = createRequire(import.meta.url)(helper).getContext('authentication token refresh login') as string+ const mine = explainPrompt('authentication token refresh login', parseRanked(RANKED)?.entries ?? [])+ const printed = [...out.matchAll(/\* \((\d\.\d\d)\)/g)].map(match => match[1])++ expect(printed).toEqual(mine.map(item => item.score.toFixed(2)))+ expect(printed.length).toBeGreaterThan(0)+ } finally {+ delete process.env.CLAUDE_PROJECT_DIR+ }+ })++ it('ranks entries by the hook’s composite', () => {+ expect(compositeRank({ pageRank: 0.1, confidence: 0.5 })).toBeCloseTo(0.26)+ })+})++describe('parsers read only what is recorded', () => {+ it('keeps ids, never a prompt, from a session file', () => {+ const got = parseSessionRecall('session-1.json', JSON.stringify({ startedAt: '2026-10-05T00:00:00Z', updatedAt: '2026-10-05T01:00:00Z', context: { lastMatchedPatterns: ['mem_a', 7, 'mem_b'] } }))++ expect(got?.ids).toEqual(['mem_a', 'mem_b'])+ expect(got?.updatedAtMs).toBe(Date.parse('2026-10-05T01:00:00Z'))+ expect(parseSessionRecall('x', '{"context":{}}')).toBeNull()+ expect(parseSessionRecall('x', 'not json')).toBeNull()+ })++ it('lists distinct past tasks newest first', () => {+ const out = parsePrompts(JSON.stringify({ outcomes: [{ task: 'a', agent: 'coder', success: true, timestamp: '2026-09-27T10:00:00Z' }, { task: 'b', agent: 'tester', success: false, timestamp: '2026-09-28T10:00:00Z' }, { task: 'a', agent: 'coder', success: true, timestamp: '2026-09-29T10:00:00Z' }, { agent: 'x' }] }))++ expect(out.map(prompt => prompt.task)).toEqual(['a', 'b'])+ expect(out[1]?.ok).toBe(false)+ expect(parsePrompts(null)).toEqual([])+ })++ it('reads the neural store without its embeddings or any field it lacks', () => {+ const rows = parseNeuralStore(MODELS) ?? []++ expect(rows.map(row => [row.id, row.usageCount, row.verdict])).toEqual([['pattern-1-a', 0, 'success'], ['pattern-2-b', 4, 'partial']])+ expect(JSON.stringify(rows)).not.toContain('embedding')+ expect(lifecycleOrder(rows).map(row => row.id)).toEqual(['pattern-2-b', 'pattern-1-a'])+ expect(wouldPrune(rows, 1)).toEqual(['pattern-1-a'])+ expect(parseNeuralStore('{}')).toBeNull()+ })+})++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 state = newState({ boot: false })++ state.snapshot = { recall: facts } as never++ it('prunes one pattern with fixed argv and says it is for good', () => {+ const spec = pruneSpec(' pattern-1-a ')++ expect(spec?.args).toEqual(['mcp', 'exec', '-t', 'neural_patterns', '-p', JSON.stringify({ action: 'delete', patternId: 'pattern-1-a' })])+ expect(spec?.note).toMatch(/DELETES FOR GOOD/)+ expect(spec?.isReadOnly).toBeUndefined()+ expect(pruneSpec('a b; c')).toBeNull()+ expect(pruneSpec('')).toBeNull()+ })++ it('promotes only a pattern the store holds, as feedback with its own text', () => {+ const spec = promoteSpec(state, 'pattern-1-a')++ expect(spec?.args).toEqual(['mcp', 'exec', '-t', 'agentdb_feedback', '-p', JSON.stringify({ taskId: 'promote-pattern-1-a', success: true, quality: 0.95, patterns: ['paths: hooks-tools.ts:142'] })])+ expect(spec?.note).toMatch(/adds a pattern/)+ expect(promoteSpec(state, 'pattern-unknown')).toBeNull()+ })++ it('prunes the never-used in bulk, with the count it would remove', () => {+ const spec = pruneUnusedSpec(state)++ expect(spec?.label).toBe('prune 1 of 2 patterns used fewer than 1 time')+ expect(spec?.args).toEqual(['mcp', 'exec', '-t', 'neural_compress', '-p', JSON.stringify({ method: 'prune', targetSize: 1 })])+ expect(pruneUnusedSpec(newState({ boot: false }))).toBeNull()+ })++ it('registers its entries under nn- ids so the result panel shows them', () => {+ expect(recallEntries(state).map(item => item.id)).toEqual(['nn-recall-prune', 'nn-recall-promote', 'nn-recall-prune-unused'])+ })+})++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')++function ctxOf(recall: RecallFacts | undefined): Ctx {+ const state = newState({ boot: false })++ state.snapshot = (recall === undefined ? {} : { recall }) as never++ return { kit, state, nowMs: 1_791_250_000_000, columns: 140, pictures: new Map(), act: new Proxy({}, { get: () => () => undefined }) as unknown as Ctx['act'] } as unknown as Ctx+}++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 }],+ neural: parseNeuralStore(MODELS),+ reads: { ranked: 'ok', sessions: 'ok', prompts: 'ok', neural: 'ok', bank: 'too-large' },+ }++ it('shows the recorded recall as ids resolved, and says what is not recorded', () => {+ pickPrompt(null)++ const text = words(recallRows(ctxOf(facts)))++ expect(text).toMatch(/neither the prompt nor its scores/)+ expect(text).toMatch(/authentication token refresh for the login service/)+ expect(text).toMatch(/mem_gone.*no longer in the ranked file/)+ })++ it('explains a picked prompt as a recomputation with the formula’s parts', () => {+ pickPrompt('authentication token refresh')++ const text = words(recallRows(ctxOf(facts)))++ pickPrompt(null)+ expect(text).toMatch(/recomputed, not what surfaced then/)+ expect(text).toMatch(/0\.6·match .* \+ 0\.4·pr 0\.040/)+ })++ it('says so when nothing clears the threshold', () => {+ pickPrompt('zzz qqq')++ const text = words(recallRows(ctxOf(facts)))++ pickPrompt(null)+ expect(text).toMatch(/nothing clears the hook’s 0\.05 threshold/)+ })++ it('draws the lifecycle table with uses and verdict, and no rank or last-used column', () => {+ const text = words(lifecycleRows(ctxOf(facts)))++ expect(text).toMatch(/pattern-2-b/)+ expect(text).toMatch(/rank and last-used time are not recorded/)+ expect(text).toMatch(/1 of 2 never used/)+ expect(text).toMatch(/over the 2 MB read cap/)+ })++ it('shows honest empty states, never invented rows', () => {+ expect(words(recallRows(ctxOf(undefined)))).toMatch(/recall probe is not wired/)+ expect(words(lifecycleRows(ctxOf({ ...facts, neural: null, reads: { ...facts.reads, neural: 'missing' } })))).toMatch(/models\.json is missing/)+ expect(words(recallRows(ctxOf({ ...facts, ranked: null, reads: { ...facts.reads, ranked: 'too-large' } })))).toMatch(/is too-large/)+ })+})++describe('the reader', () => {+ it('reads the four files, the newest sessions only, and only stats the bank', async () => {+ const files = new Map<string, string>([+ ['/p/.claude-flow/data/ranked-context.json', RANKED],+ ['/p/.claude-flow/neural/models.json', MODELS],+ ['/p/.claude-flow/routing-outcomes.json', JSON.stringify({ outcomes: [{ task: 't', agent: 'coder', success: true, timestamp: '2026-09-27T10:00:00Z' }] })],+ ['/p/.claude-flow/sessions/session-1.json', JSON.stringify({ updatedAt: '2026-10-01T00:00:00Z', context: { lastMatchedPatterns: ['mem_a'] } })],+ ['/p/.claude-flow/sessions/session-2.json', JSON.stringify({ updatedAt: '2026-10-02T00:00:00Z', context: { lastMatchedPatterns: ['mem_b'] } })],+ ])+ const reads: string[] = []+ const fs = {+ read: async (path: string) => {+ reads.push(path)++ const text = files.get(path)++ if (text === undefined) throw new Error('missing')++ return text+ },+ stat: async (path: string) => (path.endsWith('patterns.json') ? { mtimeMs: 1, size: 3_919_854, kind: 'file' } : files.has(path) ? { mtimeMs: 1, size: files.get(path)?.length ?? 0, kind: 'file' } : undefined),+ list: async () => [{ name: 'session-1.json', kind: 'file', mtimeMs: 1 }, { name: 'session-2.json', kind: 'file', mtimeMs: 2 }, { name: 'current.json', kind: 'file', mtimeMs: 3 }],+ }+ const got = await readRecall(fs as never, new Map(), '/p')++ expect(got.ranked?.entries).toHaveLength(3)+ expect(got.sessions.map(session => session.ids[0])).toEqual(['mem_b', 'mem_a'])+ expect(got.prompts[0]?.task).toBe('t')+ expect(got.neural).toHaveLength(2)+ expect(got.reads).toMatchObject({ ranked: 'ok', neural: 'ok', bank: 'too-large' })+ expect(reads.some(path => path.endsWith('patterns.json') || path.endsWith('current.json'))).toBe(false)+ })++ it('never rejects when every file is missing', async () => {+ const fs = { read: async () => { throw new Error('x') }, stat: async () => { throw new Error('x') }, list: async () => { throw new Error('x') } }+ const got = await readRecall(fs as never, new Map(), '/none')++ expect(got).toMatchObject({ ranked: null, sessions: [], prompts: [], neural: null, reads: { ranked: 'missing', bank: 'missing' } })+ })+})diff --git a/v3/docs/adr/ADR-456-explain-recall-pattern-lifecycle.md b/v3/docs/adr/ADR-456-explain-recall-pattern-lifecycle.mdnew file mode 100644index 0000000000..8617c76f83--- /dev/null+++ b/v3/docs/adr/ADR-456-explain-recall-pattern-lifecycle.md@@ -0,0 +1,64 @@+# ADR 456: Explain a recall, and the pattern lifecycle, in the Learning Lab++Status: Accepted++Date: 2026-10-05++Builds on: ADR-404 (ruflo as a mod), ADR-444 (Claude controls the console), the Learning Lab (`views/neural.ts`)++## 1. Context++The Learning Lab says how much ruflo has learned (counts from `neural/stats.json`) but not what the intelligence hook actually pulled into a prompt, nor which stored patterns are earning their place. The request: pick a past prompt and see which memories and patterns it surfaced, with scores; and a lifecycle table (age, uses, last success, rank) with promote and prune as confirm-card commands.++The real sources were read before designing. They do not hold what the request assumes:++| Source | What it holds | Console can read it? |+|---|---|---|+| `.claude/helpers/intelligence.cjs` `getContext` | prints `[INTELLIGENCE] ... (score) summary [rank #n]` into the prompt; **writes only `context.lastMatchedPatterns` (ids)** to `.claude-flow/sessions/current.json`; each ended session's own `session-<ms>.json` keeps the same `context` | sessions: yes (small) |+| `.claude-flow/data/ranked-context.json` | the entries the hook recalls from: `summary`, `category`, `confidence`, `pageRank`, `accessCount`, `words` (no created or last-used time) | yes (1.2 MB) |+| `.claude-flow/routing-outcomes.json` | `task` text, agent, success, quality, timestamp: the only prompt-like text any hook file keeps | yes |+| `.claude-flow/neural/models.json` | the store `neural_patterns {action:delete}` and `neural_compress {method:prune}` act on: `id, name, type, content, metadata.verdict, createdAt, usageCount`; no confidence, no last-used time | yes (120 KB) |+| `.claude-flow/neural/patterns.json` | the ReasoningBank (`confidence`, `usageCount`, `lastUsedAt`, `metadata.success`) | **no: 3.9 MB here, over `READ_MAX` (2 MB)**; no per-pattern verb acts on it either |++Consequences that shape the decision:++1. The hook logs **neither the prompt nor the scores it surfaced**. "Which memories did this past prompt surface, with scores" cannot be read back; it can only be recomputed.+2. There are **three stores** and each verb touches exactly one: the hook recalls from `ranked-context.json` (derived from auto-memory), the neural verbs act on `models.json`, and `patterns.json` is a third the console cannot read. A prune button on a row must act on the file the row came from, so the lifecycle table is built from `models.json` only.+3. `usageCount` is 0 for every pattern in `models.json` on the reference machine; the table shows that rather than hide it.++## 2. Decision++**Explain a recall** (section in the Learning Lab, source `ranked-context.json`, `sessions/`, `routing-outcomes.json`):++- *Recorded*: the newest session's last recall, each id resolved against the ranked file to its summary (80 characters, the clip the hook itself prints into every prompt), category, confidence, pageRank, accessCount and the hook's own sort key (`0.6 pageRank + 0.4 confidence`, labelled "rank", not "match score"). Older sessions are listed as id counts with when they ended.+- *Recomputed*: pick one of the router's past task texts, or type a prompt, and the console re-scores it against today's ranked file with the hook's formula, copied (`tokenize`, trigrams, jaccard, `0.6 match + 0.4 pageRank`, threshold 0.05, top 5, the same stop words), showing the parts of each score. It is labelled "what would surface now: recomputed, not what surfaced then". A spec runs the real `intelligence.cjs` against a fixture and requires the same two-decimal scores, so drift in the copy is caught.++**Pattern lifecycle** (section, source `models.json`): a table of pattern id, type, age (`createdAt`), uses (`usageCount`), verdict (`metadata.verdict`: the verdict at creation, not "last success") and name, ordered most-used then oldest. Each row has promote and prune; one bulk row prunes the never-used.++- *Prune* (one): `neural_patterns {action:"delete", patternId}`. Deletes for good; the confirm card says so.+- *Prune* (bulk): `neural_compress {method:"prune", targetSize:1}`, which removes patterns with `usageCount` below 1. The label carries the count the file says now.+- *Promote*: ruflo has no verb that raises a stored pattern's rank in place. The documented promotion path is `agentdb_feedback {success:true, quality:0.95, patterns:[<its text>]}`, which (memory-bridge `bridgeRecordFeedback`) stores the text in the ReasoningBank and, because quality is at least 0.9, creates a reusable skill. It **adds**; the original row is unchanged. The note on the card says exactly that.+- All three are fixed argv through `mcp exec -p <one JSON element>` (no shell), ids are validated to `[A-Za-z0-9_-]{1,80}`, all are `writes` cost so they always ask first, and their ids start `nn-` so the Learning Lab's existing result panel shows them.++**Omitted, and why** (the rule: a field the files do not record is not drawn):++- *rank* and *last use* in the lifecycle table: `models.json` records neither. (`ranked-context` has a real rank, but those rows are a different store and a prune would not touch them.)+- *last success*: only a creation-time verdict is recorded, so the column is named "verdict".+- *the surfaced list of a past prompt*: not recorded; see section 1.+- *`patterns.json`*: not read (too large); the section says so and says no per-pattern verb acts on it.++## 3. Consequences++- The console learns four reads: `readRecall` (in `data/recall.ts`) reads the ranked file, `models.json`, `routing-outcomes.json` (all through the bounded, cached reader) and at most 8 newest `session-*.json` files (each capped at 100 KB, regular files only); it stats `patterns.json` and never reads it. Nothing is read from `current.json`, auto-memory content, or any key file.+- Summaries shown are at most 80 characters of what the hook already prints on every prompt. Words arrays stay in memory only for scoring; nothing is written anywhere.+- Mutations exist only as the three confirm-card commands above.+- The ranked file is parsed again only when its text changes.+- Known limits: the typed prompt is held in a view-local variable and redrawn with `act.refresh()` (the integrator may move it into `State`); the recorded recall is only each session's last one; the recompute reflects today's ranked file, not the file as it was.++## 4. Test and benchmark plan++`tests/recall.spec.ts` (pure, under a second): parsers on fixtures shaped like the real files with embeddings present; the scoring against hand-computed 0.6/0.4 weights; **parity with the real `intelligence.cjs` `getContext`** on the same fixture; argv for all three commands and their refusals (ids that are not safe, a pattern the store does not hold, an empty store); the rows' honest empty states (probe not wired, file missing or too large) and their notes about what is not recorded; the reader against a fake file system (newest sessions only, `patterns.json` and `current.json` never read, never rejects). Benchmark: scoring 239 entries of about 400 words each is a single pass of set intersections, in the same budget as the hook's own 15 ms.++## 5. Rollback++The three new files (`hooks/data/recall.ts`, `hooks/recall.ts`, `hooks/views/recall-rows.ts`) and the two `section` calls in `views/neural.ts` are the whole change; reverting the commit removes the feature. It adds no state, no stored files and no setting. Pruned patterns cannot be restored from the console: that is stated on each card.