memorix 1.4.0 → 1.4.2

package/src/knowledge/context-assembly.ts

@@ -43,6 +43,22 @@ export interface ContextReceiptOmission {
   count: number;
 }
 
+export interface ContextReceiptGovernanceDecision {
+  kind: ContextCandidateKind;
+  id?: string;
+  disposition: 'include' | 'compact' | 'defer' | 'exclude';
+  reasons: string[];
+}
+
+/** Privacy-safe evidence qualification, never appended to the agent prompt. */
+export interface ContextReceiptGovernance {
+  /** Current implementation qualifies optional memory/knowledge, not caller task facts. */
+  scope: 'optional-evidence';
+  mode: 'abstain' | 'card' | 'workset';
+  decisions: ContextReceiptGovernanceDecision[];
+  cautions: string[];
+}
+
 export interface ContextReceipt {
   version: '1.3';
   target: ContextDeliveryTarget;
@@ -53,6 +69,7 @@ export interface ContextReceipt {
   };
   selected: ContextReceiptSelection[];
   omitted: ContextReceiptOmission[];
+  governance?: ContextReceiptGovernance;
   scheduledActions: string[];
 }
 
@@ -92,6 +109,14 @@ export function formatContextReceipt(receipt: ContextReceipt): string {
     }
   }
 
