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(memory): typed provenance in AgentDB (ADR-323, corrects dream-cycle #2804) (#2820)

rUvfac48c7b767a
diff --git a/v3/@claude-flow/cli-core/src/mcp-tools/memory-defs.ts b/v3/@claude-flow/cli-core/src/mcp-tools/memory-defs.ts
index 5f0887dd09..170e4ba268 100644
--- a/v3/@claude-flow/cli-core/src/mcp-tools/memory-defs.ts
+++ b/v3/@claude-flow/cli-core/src/mcp-tools/memory-defs.ts
@@ -39,6 +39,11 @@ export const memoryToolDefs: MCPToolDef[] = [
tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for filtering' },
ttl: { type: 'number', description: 'Time-to-live in seconds (optional)' },
upsert: { type: 'boolean', description: 'If true, update existing key instead of failing (default: false)' },
+ provenance_type: {
+ type: 'string',
+ enum: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'],
+ description: 'ADR-323: who/what produced this value, so shared-namespace retrieval can filter by trust level. Default: "unknown".',
+ },
},
required: ['key', 'value'],
},
@@ -70,6 +75,11 @@ export const memoryToolDefs: MCPToolDef[] = [
limit: { type: 'number', description: 'Maximum results (default: 10)' },
threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.3)' },
smart: { type: 'boolean', description: 'Enable SmartRetrieval pipeline β€” query expansion, RRF fusion, recency boost, MMR diversity (default: false). No-op in cli-core lite backend.' },
+ provenance_filter: {
+ type: 'array',
+ items: { type: 'string', enum: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'] },
+ description: 'ADR-323: restrict results to these provenance types. Omit for no filtering.',
+ },
},
required: ['query'],
},
diff --git a/v3/@claude-flow/cli/__tests__/adr-323-memory-provenance.test.ts b/v3/@claude-flow/cli/__tests__/adr-323-memory-provenance.test.ts
new file mode 100644
index 0000000000..9af06ec68b
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/adr-323-memory-provenance.test.ts
@@ -0,0 +1,169 @@
+/**
+ * ADR-323 β€” typed memory provenance. Regression guard for the
+ * `--provenance` / `--provenance-filter` wiring added to `memory store` /
+ * `memory search`, plus the crash discovered while implementing it: an
+ * earlier version of the provenance-filtered search path skipped the
+ * RaBitQ/HNSW acceleration branches entirely, which crashed the CLI process
+ * on exit (a libuv assertion on Windows) even though it printed correct
+ * results first. The fix keeps those branches unconditional and applies the
+ * provenance filter as a lookup within/after them instead of skipping them.
+ *
+ * Real end-to-end guard: drives the built CLI in a temp cwd exactly like a
+ * user would, because the crash only reproduced through the actual CLI
+ * process (not under the vitest/module-import transform).
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI = join(HERE, '..', 'bin', 'cli.js');
+const CLI_BUILT = existsSync(CLI);
+
+function run(args: string[], cwd: string): { stdout: string; exit: number | null } {
+ try {
+ const stdout = execFileSync('node', [CLI, ...args], {
+ cwd,
+ encoding: 'utf-8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ timeout: 60_000,
+ });
+ return { stdout, exit: 0 };
+ } catch (err) {
+ const e = err as { status?: number | null; stdout?: Buffer; stderr?: Buffer };
+ return {
+ stdout: (e.stdout?.toString() ?? '') + (e.stderr?.toString() ?? ''),
+ exit: e.status ?? null,
+ };
+ }
+}
+
+function searchJson(query: string, cwd: string, extraArgs: string[] = []) {
+ const { stdout } = run(['memory', 'search', '-q', query, '-n', 'adr323', '--threshold', '0.05', '--format', 'json', ...extraArgs], cwd);
+ const start = stdout.indexOf('{');
+ expect(start).toBeGreaterThanOrEqual(0);
+ return JSON.parse(stdout.slice(start)) as { results: Array<{ key: string; provenanceType?: string }> };
+}
+
+describe.skipIf(!CLI_BUILT)('ADR-323 typed memory provenance', () => {
+ let workdir: string;
+
+ beforeAll(() => {
+ workdir = mkdtempSync(join(tmpdir(), 'ruflo-adr323-'));
+ run(['memory', 'init'], workdir);
+ run(['memory', 'store', '-k', 'user/goal', '-n', 'adr323', '--value', 'ship the deploy by Friday', '--provenance', 'user_claim'], workdir);
+ run(['memory', 'store', '-k', 'agent/plan', '-n', 'adr323', '--value', 'deploy plan generated by planner agent', '--provenance', 'agent_output'], workdir);
+ run(['memory', 'store', '-k', 'tool/deploy', '-n', 'adr323', '--value', 'deploy status reported by tool', '--provenance', 'tool_result'], workdir);
+ run(['memory', 'store', '-k', 'misc/note', '-n', 'adr323', '--value', 'deploy notes without explicit provenance'], workdir);
+ }, 60_000);
+
+ afterAll(() => {
+ try { rmSync(workdir, { recursive: true, force: true }); } catch { /* ignore */ }
+ });
+
+ it('store rejects an invalid --provenance value with a non-zero exit', () => {
+ const { stdout, exit } = run(
+ ['memory', 'store', '-k', 'bad/entry', '-n', 'adr323', '--value', 'x', '--provenance', 'not_a_real_type'],
+ workdir,
+ );
+ expect(exit).not.toBe(0);
+ expect(stdout.toLowerCase()).toMatch(/provenance/);
+ });
+
+ it('an entry stored without --provenance defaults to "unknown"', () => {
+ const r = searchJson('notes', workdir);
+ const entry = r.results.find(x => x.key === 'misc/note');
+ expect(entry).toBeDefined();
+ expect(entry!.provenanceType).toBe('unknown');
+ });
+
+ it('search with no --provenance-filter returns entries of every provenance type', () => {
+ const r = searchJson('deploy', workdir);
+ const keys = r.results.map(x => x.key);
+ expect(keys).toContain('user/goal');
+ expect(keys).toContain('agent/plan');
+ expect(keys).toContain('misc/note');
+ });
+
+ it('persists explicit provenance through the native bridge and HNSW refresh', () => {
+ const r = searchJson('deploy', workdir);
+ expect(r.results.find(x => x.key === 'user/goal')?.provenanceType).toBe('user_claim');
+ expect(r.results.find(x => x.key === 'agent/plan')?.provenanceType).toBe('agent_output');
+ expect(r.results.find(x => x.key === 'tool/deploy')?.provenanceType).toBe('tool_result');
+ });
+
+ it('--provenance-filter user_claim returns only the user-claim entry', () => {
+ const r = searchJson('deploy', workdir, ['--provenance-filter', 'user_claim']);
+ const keys = r.results.map(x => x.key);
+ expect(keys).toContain('user/goal');
+ expect(keys).not.toContain('agent/plan');
+ expect(keys).not.toContain('misc/note');
+ });
+
+ it('--provenance-filter accepts a comma-separated list (OR semantics)', () => {
+ const r = searchJson('deploy', workdir, ['--provenance-filter', 'agent_output,tool_result']);
+ const keys = r.results.map(x => x.key);
+ expect(keys).toContain('agent/plan');
+ expect(keys).not.toContain('user/goal');
+ expect(keys).not.toContain('misc/note');
+ });
+
+ it('enforces provenance filtering in keyword and hybrid modes', () => {
+ for (const searchType of ['keyword', 'hybrid']) {
+ const r = searchJson('deploy', workdir, ['--type', searchType, '--provenance-filter', 'tool_result']);
+ const keys = r.results.map(x => x.key);
+ expect(keys).toContain('tool/deploy');
+ expect(keys).not.toContain('user/goal');
+ expect(keys).not.toContain('agent/plan');
+ expect(keys).not.toContain('misc/note');
+ }
+ });
+
+ it('enforces provenance filtering inside SmartRetrieval query expansion', () => {
+ const r = searchJson('deploy', workdir, ['--smart', '--provenance-filter', 'user_claim']);
+ const keys = r.results.map(x => x.key);
+ expect(keys).toContain('user/goal');
+ expect(keys).not.toContain('agent/plan');
+ expect(keys).not.toContain('tool/deploy');
+ expect(keys).not.toContain('misc/note');
+ });
+
+ it('preserves an existing provenance type when an upsert omits the flag', () => {
+ const updated = run(
+ ['memory', 'store', '-k', 'agent/plan', '-n', 'adr323', '--value', 'updated deploy plan'],
+ workdir,
+ );
+ expect(updated.exit).toBe(0);
+ const r = searchJson('updated deploy', workdir, ['--provenance-filter', 'agent_output']);
+ const entry = r.results.find(x => x.key === 'agent/plan');
+ expect(entry).toBeDefined();
+ expect(entry?.provenanceType).toBe('agent_output');
+ });
+
+ it('search rejects an invalid --provenance-filter value with a non-zero exit', () => {
+ const { stdout, exit } = run(
+ ['memory', 'search', '-q', 'deploy', '-n', 'adr323', '--provenance-filter', 'not_a_type', '--format', 'json'],
+ workdir,
+ );
+ expect(exit).not.toBe(0);
+ expect(stdout.toLowerCase()).toMatch(/provenance/);
+ });
+
+ // Regression for the crash found during implementation: a
+ // provenance-filtered search must exit cleanly (code 0), not just print
+ // correct JSON and then crash on process teardown.
+ it('a provenance-filtered search exits cleanly, run repeatedly', () => {
+ for (let i = 0; i < 3; i++) {
+ const { exit } = run(
+ ['memory', 'search', '-q', 'deploy', '-n', 'adr323', '--threshold', '0.05', '--provenance-filter', 'user_claim', '--format', 'json'],
+ workdir,
+ );
+ expect(exit).toBe(0);
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/memory.ts b/v3/@claude-flow/cli/src/commands/memory.ts
index a31bb40931..813178447d 100644
--- a/v3/@claude-flow/cli/src/commands/memory.ts
+++ b/v3/@claude-flow/cli/src/commands/memory.ts
@@ -91,12 +91,23 @@ const storeCommand: Command = {
description: 'Scan the value for injection payloads before persisting (dream-cycle #2752 MemPoison gate)',
type: 'boolean',
},
+ {
+ // ADR-323 β€” typed memory provenance. Distinguishes who/what produced
+ // this entry so shared-namespace retrieval can filter by trust level
+ // instead of conflating a user's stated claim with an agent's own
+ // output or a raw tool/system observation.
+ name: 'provenance',
+ description: 'Who/what produced this value: user_claim | agent_output | system_observation | tool_result | unknown (default: unknown) β€” ADR-323',
+ type: 'string',
+ choices: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'],
+ },
DB_PATH_OPTION
],
examples: [
{ command: 'claude-flow memory store -k "api/auth" -v "JWT implementation"', description: 'Store text' },
{ command: 'claude-flow memory store -k "pattern/singleton" --vector', description: 'Store vector' },
- { command: 'claude-flow memory store -k "pattern" -v "new" --no-upsert', description: 'Strict insert (fail if key exists)' }
+ { command: 'claude-flow memory store -k "pattern" -v "new" --no-upsert', description: 'Strict insert (fail if key exists)' },
+ { command: 'claude-flow memory store -k "user/goal" -v "ship by Friday" --provenance user_claim', description: 'Store with typed provenance (ADR-323)' }
],
action: async (ctx: CommandContext): Promise<CommandResult> => {
const key = ctx.flags.key as string;
@@ -119,6 +130,10 @@ const storeCommand: Command = {
// regardless of the parser gap: only an explicit `--no-upsert` (which
// arrives as `false`) turns it off.
const upsert = ctx.flags.upsert !== false;
+ // ADR-323: leave undefined (not 'unknown') when omitted so storeEntry's
+ // own default applies uniformly across the CLI, MCP tool, and direct
+ // callers β€” one place decides the default, not three.
+ const provenance = ctx.flags.provenance as string | undefined;
if (!key) {
output.printError('Key is required. Use --key or -k');
@@ -189,6 +204,7 @@ const storeCommand: Command = {
tags,
ttl,
upsert,
+ provenanceType: provenance,
dbPath
});
@@ -210,6 +226,7 @@ const storeCommand: Command = {
{ property: 'TTL', val: ttl ? `${ttl}s` : 'None' },
{ property: 'Tags', val: tags.length > 0 ? tags.join(', ') : 'None' },
{ property: 'Vector', val: result.embedding ? `Yes (${result.embedding.dimensions}-dim)` : 'No' },
+ { property: 'Provenance', val: provenance || 'unknown' },
{ property: 'ID', val: result.id.substring(0, 20) }
]
});
@@ -217,7 +234,7 @@ const storeCommand: Command = {
output.writeln();
output.printSuccess('Data stored successfully');
- return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding } };
+ return { success: true, data: { ...storeData, id: result.id, embedding: result.embedding, provenanceType: provenance || 'unknown' } };
} catch (error) {
output.printError(`Failed to store: ${error instanceof Error ? error.message : 'Unknown error'}`);
return { success: false, exitCode: 1 };
@@ -391,6 +408,15 @@ const searchCommand: Command = {
choices: ['auto', 'mixed', 'episodic', 'semantic', 'procedural'],
default: 'mixed',
},
+ {
+ // ADR-323 β€” restrict results to entries with a matching provenance
+ // type (e.g. exclude user_claim when retrieving for fact-checking,
+ // per MemSyco-Bench's memory-induced sycophancy finding). Enforced
+ // across semantic, keyword, hybrid, and SmartRetrieval paths.
+ name: 'provenance-filter',
+ description: 'Comma-separated provenance types to restrict results to: user_claim,agent_output,system_observation,tool_result,unknown β€” ADR-323',
+ type: 'string',
+ },
DB_PATH_OPTION
],
examples: [
@@ -399,11 +425,18 @@ const searchCommand: Command = {
{ command: 'claude-flow memory search -q "test" --build-hnsw', description: 'Build HNSW index and search' },
{ command: 'claude-flow memory search -q "auth patterns" --smart', description: 'SmartRetrieval with RRF + MMR' },
{ command: 'claude-flow memory search -q "when did we last touch auth" --intent auto', description: 'SCM-routed retrieval (dream-cycle #2760)' },
+ { command: 'claude-flow memory search -q "deploy plan" --provenance-filter agent_output,tool_result', description: 'Only trust agent/tool-sourced entries (ADR-323)' },
],
action: async (ctx: CommandContext): Promise<CommandResult> => {
const query = ctx.flags.query as string || ctx.args[0];
let namespace = ctx.flags.namespace as string || 'all';
const limit = ctx.flags.limit as number || 10;
+ // Matches the --build-hnsw / buildHnsw dual-check convention already used
+ // below: the parser doesn't consistently camelCase every hyphenated flag.
+ const provenanceFilterRaw = (ctx.flags['provenance-filter'] || ctx.flags.provenanceFilter) as string | undefined;
+ const provenanceFilter = provenanceFilterRaw
+ ? provenanceFilterRaw.split(',').map(s => s.trim()).filter(Boolean)
+ : undefined;
// #2790 fix β€” `||` discards an explicit `--threshold 0` (falsy) and
// silently uses the fallback; that made `--threshold 0` return
// FEWER results than `--threshold 0.01` (non-monotonic). Nullish
@@ -483,15 +516,19 @@ const searchCommand: Command = {
// the requested namespace (or all) and substring-match against key
// + content. Hybrid unions the keyword hits with the semantic hits
// and dedups by key + namespace.
- let keywordResults: { key: string; score: number; namespace: string; preview: string }[] = [];
+ let keywordResults: { key: string; score: number; namespace: string; preview: string; provenanceType?: string }[] = [];
if (searchType === 'keyword' || searchType === 'hybrid') {
const list = await listEntries({
namespace: namespace === 'all' ? undefined : namespace,
limit: 5000,
includeContent: true,
dbPath: dbPathSearch,
+ provenanceFilter,
});
- if (list.success) {
+ if (!list.success) {
+ output.printError(list.error || 'Keyword search failed');
+ return { success: false, exitCode: 1 };
+ } else {
const q = (query as string).toLowerCase();
keywordResults = list.entries
.filter((e) => {
@@ -507,6 +544,7 @@ const searchCommand: Command = {
score: inKey ? 1.0 : 0.7,
namespace: e.namespace,
preview: c.slice(0, 200),
+ provenanceType: e.provenanceType,
};
})
.sort((a, b) => b.score - a.score)
@@ -528,7 +566,7 @@ const searchCommand: Command = {
// Hybrid mode: keyword hits will be MERGED after semantic runs below.
}
- let results: { key: string; score: number; namespace: string; preview: string }[];
+ let results: { key: string; score: number; namespace: string; preview: string; provenanceType?: string }[];
let searchTimeMs: number;
let smartStats: Record<string, unknown> | undefined;
let backendLabel = 'HNSW + sql.js';
@@ -564,6 +602,7 @@ const searchCommand: Command = {
limit: req.limit || limit * 3,
threshold: req.threshold ?? threshold,
dbPath: dbPathSearch,
+ provenanceFilter,
});
return {
results: r.results.map(e => ({
@@ -572,6 +611,7 @@ const searchCommand: Command = {
content: e.content,
score: e.score,
namespace: e.namespace,
+ provenanceType: e.provenanceType,
})),
};
};
@@ -583,11 +623,12 @@ const searchCommand: Command = {
threshold,
});
- results = smartResult.results.map((r: { content: string; key: string; namespace: string; score: number }) => ({
+ results = smartResult.results.map((r: { content: string; key: string; namespace: string; score: number; provenanceType?: string }) => ({
key: r.key,
score: r.score,
namespace: r.namespace,
preview: r.content,
+ provenanceType: r.provenanceType,
}));
searchTimeMs = smartResult.stats.durationMs;
smartStats = smartResult.stats as unknown as Record<string, unknown>;
@@ -598,7 +639,8 @@ const searchCommand: Command = {
namespace,
limit,
threshold,
- dbPath: dbPathSearch
+ dbPath: dbPathSearch,
+ provenanceFilter
});
if (!searchResult.success) {
@@ -610,7 +652,8 @@ const searchCommand: Command = {
key: r.key,
score: r.score,
namespace: r.namespace,
- preview: r.content
+ preview: r.content,
+ provenanceType: r.provenanceType,
}));
searchTimeMs = searchResult.searchTime;
}
diff --git a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
index 3caf15afda..e18483eb83 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts
@@ -308,6 +308,11 @@ export const memoryTools: MCPTool[] = [
},
ttl: { type: 'number', description: 'Time-to-live in seconds (optional)' },
upsert: { type: 'boolean', description: 'Update existing key instead of failing (default: true, matching CLI `memory store`; set false for strict-insert). #2775 parity.' },
+ provenance_type: {
+ type: 'string',
+ enum: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'],
+ description: 'ADR-323: who/what produced this value, so shared-namespace retrieval can filter by trust level instead of conflating a user\'s stated claim with an agent\'s own output. Default: "unknown".',
+ },
},
required: ['key', 'value'],
},
@@ -323,6 +328,9 @@ export const memoryTools: MCPTool[] = [
const ttl = input.ttl as number | undefined;
// #2775 parity with CLI: default true; only explicit `upsert: false` opts out.
const upsert = input.upsert !== false;
+ // ADR-323: leave undefined when omitted so storeEntry's own default
+ // ('unknown') applies uniformly across the CLI, MCP tool, and other callers.
+ const provenanceType = input.provenance_type as string | undefined;
if (!value) {
return {
@@ -347,6 +355,7 @@ export const memoryTools: MCPTool[] = [
tags,
ttl,
upsert,
+ provenanceType,
});
const duration = performance.now() - startTime;
@@ -359,6 +368,7 @@ export const memoryTools: MCPTool[] = [
storedAt: new Date().toISOString(),
hasEmbedding: !!result.embedding,
embeddingDimensions: result.embedding?.dimensions || null,
+ provenanceType: provenanceType || 'unknown',
backend: 'sql.js + HNSW',
storeTime: `${duration.toFixed(2)}ms`,
error: result.error,
@@ -448,6 +458,11 @@ export const memoryTools: MCPTool[] = [
limit: { type: 'number', description: 'Maximum results (default: 10)' },
threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.3)' },
smart: { type: 'boolean', description: 'Enable SmartRetrieval pipeline β€” query expansion, RRF fusion, recency boost, MMR diversity (default: false)' },
+ provenance_filter: {
+ type: 'array',
+ items: { type: 'string', enum: ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'] },
+ description: 'ADR-323: restrict results to these provenance types (e.g. exclude user_claim when fact-checking). Omit for no filtering. Enforced for standard and SmartRetrieval searches.',
+ },
},
required: ['query'],
},
@@ -456,6 +471,7 @@ export const memoryTools: MCPTool[] = [
const { searchEntries } = await getMemoryFunctions();
const query = input.query as string;
+ const provenanceFilter = input.provenance_filter as string[] | undefined;
// #2646 (3rd occurrence of #1123/#1131 shape): do NOT coerce an omitted
// namespace to the literal string 'default' here. Both searchEntries()
// and bridgeSearchEntries() already resolve an omitted/undefined
@@ -500,6 +516,7 @@ export const memoryTools: MCPTool[] = [
namespace: req.namespace || namespace,
limit: req.limit || limit * 3,
threshold: req.threshold ?? threshold,
+ provenanceFilter,
});
return {
results: r.results.map(e => ({
@@ -508,6 +525,7 @@ export const memoryTools: MCPTool[] = [
content: e.content,
score: e.score,
namespace: e.namespace,
+ provenanceType: e.provenanceType,
})),
};
};
@@ -521,7 +539,7 @@ export const memoryTools: MCPTool[] = [
const duration = performance.now() - startTime;
- const results = smartResult.results.map((r: { content: string; key: string; namespace: string; score: number }) => {
+ const results = smartResult.results.map((r: { content: string; key: string; namespace: string; score: number; provenanceType?: string }) => {
let value: unknown = r.content;
try { value = JSON.parse(r.content); } catch { /* keep as string */ }
return {
@@ -529,6 +547,7 @@ export const memoryTools: MCPTool[] = [
namespace: r.namespace,
value,
similarity: r.score,
+ provenanceType: r.provenanceType,
};
});
@@ -551,13 +570,20 @@ export const memoryTools: MCPTool[] = [
// Original non-smart path (unchanged) β€” also reached when smart was
// requested but unavailable. We attach `smartFallback` to the
// response so callers can see the degradation explicitly.
+ // ADR-323: the same filter is also passed into every raw search used
+ // by SmartRetrieval above, so query expansion cannot widen trust scope.
const result = await searchEntries({
query,
namespace,
limit,
threshold,
+ provenanceFilter,
});
+ if (!result.success) {
+ return { query, results: [], total: 0, error: result.error };
+ }
+
const duration = performance.now() - startTime;
// Parse JSON values in results
@@ -574,6 +600,7 @@ export const memoryTools: MCPTool[] = [
namespace: r.namespace,
value,
similarity: r.score,
+ provenanceType: r.provenanceType,
};
});
diff --git a/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
index 6a160a34a7..5992b98fd8 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
@@ -618,7 +618,7 @@ export const metaharnessTools: MCPTool[] = [
},
{
name: 'metaharness_flywheel',
- description: 'ADR-322 β€” evaluate candidates into immutable receipts, inspect the append-only promotion ledger, and explicitly promote one signed receipt with atomic compare-and-swap semantics. Evaluation never mutates the active champion. Promotion requires confirm=true and a local approved Ed25519 public-key PEM path; explicit trust is mandatory.',
+ description: 'ADR-322 β€” evaluate candidates into immutable receipts, inspect the append-only promotion ledger, and explicitly promote one signed receipt with atomic compare-and-swap semantics. Use when running governed flywheel evaluation or promotion; evaluation never mutates the active champion, and promotion requires confirm=true plus a locally approved Ed25519 public-key PEM path.',
category: 'metaharness',
inputSchema: {
type: 'object',
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 619d555325..c2b0a46b3f 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -27,6 +27,23 @@ let registryPromise: Promise<any> | null = null;
let registryInstance: any = null;
let bridgeAvailable: boolean | null = null;
+/**
+ * ADR-323: reuse memory-initializer's provenance-type allowlist rather than
+ * duplicating it (drift risk). Lazy CJS require for the same circular-ESM-
+ * dependency reason as getDbPath() below.
+ */
+function isValidProvenanceType(value: unknown): boolean {
+ try {
+ const cjsRequire = createRequire(import.meta.url);
+ const mod = cjsRequire('./memory-initializer.js') as { isValidProvenanceType?: (v: unknown) => boolean };
+ if (typeof mod.isValidProvenanceType === 'function') {
+ return mod.isValidProvenanceType(value);
+ }
+ } catch { /* memory-initializer not resolvable in this build */ }
+ // Fallback allowlist β€” keep in sync with memory-initializer.ts's PROVENANCE_TYPES.
+ return typeof value === 'string' && ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'].includes(value);
+}
+
/**
* Resolve database path with path traversal protection.
* Only allows paths within or below the project's working directory,
@@ -681,6 +698,8 @@ export async function bridgeStoreEntry(options: {
ttl?: number;
dbPath?: string;
upsert?: boolean;
+ /** ADR-323: defaults to 'unknown' when omitted. */
+ provenanceType?: string;
}): Promise<{
success: boolean;
id: string;
@@ -691,6 +710,17 @@ export async function bridgeStoreEntry(options: {
attested?: boolean;
error?: string;
} | null> {
+ // ADR-323 β€” validated once in storeEntry() before this is reached on that
+ // path, but bridgeStoreEntry() also has direct internal callers, so check
+ // again here rather than trust every call site.
+ if (options.provenanceType !== undefined && !isValidProvenanceType(options.provenanceType)) {
+ return {
+ success: false,
+ id: '',
+ error: `Invalid provenance type "${options.provenanceType}"`,
+ };
+ }
+
const registry = await getRegistry(options.dbPath);
if (!registry) return null;
@@ -699,6 +729,18 @@ export async function bridgeStoreEntry(options: {
try {
const { key, value, namespace = 'default', tags = [], ttl } = options;
+ let provenanceType = options.provenanceType ?? 'unknown';
+ // An omitted type on an upsert means "update the value", not "erase the
+ // existing trust label". New rows still receive the backward-compatible
+ // unknown default.
+ if (options.upsert && options.provenanceType === undefined) {
+ try {
+ const existing = ctx.db.prepare(
+ 'SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1'
+ ).get(namespace, key);
+ provenanceType = existing?.provenance_type || 'unknown';
+ } catch { /* legacy schema or new row β€” keep unknown */ }
+ }
const id = generateId('entry');
const now = Date.now();
@@ -759,13 +801,13 @@ export async function bridgeStoreEntry(options: {
? `INSERT OR REPLACE INTO memory_entries (
id, key, namespace, content, type,
embedding, embedding_dimensions, embedding_model,
- tags, metadata, created_at, updated_at, expires_at, status
- ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
+ tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+ ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
: `INSERT INTO memory_entries (
id, key, namespace, content, type,
embedding, embedding_dimensions, embedding_model,
- tags, metadata, created_at, updated_at, expires_at, status
- ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')
+ tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+ ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')
ON CONFLICT(namespace, key) DO UPDATE SET
id = excluded.id,
content = excluded.content,
@@ -774,6 +816,7 @@ export async function bridgeStoreEntry(options: {
embedding_model = excluded.embedding_model,
tags = excluded.tags,
metadata = excluded.metadata,
+ provenance_type = excluded.provenance_type,
created_at = excluded.created_at,
updated_at = excluded.updated_at,
expires_at = excluded.expires_at,
@@ -797,6 +840,7 @@ export async function bridgeStoreEntry(options: {
embeddingJson, dimensions || null, model,
tags.length > 0 ? JSON.stringify(tags) : null,
'{}',
+ provenanceType,
now, now,
ttl ? now + (ttl * 1000) : null
);
@@ -893,6 +937,8 @@ export async function bridgeSearchEntries(options: {
limit?: number;
threshold?: number;
dbPath?: string;
+ /** ADR-323: restrict results to these provenance types. */
+ provenanceFilter?: string[];
}): Promise<{
success: boolean;
results: {
@@ -902,11 +948,20 @@ export async function bridgeSearchEntries(options: {
score: number;
namespace: string;
provenance?: string;
+ /** ADR-323 β€” NOT the same as `provenance` above (that's the
+ * ExplainableRecall score breakdown). This is the entry's
+ * user_claim/agent_output/... provenance type. */
+ provenanceType?: string;
}[];
searchTime: number;
searchMethod?: string;
error?: string;
} | null> {
+ if (options.provenanceFilter?.length) {
+ const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
+ if (invalid.length > 0) return null; // caller (searchEntries) demotes to sql.js, which returns a typed error
+ }
+
const registry = await getRegistry(options.dbPath);
if (!registry) return null;
@@ -914,7 +969,7 @@ export async function bridgeSearchEntries(options: {
if (!ctx) return null;
try {
- const { query: queryStr, namespace, limit = 10, threshold = 0.3 } = options;
+ const { query: queryStr, namespace, limit = 10, threshold = 0.3, provenanceFilter } = options;
const effectiveNamespace = namespace || 'all';
const startTime = Date.now();
@@ -931,19 +986,28 @@ export async function bridgeSearchEntries(options: {
}
// better-sqlite3: .prepare().all() returns array of objects
- const nsFilter = effectiveNamespace !== 'all'
- ? `AND namespace = ?`
- : '';
+ // ADR-323: compose namespace + provenance filters into one WHERE clause.
+ const filters: string[] = [];
+ const filterParams: string[] = [];
+ if (effectiveNamespace !== 'all') {
+ filters.push('namespace = ?');
+ filterParams.push(effectiveNamespace);
+ }
+ if (provenanceFilter?.length) {
+ filters.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+ filterParams.push(...provenanceFilter);
+ }
+ const whereExtra = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
let rows: any[];
try {
const stmt = ctx.db.prepare(`
- SELECT id, key, namespace, content, embedding
+ SELECT id, key, namespace, content, embedding, provenance_type
FROM memory_entries
- WHERE status = 'active' ${nsFilter}
+ WHERE status = 'active' ${whereExtra}
LIMIT 1000
`);
- rows = effectiveNamespace !== 'all' ? stmt.all(effectiveNamespace) : stmt.all();
+ rows = filterParams.length > 0 ? stmt.all(...filterParams) : stmt.all();
} catch {
return null;
}
@@ -956,7 +1020,7 @@ export async function bridgeSearchEntries(options: {
const { termDocFreqs, avgDocLength } = computeTermDocFreqs(queryTerms, docs);
const docCount = rows.length;
- const results: { id: string; key: string; content: string; score: number; namespace: string; provenance?: string }[] = [];
+ const results: { id: string; key: string; content: string; score: number; namespace: string; provenance?: string; provenanceType?: string }[] = [];
for (let i = 0; i < rows.length; i++) {
const row = rows[i];
@@ -1018,6 +1082,7 @@ export async function bridgeSearchEntries(options: {
score,
namespace: row.namespace || 'default',
provenance,
+ provenanceType: row.provenance_type || 'unknown',
});
}
}
@@ -1045,6 +1110,8 @@ export async function bridgeListEntries(options: {
dbPath?: string;
/** #2073: When true, include the entry's full `content` string in each result. */
includeContent?: boolean;
+ /** ADR-323: restrict rows to these provenance types. */
+ provenanceFilter?: string[];
}): Promise<{
success: boolean;
entries: {
@@ -1058,6 +1125,7 @@ export async function bridgeListEntries(options: {
hasEmbedding: boolean;
/** #2073: Present when `includeContent: true` was requested. */
content?: string;
+ provenanceType?: string;
}[];
total: number;
error?: string;
@@ -1069,10 +1137,20 @@ export async function bridgeListEntries(options: {
if (!ctx) return null;
try {
- const { namespace, limit = 20, offset = 0 } = options;
+ const { namespace, limit = 20, offset = 0, provenanceFilter } = options;
+ if (provenanceFilter?.some(p => !isValidProvenanceType(p))) return null;
- const nsFilter = namespace ? `AND namespace = ?` : '';
- const nsParams = namespace ? [namespace] : [];
+ const filters: string[] = [];
+ const filterParams: string[] = [];
+ if (namespace) {
+ filters.push('namespace = ?');
+ filterParams.push(namespace);
+ }
+ if (provenanceFilter?.length) {
+ filters.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+ filterParams.push(...provenanceFilter);
+ }
+ const extraFilter = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
// #2120 β€” `status IS NULL` accepted alongside `'active'`. Old
// databases imported by the auto-memory bridge (before the status
@@ -1088,9 +1166,9 @@ export async function bridgeListEntries(options: {
let total = 0;
try {
const countStmt = ctx.db.prepare(
- `SELECT COUNT(*) as cnt FROM memory_entries WHERE ${statusFilter} ${nsFilter}`
+ `SELECT COUNT(*) as cnt FROM memory_entries WHERE ${statusFilter} ${extraFilter}`
);
- const countRow = countStmt.get(...nsParams);
+ const countRow = countStmt.get(...filterParams);
total = countRow?.cnt ?? 0;
} catch {
return null;
@@ -1100,13 +1178,13 @@ export async function bridgeListEntries(options: {
const entries: any[] = [];
try {
const stmt = ctx.db.prepare(`
- SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at
+ SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type
FROM memory_entries
- WHERE ${statusFilter} ${nsFilter}
+ WHERE ${statusFilter} ${extraFilter}
ORDER BY updated_at DESC
LIMIT ? OFFSET ?
`);
- const rows = stmt.all(...nsParams, limit, offset);
+ const rows = stmt.all(...filterParams, limit, offset);
for (const row of rows) {
const entry: Record<string, unknown> = {
// #2073: don't truncate id when content is requested β€” callers
@@ -1119,6 +1197,7 @@ export async function bridgeListEntries(options: {
createdAt: row.created_at || new Date().toISOString(),
updatedAt: row.updated_at || new Date().toISOString(),
hasEmbedding: !!(row.embedding && String(row.embedding).length > 10),
+ provenanceType: row.provenance_type || 'unknown',
};
if (options.includeContent) {
entry.content = row.content || '';
@@ -1623,12 +1702,25 @@ export async function bridgeAddToHNSW(
try {
const now = Date.now();
const embeddingJson = JSON.stringify(embedding);
+ // Do not use INSERT OR REPLACE here. storeEntry() has already written the
+ // authoritative row, including provenance/tags/metadata; REPLACE deleted
+ // that row and recreated it without provenance_type, silently resetting
+ // every typed CLI/MCP write to "unknown".
ctx.db.prepare(`
- INSERT OR REPLACE INTO memory_entries (
+ INSERT INTO memory_entries (
id, key, namespace, content, type,
embedding, embedding_dimensions, embedding_model,
created_at, updated_at, status
) VALUES (?, ?, ?, ?, 'semantic', ?, ?, 'Xenova/all-MiniLM-L6-v2', ?, ?, 'active')
+ ON CONFLICT(namespace, key) DO UPDATE SET
+ id = excluded.id,
+ content = excluded.content,
+ type = excluded.type,
+ embedding = excluded.embedding,
+ embedding_dimensions = excluded.embedding_dimensions,
+ embedding_model = excluded.embedding_model,
+ updated_at = excluded.updated_at,
+ status = 'active'
`).run(
id, entry.key, entry.namespace, entry.content,
embeddingJson, embedding.length,
diff --git a/v3/@claude-flow/cli/src/memory/memory-initializer.ts b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
index 1147acba36..53105f3aa7 100644
--- a/v3/@claude-flow/cli/src/memory/memory-initializer.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-initializer.ts
@@ -15,6 +15,27 @@ import { createRequire } from 'node:module';
import { readFileMaybeEncrypted, writeFileAtomic, writeFileRestricted } from '../fs-secure.js';
import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
+/**
+ * ADR-323 β€” typed memory provenance. Distinguishes WHO/WHAT wrote a memory
+ * entry (a user's stated claim vs an agent's own output vs a tool result vs
+ * a raw system observation) so retrieval can filter by trust level instead
+ * of treating every entry in a shared namespace as equally authoritative.
+ * `unknown` is the backward-compatible default for entries written before
+ * this field existed, and for callers that don't pass one.
+ */
+export const PROVENANCE_TYPES = [
+ 'user_claim',
+ 'agent_output',
+ 'system_observation',
+ 'tool_result',
+ 'unknown',
+] as const;
+export type ProvenanceType = (typeof PROVENANCE_TYPES)[number];
+
+export function isValidProvenanceType(value: unknown): value is ProvenanceType {
+ return typeof value === 'string' && (PROVENANCE_TYPES as readonly string[]).includes(value);
+}
+
/**
* #2356 β€” cached, synchronous capability probe for @ruvector/core. `getHNSWStatus`
* is sync and is called by `neural status` in a fresh process that never warms
@@ -194,6 +215,13 @@ CREATE TABLE IF NOT EXISTS memory_entries (
metadata TEXT, -- JSON object
owner_id TEXT,
+ -- ADR-323: who/what produced this entry β€” lets shared-namespace retrieval
+ -- filter by trust level instead of conflating a user's stated claim with
+ -- an agent's own output or a raw tool/system observation.
+ provenance_type TEXT DEFAULT 'unknown' CHECK(provenance_type IN (
+ 'user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'
+ )),
+
-- Timestamps
created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
@@ -1178,7 +1206,13 @@ export async function ensureSchemaColumns(dbPath: string): Promise<{
{ name: 'expires_at', definition: 'expires_at INTEGER' },
{ name: 'last_accessed_at', definition: 'last_accessed_at INTEGER' },
{ name: 'access_count', definition: 'access_count INTEGER DEFAULT 0' },
- { name: 'status', definition: "status TEXT DEFAULT 'active'" }
+ { name: 'status', definition: "status TEXT DEFAULT 'active'" },
+ // ADR-323: older DBs predate provenance typing entirely β€” backfilled
+ // as 'unknown' via the DEFAULT, same convention as 'type'/'status'
+ // above (no CHECK on the ALTER; enforcement happens in storeEntry()/
+ // bridgeStoreEntry() so an invalid value gets a CLI-friendly error
+ // instead of a raw SQLite constraint failure).
+ { name: 'provenance_type', definition: "provenance_type TEXT DEFAULT 'unknown'" }
];
let modified = false;
@@ -2650,12 +2684,25 @@ export async function storeEntry(options: {
ttl?: number;
dbPath?: string;
upsert?: boolean;
+ /** ADR-323: defaults to 'unknown' when omitted. */
+ provenanceType?: string;
}): Promise<{
success: boolean;
id: string;
embedding?: { dimensions: number; model: string };
error?: string;
}> {
+ // ADR-323: validate before touching either backend so an invalid value
+ // gets one clear error instead of a raw SQLite CHECK-constraint failure
+ // from whichever path (bridge vs sql.js) happens to run.
+ if (options.provenanceType !== undefined && !isValidProvenanceType(options.provenanceType)) {
+ return {
+ success: false,
+ id: '',
+ error: `Invalid provenance type "${options.provenanceType}" β€” must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+ };
+ }
+
// ADR-053: Try AgentDB v3 bridge first
const bridge = await getBridge();
if (bridge) {
@@ -2684,7 +2731,8 @@ export async function storeEntry(options: {
tags = [],
ttl,
dbPath: customPath,
- upsert = false
+ upsert = false,
+ provenanceType
} = options;
const swarmDir = getMemoryRoot();
@@ -2720,6 +2768,20 @@ export async function storeEntry(options: {
const fileBuffer = readFileMaybeEncrypted(dbPath, null);
const db = new SQL.Database(fileBuffer);
+ let persistedProvenance = provenanceType ?? 'unknown';
+ if (upsert && provenanceType === undefined) {
+ try {
+ const stmt = db.prepare(
+ 'SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1'
+ );
+ stmt.bind([namespace, key]);
+ if (stmt.step()) {
+ const existingType = stmt.get()[0];
+ persistedProvenance = isValidProvenanceType(existingType) ? existingType : 'unknown';
+ }
+ stmt.free();
+ } catch { /* legacy schema or new row β€” keep unknown */ }
+ }
const id = `entry_${Date.now()}_${Math.random().toString(36).substring(7)}`;
const now = Date.now();
@@ -2753,13 +2815,13 @@ export async function storeEntry(options: {
? `INSERT OR REPLACE INTO memory_entries (
id, key, namespace, content, type,
embedding, embedding_dimensions, embedding_model,
- tags, metadata, created_at, updated_at, expires_at, status
- ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
+ tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+ ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
: `INSERT INTO memory_entries (
id, key, namespace, content, type,
embedding, embedding_dimensions, embedding_model,
- tags, metadata, created_at, updated_at, expires_at, status
- ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
+ tags, metadata, provenance_type, created_at, updated_at, expires_at, status
+ ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
db.run(insertSql, [
id,
@@ -2771,6 +2833,7 @@ export async function storeEntry(options: {
embeddingModel,
tags.length > 0 ? JSON.stringify(tags) : null,
'{}',
+ persistedProvenance,
now,
now,
ttl ? now + (ttl * 1000) : null
@@ -2816,6 +2879,10 @@ export async function searchEntries(options: {
limit?: number;
threshold?: number;
dbPath?: string;
+ /** ADR-323: restrict results to these provenance types (e.g. exclude
+ * 'user_claim' when retrieving for fact-checking, per MemSyco-Bench's
+ * sycophancy finding). Omit/empty = no filtering (all types). */
+ provenanceFilter?: string[];
}): Promise<{
success: boolean;
results: {
@@ -2824,10 +2891,23 @@ export async function searchEntries(options: {
content: string;
score: number;
namespace: string;
+ provenanceType?: string;
}[];
searchTime: number;
error?: string;
}> {
+ if (options.provenanceFilter?.length) {
+ const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
+ if (invalid.length > 0) {
+ return {
+ success: false,
+ results: [],
+ searchTime: 0,
+ error: `Invalid provenance filter value(s): ${invalid.join(', ')} β€” must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+ };
+ }
+ }
+
// ADR-053: Try AgentDB v3 bridge first
const bridge = await getBridge();
if (bridge) {
@@ -2841,7 +2921,8 @@ export async function searchEntries(options: {
namespace,
limit = 10,
threshold = 0.3,
- dbPath: customPath
+ dbPath: customPath,
+ provenanceFilter
} = options;
const effectiveNamespace = namespace || 'all';
@@ -2871,13 +2952,21 @@ export async function searchEntries(options: {
const SQL = await initSqlJs();
const fileBuffer = readFileMaybeEncrypted(dbPath, null);
const db = new SQL.Database(fileBuffer);
- const reranked: { id: string; key: string; content: string; score: number; namespace: string }[] = [];
+ const reranked: { id: string; key: string; content: string; score: number; namespace: string; provenanceType?: string }[] = [];
for (const candidate of rabitqCandidates) {
- const stmt = db.prepare('SELECT content, embedding FROM memory_entries WHERE id = ? AND status = ?');
+ // ADR-323: provenance_type is fetched in the same per-candidate
+ // query (no extra round-trip) so a provenance-filtered search
+ // still gets RaBitQ's speedup instead of falling back to brute
+ // force.
+ const stmt = db.prepare('SELECT content, embedding, provenance_type FROM memory_entries WHERE id = ? AND status = ?');
stmt.bind([candidate.id, 'active']);
if (stmt.step()) {
- const [content, embeddingJson] = stmt.get() as [string, string | null];
+ const [content, embeddingJson, provenanceTypeVal] = stmt.get() as [string, string | null, string | null];
+ if (provenanceFilter?.length && !provenanceFilter.includes(provenanceTypeVal || 'unknown')) {
+ stmt.free();
+ continue;
+ }
let score = 0;
if (embeddingJson) {
try {
@@ -2892,6 +2981,7 @@ export async function searchEntries(options: {
content: (content || '').substring(0, 60) + ((content || '').length > 60 ? '...' : ''),
score,
namespace: candidate.namespace,
+ provenanceType: provenanceTypeVal || 'unknown',
});
}
}
@@ -2899,7 +2989,10 @@ export async function searchEntries(options: {
}
db.close();
- if (reranked.length > 0) {
+ // A filtered ANN candidate window can underfill even when qualifying
+ // rows exist outside that window. Fall through to the authoritative
+ // filtered SQL scan unless ANN filled the requested page.
+ if (reranked.length > 0 && (!provenanceFilter?.length || reranked.length >= limit)) {
reranked.sort((a, b) => b.score - a.score);
return { success: true, results: reranked.slice(0, limit), searchTime: Date.now() - startTime };
}
@@ -2907,15 +3000,58 @@ export async function searchEntries(options: {
} catch { /* RaBitQ unavailable, fall through */ }
// Try HNSW search (150x faster than brute-force)
- const hnswResults = await searchHNSWIndex(queryEmbedding, { k: limit, namespace: effectiveNamespace });
+ const hnswResults = await searchHNSWIndex(queryEmbedding, {
+ k: provenanceFilter?.length ? Math.max(limit * 4, limit + 32) : limit,
+ namespace: effectiveNamespace,
+ });
if (hnswResults && hnswResults.length > 0) {
// Filter by threshold
- const filtered = hnswResults.filter(r => r.score >= threshold);
- return {
- success: true,
- results: filtered,
- searchTime: Date.now() - startTime
- };
+ let filtered: Array<{ id: string; key: string; content: string; score: number; namespace: string; provenanceType?: string }> =
+ hnswResults.filter(r => r.score >= threshold);
+
+ // ADR-323: the in-memory HNSW index doesn't carry provenance_type on
+ // its entries, so resolve it from SQLite for a consistent result shape
+ // and apply any trust filter before returning.
+ if (filtered.length > 0) {
+ try {
+ const initSqlJs = (await import('sql.js')).default;
+ const SQL = await initSqlJs();
+ const fileBuffer = readFileMaybeEncrypted(dbPath, null);
+ const db = new SQL.Database(fileBuffer);
+ const provenanceByKey = new Map<string, string>();
+ for (const r of filtered) {
+ const stmt = db.prepare('SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1');
+ stmt.bind([r.namespace, r.key]);
+ if (stmt.step()) {
+ provenanceByKey.set(`${r.namespace}::${r.key}`, (stmt.get()[0] as string | null) || 'unknown');
+ }
+ stmt.free();
+ }
+ db.close();
+ filtered = filtered
+ .map(r => ({ ...r, provenanceType: provenanceByKey.get(`${r.namespace}::${r.key}`) || 'unknown' }));
+ if (provenanceFilter?.length) {
+ filtered = filtered.filter(r => provenanceFilter.includes(r.provenanceType!));
+ }
+ } catch {
+ // A requested trust filter fails closed. Unfiltered callers retain
+ // backward-compatible results with an explicit unknown label.
+ filtered = provenanceFilter?.length
+ ? []
+ : filtered.map(r => ({ ...r, provenanceType: 'unknown' }));
+ }
+ }
+
+ if (!provenanceFilter?.length || filtered.length >= limit) {
+ return {
+ success: true,
+ results: filtered.slice(0, limit),
+ searchTime: Date.now() - startTime
+ };
+ }
+ // The ANN window did not contain enough matching provenance rows.
+ // Continue into the filtered SQL path to avoid false-empty/underfilled
+ // results caused by post-filtering only the unfiltered top-k.
}
// Fall back to brute-force SQLite search
@@ -2926,13 +3062,23 @@ export async function searchEntries(options: {
const db = new SQL.Database(fileBuffer);
// Get entries with embeddings
+ // ADR-323: build the WHERE clause incrementally so namespace and
+ // provenance filters compose (both, either, or neither).
+ const whereClauses = [`status = 'active'`];
+ const whereParams: (string)[] = [];
+ if (effectiveNamespace !== 'all') {
+ whereClauses.push('namespace = ?');
+ whereParams.push(effectiveNamespace);
+ }
+ if (provenanceFilter?.length) {
+ whereClauses.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+ whereParams.push(...provenanceFilter);
+ }
const searchStmt = db.prepare(
- effectiveNamespace !== 'all'
- ? `SELECT id, key, namespace, content, embedding FROM memory_entries WHERE status = 'active' AND namespace = ? LIMIT 1000`
- : `SELECT id, key, namespace, content, embedding FROM memory_entries WHERE status = 'active' LIMIT 1000`
+ `SELECT id, key, namespace, content, embedding, provenance_type FROM memory_entries WHERE ${whereClauses.join(' AND ')} LIMIT 1000`
);
- if (effectiveNamespace !== 'all') {
- searchStmt.bind([effectiveNamespace]);
+ if (whereParams.length > 0) {
+ searchStmt.bind(whereParams);
}
const searchRows: unknown[][] = [];
while (searchStmt.step()) {
@@ -2941,11 +3087,11 @@ export async function searchEntries(options: {
searchStmt.free();
const entries = searchRows.length > 0 ? [{ values: searchRows }] : [];
- const results: { id: string; key: string; content: string; score: number; namespace: string }[] = [];
+ const results: { id: string; key: string; content: string; score: number; namespace: string; provenanceType?: string }[] = [];
if (entries[0]?.values) {
for (const row of entries[0].values) {
- const [id, key, ns, content, embeddingJson] = row as [string, string, string, string, string | null];
+ const [id, key, ns, content, embeddingJson, provenanceTypeVal] = row as [string, string, string, string, string | null, string | null];
let score = 0;
@@ -2974,7 +3120,8 @@ export async function searchEntries(options: {
key: key || id.substring(0, 15),
content: (content || '').substring(0, 60) + ((content || '').length > 60 ? '...' : ''),
score,
- namespace: ns || 'default'
+ namespace: ns || 'default',
+ provenanceType: provenanceTypeVal || 'unknown',
});
}
}
@@ -3034,6 +3181,8 @@ export async function listEntries(options: {
dbPath?: string;
/** #2073: When true, include the entry's full `content` string in each result. */
includeContent?: boolean;
+ /** ADR-323: restrict rows to these provenance types. */
+ provenanceFilter?: string[];
}): Promise<{
success: boolean;
entries: {
@@ -3047,10 +3196,23 @@ export async function listEntries(options: {
hasEmbedding: boolean;
/** #2073: Present when `includeContent: true` was requested. */
content?: string;
+ provenanceType?: string;
}[];
total: number;
error?: string;
}> {
+ if (options.provenanceFilter?.length) {
+ const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
+ if (invalid.length > 0) {
+ return {
+ success: false,
+ entries: [],
+ total: 0,
+ error: `Invalid provenance filter value(s): ${invalid.join(', ')} β€” must be one of: ${PROVENANCE_TYPES.join(', ')}`,
+ };
+ }
+ }
+
// ADR-053: Try AgentDB v3 bridge first
const bridge = await getBridge();
if (bridge) {
@@ -3063,7 +3225,8 @@ export async function listEntries(options: {
namespace,
limit = 20,
offset = 0,
- dbPath: customPath
+ dbPath: customPath,
+ provenanceFilter
} = options;
const swarmDir = getMemoryRoot();
@@ -3087,12 +3250,19 @@ export async function listEntries(options: {
// that predate the status column may have NULL after migration.
// See memory-bridge.ts:bridgeListEntries for full context.
// Get total count
- const countStmt = namespace
- ? db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE (status = 'active' OR status IS NULL) AND namespace = ?`)
- : db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE (status = 'active' OR status IS NULL)`);
+ const whereClauses = [`(status = 'active' OR status IS NULL)`];
+ const whereParams: string[] = [];
if (namespace) {
- countStmt.bind([namespace]);
+ whereClauses.push('namespace = ?');
+ whereParams.push(namespace);
}
+ if (provenanceFilter?.length) {
+ whereClauses.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
+ whereParams.push(...provenanceFilter);
+ }
+ const whereSql = whereClauses.join(' AND ');
+ const countStmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${whereSql}`);
+ if (whereParams.length > 0) countStmt.bind(whereParams);
const countRows: unknown[][] = [];
while (countStmt.step()) {
countRows.push(countStmt.get());
@@ -3105,14 +3275,12 @@ export async function listEntries(options: {
const safeLimit = parseInt(String(limit), 10) || 100;
const safeOffset = parseInt(String(offset), 10) || 0;
// #2120 β€” same NULL-as-active acceptance as the count above.
- const listStmt = namespace
- ? db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at FROM memory_entries WHERE (status = 'active' OR status IS NULL) AND namespace = ? ORDER BY updated_at DESC LIMIT ? OFFSET ?`)
- : db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at FROM memory_entries WHERE (status = 'active' OR status IS NULL) ORDER BY updated_at DESC LIMIT ? OFFSET ?`);
- if (namespace) {
- listStmt.bind([namespace, safeLimit, safeOffset]);
- } else {
- listStmt.bind([safeLimit, safeOffset]);
- }
+ const listStmt = db.prepare(
+ `SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type
+ FROM memory_entries WHERE ${whereSql}
+ ORDER BY updated_at DESC LIMIT ? OFFSET ?`
+ );
+ listStmt.bind([...whereParams, safeLimit, safeOffset]);
const listRows: unknown[][] = [];
while (listStmt.step()) {
listRows.push(listStmt.get());
@@ -3129,12 +3297,13 @@ export async function listEntries(options: {
updatedAt: string;
hasEmbedding: boolean;
content?: string;
+ provenanceType?: string;
}[] = [];
if (result[0]?.values) {
for (const row of result[0].values) {
- const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt] = row as [
- string, string, string, string, string | null, number, string, string
+ const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal] = row as [
+ string, string, string, string, string | null, number, string, string, string | null
];
const entry: {
id: string;
@@ -3146,6 +3315,7 @@ export async function listEntries(options: {
updatedAt: string;
hasEmbedding: boolean;
content?: string;
+ provenanceType?: string;
} = {
// #2073: don't truncate id when content is requested β€” callers
// (notably memory_export) need the full id to round-trip via import.
@@ -3156,7 +3326,8 @@ export async function listEntries(options: {
accessCount: accessCount || 0,
createdAt: createdAt || new Date().toISOString(),
updatedAt: updatedAt || new Date().toISOString(),
- hasEmbedding: !!embedding && embedding.length > 10
+ hasEmbedding: !!embedding && embedding.length > 10,
+ provenanceType: provenanceTypeVal || 'unknown'
};
if (options.includeContent) {
entry.content = content || '';
diff --git a/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts b/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts
index 4f0487835d..78895a2c6d 100644
--- a/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts
+++ b/v3/@claude-flow/cli/src/services/harness-flywheel-runtime.ts
@@ -93,6 +93,7 @@ export async function runFlywheelWorker(
maxFailureRate: 0.01,
maxEvaluationCostMicros: 1_000_000,
};
+ // CLI flag opts.proposer takes precedence over RUFLO_FLYWHEEL_PROPOSER.
const proposerMode = opts.proposer
?? ((process.env.RUFLO_FLYWHEEL_PROPOSER as ProposerMode | undefined) ?? 'auto');
if (!['auto', 'local', 'darwin'].includes(proposerMode)) {
diff --git a/v3/docs/adr/ADR-323-typed-memory-provenance.md b/v3/docs/adr/ADR-323-typed-memory-provenance.md
new file mode 100644
index 0000000000..126110d64a
--- /dev/null
+++ b/v3/docs/adr/ADR-323-typed-memory-provenance.md
@@ -0,0 +1,90 @@
+# ADR-323: Typed Memory Provenance in AgentDB
+
+**Status:** Accepted
+**Date:** 2026-07-28
+**Supersedes:** the dream-cycle research PR #2804's `ADR-322-dream-cycle-memory-typed-provenance.md` (closed as superseded β€” its filename collided with the already-merged `ADR-322-metaharness-flywheel-integration.md` from #2817, and its proposed schema target was wrong; see "Correction" below).
+
+## Context
+
+Ruflo's AgentDB (`memory_entries` table) stores every memory entry as flat text with an HNSW vector embedding β€” no typing of *who or what produced it*. In multi-agent deployments, a user's stated claim, an agent's own output, a raw tool result, and a system observation can all land in the same shared namespace (e.g. `collaboration`, `patterns`) indistinguishably.
+
+The 2026-07-28 dream-cycle research report (PR #2804) identified this as "provenance-role collapse," citing:
+- **arXiv 2605.25869 (MemIR, May 2026)** β€” a 3-layer typed representation (raw evidence β†’ retrieval cues β†’ factual claims) with provenance-scoped utilization outperforms flat baselines on LoCoMo + BEAM-100K.
+- **arXiv 2607.01071 (MemSyco-Bench, Jul 2026)** β€” retrieved memories induce sycophancy: agents over-align with user-stated facts at the cost of factual accuracy when provenance isn't enforced at retrieval time.
+
+## Correction to the original dream-cycle proposal
+
+The dream-cycle PR's proposed decision was:
+
+```sql
+ALTER TABLE vector_indexes ADD COLUMN provenance_type TEXT ...
+```
+
+This targets the wrong table. `vector_indexes` is per-*namespace* HNSW index metadata (id, name, dimensions, HNSW params, `total_vectors`) β€” one row per namespace, not one row per memory entry. The correct target, and what this ADR actually implements, is `memory_entries` β€” the per-record table that already carries `tags`/`metadata`/a `type` enum (`semantic`/`episodic`/`procedural`/`working`/`pattern`) in exactly the shape a new typed column belongs in.
+
+The dream-cycle PR (#2804) was closed without merging; this ADR and its implementation replace it, corrected against the real schema.
+
+## Decision
+
+Add a `provenance_type` column to `memory_entries`, mirroring the existing `type` column's convention (`TEXT DEFAULT ... CHECK(...)` on fresh installs; plain `TEXT DEFAULT` β€” no CHECK β€” in the `ensureSchemaColumns()` migration path for existing DBs, consistent with how `type`/`status` are backfilled):
+
+```sql
+-- Fresh installs (memory-initializer.ts CREATE TABLE)
+provenance_type TEXT DEFAULT 'unknown' CHECK(provenance_type IN (
+ 'user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'
+))
+
+-- Existing DBs (ensureSchemaColumns() migration)
+ALTER TABLE memory_entries ADD COLUMN provenance_type TEXT DEFAULT 'unknown'
+```
+
+Application-level validation (`isValidProvenanceType()`, exported from `memory-initializer.ts`) is the actual enforcement mechanism β€” both `storeEntry()` and `bridgeStoreEntry()` reject an invalid value with a typed error before touching either backend, rather than surfacing a raw SQLite CHECK-constraint failure. This is why the migration path omits the CHECK: it's belt-and-suspenders on fresh installs, not the primary guard.
+
+### Write path
+
+- CLI: `memory store --provenance <type>` (choices-validated by the CLI parser itself, then re-validated in `storeEntry()`).
+- MCP tool: `memory_store`'s `provenance_type` parameter.
+- Both default to `'unknown'` when omitted β€” the same value existing (pre-ADR-323) entries get on migration, so there is no behavior change for callers that don't opt in.
+
+### Read path
+
+- CLI: `memory search --provenance-filter <comma-separated types>`.
+- MCP tool: `memory_search`'s `provenance_filter` array parameter.
+- Applies across all three internal search strategies (RaBitQ pre-filter, in-memory HNSW, and the brute-force/BM25-hybrid SQL path) β€” see "Implementation note" below for why this needed a specific design after an initial approach crashed the CLI.
+- Applies to SmartRetrieval (RRF/MMR) by binding the provenance filter into every raw search used for query expansion. The external package does not need to understand the field and cannot widen the caller's trust scope.
+
+## Implementation note: why RaBitQ/HNSW aren't skipped for a filtered search
+
+The first implementation attempt, when a provenance filter was requested, skipped the RaBitQ and in-memory-HNSW acceleration paths entirely (neither carries `provenance_type` on their candidates) and went straight to a brute-force SQL query with the filter applied server-side. This was simpler to write, but reproducibly **crashed the CLI process on exit** (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76` on Windows) β€” after printing correct JSON output. Confirmed via bisection: removing the `if (!provenanceFilter?.length) { …RaBitQ…HNSW… }` skip and always executing those two dynamic-import branches (regardless of whether a filter was requested) eliminated the crash across repeated runs.
+
+The root cause was not fully isolated (a libuv async-handle timing issue tied to skipping the `import('./rabitq-index.js')` / `searchHNSWIndex()` calls, likely interacting with the embedder's own async initialization) β€” rather than ship a fix for a symptom without full confidence in the mechanism, the design was changed to avoid the crashing code shape entirely:
+
+- **RaBitQ path**: `provenance_type` is now fetched in the *same* per-candidate SQL query that already looks up `content`/`embedding` for reranking β€” no extra round-trip, and the branch always runs.
+- **HNSW path**: after the existing threshold filter, a single batched lookup by `(namespace, key)` β€” the schema's natural unique pair β€” fetches `provenance_type` for the candidate set, and results are filtered against it. This branch also always runs; on lookup failure it fails closed (returns no results) rather than silently ignoring the filter.
+- **Brute-force path**: filters directly in the SQL `WHERE` clause (`provenance_type IN (...)`) β€” no candidates to reconcile after the fact.
+
+Net effect: correctness is now handled per-path rather than by bypassing acceleration, and the crash reproduced 100% of the time before the fix and 0% of the time (multiple repeated runs) after it.
+
+## Consequences
+
+**Positive:**
+- Retrieval can now distinguish "the user said X" from "an agent inferred X" from "a tool reported X," addressing MemSyco-Bench's sycophancy finding directly.
+- Fully backward compatible: existing entries read as `'unknown'`; no caller is required to pass a provenance type.
+- No acceleration path (RaBitQ/HNSW) is sacrificed for provenance-filtered queries.
+
+**Negative / open gaps (stated plainly, not glossed over):**
+- Filtering an ANN candidate window can underfill the requested page. Filtered RaBitQ/HNSW searches therefore fall through to the authoritative filtered SQL scan whenever the accelerated window does not fill the requested limit.
+- Plugin SDK enforcement (requiring official plugins to pass `provenance_type` on writes, with a `pre-edit` lint gate) β€” proposed in the original dream-cycle research β€” is **not implemented** in this ADR. Scoped out as a separate, larger change touching the plugin SDK contract.
+- The `audit` worker webhook-trigger idea from the same dream-cycle report is unrelated to provenance typing and is not part of this ADR.
+- No governance/rollback layer (the dream-cycle report's AOEP-v0 reference) β€” this ADR is the typing primitive only, not a full governance system.
+
+## References
+
+- arXiv 2605.25869 β€” MemIR: Typed Memory Intermediate Representation
+- arXiv 2607.01071 β€” MemSyco-Bench: Sycophancy in Agent Memory
+- Dream-cycle research: PR #2804 (closed, superseded by this ADR)
+- `v3/@claude-flow/cli/src/memory/memory-initializer.ts` β€” schema, `storeEntry()`, `searchEntries()`
+- `v3/@claude-flow/cli/src/memory/memory-bridge.ts` β€” `bridgeStoreEntry()`, `bridgeSearchEntries()`
+- `v3/@claude-flow/cli/src/commands/memory.ts` β€” `memory store --provenance`, `memory search --provenance-filter`
+- `v3/@claude-flow/cli/src/mcp-tools/memory-tools.ts`, `v3/@claude-flow/cli-core/src/mcp-tools/memory-defs.ts` β€” MCP tool schemas
+- `v3/@claude-flow/cli/__tests__/adr-323-memory-provenance.test.ts` β€” end-to-end regression guard, including the crash-repro test
diff --git a/v3/docs/adr/README.md b/v3/docs/adr/README.md
index 592ed4903d..2ef956937b 100644
--- a/v3/docs/adr/README.md
+++ b/v3/docs/adr/README.md
@@ -40,6 +40,7 @@ All ADRs are located in [`/v3/implementation/adrs/`](../../implementation/adrs/)
| [ADR-309](ADR-309-funnel-governance-privacy-ecosystem.md) | Funnel Governance, Privacy, and Ecosystem Policy | Proposed |
| [ADR-310](ADR-310-funnel-rollout-measurement-emergency-controls.md) | Funnel Rollout, Measurement, and Emergency Controls | Proposed |
| [ADR-320](ADR-320-mcp-composition-inspector-channel-guardrails.md) | MCP Tool Composition Inspector + Inter-Agent Channel Guardrails | Accepted |
+| [ADR-323](ADR-323-typed-memory-provenance.md) | Typed Memory Provenance in AgentDB (MemIR-style claim typing, corrects #2804's dream-cycle proposal) | Accepted |
## Summary Documents