π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 SETid = 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_typeFROM 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_typeFROM memory_entries- WHERE ${statusFilter} ${nsFilter}+ WHERE ${statusFilter} ${extraFilter}ORDER BY updated_at DESCLIMIT ? 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.tsindex 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 objectowner_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'+ )),+-- Timestampscreated_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 firstconst 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 firstconst 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 firstconst 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.tsindex 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.mdnew file mode 100644index 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 testdiff --git a/v3/docs/adr/README.md b/v3/docs/adr/README.mdindex 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