π 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(cli): recall log in the intelligence hook and memory list --embeddings (ADR-472)
ruvb68ab59e6077
diff --git a/.claude/helpers/hook-handler.cjs b/.claude/helpers/hook-handler.cjsindex 3fda14ca1a..5677eab738 100755--- a/.claude/helpers/hook-handler.cjs+++ b/.claude/helpers/hook-handler.cjs@@ -379,14 +379,33 @@ async function main() {const handlers = {'route': () => {// Inject ranked intelligence context before routing- if (intelligence && intelligence.getContext) {+ // ADR-472: keep the detailed recall so ONE bounded log record (ids, scores, router pick; never the prompt) is appended after routing.+ let recall = null;+ if (intelligence && (intelligence.getContextDetailed || intelligence.getContext)) {try {- const ctx = intelligence.getContext(prompt);- if (ctx) console.log(ctx);+ if (intelligence.getContextDetailed) {+ recall = intelligence.getContextDetailed(prompt);+ if (recall && recall.text) console.log(recall.text);+ } else {+ const ctx = intelligence.getContext(prompt);+ if (ctx) console.log(ctx);+ }} catch (e) { /* non-fatal */ }}+ const logRecall = (result) => {+ try {+ if (recall && intelligence.appendRecall) {+ intelligence.appendRecall(recall, {+ sessionId: hookInput.session_id || hookInput.sessionId || null,+ agent: result && result.agent,+ confidence: result && result.confidence,+ });+ }+ } catch (e) { /* non-fatal: the log never blocks a prompt */ }+ };if (router && router.routeTask) {const result = router.routeTask(prompt);+ logRecall(result);// Format output for Claude Code hook consumption β real data onlyconst row = (text) => `| ${text.substring(0, 60).padEnd(60)} |`;const output = [@@ -400,6 +419,7 @@ const handlers = {];console.log(output.join('\n'));} else {+ logRecall(null);console.log('[INFO] Router not available, using default routing');}diff --git a/.claude/helpers/intelligence.cjs b/.claude/helpers/intelligence.cjsindex a9dbd6fc25..4c1e4d432b 100755--- a/.claude/helpers/intelligence.cjs+++ b/.claude/helpers/intelligence.cjs@@ -16,6 +16,7 @@const fs = require('fs');const path = require('path');+const crypto = require('crypto');function resolveProjectRoot(startDir) {if (process.env.CLAUDE_PROJECT_DIR) {@@ -39,6 +40,10 @@ const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');const GRAPH_PATH = path.join(DATA_DIR, 'graph-state.json');const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');+// ADR-472: bounded local log of WHICH ranked entries each recall surfaced (ids + scores; never the prompt text).+const RECALL_LOG_PATH = path.join(DATA_DIR, 'recall-log.jsonl');+const RECALL_LOG_MAX_BYTES = 1024 * 1024; // under the console's 2 MB read cap, so the log is readable when fullest+const RECALL_LOG_MAX_RECORDS = 1000;const LEGACY_PENDING_PATH = path.join(process.cwd(), '.claude-flow', 'data', 'pending-insights.jsonl');const SESSION_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'sessions');const SESSION_FILE = path.join(SESSION_DIR, 'current.json');@@ -595,11 +600,94 @@ function init() {};}+// ββ Recall log (ADR-472) βββββββββββββββββββββββββββββββββββββββββββββββββββββ+// One compact record per surfaced recall: when, which session, a one-way digest of the prompt, and the ids / scores /+// ranks the hook surfaced (plus the router's pick). Never the prompt text, never values. Local, bounded, fail-open.++/** First 16 hex characters of sha256(trimmed prompt): a join key, not a copy of the prompt. */+function promptDigest(prompt) {+ return crypto.createHash('sha256').update(String(prompt).trim()).digest('hex').slice(0, 16);+}++/** Ids and categories come from the user's own memory files; mask anything shaped like a credential before it is written. */+function maskToken(value, max) {+ return String(value == null ? '' : value)+ .replace(/[\u0000-\u001f\u007f]/g, ' ')+ .replace(/(?:sk-|ghp_|gho_|xox[abp]-|AKIA|eyJ)[A-Za-z0-9_\-]{8,}|[A-Za-z0-9+\/=_-]{40,}/g, '[masked]')+ .slice(0, max);+}++const OFF_RE = /^(0|false|off|no)$/i;++/** Default ON (local file, ids and scores only; routing-outcomes.json already keeps task text). Off by RUFLO_RECALL_LOG=0 or claude-flow.config.json {"recallLog":{"enabled":false}}. */+function recallLogEnabled() {+ const env = process.env.RUFLO_RECALL_LOG;+ if (env !== undefined && String(env).trim() !== '') return !OFF_RE.test(String(env).trim());+ try {+ const cfg = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, 'claude-flow.config.json'), 'utf-8'));+ if (cfg && cfg.recallLog && cfg.recallLog.enabled === false) return false;+ } catch { /* absent or malformed config = enabled */ }+ return true;+}++/** A record is at least ~140 bytes, so a file under this size cannot hold more than RECALL_LOG_MAX_RECORDS: no need to count lines. */+const RECALL_LOG_COUNT_FLOOR = 100 * 1024;++/** Keep the newest half when the log passes its byte or record cap. Rewrite through a temp file so a reader never sees half a file. */+function rotateRecallLog() {+ try {+ const stat = fs.statSync(RECALL_LOG_PATH);+ if (stat.size < RECALL_LOG_COUNT_FLOOR) return;+ const lines = fs.readFileSync(RECALL_LOG_PATH, 'utf-8').split('\n').filter(Boolean);+ if (stat.size <= RECALL_LOG_MAX_BYTES && lines.length <= RECALL_LOG_MAX_RECORDS) return;+ // Newest first until half of either cap is reached.+ const keep = [];+ let bytes = 0;+ for (let i = lines.length - 1; i >= 0 && keep.length < RECALL_LOG_MAX_RECORDS / 2; i--) {+ bytes += lines[i].length + 1;+ if (bytes > RECALL_LOG_MAX_BYTES / 2) break;+ keep.unshift(lines[i]);+ }+ const tmp = RECALL_LOG_PATH + '.' + process.pid + '.tmp';+ fs.writeFileSync(tmp, keep.join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });+ fs.renameSync(tmp, RECALL_LOG_PATH);+ } catch { /* best effort */ }+}++/**+ * appendRecall(detailed, meta) β one JSONL record for a recall getContextDetailed returned. meta: { sessionId, agent, confidence }.+ * Returns true when a record was written. Never throws and never blocks the hook.+ */+function appendRecall(detailed, meta) {+ try {+ if (!detailed || !Array.isArray(detailed.surfaced) || detailed.surfaced.length === 0) return false;+ if (!recallLogEnabled()) return false;+ const m = meta || {};+ const record = {+ v: 1,+ at: Date.now(),+ sid: m.sessionId ? maskToken(m.sessionId, 64) : null,+ digest: detailed.digest,+ surfaced: detailed.surfaced.slice(0, 10).map((e) => ({+ id: maskToken(e.id, 80),+ score: Math.round((e.score || 0) * 10000) / 10000,+ rank: e.rank,+ cat: maskToken(e.category, 40),+ })),+ };+ if (m.agent) record.router = { agent: maskToken(m.agent, 30), confidence: typeof m.confidence === 'number' ? Math.round(m.confidence * 1000) / 1000 : null };+ ensureDataDir();+ rotateRecallLog();+ fs.appendFileSync(RECALL_LOG_PATH, JSON.stringify(record) + '\n', { encoding: 'utf-8', mode: 0o600 });+ return true;+ } catch { return false; }+}+/*** getContext(prompt) β Called from route. Budget: <15ms.* Matches prompt to ranked entries, returns top-5 formatted context.*/-function getContext(prompt) {+function getContextDetailed(prompt) {if (!prompt) return null;const ranked = readJSON(RANKED_PATH);@@ -653,7 +741,17 @@ function getContext(prompt) {lines.push(` * (${e.score.toFixed(2)}) ${display} [rank #${i + 1}, ${accessed}x accessed]`);}- return lines.join('\n');+ return {+ text: lines.join('\n'),+ digest: promptDigest(prompt),+ surfaced: topEntries.map((e, i) => ({ id: e.id, score: e.score, rank: i + 1, category: e.category || '' })),+ };+}++/** The context text the hook prints, or null. Thin wrapper over getContextDetailed (callers that only print keep working). */+function getContext(prompt) {+ const detailed = getContextDetailed(prompt);+ return detailed ? detailed.text : null;}/**@@ -1137,6 +1235,10 @@ function stats(outputJson) {module.exports = {init,getContext,+ getContextDetailed,+ appendRecall,+ recallLogEnabled,+ promptDigest,recordEdit,feedback,consolidate,diff --git a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjsindex 3fda14ca1a..5677eab738 100755--- a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs+++ b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs@@ -379,14 +379,33 @@ async function main() {const handlers = {'route': () => {// Inject ranked intelligence context before routing- if (intelligence && intelligence.getContext) {+ // ADR-472: keep the detailed recall so ONE bounded log record (ids, scores, router pick; never the prompt) is appended after routing.+ let recall = null;+ if (intelligence && (intelligence.getContextDetailed || intelligence.getContext)) {try {- const ctx = intelligence.getContext(prompt);- if (ctx) console.log(ctx);+ if (intelligence.getContextDetailed) {+ recall = intelligence.getContextDetailed(prompt);+ if (recall && recall.text) console.log(recall.text);+ } else {+ const ctx = intelligence.getContext(prompt);+ if (ctx) console.log(ctx);+ }} catch (e) { /* non-fatal */ }}+ const logRecall = (result) => {+ try {+ if (recall && intelligence.appendRecall) {+ intelligence.appendRecall(recall, {+ sessionId: hookInput.session_id || hookInput.sessionId || null,+ agent: result && result.agent,+ confidence: result && result.confidence,+ });+ }+ } catch (e) { /* non-fatal: the log never blocks a prompt */ }+ };if (router && router.routeTask) {const result = router.routeTask(prompt);+ logRecall(result);// Format output for Claude Code hook consumption β real data onlyconst row = (text) => `| ${text.substring(0, 60).padEnd(60)} |`;const output = [@@ -400,6 +419,7 @@ const handlers = {];console.log(output.join('\n'));} else {+ logRecall(null);console.log('[INFO] Router not available, using default routing');}diff --git a/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs b/v3/@claude-flow/cli/.claude/helpers/intelligence.cjsindex a9dbd6fc25..4c1e4d432b 100755--- a/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs+++ b/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs@@ -16,6 +16,7 @@const fs = require('fs');const path = require('path');+const crypto = require('crypto');function resolveProjectRoot(startDir) {if (process.env.CLAUDE_PROJECT_DIR) {@@ -39,6 +40,10 @@ const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');const GRAPH_PATH = path.join(DATA_DIR, 'graph-state.json');const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');+// ADR-472: bounded local log of WHICH ranked entries each recall surfaced (ids + scores; never the prompt text).+const RECALL_LOG_PATH = path.join(DATA_DIR, 'recall-log.jsonl');+const RECALL_LOG_MAX_BYTES = 1024 * 1024; // under the console's 2 MB read cap, so the log is readable when fullest+const RECALL_LOG_MAX_RECORDS = 1000;const LEGACY_PENDING_PATH = path.join(process.cwd(), '.claude-flow', 'data', 'pending-insights.jsonl');const SESSION_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'sessions');const SESSION_FILE = path.join(SESSION_DIR, 'current.json');@@ -595,11 +600,94 @@ function init() {};}+// ββ Recall log (ADR-472) βββββββββββββββββββββββββββββββββββββββββββββββββββββ+// One compact record per surfaced recall: when, which session, a one-way digest of the prompt, and the ids / scores /+// ranks the hook surfaced (plus the router's pick). Never the prompt text, never values. Local, bounded, fail-open.++/** First 16 hex characters of sha256(trimmed prompt): a join key, not a copy of the prompt. */+function promptDigest(prompt) {+ return crypto.createHash('sha256').update(String(prompt).trim()).digest('hex').slice(0, 16);+}++/** Ids and categories come from the user's own memory files; mask anything shaped like a credential before it is written. */+function maskToken(value, max) {+ return String(value == null ? '' : value)+ .replace(/[\u0000-\u001f\u007f]/g, ' ')+ .replace(/(?:sk-|ghp_|gho_|xox[abp]-|AKIA|eyJ)[A-Za-z0-9_\-]{8,}|[A-Za-z0-9+\/=_-]{40,}/g, '[masked]')+ .slice(0, max);+}++const OFF_RE = /^(0|false|off|no)$/i;++/** Default ON (local file, ids and scores only; routing-outcomes.json already keeps task text). Off by RUFLO_RECALL_LOG=0 or claude-flow.config.json {"recallLog":{"enabled":false}}. */+function recallLogEnabled() {+ const env = process.env.RUFLO_RECALL_LOG;+ if (env !== undefined && String(env).trim() !== '') return !OFF_RE.test(String(env).trim());+ try {+ const cfg = JSON.parse(fs.readFileSync(path.join(PROJECT_ROOT, 'claude-flow.config.json'), 'utf-8'));+ if (cfg && cfg.recallLog && cfg.recallLog.enabled === false) return false;+ } catch { /* absent or malformed config = enabled */ }+ return true;+}++/** A record is at least ~140 bytes, so a file under this size cannot hold more than RECALL_LOG_MAX_RECORDS: no need to count lines. */+const RECALL_LOG_COUNT_FLOOR = 100 * 1024;++/** Keep the newest half when the log passes its byte or record cap. Rewrite through a temp file so a reader never sees half a file. */+function rotateRecallLog() {+ try {+ const stat = fs.statSync(RECALL_LOG_PATH);+ if (stat.size < RECALL_LOG_COUNT_FLOOR) return;+ const lines = fs.readFileSync(RECALL_LOG_PATH, 'utf-8').split('\n').filter(Boolean);+ if (stat.size <= RECALL_LOG_MAX_BYTES && lines.length <= RECALL_LOG_MAX_RECORDS) return;+ // Newest first until half of either cap is reached.+ const keep = [];+ let bytes = 0;+ for (let i = lines.length - 1; i >= 0 && keep.length < RECALL_LOG_MAX_RECORDS / 2; i--) {+ bytes += lines[i].length + 1;+ if (bytes > RECALL_LOG_MAX_BYTES / 2) break;+ keep.unshift(lines[i]);+ }+ const tmp = RECALL_LOG_PATH + '.' + process.pid + '.tmp';+ fs.writeFileSync(tmp, keep.join('\n') + '\n', { encoding: 'utf-8', mode: 0o600 });+ fs.renameSync(tmp, RECALL_LOG_PATH);+ } catch { /* best effort */ }+}++/**+ * appendRecall(detailed, meta) β one JSONL record for a recall getContextDetailed returned. meta: { sessionId, agent, confidence }.+ * Returns true when a record was written. Never throws and never blocks the hook.+ */+function appendRecall(detailed, meta) {+ try {+ if (!detailed || !Array.isArray(detailed.surfaced) || detailed.surfaced.length === 0) return false;+ if (!recallLogEnabled()) return false;+ const m = meta || {};+ const record = {+ v: 1,+ at: Date.now(),+ sid: m.sessionId ? maskToken(m.sessionId, 64) : null,+ digest: detailed.digest,+ surfaced: detailed.surfaced.slice(0, 10).map((e) => ({+ id: maskToken(e.id, 80),+ score: Math.round((e.score || 0) * 10000) / 10000,+ rank: e.rank,+ cat: maskToken(e.category, 40),+ })),+ };+ if (m.agent) record.router = { agent: maskToken(m.agent, 30), confidence: typeof m.confidence === 'number' ? Math.round(m.confidence * 1000) / 1000 : null };+ ensureDataDir();+ rotateRecallLog();+ fs.appendFileSync(RECALL_LOG_PATH, JSON.stringify(record) + '\n', { encoding: 'utf-8', mode: 0o600 });+ return true;+ } catch { return false; }+}+/*** getContext(prompt) β Called from route. Budget: <15ms.* Matches prompt to ranked entries, returns top-5 formatted context.*/-function getContext(prompt) {+function getContextDetailed(prompt) {if (!prompt) return null;const ranked = readJSON(RANKED_PATH);@@ -653,7 +741,17 @@ function getContext(prompt) {lines.push(` * (${e.score.toFixed(2)}) ${display} [rank #${i + 1}, ${accessed}x accessed]`);}- return lines.join('\n');+ return {+ text: lines.join('\n'),+ digest: promptDigest(prompt),+ surfaced: topEntries.map((e, i) => ({ id: e.id, score: e.score, rank: i + 1, category: e.category || '' })),+ };+}++/** The context text the hook prints, or null. Thin wrapper over getContextDetailed (callers that only print keep working). */+function getContext(prompt) {+ const detailed = getContextDetailed(prompt);+ return detailed ? detailed.text : null;}/**@@ -1137,6 +1235,10 @@ function stats(outputJson) {module.exports = {init,getContext,+ getContextDetailed,+ appendRecall,+ recallLogEnabled,+ promptDigest,recordEdit,feedback,consolidate,diff --git a/v3/@claude-flow/cli/__tests__/adr-472-memory-list-embeddings.test.ts b/v3/@claude-flow/cli/__tests__/adr-472-memory-list-embeddings.test.tsnew file mode 100644index 0000000000..fb5e8a6105--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/adr-472-memory-list-embeddings.test.ts@@ -0,0 +1,114 @@+/**+ * ADR-472: `memory list --embeddings` (listEntries includeEmbedding) emits each stored vector as int8 + scale, read-only and bounded.+ */+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { encodeEmbeddingQ8, MAX_EMBEDDING_DIMS, MAX_LIST_EMBEDDINGS } from '../src/memory/embedding-q8.js';++// The command module pulls in the MCP tool graph, whose password hasher needs a native dep a bare worktree may lack; the list action needs none of it.+vi.mock('bcryptjs', () => ({}));++const decode = (q: { dims: number; scale: number; b64: string }): number[] => Array.from(new Int8Array(Buffer.from(q.b64, 'base64'))).map(v => v * q.scale);+const cosine = (a: number[], b: number[]): number => {+ let dot = 0, na = 0, nb = 0;+ for (let i = 0; i < a.length; i++) { dot += a[i]! * b[i]!; na += a[i]! ** 2; nb += b[i]! ** 2; }+ return dot / Math.sqrt(na * nb);+};+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((s, x) => s + x * x, 0));+ return v.map(x => x / norm);+};++describe('encodeEmbeddingQ8', () => {+ it('round-trips a 384-dim unit vector at cosine > 0.9999 in ~1/4 the bytes of 4-decimal JSON', () => {+ const v = unit(384, 3);+ const q = encodeEmbeddingQ8(JSON.stringify(v))!;++ expect(q.dims).toBe(384);+ expect(cosine(decode(q), v)).toBeGreaterThan(0.9999);+ expect(q.b64.length).toBeLessThan(JSON.stringify(v.map(x => Number(x.toFixed(4)))).length / 3);+ });++ it('accepts an already-parsed array and refuses anything it cannot encode faithfully', () => {+ expect(encodeEmbeddingQ8([0.5, -0.5])?.dims).toBe(2);+ for (const bad of [null, undefined, '', 'not json', '{"a":1}', '[1]', '[0,0,0]', '[1,"x"]', '[1,null,2]', `[${Array(MAX_EMBEDDING_DIMS + 1).fill(0.1).join(',')}]`, 7]) {+ expect(encodeEmbeddingQ8(bad), String(bad).slice(0, 20)).toBeUndefined();+ }+ expect(encodeEmbeddingQ8('[1e999,1]')).toBeUndefined();+ });+});++describe('listEntries includeEmbedding (sql.js path, fixture store)', () => {+ let root: string;+ const saved = { path: process.env.CLAUDE_FLOW_MEMORY_PATH, bridge: process.env.CLAUDE_FLOW_DISABLE_BRIDGE };++ beforeEach(() => {+ root = mkdtempSync(path.join(tmpdir(), 'ruflo-472-list-'));+ process.env.CLAUDE_FLOW_MEMORY_PATH = root;+ process.env.CLAUDE_FLOW_DISABLE_BRIDGE = '1';+ vi.resetModules();+ });++ afterEach(() => {+ vi.resetModules();+ if (saved.path === undefined) delete process.env.CLAUDE_FLOW_MEMORY_PATH; else process.env.CLAUDE_FLOW_MEMORY_PATH = saved.path;+ if (saved.bridge === undefined) delete process.env.CLAUDE_FLOW_DISABLE_BRIDGE; else process.env.CLAUDE_FLOW_DISABLE_BRIDGE = saved.bridge;+ rmSync(root, { recursive: true, force: true });+ });++ it('adds embeddingQ8 only when asked, never content, never writes the store, and caps the rows', async () => {+ const memory = await import('../src/memory/memory-initializer.js');++ expect((await memory.initializeMemoryDatabase({ force: true, migrate: false })).success).toBe(true);+ for (const key of ['alpha', 'beta', 'gamma']) expect((await memory.storeEntry({ key, namespace: 'n', value: `value for ${key}`, generateEmbeddingFlag: true } as never)).success).toBe(true);++ const dbPath = memory.resolveDbPath(undefined);+ const before = readFileSync(dbPath);+ const plain = await memory.listEntries({ limit: 10, dbPath });+ const withVectors = await memory.listEntries({ limit: 10, dbPath, includeEmbedding: true });++ expect(plain.entries.every(e => e.embeddingQ8 === undefined)).toBe(true);+ expect(withVectors.entries.length).toBe(plain.entries.length);+ expect(withVectors.entries.every(e => e.content === undefined)).toBe(true);++ const embedded = withVectors.entries.filter(e => e.hasEmbedding);++ expect(embedded.length).toBeGreaterThan(0);+ expect(embedded.every(e => e.embeddingQ8 !== undefined && e.embeddingQ8.dims > 1)).toBe(true);+ expect(withVectors.entries.filter(e => !e.hasEmbedding).every(e => e.embeddingQ8 === undefined)).toBe(true);+ expect(statSync(dbPath).size).toBe(before.length);+ expect(MAX_LIST_EMBEDDINGS).toBe(500);++ const capped = await memory.listEntries({ limit: 100_000, dbPath, includeEmbedding: true });++ expect(capped.entries.length).toBeLessThanOrEqual(MAX_LIST_EMBEDDINGS);+ });++ it('the `memory list --format json --embeddings` command prints embeddingQ8, and without the flag it does not', async () => {+ const memory = await import('../src/memory/memory-initializer.js');+ const { output } = await import('../src/output.js');+ const { memoryCommand } = await import('../src/commands/memory.js');+ const list = memoryCommand.subcommands!.find(c => c.name === 'list')!;+ const printed: unknown[] = [];+ const spy = vi.spyOn(output, 'printJson').mockImplementation((value: unknown) => { printed.push(value); });++ await memory.initializeMemoryDatabase({ force: true, migrate: false });+ await memory.storeEntry({ key: 'k1', namespace: 'n', value: 'some value', generateEmbeddingFlag: true } as never);++ const run = (flags: Record<string, unknown>) => list.action!({ args: [], flags: { format: 'json', limit: 20, ...flags }, cwd: root } as never);++ await run({});+ await run({ embeddings: true });+ await run({ embeddings: true, format: 'table' });+ spy.mockRestore();++ const [without, withVec] = printed as { embeddingQ8?: { dims: number } }[][];++ expect(without?.every(e => e.embeddingQ8 === undefined)).toBe(true);+ expect(withVec?.[0]?.embeddingQ8?.dims).toBeGreaterThan(1);+ expect(printed).toHaveLength(2);+ });+});diff --git a/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts b/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.tsnew file mode 100644index 0000000000..7b14891fd3--- /dev/null+++ b/v3/@claude-flow/cli/__tests__/adr-472-recall-log.test.ts@@ -0,0 +1,144 @@+/**+ * ADR-472: the intelligence hook logs WHICH ranked entries each recall surfaced (ids, scores, ranks, the router's pick),+ * keyed by a one-way digest of the prompt. These tests run the real shipped helpers in a throwaway project.+ */+import { createHash } from 'node:crypto';+import { execFileSync } from 'node:child_process';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { afterEach, beforeEach, describe, expect, it } from 'vitest';++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 SECRET_ID = 'mem-sk-abcdefghijklmnopqrstuvwxyz0123456789ABCDEF-token';++let root: string;+const logPath = () => join(root, '.claude-flow', 'data', 'recall-log.jsonl');+const records = () => readFileSync(logPath(), 'utf-8').split('\n').filter(Boolean).map(line => JSON.parse(line) as Record<string, any>);++const entry = (id: string, summary: string, words: string[], pageRank: number) => ({ id, summary, content: summary, category: 'project_notes', confidence: 0.8, pageRank, accessCount: 2, words });++beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), 'ruflo-472-'));+ mkdirSync(join(root, '.claude-flow', 'data'), { recursive: true });+ writeFileSync(+ join(root, '.claude-flow', 'data', 'ranked-context.json'),+ JSON.stringify({+ computedAt: new Date().toISOString(),+ 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('mem-unrelated-3', 'Cooking notes', ['pasta', 'tomato'], 0.0),+ ],+ }),+ );+});++afterEach(() => rmSync(root, { recursive: true, force: true }));++const runIntel = (code: string, env: Record<string, string> = {}) =>+ execFileSync(process.execPath, ['-e', `const i=require(${JSON.stringify(INTEL)});${code}`], { cwd: root, env: { ...process.env, CLAUDE_PROJECT_DIR: root, ...env }, encoding: 'utf-8' });++const recallCode = (meta = '{}') => `const d=i.getContextDetailed(${JSON.stringify(PROMPT)});console.log(JSON.stringify({wrote:i.appendRecall(d,${meta}),text:d&&d.text}))`;++describe('ADR-472 recall log', () => {+ it('appends one record with ids, scores, ranks, router pick and a digest, and never the prompt text', () => {+ const out = JSON.parse(runIntel(recallCode('{sessionId:"sess-1",agent:"coder",confidence:0.8123456}')));+ const [record] = records();++ expect(out.wrote).toBe(true)+ expect(records()).toHaveLength(1)+ 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[0].id).toBe('mem-swarm-planner-1')+ expect(record?.surfaced[0].score).toBeGreaterThan(0.05)+ expect(record?.router).toEqual({ agent: 'coder', confidence: 0.812 })+ expect(record?.at).toBeGreaterThan(1_700_000_000_000)++ const raw = readFileSync(logPath(), 'utf-8');++ for (const word of ['refactor', 'zebra', 'coordination planner', 'Swarm coordination planner notes']) expect(raw).not.toContain(word);+ });++ it('masks a credential-shaped id and writes null for a missing session id', () => {+ runIntel(recallCode());+ const raw = readFileSync(logPath(), 'utf-8');++ expect(raw).not.toContain('sk-abcdefghijklmnop');+ expect(raw).toContain('[masked]');+ expect(records()[0]?.sid).toBeNull();+ expect(records()[0]?.router).toBeUndefined();+ });++ it('leaves getContext printing exactly the text getContextDetailed returns', () => {+ const detailed = JSON.parse(runIntel(recallCode())).text;+ const plain = runIntel(`console.log(JSON.stringify(i.getContext(${JSON.stringify(PROMPT)})))`);++ expect(JSON.parse(plain)).toBe(detailed);+ });++ it('is off with RUFLO_RECALL_LOG=0 and with recallLog.enabled=false in claude-flow.config.json, on otherwise', () => {+ expect(JSON.parse(runIntel(recallCode(), { RUFLO_RECALL_LOG: '0' })).wrote).toBe(false);+ expect(existsSync(logPath())).toBe(false);++ writeFileSync(join(root, 'claude-flow.config.json'), JSON.stringify({ recallLog: { enabled: false } }));+ expect(JSON.parse(runIntel(recallCode())).wrote).toBe(false);+ expect(existsSync(logPath())).toBe(false);+ // the env var wins over the file: an explicit "on" re-enables it+ expect(JSON.parse(runIntel(recallCode(), { RUFLO_RECALL_LOG: '1' })).wrote).toBe(true);++ rmSync(join(root, 'claude-flow.config.json'));+ rmSync(logPath());+ expect(JSON.parse(runIntel(recallCode())).wrote).toBe(true);+ });++ it('writes nothing when nothing surfaced, and never throws on a bad record', () => {+ const out = runIntel(`console.log(JSON.stringify([i.appendRecall(null,{}),i.appendRecall({surfaced:[]},{}),i.appendRecall({surfaced:[{id:null,score:NaN,rank:1}],digest:'d'},{})]))`);++ expect(JSON.parse(out)).toEqual([false, false, true]);+ expect(records()).toHaveLength(1);+ });++ it('rotates by record count: past the cap the newest half is kept', () => {+ const line = (n: number) => JSON.stringify({ v: 1, at: 1_800_000_000_000 + n, sid: null, digest: `d${n}`, surfaced: [{ id: `x${n}`, score: 0.5, rank: 1, cat: 'c' }] });++ writeFileSync(logPath(), Array.from({ length: 1100 }, (_, n) => line(n)).join('\n') + '\n');+ runIntel(recallCode());+ const kept = records();++ expect(kept.length).toBeLessThanOrEqual(501);+ expect(kept.length).toBeGreaterThan(400);+ expect(kept[0]?.digest).toBe('d600');+ expect(kept.at(-1)?.surfaced[0].id).toBe('mem-swarm-planner-1');+ });++ it('rotates by bytes too: a log over 1 MB is cut', () => {+ const fat = JSON.stringify({ v: 1, at: 1, sid: null, digest: 'f', surfaced: [{ id: 'y'.repeat(70), score: 0.1, rank: 1, cat: 'c'.repeat(40) }], pad: 'p'.repeat(5000) });++ writeFileSync(logPath(), Array.from({ length: 300 }, () => fat).join('\n') + '\n');+ runIntel(recallCode());+ expect(readFileSync(logPath(), 'utf-8').length).toBeLessThan(1024 * 1024);+ expect(records().length).toBeLessThanOrEqual(501);+ });++ it('hook-handler route: one record per prompt with the stdin session id and the router pick; the printed context is unchanged', () => {+ const run = (env: Record<string, string> = {}) =>+ execFileSync(process.execPath, [HANDLER, 'route'], { cwd: root, input: JSON.stringify({ prompt: PROMPT, session_id: 'abc-123' }), env: { ...process.env, CLAUDE_PROJECT_DIR: root, RUFLO_FUNNEL: '0', RUFLO_MODS_OWNS: '', ...env }, encoding: 'utf-8' });+ const out = run();++ expect(out).toContain('[INTELLIGENCE] Relevant patterns for this task:');+ expect(records()).toHaveLength(1);+ expect(records()[0]?.sid).toBe('abc-123');+ expect(typeof records()[0]?.router?.agent).toBe('string');++ const off = run({ RUFLO_RECALL_LOG: 'off' });++ expect(off).toContain('[INTELLIGENCE]');+ expect(records()).toHaveLength(1);+ });+});diff --git a/v3/@claude-flow/cli/src/commands/memory.ts b/v3/@claude-flow/cli/src/commands/memory.tsindex 4c9aa1e6c9..fadfbfe7a6 100644--- a/v3/@claude-flow/cli/src/commands/memory.ts+++ b/v3/@claude-flow/cli/src/commands/memory.ts@@ -11,6 +11,7 @@ import { distillCommand } from './memory-distill.js';import { backupCommand } from './memory-backup.js';import { countSiblingStoreRows } from '../memory/sibling-store.js';import { resolveDbPath } from '../memory/memory-initializer.js';+import { MAX_LIST_EMBEDDINGS } from '../memory/embedding-q8.js';import { existsSync } from 'node:fs';import { siblingAgentDbPath } from '../memory/memory-bridge.js';import { validateIdentifier } from '../mcp-tools/validate-input.js';@@ -828,17 +829,24 @@ const listCommand: Command = {type: 'number',default: 20},+ {+ name: 'embeddings',+ description: `ADR-472: with --format json, add each entry's stored embedding as int8+scale (embeddingQ8: {dims, scale, b64}); read-only, at most ${MAX_LIST_EMBEDDINGS} entries per call`,+ type: 'boolean',+ default: false+ },DB_PATH_OPTION],action: async (ctx: CommandContext): Promise<CommandResult> => {const namespace = ctx.flags.namespace as string;const limit = ctx.flags.limit as number;+ const includeEmbedding = ctx.flags.embeddings === true && ctx.flags.format === 'json';// Use sql.js directly for consistent data accesstry {const { listEntries, resolveDbPath: _rdbList } = await import('../memory/memory-initializer.js');const dbPathList = _rdbList(ctx.flags.path as string | undefined);- const listResult = await listEntries({ namespace, limit, offset: 0, dbPath: dbPathList });+ const listResult = await listEntries({ namespace, limit, offset: 0, dbPath: dbPathList, ...(includeEmbedding && { includeEmbedding: true }) });if (!listResult.success) {output.printError(`Failed to list: ${listResult.error}`);diff --git a/v3/@claude-flow/cli/src/memory/embedding-q8.ts b/v3/@claude-flow/cli/src/memory/embedding-q8.tsnew file mode 100644index 0000000000..c6aef5b39c--- /dev/null+++ b/v3/@claude-flow/cli/src/memory/embedding-q8.ts@@ -0,0 +1,37 @@+/**+ * ADR-472: a stored embedding as int8 + scale, for `memory list --embeddings`. Pure; no store access.+ */++/** Most embeddings `memory list --embeddings` will emit per call, and the longest vector it will encode. */+export const MAX_LIST_EMBEDDINGS = 500;+export const MAX_EMBEDDING_DIMS = 4096;++/** A stored embedding as int8 with one scale, base64: ~1/4 the bytes of rounded JSON floats, enough for a 2D projection or a cosine screen. */+export type EmbeddingQ8 = { dims: number; scale: number; b64: string };++/**+ * Read-only view of a stored embedding (a JSON array in the `embedding` column) as int8 + scale. Returns undefined for a missing,+ * malformed, non-finite, constant-zero or over-long vector, so a caller never gets a guessed one. Each value is within scale/2 of the+ * original (scale = max|v| / 127); cosine against the original stays above 0.9999 for unit-scale text embeddings.+ */+export function encodeEmbeddingQ8(stored: unknown): EmbeddingQ8 | undefined {+ if (stored === null || stored === undefined) return undefined;+ let values: unknown;+ try {+ values = typeof stored === 'string' ? JSON.parse(stored) : stored;+ } catch {+ return undefined;+ }+ if (!Array.isArray(values) || values.length < 2 || values.length > MAX_EMBEDDING_DIMS) return undefined;+ let max = 0;+ for (const v of values) {+ if (typeof v !== 'number' || !Number.isFinite(v)) return undefined;+ max = Math.max(max, Math.abs(v));+ }+ if (max === 0) return undefined;+ const scale = max / 127;+ const bytes = new Int8Array(values.length);+ for (let i = 0; i < values.length; i++) bytes[i] = Math.max(-127, Math.min(127, Math.round((values[i] as number) / scale)));+ return { dims: values.length, scale: Number(scale.toPrecision(6)), b64: Buffer.from(bytes.buffer).toString('base64') };+}+diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.tsindex df0252ca75..22f6d090f2 100644--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts@@ -18,6 +18,7 @@*/import { liveMemoryRowSql } from './live-memory-row.js';+import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';import * as path from 'path';import * as crypto from 'crypto';import { realpathSync } from 'node:fs';@@ -1495,6 +1496,8 @@ export async function bridgeListEntries(options: {includeContent?: boolean;/** ADR-323: restrict rows to these provenance types. */provenanceFilter?: string[];+ /** ADR-472: include each entry's embedding as int8+scale (`embeddingQ8`); at most MAX_LIST_EMBEDDINGS rows. */+ includeEmbedding?: boolean;}): Promise<{success: boolean;entries: {@@ -1509,6 +1512,7 @@ export async function bridgeListEntries(options: {/** #2073: Present when `includeContent: true` was requested. */content?: string;provenanceType?: string;+ embeddingQ8?: { dims: number; scale: number; b64: string };}[];total: number;error?: string;@@ -1568,7 +1572,7 @@ export async function bridgeListEntries(options: {ORDER BY updated_at DESCLIMIT ? OFFSET ?`);- const rows = stmt.all(...filterParams, limit, offset);+ const rows = stmt.all(...filterParams, options.includeEmbedding ? Math.min(limit, MAX_LIST_EMBEDDINGS) : limit, offset);for (const row of rows) {const entry: Record<string, unknown> = {// #2073: don't truncate id when content is requested β callers@@ -1586,6 +1590,10 @@ export async function bridgeListEntries(options: {if (options.includeContent) {entry.content = row.content || '';}+ if (options.includeEmbedding) {+ const q8 = encodeEmbeddingQ8(row.embedding);+ if (q8) entry.embeddingQ8 = q8;+ }entries.push(entry);}} catch {diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.tsindex a2600fd649..c017a16dd7 100644--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts@@ -10,6 +10,7 @@*/import { liveMemoryRowSql } from './live-memory-row.js';+import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS, type EmbeddingQ8 } from './embedding-q8.js';import * as fs from 'fs';import * as path from 'path';import { AsyncLocalStorage } from 'node:async_hooks';@@ -3424,6 +3425,8 @@ export async function listEntries(options: {includeContent?: boolean;/** ADR-323: restrict rows to these provenance types. */provenanceFilter?: string[];+ /** ADR-472: include each entry's embedding as int8+scale (`embeddingQ8`); at most MAX_LIST_EMBEDDINGS rows. Read-only. */+ includeEmbedding?: boolean;}): Promise<{success: boolean;entries: {@@ -3438,6 +3441,8 @@ export async function listEntries(options: {/** #2073: Present when `includeContent: true` was requested. */content?: string;provenanceType?: string;+ /** ADR-472: present when `includeEmbedding: true` and the row has a valid stored vector. */+ embeddingQ8?: EmbeddingQ8;}[];total: number;error?: string;@@ -3520,7 +3525,7 @@ export async function listEntries(options: {const total = countResult[0]?.values?.[0]?.[0] as number || 0;// Get entries- const safeLimit = parseInt(String(limit), 10) || 100;+ const safeLimit = Math.min(parseInt(String(limit), 10) || 100, options.includeEmbedding ? MAX_LIST_EMBEDDINGS : Number.MAX_SAFE_INTEGER);const safeOffset = parseInt(String(offset), 10) || 0;// #2120 β same NULL-as-active acceptance as the count above.const listStmt = db.prepare(@@ -3546,6 +3551,7 @@ export async function listEntries(options: {hasEmbedding: boolean;content?: string;provenanceType?: string;+ embeddingQ8?: EmbeddingQ8;}[] = [];if (result[0]?.values) {@@ -3564,6 +3570,7 @@ export async function listEntries(options: {hasEmbedding: boolean;content?: string;provenanceType?: string;+ embeddingQ8?: EmbeddingQ8;} = {// #2073: don't truncate id when content is requested β callers// (notably memory_export) need the full id to round-trip via import.@@ -3580,6 +3587,10 @@ export async function listEntries(options: {if (options.includeContent) {entry.content = content || '';}+ if (options.includeEmbedding) {+ const q8 = encodeEmbeddingQ8(embedding);+ if (q8) entry.embeddingQ8 = q8;+ }entries.push(entry);}}