Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(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.cjs
index 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 only
const 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.cjs
index 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.cjs
index 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 only
const 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.cjs
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 access
try {
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.ts
new file mode 100644
index 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.ts
index 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 DESC
LIMIT ? 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.ts
index 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);
}
}