memory-braid 0.4.7 → 0.6.0

package/src/observability.ts

@@ -0,0 +1,269 @@
+type UsageLike = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  total?: number;
+};
+
+export type UsageSnapshot = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  total: number;
+  promptTokens: number;
+  cacheHitRate: number;
+  cacheWriteRate: number;
+  estimatedCostUsd?: number;
+  costEstimateBasis: "estimated" | "token_only";
+};
+
+export type TrendState = "rising" | "stable" | "improving" | "insufficient_data";
+
+export type UsageWindowEntry = UsageSnapshot & {
+  at: number;
+  runId: string;
+};
+
+export type UsageTrendSummary = {
+  turnsSeen: number;
+  window5: {
+    avgPromptTokens: number;
+    avgCacheRead: number;
+    avgCacheWrite: number;
+    avgCacheHitRate: number;
+    avgCacheWriteRate: number;
+    avgEstimatedCostUsd?: number;
+  };
+  window20: {
+    avgPromptTokens: number;
+    avgCacheRead: number;
+    avgCacheWrite: number;
+    avgCacheHitRate: number;
+    avgCacheWriteRate: number;
+    avgEstimatedCostUsd?: number;
+  };
+  trends: {
+    cacheWriteRate: TrendState;
+    cacheHitRate: TrendState;
+    promptTokens: TrendState;
+    estimatedCostUsd: TrendState;
+  };
+  alerts: string[];
+};
+
+type PriceConfig = {
+  inputPerM: number;
+  outputPerM: number;
+  cacheReadPerM?: number;
+  cacheWritePerM?: number;
+};
+
+const WINDOW_LIMIT = 20;
+
+const PRICE_CONFIGS: Array<{
+  provider: string;
+  match: RegExp;
+  price: PriceConfig;
+}> = [
+  {
+    provider: "anthropic",
+    match: /claude-.*opus/i,
+    price: {
+      inputPerM: 15,
+      outputPerM: 75,
+      cacheReadPerM: 1.5,
+      cacheWritePerM: 18.75,
+    },
+  },
+  {
+    provider: "anthropic",
+    match: /claude-.*sonnet/i,
+    price: {
+      inputPerM: 3,
+      outputPerM: 15,
+      cacheReadPerM: 0.3,
+      cacheWritePerM: 3.75,
+    },
+  },
+  {
+    provider: "anthropic",
+    match: /claude-.*haiku/i,
+    price: {
+      inputPerM: 0.8,
+      outputPerM: 4,
+      cacheReadPerM: 0.08,
+      cacheWritePerM: 1,
+    },
+  },
+  {
+    provider: "openai",
+    match: /^gpt-4o$/i,
+    price: {
+      inputPerM: 2.5,
+      outputPerM: 10,
+      cacheReadPerM: 1.25,
+      cacheWritePerM: 1.25,
+    },
+  },
+  {
+    provider: "openai",
+    match: /^gpt-4o-mini$/i,
+    price: {
+      inputPerM: 0.15,
+      outputPerM: 0.6,
+      cacheReadPerM: 0.075,
+      cacheWritePerM: 0.075,
+    },
+  },
+];
+
+function finite(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function average(values: number[]): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function averageOptional(values: Array<number | undefined>): number | undefined {
+  const filtered = values.filter((value): value is number => typeof value === "number");
+  if (filtered.length === 0) {
+    return undefined;
+  }
+  return average(filtered);
+}
+
+function resolvePriceConfig(provider: string, model: string): PriceConfig | undefined {
+  const normalizedProvider = provider.trim().toLowerCase();
+  for (const candidate of PRICE_CONFIGS) {
+    if (candidate.provider !== normalizedProvider) {
+      continue;
+    }
+    if (candidate.match.test(model)) {
+      return candidate.price;
+    }
+  }
+  return undefined;
+}
+
+export function createUsageSnapshot(params: {
+  provider: string;
+  model: string;
+  usage?: UsageLike;
+}): UsageSnapshot {
+  const input = finite(params.usage?.input);
+  const output = finite(params.usage?.output);
+  const cacheRead = finite(params.usage?.cacheRead);
+  const cacheWrite = finite(params.usage?.cacheWrite);
+  const total = finite(params.usage?.total) || input + output + cacheRead + cacheWrite;
+  const promptTokens = input + cacheRead + cacheWrite;
+  const cacheBase = Math.max(1, promptTokens);
+  const price = resolvePriceConfig(params.provider, params.model);
+  const estimatedCostUsd = price
+    ? (input / 1_000_000) * price.inputPerM +
+      (output / 1_000_000) * price.outputPerM +
+      (cacheRead / 1_000_000) * (price.cacheReadPerM ?? price.inputPerM) +
+      (cacheWrite / 1_000_000) * (price.cacheWritePerM ?? price.inputPerM)
+    : undefined;
+
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    total,
+    promptTokens,
+    cacheHitRate: cacheRead / cacheBase,
+    cacheWriteRate: cacheWrite / cacheBase,
+    estimatedCostUsd,
+    costEstimateBasis: estimatedCostUsd === undefined ? "token_only" : "estimated",
+  };
+}
+
+function classifyTrend(current: number | undefined, prior: number | undefined): TrendState {
+  if (typeof current !== "number" || typeof prior !== "number" || prior <= 0) {
+    return "insufficient_data";
+  }
+  if (current >= prior * 1.2) {
+    return "rising";
+  }
+  if (current <= prior * 0.85) {
+    return "improving";
+  }
+  return "stable";
+}
+
+function movingWindow(entries: UsageWindowEntry[], size: number): UsageWindowEntry[] {
+  return entries.slice(Math.max(0, entries.length - size));
+}
+
+function previousWindow(entries: UsageWindowEntry[], size: number): UsageWindowEntry[] {
+  const end = Math.max(0, entries.length - size);
+  const start = Math.max(0, end - size);
+  return entries.slice(start, end);
+}
+
+function summarizeWindow(entries: UsageWindowEntry[]) {
+  return {
+    avgPromptTokens: average(entries.map((entry) => entry.promptTokens)),
+    avgCacheRead: average(entries.map((entry) => entry.cacheRead)),
+    avgCacheWrite: average(entries.map((entry) => entry.cacheWrite)),
+    avgCacheHitRate: average(entries.map((entry) => entry.cacheHitRate)),
+    avgCacheWriteRate: average(entries.map((entry) => entry.cacheWriteRate)),
+    avgEstimatedCostUsd: averageOptional(entries.map((entry) => entry.estimatedCostUsd)),
+  };
+}
+
+export function appendUsageWindow(
+  history: UsageWindowEntry[],
+  entry: UsageWindowEntry,
+): UsageWindowEntry[] {
+  const next = [...history, entry];
+  if (next.length <= WINDOW_LIMIT) {
+    return next;
+  }
+  return next.slice(next.length - WINDOW_LIMIT);
+}
+
+export function summarizeUsageWindow(history: UsageWindowEntry[]): UsageTrendSummary {
+  const window5Entries = movingWindow(history, 5);
+  const window20Entries = movingWindow(history, 20);
+  const prior5Entries = previousWindow(history, 5);
+  const current5 = summarizeWindow(window5Entries);
+  const current20 = summarizeWindow(window20Entries);
+  const prior5 = summarizeWindow(prior5Entries);
+
+  const cacheWriteRateTrend = classifyTrend(current5.avgCacheWriteRate, prior5.avgCacheWriteRate);
+  const cacheHitRateTrend = classifyTrend(current5.avgCacheHitRate, prior5.avgCacheHitRate);
+  const promptTokensTrend = classifyTrend(current5.avgPromptTokens, prior5.avgPromptTokens);
+  const costTrend = classifyTrend(current5.avgEstimatedCostUsd, prior5.avgEstimatedCostUsd);
+
+  const alerts: string[] = [];
+  if (cacheWriteRateTrend === "rising" && current5.avgCacheWriteRate >= 0.12) {
+    alerts.push("cache_write_rate_rising");
+  }
+  if (promptTokensTrend === "rising" && current5.avgPromptTokens >= 20_000) {
+    alerts.push("prompt_tokens_rising");
+  }
+  if (costTrend === "rising" && (current5.avgEstimatedCostUsd ?? 0) >= 0.05) {
+    alerts.push("estimated_cost_rising");
+  }
+
+  return {
+    turnsSeen: history.length,
+    window5: current5,
+    window20: current20,
+    trends: {
+      cacheWriteRate: cacheWriteRateTrend,
+      cacheHitRate: cacheHitRateTrend,
+      promptTokens: promptTokensTrend,
+      estimatedCostUsd: costTrend,
+    },
+    alerts,
+  };
+}