+  if (receipt.governance?.decisions.length) {
+    lines.push('', 'Optional evidence qualification');
+    for (const item of receipt.governance.decisions.slice(0, 20)) {
+      const id = item.id ? ` ${item.id}` : '';
+      lines.push(`- ${item.kind}${id}: ${item.disposition} (${item.reasons.join(', ')})`);
+    }
+  }
+
   if (receipt.scheduledActions.length > 0) {
     lines.push('', 'Scheduled follow-up');
     for (const action of receipt.scheduledActions) lines.push(`- ${action}`);

package/src/knowledge/governor.ts

@@ -0,0 +1,156 @@
+import type {
+  ContextCandidateFreshness,
+  ContextCandidateKind,
+  ContextCandidateTrust,
+} from './context-assembly.js';
+
+/**
+ * A small, serializable description of an item competing for agent context.
+ * This is intentionally independent from stores and prompt rendering so every
+ * delivery surface can apply the same evidence rules.
+ */
+export interface GovernanceCandidate {
+  kind: ContextCandidateKind;
+  id?: string;
+  estimatedTokens: number;
+  relevance: number;
+  scopeAllowed: boolean;
+  freshness?: ContextCandidateFreshness;
+  trust?: ContextCandidateTrust;
+  quality?: 'verified' | 'probationary' | 'degraded' | 'blocked';
+  conflict?: 'none' | 'possible' | 'confirmed';
+  evidenceCount?: number;
+}
+
+export type GovernanceDisposition = 'include' | 'compact' | 'defer' | 'exclude';
+
+export type GovernanceReason =
+  | 'scope-forbidden'
+  | 'confirmed-conflict'
+  | 'blocked-quality'
+  | 'degraded-quality'
+  | 'stale-evidence'
+  | 'unknown-freshness'
+  | 'possible-conflict'
+  | 'probationary-evidence'
+  | 'token-budget'
+  | 'current-source-backed-evidence'
+  | 'relevant-evidence'
+  | 'no-qualified-evidence';
+
+export interface GovernanceDecision {
+  candidate: GovernanceCandidate;
+  disposition: GovernanceDisposition;
+  reasons: GovernanceReason[];
+}
+
+export interface GovernancePlan {
+  mode: 'abstain' | 'card' | 'workset';
+  budget: { maxTokens: number; usedTokens: number };
+  decisions: GovernanceDecision[];
+  cautions: GovernanceReason[];
+}
+
+function clampRelevance(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+
+function classify(candidate: GovernanceCandidate): Omit<GovernanceDecision, 'candidate'> {
+  const freshness = candidate.freshness ?? 'unknown';
+  const trust = candidate.trust ?? 'historical';
+  const quality = candidate.quality ?? 'probationary';
+  const conflict = candidate.conflict ?? 'none';
+
+  if (!candidate.scopeAllowed) {
+    return { disposition: 'exclude', reasons: ['scope-forbidden'] };
+  }
+  if (conflict === 'confirmed') {
+    return { disposition: 'exclude', reasons: ['confirmed-conflict'] };
+  }
+  if (quality === 'blocked') {
+    return { disposition: 'exclude', reasons: ['blocked-quality'] };
+  }
+  if (quality === 'degraded') {
+    return { disposition: 'defer', reasons: ['degraded-quality'] };
+  }
+  if (freshness === 'stale') {
+    return { disposition: 'defer', reasons: ['stale-evidence'] };
+  }
+
+  const reasons: GovernanceReason[] = [];
+  let disposition: GovernanceDisposition = 'include';
+  if (freshness === 'unknown') {
+    disposition = 'compact';
+    reasons.push('unknown-freshness');
+  }
+  if (conflict === 'possible') {
+    disposition = 'compact';
+    reasons.push('possible-conflict');
+  }
+  if (quality === 'probationary') {
+    disposition = 'compact';
+    reasons.push('probationary-evidence');
+  }
+  if (disposition === 'include' && freshness === 'current' && trust === 'source-backed') {
+    reasons.push('current-source-backed-evidence');
+  } else if (reasons.length === 0) {
+    reasons.push('relevant-evidence');
+  }
+  return { disposition, reasons };
+}
+
+function priority(decision: GovernanceDecision): number {
+  const dispositionWeight: Record<GovernanceDisposition, number> = {
+    include: 3,
+    compact: 2,
+    defer: 1,
+    exclude: 0,
+  };
+  const evidence = Math.min(3, decision.candidate.evidenceCount ?? 0) / 10;
+  return dispositionWeight[decision.disposition] + clampRelevance(decision.candidate.relevance) + evidence;
+}
+
+/**
+ * Decide which evidence may enter a bounded context response. The result never
+ * mutates memory and deliberately prefers an explicit abstention to a generic
+ * history dump.
+ */
+export function governContextCandidates(
+  candidates: GovernanceCandidate[],
+  maxTokens: number,
+): GovernancePlan {
+  const safeBudget = Math.max(0, Math.floor(maxTokens));
+  const decisions = candidates.map(candidate => ({ candidate, ...classify(candidate) }));
+  const eligible = decisions
+    .filter(decision => decision.disposition === 'include' || decision.disposition === 'compact')
+    .sort((left, right) => priority(right) - priority(left));
+  let usedTokens = 0;
+
+  for (const decision of eligible) {
+    const tokens = Math.max(0, Math.ceil(decision.candidate.estimatedTokens));
+    if (usedTokens + tokens <= safeBudget) {
+      usedTokens += tokens;
+      continue;
+    }
+    decision.disposition = 'defer';
+    decision.reasons = [...decision.reasons, 'token-budget'];
+  }
+
+  const delivered = decisions.filter(decision => decision.disposition === 'include' || decision.disposition === 'compact');
+  const mode = delivered.length === 0
+    ? 'abstain'
+    : delivered.some(decision => decision.disposition === 'include')
+      ? 'workset'
+      : 'card';
+  const cautions = [...new Set(decisions
+    .filter(decision => decision.disposition !== 'include')
+    .flatMap(decision => decision.reasons))];
+
+  return {
+    mode,
+    budget: { maxTokens: safeBudget, usedTokens },
+    decisions,
+    cautions: cautions.length > 0 ? cautions : ['no-qualified-evidence'],
+  };
+}

package/src/knowledge/outcome-store.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { getDatabase } from '../store/sqlite-db.js';
+import {
+  MEMORY_OUTCOME_CANDIDATE_KINDS,
+  MEMORY_OUTCOME_SIGNAL_KINDS,
+  type MemoryOutcomeCandidateKind,
+  type MemoryOutcomeSignal,
+  type MemoryOutcomeSignalKind,
+} from './outcome-types.js';
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function text(value: string, field: string, max = 1_000): string {
+  const safe = sanitizeCredentials(value).replace(/\s+/g, ' ').trim();
+  if (!safe) throw new Error('Outcome signal ' + field + ' is required.');
+  if (safe.length > max) throw new Error('Outcome signal ' + field + ' is too long.');
+  return safe;
+}
+
+function oneOf<T extends readonly string[]>(value: unknown, values: T, field: string): T[number] {
+  if (typeof value !== 'string' || !(values as readonly string[]).includes(value)) {
+    throw new Error('Outcome signal ' + field + ' is invalid.');
+  }
+  return value as T[number];
+}
+
+function rowToSignal(row: any): MemoryOutcomeSignal {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    candidateKind: row.candidateKind,
+    candidateId: row.candidateId,
+    kind: row.kind,
+    sourceRef: row.sourceRef,
+    ...(optionalText(row.snapshotId) ? { snapshotId: row.snapshotId } : {}),
+    ...(optionalText(row.detail) ? { detail: row.detail } : {}),
+    observedAt: row.observedAt,
+  } as MemoryOutcomeSignal;
+}
+
+/** Persistence only; callers decide which real-world event is worth recording. */
+export class OutcomeStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  record(input: Omit<MemoryOutcomeSignal, 'id' | 'observedAt'> & { observedAt?: string }): MemoryOutcomeSignal {
+    const signal: MemoryOutcomeSignal = {
+      id: randomUUID(),
+      projectId: text(input.projectId, 'project id'),
+      candidateKind: oneOf(input.candidateKind, MEMORY_OUTCOME_CANDIDATE_KINDS, 'candidate kind'),
+      candidateId: text(input.candidateId, 'candidate id'),
+      kind: oneOf(input.kind, MEMORY_OUTCOME_SIGNAL_KINDS, 'kind'),
+      sourceRef: text(input.sourceRef, 'source reference'),
+      ...(input.snapshotId ? { snapshotId: text(input.snapshotId, 'snapshot id') } : {}),
+      ...(input.detail ? { detail: text(input.detail, 'detail') } : {}),
+      observedAt: input.observedAt ?? new Date().toISOString(),
+    };
+    this.db.prepare(`
+      INSERT INTO memory_outcome_signals (
+        id, projectId, candidateKind, candidateId, kind, sourceRef, snapshotId, detail, observedAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      signal.id,
+      signal.projectId,
+      signal.candidateKind,
+      signal.candidateId,
+      signal.kind,
+      signal.sourceRef,
+      signal.snapshotId ?? null,
+      signal.detail ?? null,
+      signal.observedAt,
+    );
+    return signal;
+  }
+
+  latestForCandidates(
+    projectId: string,
+    candidateKind: MemoryOutcomeCandidateKind,
+    candidateIds: string[],
+  ): Map<string, MemoryOutcomeSignal> {
+    const ids = [...new Set(candidateIds.filter(Boolean))];
+    if (ids.length === 0) return new Map();
+    const placeholders = ids.map(() => '?').join(', ');
+    const rows = this.db.prepare(`
+      SELECT * FROM memory_outcome_signals
+      WHERE projectId = ? AND candidateKind = ? AND candidateId IN (${placeholders})
+      ORDER BY observedAt DESC, id DESC
+    `).all(projectId, candidateKind, ...ids);
+    const latest = new Map<string, MemoryOutcomeSignal>();
+    for (const row of rows) {
+      const signal = rowToSignal(row);
+      if (!latest.has(signal.candidateId)) latest.set(signal.candidateId, signal);
+    }
+    return latest;
+  }
+}

package/src/knowledge/outcome-types.ts

@@ -0,0 +1,49 @@
+/**
+ * Append-only evidence about whether a context artifact helped or was
+ * contradicted. Signals never replace the artifact they describe.
+ */
+export const MEMORY_OUTCOME_CANDIDATE_KINDS = ['claim', 'durable-memory', 'workflow'] as const;
+export type MemoryOutcomeCandidateKind = typeof MEMORY_OUTCOME_CANDIDATE_KINDS[number];
+
+export const MEMORY_OUTCOME_SIGNAL_KINDS = [
+  'verification-passed',
+  'verification-failed',
+  'verified-reuse',
+  'user-pin',
+  'user-correction',
+  'source-changed',
+  'conflict-confirmed',
+  'manual-review',
+] as const;
+export type MemoryOutcomeSignalKind = typeof MEMORY_OUTCOME_SIGNAL_KINDS[number];
+
+export interface MemoryOutcomeSignal {
+  id: string;
+  projectId: string;
+  candidateKind: MemoryOutcomeCandidateKind;
+  candidateId: string;
+  kind: MemoryOutcomeSignalKind;
+  sourceRef: string;
+  snapshotId?: string;
+  detail?: string;
+  observedAt: string;
+}
+
+export type OutcomeQuality = 'verified' | 'probationary' | 'degraded';
+
+/** The newest auditable signal wins; missing signals leave lifecycle state in charge. */
+export function qualityFromOutcome(signal?: Pick<MemoryOutcomeSignal, 'kind'>): OutcomeQuality | undefined {
+  if (!signal) return undefined;
+  if (signal.kind === 'verification-failed'
+    || signal.kind === 'user-correction'
+    || signal.kind === 'source-changed'
+    || signal.kind === 'conflict-confirmed') {
+    return 'degraded';
+  }
+  if (signal.kind === 'verification-passed'
+    || signal.kind === 'verified-reuse'
+    || signal.kind === 'user-pin') {
+    return 'verified';
+  }
+  return undefined;
+}

package/src/knowledge/workflows.ts

@@ -7,6 +7,8 @@ import { atomicWriteFile, withFileLock } from '../store/file-lock.js';
 import { WorkflowSyncer } from '../workspace/workflow-sync.js';
 import { getKnowledgeWorkspacePaths, resolveKnowledgeWorkspaceFile } from './workspace.js';
 import { WorkflowStore } from './workflow-store.js';
+import { OutcomeStore } from './outcome-store.js';
+import type { MemoryOutcomeCandidateKind, MemoryOutcomeSignalKind } from './outcome-types.js';
 import { containsTaskKeyword } from '../codegraph/task-lens.js';
 import type {
   WorkflowAdapterPreview,
@@ -751,7 +753,36 @@ export async function recordWorkflowRun(input: {
     throw new Error('Workflow was not found for this workspace');
   }
   if (!input.run.task.trim()) throw new Error('Workflow run task is required');
-  return store.recordRun(input.run);
+  const run = store.recordRun(input.run);
+  const kind: MemoryOutcomeSignalKind | undefined = run.outcome === 'passed' && run.verificationVerdict === 'passed'
+    ? 'verification-passed'
+    : run.outcome === 'failed' || run.verificationVerdict === 'failed'
+      ? 'verification-failed'
+      : undefined;
+  if (!kind) return run;
+
+  const evidence = new Map<string, MemoryOutcomeCandidateKind>();
+  evidence.set(workflow.id, 'workflow');
+  for (const reference of run.selectedEvidence) {
+    const match = /^(claim|durable):(.+)$/.exec(reference);
+    if (!match) continue;
+    evidence.set(match[2], match[1] === 'claim' ? 'claim' : 'durable-memory');
+  }
+  const outcomes = new OutcomeStore();
+  await outcomes.init(workflowStoreDataDir(input.workspace));
+  for (const [candidateId, candidateKind] of evidence) {
+    outcomes.record({
+      projectId: run.projectId,
+      candidateKind,
+      candidateId,
+      kind,
+      sourceRef: 'workflow-run:' + run.id,
+      ...(run.startingSnapshotId ? { snapshotId: run.startingSnapshotId } : {}),
+      ...(run.failureReason ? { detail: run.failureReason } : {}),
+      observedAt: run.completedAt ?? run.startedAt,
+    });
+  }
+  return run;
 }
 
 export async function selectWorkspaceWorkflows(input: {