@xopcai/xopc 0.0.136 → 0.0.138

package/dist/src/storage/sqlite/memory-records-repository.d.ts

@@ -1,4 +1,4 @@
-import type { MemoryKind, MemoryRecord, MemorySensitivity, MemorySearchResult, MemorySignal, MemoryStatus } from '../../agent/memory/types.js';
+import type { MemoryDisclosurePolicy, MemoryDurability, MemoryExplicitness, MemoryKind, MemoryRecord, MemorySensitivity, MemorySearchResult, MemorySignal, MemoryStatus } from '../../agent/memory/types.js';
 export interface UpsertMemoryRecordInput {
     id?: string;
     providerId: string;
@@ -8,14 +8,23 @@ export interface UpsertMemoryRecordInput {
     sessionKey?: string;
     projectId?: string;
     content: string;
+    canonicalKey?: string;
     source?: MemoryRecord['source'];
     confidence?: number;
     tags?: string[];
     status?: MemoryStatus;
     sensitivity?: MemorySensitivity;
+    explicitness?: MemoryExplicitness;
+    durability?: MemoryDurability;
+    importance?: number;
+    disclosurePolicy?: MemoryDisclosurePolicy;
     evidence?: MemoryRecord['evidence'];
+    validFrom?: string;
+    validTo?: string;
     reviewAfter?: string;
     expiresAt?: string;
+    supersedesRecordId?: string;
+    conflictGroupId?: string;
     nowMs?: number;
 }
 export interface ListMemoryRecordsOptions {
@@ -25,6 +34,7 @@ export interface ListMemoryRecordsOptions {
     projectId?: string;
     kind?: MemoryKind;
     status?: MemoryStatus;
+    canonicalKey?: string;
     limit?: number;
     offset?: number;
 }
@@ -70,9 +80,10 @@ export interface MemoryTraceFeedback {
     updatedAt?: string;
 }
 export interface AppendMemoryTraceEventInput {
+    traceId?: string;
     sessionKey?: string;
     turnId?: string;
-    phase: 'search' | 'read' | 'write' | 'update' | 'delete' | 'sync' | 'inject' | 'test';
+    phase: 'search' | 'read' | 'write' | 'update' | 'delete' | 'sync' | 'inject' | 'test' | 'understanding' | 'remediation';
     providerId: string;
     request?: unknown;
     resultCount?: number;
@@ -91,6 +102,14 @@ export interface SetMemoryTraceFeedbackInput {
     };
     nowMs?: number;
 }
+export interface SetLatestMemoryInjectFeedbackInput {
+    sessionKey: string;
+    beforeMs?: number;
+    requireSelectedRecords?: boolean;
+    feedback: SetMemoryTraceFeedbackInput['feedback'];
+    nowMs?: number;
+}
+export type FindLatestMemoryInjectTraceInput = Pick<SetLatestMemoryInjectFeedbackInput, 'sessionKey' | 'beforeMs' | 'requireSelectedRecords'>;
 export interface MemoryTraceEventPayload {
     traceId: string;
     sessionKey?: string;
@@ -103,9 +122,19 @@ export interface MemoryTraceEventPayload {
     skippedReason?: string;
     error?: string;
     feedback?: MemoryTraceFeedback;
+    remediation?: MemoryFeedbackRemediationResult;
     durationMs: number;
     createdAt: string;
 }
+export interface MemoryFeedbackRemediationResult {
+    triggerTraceId: string;
+    evaluatedRecordIds: string[];
+    needsReviewRecordIds: string[];
+}
+export declare const USER_UNDERSTANDING_REMEDIATION_POLICY: {
+    readonly minNotHelpful: 2;
+    readonly confidencePenalty: 0.2;
+};
 export interface MemoryRecallFeedbackSummary {
     recordId: string;
     helpful: number;
@@ -116,6 +145,47 @@ export interface MemoryRecallFeedbackSummary {
     averageScore: number | null;
     lastFeedbackAt?: string;
 }
+export interface UserUnderstandingQualityMetrics {
+    agentId?: string;
+    windowDays: number;
+    since: string;
+    attempts: {
+        total: number;
+        turn: number;
+        background: number;
+    };
+    candidates: {
+        proposed: number;
+        created: number;
+        deduplicated: number;
+        rejectedByPolicy: number;
+    };
+    records: {
+        total: number;
+        candidate: number;
+        active: number;
+        rejected: number;
+        needsReview: number;
+        stale: number;
+        archived: number;
+        agingCandidates: number;
+        explicit: number;
+        inferred: number;
+        averageConfidence: number | null;
+    };
+    decisions: {
+        total: number;
+        acceptanceRate: number | null;
+    };
+    recall: {
+        total: number;
+        helpful: number;
+        notHelpful: number;
+        mixed: number;
+        irrelevant: number;
+        helpfulRate: number | null;
+    };
+}
 export declare function upsertMemoryRecord(input: UpsertMemoryRecordInput): MemoryRecord;
 export declare function getMemoryRecord(recordId: string): MemoryRecord | null;
 export declare function listMemoryRecords(options?: ListMemoryRecordsOptions): MemoryRecord[];
@@ -139,9 +209,17 @@ export declare function listMemoryTraceEvents(options?: {
     limit?: number;
 }): MemoryTraceEventPayload[];
 export declare function setMemoryTraceFeedback(input: SetMemoryTraceFeedbackInput): MemoryTraceEventPayload | null;
+export declare function findLatestMemoryInjectTrace(input: FindLatestMemoryInjectTraceInput): MemoryTraceEventPayload | null;
+export declare function setLatestMemoryInjectFeedback(input: SetLatestMemoryInjectFeedbackInput): MemoryTraceEventPayload | null;
 export declare function summarizeMemoryRecallFeedback(options?: {
     recordId?: string;
     providerId?: string;
     sessionKey?: string;
     limit?: number;
 }): MemoryRecallFeedbackSummary[];
+export declare function summarizeUserUnderstandingQuality(options?: {
+    agentId?: string;
+    windowDays?: number;
+    agingCandidateDays?: number;
+    nowMs?: number;
+}): UserUnderstandingQualityMetrics;

package/dist/src/storage/sqlite/memory-records-repository.js

@@ -2,6 +2,10 @@ import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
 import { escapeFts5Query } from "./fts.js";
 import { randomUUID } from "node:crypto";
 //#region src/storage/sqlite/memory-records-repository.ts
+const USER_UNDERSTANDING_REMEDIATION_POLICY = {
+	minNotHelpful: 2,
+	confidencePenalty: .2
+};
 function parseStringArray(json) {
 	try {
 		const parsed = JSON.parse(json);
@@ -90,6 +94,7 @@ function rowToRecord(row) {
 		id: row.record_id,
 		kind: row.kind,
 		status: row.status,
+		...row.canonical_key ? { canonicalKey: row.canonical_key } : {},
 		scope: {
 			agentId: row.agent_id,
 			...row.workspace_id ? { workspaceId: row.workspace_id } : {},
@@ -100,9 +105,17 @@ function rowToRecord(row) {
 		source: parseSource(row.source_json),
 		...row.confidence != null ? { confidence: row.confidence } : {},
 		sensitivity: row.sensitivity,
+		explicitness: row.explicitness,
+		durability: row.durability,
+		importance: row.importance,
+		disclosurePolicy: row.disclosure_policy,
 		evidence: parseEvidence(row.evidence_json),
+		...timestampToIso(row.valid_from) ? { validFrom: timestampToIso(row.valid_from) } : {},
+		...timestampToIso(row.valid_to) ? { validTo: timestampToIso(row.valid_to) } : {},
 		...timestampToIso(row.review_after) ? { reviewAfter: timestampToIso(row.review_after) } : {},
 		...timestampToIso(row.expires_at) ? { expiresAt: timestampToIso(row.expires_at) } : {},
+		...row.supersedes_record_id ? { supersedesRecordId: row.supersedes_record_id } : {},
+		...row.conflict_group_id ? { conflictGroupId: row.conflict_group_id } : {},
 		createdAt: new Date(row.created_at).toISOString(),
 		updatedAt: new Date(row.updated_at).toISOString(),
 		tags: parseStringArray(row.tags_json)
@@ -123,6 +136,12 @@ function upsertMemoryRecord(input) {
 	const now = input.nowMs ?? Date.now();
 	const status = input.status ?? "active";
 	const sensitivity = input.sensitivity ?? "normal";
+	const explicitness = input.explicitness ?? "inferred";
+	const durability = input.durability ?? "durable";
+	const importance = Math.max(0, Math.min(1, input.importance ?? .5));
+	const disclosurePolicy = input.disclosurePolicy ?? "referenceable";
+	const validFrom = parseOptionalTimestamp(input.validFrom);
+	const validTo = parseOptionalTimestamp(input.validTo);
 	const reviewAfter = parseOptionalTimestamp(input.reviewAfter);
 	const expiresAt = parseOptionalTimestamp(input.expiresAt);
 	const source = {
@@ -133,8 +152,10 @@ function upsertMemoryRecord(input) {
 		db.prepare(`INSERT INTO memory_records (
         record_id, provider_id, kind, agent_id, workspace_id, session_key, project_id,
         content, source_json, confidence, tags_json, status, sensitivity,
-        evidence_json, review_after, expires_at, created_at, updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        evidence_json, canonical_key, explicitness, durability, importance,
+        disclosure_policy, valid_from, valid_to, review_after, expires_at,
+        supersedes_record_id, conflict_group_id, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(record_id) DO UPDATE SET
         provider_id = excluded.provider_id,
         kind = excluded.kind,
@@ -149,18 +170,44 @@ function upsertMemoryRecord(input) {
         status = excluded.status,
         sensitivity = excluded.sensitivity,
         evidence_json = excluded.evidence_json,
+        canonical_key = excluded.canonical_key,
+        explicitness = excluded.explicitness,
+        durability = excluded.durability,
+        importance = excluded.importance,
+        disclosure_policy = excluded.disclosure_policy,
+        valid_from = excluded.valid_from,
+        valid_to = excluded.valid_to,
         review_after = excluded.review_after,
         expires_at = excluded.expires_at,
-        updated_at = excluded.updated_at`).run(id, input.providerId, input.kind, input.agentId, input.workspaceId ?? null, input.sessionKey ?? null, input.projectId ?? null, input.content, JSON.stringify(source), input.confidence ?? null, JSON.stringify(input.tags ?? []), status, sensitivity, JSON.stringify(input.evidence ?? []), reviewAfter, expiresAt, now, now);
+        supersedes_record_id = excluded.supersedes_record_id,
+        conflict_group_id = excluded.conflict_group_id,
+        updated_at = excluded.updated_at`).run(id, input.providerId, input.kind, input.agentId, input.workspaceId ?? null, input.sessionKey ?? null, input.projectId ?? null, input.content, JSON.stringify(source), input.confidence ?? null, JSON.stringify(input.tags ?? []), status, sensitivity, JSON.stringify(input.evidence ?? []), input.canonicalKey ?? null, explicitness, durability, importance, disclosurePolicy, validFrom, validTo, reviewAfter, expiresAt, input.supersedesRecordId ?? null, input.conflictGroupId ?? null, now, now);
 		upsertMemoryRecordFts(db, {
 			...input,
 			id
 		});
+		if (input.supersedesRecordId && input.supersedesRecordId !== id) {
+			if (db.prepare(`SELECT 1 FROM memory_records WHERE record_id = ?`).get(input.supersedesRecordId)) {
+				db.prepare(`INSERT INTO memory_relations (
+            relation_id, from_record_id, relation_type, to_record_id,
+            confidence, valid_from, valid_to, created_at, updated_at
+          ) VALUES (?, ?, 'supersedes', ?, ?, ?, NULL, ?, ?)
+          ON CONFLICT(from_record_id, relation_type, to_record_id) DO UPDATE SET
+            confidence = excluded.confidence,
+            valid_from = excluded.valid_from,
+            valid_to = NULL,
+            updated_at = excluded.updated_at`).run(randomUUID(), id, input.supersedesRecordId, input.confidence ?? 1, validFrom ?? now, now, now);
+				if (status === "active") db.prepare(`UPDATE memory_records
+             SET status = 'archived', valid_to = COALESCE(valid_to, ?), updated_at = ?
+             WHERE record_id = ? AND status IN ('active', 'needs_review', 'stale')`).run(now, now, input.supersedesRecordId);
+			}
+		}
 	});
 	return {
 		id,
 		kind: input.kind,
 		status,
+		...input.canonicalKey ? { canonicalKey: input.canonicalKey } : {},
 		scope: {
 			agentId: input.agentId,
 			...input.workspaceId ? { workspaceId: input.workspaceId } : {},
@@ -171,9 +218,17 @@ function upsertMemoryRecord(input) {
 		source,
 		...input.confidence != null ? { confidence: input.confidence } : {},
 		sensitivity,
+		explicitness,
+		durability,
+		importance,
+		disclosurePolicy,
 		evidence: input.evidence ?? [],
+		...validFrom != null ? { validFrom: new Date(validFrom).toISOString() } : {},
+		...validTo != null ? { validTo: new Date(validTo).toISOString() } : {},
 		...reviewAfter != null ? { reviewAfter: new Date(reviewAfter).toISOString() } : {},
 		...expiresAt != null ? { expiresAt: new Date(expiresAt).toISOString() } : {},
+		...input.supersedesRecordId ? { supersedesRecordId: input.supersedesRecordId } : {},
+		...input.conflictGroupId ? { conflictGroupId: input.conflictGroupId } : {},
 		createdAt: new Date(now).toISOString(),
 		updatedAt: new Date(now).toISOString(),
 		tags: input.tags ?? []
@@ -210,6 +265,10 @@ function listMemoryRecords(options = {}) {
 		where.push("status = ?");
 		params.push(options.status);
 	}
+	if (options.canonicalKey) {
+		where.push("canonical_key = ?");
+		params.push(options.canonicalKey);
+	}
 	const limit = Math.max(1, Math.min(500, options.limit ?? 100));
 	const offset = Math.max(0, options.offset ?? 0);
 	return getSqliteDatabase().prepare(`SELECT * FROM memory_records
@@ -357,7 +416,7 @@ function setMemoryProviderState(providerId, scopeKey, state) {
 	});
 }
 function appendMemoryTraceEvent(input) {
-	const id = randomUUID();
+	const id = input.traceId ?? randomUUID();
 	const now = input.nowMs ?? Date.now();
 	const feedback = input.feedback ? normalizeMemoryTraceFeedback(input.feedback, now) : void 0;
 	runSqliteWriteTransaction((db) => {
@@ -392,13 +451,100 @@ function listMemoryTraceEvents(options = {}) {
 function setMemoryTraceFeedback(input) {
 	const existing = getSqliteDatabase().prepare(`SELECT * FROM memory_trace_events WHERE trace_id = ?`).get(input.traceId);
 	if (!existing) return null;
-	const feedback = normalizeMemoryTraceFeedback(input.feedback, input.nowMs, parseMemoryTraceFeedback(existing.feedback_json));
+	const nowMs = input.nowMs ?? Date.now();
+	const feedback = normalizeMemoryTraceFeedback(input.feedback, nowMs, parseMemoryTraceFeedback(existing.feedback_json));
+	let remediation;
 	runSqliteWriteTransaction((db) => {
 		db.prepare(`UPDATE memory_trace_events SET feedback_json = ? WHERE trace_id = ?`).run(JSON.stringify(feedback), input.traceId);
+		remediation = reconcileUserUnderstandingFeedback(db, existing, feedback, nowMs);
 	});
-	return memoryTraceRowToPayload({
-		...existing,
-		feedback_json: JSON.stringify(feedback)
+	return {
+		...memoryTraceRowToPayload({
+			...existing,
+			feedback_json: JSON.stringify(feedback)
+		}),
+		...remediation ? { remediation } : {}
+	};
+}
+function reconcileUserUnderstandingFeedback(db, trace, feedback, nowMs) {
+	if (trace.phase !== "inject" || feedback.outcome !== "not_helpful") return void 0;
+	const explicitCorrection = feedback.source === "system" && feedback.reason === "detected_explicit_user_correction";
+	const evaluatedRecordIds = [];
+	const needsReviewRecordIds = [];
+	const actions = [];
+	for (const recordId of new Set(parseStringArray(trace.selected_record_ids_json))) {
+		const record = db.prepare(`SELECT * FROM memory_records
+       WHERE record_id = ?
+         AND status = 'active'
+         AND tags_json LIKE '%\"user-understanding\"%'`).get(recordId);
+		if (!record) continue;
+		evaluatedRecordIds.push(recordId);
+		const feedbackRows = db.prepare(`SELECT trace.feedback_json
+       FROM memory_trace_events AS trace
+       JOIN json_each(trace.selected_record_ids_json) AS selected
+         ON selected.value = ?
+       WHERE trace.phase = 'inject'`).all(recordId);
+		let helpful = 0;
+		let notHelpful = 0;
+		for (const row of feedbackRows) {
+			const recordFeedback = parseMemoryTraceFeedback(row.feedback_json);
+			if (recordFeedback?.outcome === "helpful") helpful += 1;
+			if (recordFeedback?.outcome === "not_helpful") notHelpful += 1;
+		}
+		if (!explicitCorrection && (notHelpful < USER_UNDERSTANDING_REMEDIATION_POLICY.minNotHelpful || notHelpful <= helpful)) continue;
+		const nextConfidence = record.confidence == null ? null : Math.round(Math.max(.1, record.confidence - USER_UNDERSTANDING_REMEDIATION_POLICY.confidencePenalty) * 1e3) / 1e3;
+		if (db.prepare(`UPDATE memory_records
+       SET status = 'needs_review', confidence = ?, review_after = ?, updated_at = ?
+       WHERE record_id = ? AND status = 'active'`).run(nextConfidence, nowMs, nowMs, recordId).changes === 0) continue;
+		needsReviewRecordIds.push(recordId);
+		actions.push({
+			recordId,
+			previousStatus: record.status,
+			nextStatus: "needs_review",
+			previousConfidence: record.confidence,
+			nextConfidence,
+			helpful,
+			notHelpful
+		});
+	}
+	const result = {
+		triggerTraceId: trace.trace_id,
+		evaluatedRecordIds,
+		needsReviewRecordIds
+	};
+	if (needsReviewRecordIds.length > 0) db.prepare(`INSERT INTO memory_trace_events (
+        trace_id, session_key, turn_id, phase, provider_id, request_json,
+        result_count, selected_record_ids_json, skipped_reason, error,
+        feedback_json, duration_ms, created_at
+      ) VALUES (?, ?, ?, 'remediation', 'user-understanding', ?, ?, ?, NULL, NULL, '{}', 0, ?)`).run(randomUUID(), trace.session_key, trace.turn_id, JSON.stringify({
+		triggerTraceId: trace.trace_id,
+		reason: explicitCorrection ? "explicit_user_correction" : "repeated_not_helpful_feedback",
+		policy: USER_UNDERSTANDING_REMEDIATION_POLICY,
+		actions
+	}), needsReviewRecordIds.length, JSON.stringify(needsReviewRecordIds), nowMs);
+	return result;
+}
+function findLatestMemoryInjectTrace(input) {
+	const row = getSqliteDatabase().prepare(`SELECT * FROM memory_trace_events
+       WHERE ${[
+		`session_key = ?`,
+		`phase = 'inject'`,
+		`created_at <= ?`
+	].join(" AND ")}
+       ORDER BY created_at DESC
+       LIMIT 1`).get(input.sessionKey, input.beforeMs ?? Date.now());
+	if (!row) return null;
+	const trace = memoryTraceRowToPayload(row);
+	if (input.requireSelectedRecords && trace.selectedRecordIds.length === 0) return null;
+	return trace;
+}
+function setLatestMemoryInjectFeedback(input) {
+	const row = findLatestMemoryInjectTrace(input);
+	if (!row) return null;
+	return setMemoryTraceFeedback({
+		traceId: row.traceId,
+		feedback: input.feedback,
+		nowMs: input.nowMs
 	});
 }
 function summarizeMemoryRecallFeedback(options = {}) {
@@ -451,6 +597,122 @@ function summarizeMemoryRecallFeedback(options = {}) {
 	}
 	return [...summaries.values()].map(({ scoreTotal: _scoreTotal, scoreCount: _scoreCount, ...summary }) => summary).sort((a, b) => b.total - a.total);
 }
+function boundedMetricCount(value) {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+function metricRate(numerator, denominator) {
+	return denominator > 0 ? Math.round(numerator / denominator * 1e4) / 1e4 : null;
+}
+function summarizeUserUnderstandingQuality(options = {}) {
+	const nowMs = options.nowMs ?? Date.now();
+	const windowDays = Math.max(1, Math.min(365, Math.floor(options.windowDays ?? 30)));
+	const sinceMs = nowMs - windowDays * 24 * 60 * 60 * 1e3;
+	const agingCutoffMs = nowMs - Math.max(1, Math.min(windowDays, Math.floor(options.agingCandidateDays ?? 7))) * 24 * 60 * 60 * 1e3;
+	const db = getSqliteDatabase();
+	const agentWhere = options.agentId ? "AND agent_id = ?" : "";
+	const recordRows = db.prepare(`SELECT record_id, status, explicitness, confidence, created_at, updated_at
+     FROM memory_records
+     WHERE tags_json LIKE '%"user-understanding"%'
+       ${agentWhere}`).all(...options.agentId ? [options.agentId] : []);
+	const records = {
+		total: recordRows.length,
+		candidate: 0,
+		active: 0,
+		rejected: 0,
+		needsReview: 0,
+		stale: 0,
+		archived: 0,
+		agingCandidates: 0,
+		explicit: 0,
+		inferred: 0,
+		averageConfidence: null
+	};
+	let confidenceTotal = 0;
+	let confidenceCount = 0;
+	const understandingRecordIds = /* @__PURE__ */ new Set();
+	for (const row of recordRows) {
+		understandingRecordIds.add(row.record_id);
+		if (row.status === "candidate") records.candidate += 1;
+		if (row.status === "active") records.active += 1;
+		if (row.status === "rejected") records.rejected += 1;
+		if (row.status === "needs_review") records.needsReview += 1;
+		if (row.status === "stale") records.stale += 1;
+		if (row.status === "archived") records.archived += 1;
+		if (row.status === "candidate" && row.created_at <= agingCutoffMs) records.agingCandidates += 1;
+		if (row.explicitness === "explicit") records.explicit += 1;
+		if (row.explicitness === "inferred") records.inferred += 1;
+		if (typeof row.confidence === "number") {
+			confidenceTotal += row.confidence;
+			confidenceCount += 1;
+		}
+	}
+	records.averageConfidence = confidenceCount > 0 ? Math.round(confidenceTotal / confidenceCount * 1e4) / 1e4 : null;
+	const attempts = {
+		total: 0,
+		turn: 0,
+		background: 0
+	};
+	const candidates = {
+		proposed: 0,
+		created: 0,
+		deduplicated: 0,
+		rejectedByPolicy: 0
+	};
+	const understandingTraces = db.prepare(`SELECT request_json FROM memory_trace_events
+     WHERE phase = 'understanding' AND created_at >= ?`).all(sinceMs);
+	for (const row of understandingTraces) {
+		const parsed = parseJsonValue(row.request_json, {});
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+		const request = parsed;
+		if (options.agentId && request.agentId !== options.agentId) continue;
+		attempts.total += 1;
+		if (request.source === "turn") attempts.turn += 1;
+		if (request.source === "background") attempts.background += 1;
+		candidates.proposed += boundedMetricCount(request.proposed);
+		candidates.created += boundedMetricCount(request.created);
+		candidates.deduplicated += boundedMetricCount(request.deduplicated);
+		candidates.rejectedByPolicy += boundedMetricCount(request.rejected);
+	}
+	const recall = {
+		total: 0,
+		helpful: 0,
+		notHelpful: 0,
+		mixed: 0,
+		irrelevant: 0,
+		helpfulRate: null
+	};
+	if (understandingRecordIds.size > 0) {
+		const recallRows = db.prepare(`SELECT selected_record_ids_json, feedback_json FROM memory_trace_events
+       WHERE phase IN ('search', 'inject') AND created_at >= ?`).all(sinceMs);
+		for (const row of recallRows) {
+			const feedback = parseMemoryTraceFeedback(row.feedback_json);
+			if (!feedback) continue;
+			if (!parseStringArray(row.selected_record_ids_json).some((recordId) => understandingRecordIds.has(recordId))) continue;
+			recall.total += 1;
+			if (feedback.outcome === "helpful") recall.helpful += 1;
+			if (feedback.outcome === "not_helpful") recall.notHelpful += 1;
+			if (feedback.outcome === "mixed") recall.mixed += 1;
+			if (feedback.outcome === "irrelevant") recall.irrelevant += 1;
+		}
+	}
+	recall.helpfulRate = metricRate(recall.helpful, recall.total);
+	const recentDecisions = recordRows.filter((row) => (row.status === "active" || row.status === "rejected") && row.updated_at >= sinceMs);
+	const acceptedDecisions = recentDecisions.filter((row) => row.status === "active").length;
+	const decisionTotal = recentDecisions.length;
+	return {
+		...options.agentId ? { agentId: options.agentId } : {},
+		windowDays,
+		since: new Date(sinceMs).toISOString(),
+		attempts,
+		candidates,
+		records,
+		decisions: {
+			total: decisionTotal,
+			acceptanceRate: metricRate(acceptedDecisions, decisionTotal)
+		},
+		recall
+	};
+}
 function parseJsonValue(json, fallback) {
 	try {
 		return JSON.parse(json);
@@ -459,6 +721,6 @@ function parseJsonValue(json, fallback) {
 	}
 }
 //#endregion
-export { appendMemorySignal, appendMemoryTraceEvent, deleteMemoryRecord, getMemoryProviderState, getMemoryRecord, listMemoryRecords, listMemorySignals, listMemoryTraceEvents, searchMemoryRecords, setMemoryProviderState, setMemoryTraceFeedback, summarizeMemoryRecallFeedback, upsertMemoryRecord };
+export { USER_UNDERSTANDING_REMEDIATION_POLICY, appendMemorySignal, appendMemoryTraceEvent, deleteMemoryRecord, findLatestMemoryInjectTrace, getMemoryProviderState, getMemoryRecord, listMemoryRecords, listMemorySignals, listMemoryTraceEvents, searchMemoryRecords, setLatestMemoryInjectFeedback, setMemoryProviderState, setMemoryTraceFeedback, summarizeMemoryRecallFeedback, summarizeUserUnderstandingQuality, upsertMemoryRecord };
 
 //# sourceMappingURL=memory-records-repository.js.map