package/src/remediation.ts

@@ -0,0 +1,257 @@
+import { normalizeWhitespace } from "./chunking.js";
+import { isLikelyTranscriptLikeText, isOversizedAtomicMemory } from "./capture.js";
+import type { MemoryBraidResult, RemediationState } from "./types.js";
+
+export type RemediationAction = "audit" | "quarantine" | "delete" | "purge-all-captured";
+
+export type AuditReason =
+  | "legacy_capture_missing_provenance"
+  | "invalid_capture_metadata"
+  | "transcript_like_content"
+  | "oversized_capture_content";
+
+export type AuditRecord = {
+  memory: MemoryBraidResult;
+  sourceType: string;
+  captureOrigin?: string;
+  pluginCaptureVersion?: string;
+  quarantined: boolean;
+  quarantineReason?: string;
+  suspiciousReasons: AuditReason[];
+};
+
+export type AuditSummary = {
+  total: number;
+  captured: number;
+  suspicious: number;
+  quarantined: number;
+  bySourceType: Record<string, number>;
+  byCaptureOrigin: Record<string, number>;
+  byPluginVersion: Record<string, number>;
+  suspiciousByReason: Record<AuditReason, number>;
+  samples: Array<{
+    id?: string;
+    reasons: AuditReason[];
+    snippet: string;
+  }>;
+  records: AuditRecord[];
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function isKnownCaptureOrigin(value: string | undefined): boolean {
+  return value === "external_user" || value === "assistant_derived";
+}
+
+function isKnownCapturePath(value: string | undefined): boolean {
+  return value === "before_message_write" || value === "agent_end_last_turn";
+}
+
+export function isQuarantinedMemory(
+  record: MemoryBraidResult,
+  remediationState?: RemediationState,
+): { quarantined: boolean; reason?: string } {
+  const metadata = asRecord(record.metadata);
+  const local = record.id ? remediationState?.quarantined?.[record.id] : undefined;
+  if (local) {
+    return {
+      quarantined: true,
+      reason: local.reason,
+    };
+  }
+
+  const status = asString(metadata.remediationStatus);
+  const quarantinedAt = asString(metadata.quarantinedAt);
+  if (status === "quarantined" || quarantinedAt) {
+    return {
+      quarantined: true,
+      reason: asString(metadata.quarantineReason),
+    };
+  }
+
+  return { quarantined: false };
+}
+
+export function buildQuarantineMetadata(
+  metadata: Record<string, unknown> | undefined,
+  reason: string,
+  quarantinedAt: string,
+): Record<string, unknown> {
+  return {
+    ...(metadata ?? {}),
+    remediationStatus: "quarantined",
+    quarantinedAt,
+    quarantineReason: reason,
+  };
+}
+
+export function clearQuarantineMetadata(
+  metadata: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  const next = { ...(metadata ?? {}) };
+  delete next.remediationStatus;
+  delete next.quarantinedAt;
+  delete next.quarantineReason;
+  return next;
+}
+
+export function analyzeMemoryRecord(
+  memory: MemoryBraidResult,
+  remediationState?: RemediationState,
+): AuditRecord {
+  const metadata = asRecord(memory.metadata);
+  const sourceType = asString(metadata.sourceType) ?? "unknown";
+  const captureOrigin = asString(metadata.captureOrigin);
+  const capturePath = asString(metadata.capturePath);
+  const pluginCaptureVersion = asString(metadata.pluginCaptureVersion);
+  const suspiciousReasons: AuditReason[] = [];
+  const snippet = normalizeWhitespace(memory.snippet);
+
+  if (sourceType === "capture") {
+    const missingProvenance =
+      !captureOrigin || !pluginCaptureVersion || !capturePath;
+    if (missingProvenance) {
+      suspiciousReasons.push("legacy_capture_missing_provenance");
+    } else if (!isKnownCaptureOrigin(captureOrigin) || !isKnownCapturePath(capturePath)) {
+      suspiciousReasons.push("invalid_capture_metadata");
+    }
+
+    if (isLikelyTranscriptLikeText(snippet)) {
+      suspiciousReasons.push("transcript_like_content");
+    }
+    if (isOversizedAtomicMemory(snippet)) {
+      suspiciousReasons.push("oversized_capture_content");
+    }
+  }
+
+  const quarantine = isQuarantinedMemory(memory, remediationState);
+  return {
+    memory,
+    sourceType,
+    captureOrigin,
+    pluginCaptureVersion,
+    quarantined: quarantine.quarantined,
+    quarantineReason: quarantine.reason,
+    suspiciousReasons: Array.from(new Set(suspiciousReasons)),
+  };
+}
+
+export function buildAuditSummary(params: {
+  records: MemoryBraidResult[];
+  remediationState?: RemediationState;
+  sampleLimit?: number;
+}): AuditSummary {
+  const bySourceType: Record<string, number> = {};
+  const byCaptureOrigin: Record<string, number> = {};
+  const byPluginVersion: Record<string, number> = {};
+  const suspiciousByReason: Record<AuditReason, number> = {
+    legacy_capture_missing_provenance: 0,
+    invalid_capture_metadata: 0,
+    transcript_like_content: 0,
+    oversized_capture_content: 0,
+  };
+
+  const analyzed = params.records.map((record) => analyzeMemoryRecord(record, params.remediationState));
+  for (const record of analyzed) {
+    bySourceType[record.sourceType] = (bySourceType[record.sourceType] ?? 0) + 1;
+    if (record.captureOrigin) {
+      byCaptureOrigin[record.captureOrigin] = (byCaptureOrigin[record.captureOrigin] ?? 0) + 1;
+    } else if (record.sourceType === "capture") {
+      byCaptureOrigin["missing"] = (byCaptureOrigin.missing ?? 0) + 1;
+    }
+
+    if (record.pluginCaptureVersion) {
+      byPluginVersion[record.pluginCaptureVersion] =
+        (byPluginVersion[record.pluginCaptureVersion] ?? 0) + 1;
+    } else if (record.sourceType === "capture") {
+      byPluginVersion["missing"] = (byPluginVersion.missing ?? 0) + 1;
+    }
+
+    for (const reason of record.suspiciousReasons) {
+      suspiciousByReason[reason] += 1;
+    }
+  }
+
+  const suspiciousRecords = analyzed.filter((record) => record.suspiciousReasons.length > 0);
+  const sampleLimit = Math.max(1, params.sampleLimit ?? 5);
+  return {
+    total: analyzed.length,
+    captured: analyzed.filter((record) => record.sourceType === "capture").length,
+    suspicious: suspiciousRecords.length,
+    quarantined: analyzed.filter((record) => record.quarantined).length,
+    bySourceType,
+    byCaptureOrigin,
+    byPluginVersion,
+    suspiciousByReason,
+    samples: suspiciousRecords.slice(0, sampleLimit).map((record) => ({
+      id: record.memory.id,
+      reasons: record.suspiciousReasons,
+      snippet: record.memory.snippet,
+    })),
+    records: analyzed,
+  };
+}
+
+export function selectRemediationTargets(
+  summary: AuditSummary,
+  action: RemediationAction,
+): AuditRecord[] {
+  if (action === "purge-all-captured") {
+    return summary.records.filter((record) => record.sourceType === "capture");
+  }
+  if (action === "audit") {
+    return [];
+  }
+  return summary.records.filter(
+    (record) =>
+      record.sourceType === "capture" &&
+      record.suspiciousReasons.length > 0 &&
+      Boolean(record.memory.id),
+  );
+}
+
+function formatCounts(label: string, counts: Record<string, number>): string[] {
+  const entries = Object.entries(counts).sort((left, right) => right[1] - left[1]);
+  if (entries.length === 0) {
+    return [`${label}: n/a`];
+  }
+  return [`${label}:`, ...entries.map(([key, value]) => `- ${key}: ${value}`)];
+}
+
+export function formatAuditSummary(summary: AuditSummary): string {
+  const lines = [
+    "Memory Braid remediation audit",
+    `- total: ${summary.total}`,
+    `- captured: ${summary.captured}`,
+    `- suspicious: ${summary.suspicious}`,
+    `- quarantined: ${summary.quarantined}`,
+    ...formatCounts("By sourceType", summary.bySourceType),
+    ...formatCounts("By captureOrigin", summary.byCaptureOrigin),
+    ...formatCounts("By pluginCaptureVersion", summary.byPluginVersion),
+    ...formatCounts("Suspicious by reason", summary.suspiciousByReason),
+  ];
+
+  if (summary.samples.length > 0) {
+    lines.push("Samples:");
+    for (const sample of summary.samples) {
+      lines.push(
+        `- ${sample.id ?? "unknown"} [${sample.reasons.join(", ")}] ${normalizeWhitespace(sample.snippet).slice(0, 140)}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/state.ts

@@ -4,6 +4,7 @@ import type {
   CaptureDedupeState,
   LifecycleState,
   PluginStatsState,
+  RemediationState,
 } from "./types.js";
 
 const DEFAULT_CAPTURE_DEDUPE: CaptureDedupeState = {
@@ -30,14 +31,36 @@ const DEFAULT_STATS: PluginStatsState = {
     mem0AddWithoutId: 0,
     entityAnnotatedCandidates: 0,
     totalEntitiesAttached: 0,
+    trustedTurns: 0,
+    fallbackTurnSlices: 0,
+    provenanceSkipped: 0,
+    transcriptShapeSkipped: 0,
+    quarantinedFiltered: 0,
+    remediationQuarantined: 0,
+    remediationDeleted: 0,
+    agentLearningToolCalls: 0,
+    agentLearningAccepted: 0,
+    agentLearningRejectedValidation: 0,
+    agentLearningRejectedNovelty: 0,
+    agentLearningRejectedCooldown: 0,
+    agentLearningAutoCaptured: 0,
+    agentLearningAutoRejected: 0,
+    agentLearningInjected: 0,
+    agentLearningRecallHits: 0,
   },
 };
 
+const DEFAULT_REMEDIATION: RemediationState = {
+  version: 1,
+  quarantined: {},
+};
+
 export type StatePaths = {
   rootDir: string;
   captureDedupeFile: string;
   lifecycleFile: string;
   statsFile: string;
+  remediationFile: string;
   stateLockFile: string;
 };
 
@@ -48,6 +71,7 @@ export function createStatePaths(stateDir: string): StatePaths {
     captureDedupeFile: path.join(rootDir, "capture-dedupe.v1.json"),
     lifecycleFile: path.join(rootDir, "lifecycle.v1.json"),
     statsFile: path.join(rootDir, "stats.v1.json"),
+    remediationFile: path.join(rootDir, "remediation.v1.json"),
     stateLockFile: path.join(rootDir, "state.v1.lock"),
   };
 }
@@ -121,6 +145,21 @@ export async function writeStatsState(paths: StatePaths, state: PluginStatsState
   await writeJsonFile(paths.statsFile, state);
 }
 
+export async function readRemediationState(paths: StatePaths): Promise<RemediationState> {
+  const value = await readJsonFile(paths.remediationFile, DEFAULT_REMEDIATION);
+  return {
+    version: 1,
+    quarantined: { ...(value.quarantined ?? {}) },
+  };
+}
+
+export async function writeRemediationState(
+  paths: StatePaths,
+  state: RemediationState,
+): Promise<void> {
+  await writeJsonFile(paths.remediationFile, state);
+}
+
 export async function withStateLock<T>(
   lockFilePath: string,
   fn: () => Promise<T>,

package/src/types.ts

@@ -1,5 +1,29 @@
 export type MemoryBraidSource = "local" | "mem0";
 
+export const PLUGIN_CAPTURE_VERSION = "2026-03-provenance-v1";
+
+export type CaptureOrigin = "external_user" | "assistant_derived";
+
+export type CapturePath = "before_message_write" | "agent_end_last_turn";
+
+export type MemoryOwner = "user" | "agent";
+
+export type MemoryKind =
+  | "fact"
+  | "preference"
+  | "decision"
+  | "task"
+  | "heuristic"
+  | "lesson"
+  | "strategy"
+  | "other";
+
+export type CaptureIntent = "observed" | "inferred" | "self_reflection" | "explicit_tool";
+
+export type RecallTarget = "response" | "planning" | "both";
+
+export type Stability = "ephemeral" | "session" | "durable";
+
 export type ScopeKey = {
   workspaceHash: string;
   agentId: string;
@@ -62,7 +86,24 @@ export type CaptureStats = {
   mem0AddWithoutId: number;
   entityAnnotatedCandidates: number;
   totalEntitiesAttached: number;
+  trustedTurns: number;
+  fallbackTurnSlices: number;
+  provenanceSkipped: number;
+  transcriptShapeSkipped: number;
+  quarantinedFiltered: number;
+  remediationQuarantined: number;
+  remediationDeleted: number;
+  agentLearningToolCalls: number;
+  agentLearningAccepted: number;
+  agentLearningRejectedValidation: number;
+  agentLearningRejectedNovelty: number;
+  agentLearningRejectedCooldown: number;
+  agentLearningAutoCaptured: number;
+  agentLearningAutoRejected: number;
+  agentLearningInjected: number;
+  agentLearningRecallHits: number;
   lastRunAt?: string;
+  lastRemediationAt?: string;
 };
 
 export type PluginStatsState = {
@@ -76,3 +117,36 @@ export type ExtractedCandidate = {
   score: number;
   source: "heuristic" | "ml";
 };
+
+export type PendingInboundTurn = {
+  text: string;
+  messageHash: string;
+  receivedAt: number;
+};
+
+export type CaptureInputMessage = {
+  role: "user" | "assistant";
+  text: string;
+  origin: CaptureOrigin;
+  messageHash: string;
+};
+
+export type AssembledCaptureInput = {
+  messages: CaptureInputMessage[];
+  capturePath: CapturePath;
+  turnHash: string;
+  fallbackUsed: boolean;
+};
+
+export type RemediationState = {
+  version: 1;
+  quarantined: Record<
+    string,
+    {
+      memoryId: string;
+      reason: string;
+      quarantinedAt: string;
+      updatedRemotely?: boolean;
+    }
+  >;
+};