@remnic/core 1.1.12 → 1.1.13

package/src/identity-continuity.ts

@@ -0,0 +1,333 @@
+import type {
+  ContinuityIncidentCloseInput,
+  ContinuityIncidentOpenInput,
+  ContinuityImprovementLoop,
+  ContinuityLoopCadence,
+  ContinuityLoopReviewInput,
+  ContinuityLoopStatus,
+  ContinuityLoopUpsertInput,
+  ContinuityIncidentRecord,
+  ContinuityIncidentState,
+} from "./types.js";
+
+function parseFrontmatterValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function parseFrontmatter(raw: string): Record<string, unknown> {
+  const parsed: Record<string, unknown> = {};
+  for (const line of raw.split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim();
+    const value = line.slice(idx + 1).trim();
+    parsed[key] = parseFrontmatterValue(value);
+  }
+  return parsed;
+}
+
+function emitSection(lines: string[], title: string, value?: string): void {
+  if (!value || value.trim().length === 0) return;
+  lines.push(`## ${title}`, "", value.trim(), "");
+}
+
+function parseSection(body: string, title: string): string | undefined {
+  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`## ${escaped}\\n\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const match = body.match(re);
+  if (!match) return undefined;
+  const value = match[1].trim();
+  return value.length > 0 ? value : undefined;
+}
+
+export function serializeContinuityIncident(incident: ContinuityIncidentRecord): string {
+  const lines = [
+    "---",
+    `id: ${JSON.stringify(incident.id)}`,
+    `state: ${JSON.stringify(incident.state)}`,
+    `openedAt: ${JSON.stringify(incident.openedAt)}`,
+    `updatedAt: ${JSON.stringify(incident.updatedAt)}`,
+  ];
+  if (incident.closedAt) lines.push(`closedAt: ${JSON.stringify(incident.closedAt)}`);
+  if (incident.triggerWindow) lines.push(`triggerWindow: ${JSON.stringify(incident.triggerWindow)}`);
+  lines.push("---", "");
+
+  emitSection(lines, "Symptom", incident.symptom);
+  emitSection(lines, "Suspected Cause", incident.suspectedCause);
+  emitSection(lines, "Fix Applied", incident.fixApplied);
+  emitSection(lines, "Verification Result", incident.verificationResult);
+  emitSection(lines, "Preventive Rule", incident.preventiveRule);
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+export function parseContinuityIncident(raw: string): ContinuityIncidentRecord | null {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return null;
+  const frontmatter = parseFrontmatter(match[1]);
+  const body = match[2] ?? "";
+
+  const id = typeof frontmatter.id === "string" ? frontmatter.id : "";
+  const stateRaw = frontmatter.state;
+  const state: ContinuityIncidentState = stateRaw === "closed" ? "closed" : "open";
+  const openedAt = typeof frontmatter.openedAt === "string" ? frontmatter.openedAt : "";
+  const updatedAt = typeof frontmatter.updatedAt === "string" ? frontmatter.updatedAt : openedAt;
+  const symptom = parseSection(body, "Symptom");
+
+  if (!id || !openedAt || !updatedAt || !symptom) return null;
+
+  return {
+    id,
+    state,
+    openedAt,
+    updatedAt,
+    triggerWindow: typeof frontmatter.triggerWindow === "string" ? frontmatter.triggerWindow : undefined,
+    symptom,
+    suspectedCause: parseSection(body, "Suspected Cause"),
+    fixApplied: parseSection(body, "Fix Applied"),
+    verificationResult: parseSection(body, "Verification Result"),
+    preventiveRule: parseSection(body, "Preventive Rule"),
+    closedAt: typeof frontmatter.closedAt === "string" ? frontmatter.closedAt : undefined,
+  };
+}
+
+export function createContinuityIncidentRecord(
+  id: string,
+  input: ContinuityIncidentOpenInput,
+  nowIso: string,
+): ContinuityIncidentRecord {
+  return {
+    id,
+    state: "open",
+    openedAt: nowIso,
+    updatedAt: nowIso,
+    triggerWindow: input.triggerWindow?.trim() || undefined,
+    symptom: input.symptom.trim(),
+    suspectedCause: input.suspectedCause?.trim() || undefined,
+  };
+}
+
+export function closeContinuityIncidentRecord(
+  incident: ContinuityIncidentRecord,
+  closure: ContinuityIncidentCloseInput,
+  nowIso: string,
+): ContinuityIncidentRecord {
+  return {
+    ...incident,
+    state: "closed",
+    updatedAt: nowIso,
+    closedAt: nowIso,
+    fixApplied: closure.fixApplied.trim(),
+    verificationResult: closure.verificationResult.trim(),
+    preventiveRule: closure.preventiveRule?.trim() || incident.preventiveRule,
+  };
+}
+
+const LOOP_HEADER = "# Continuity Improvement Loops";
+const LOOP_CADENCES = new Set<ContinuityLoopCadence>(["daily", "weekly", "monthly", "quarterly"]);
+const LOOP_STATUSES = new Set<ContinuityLoopStatus>(["active", "paused", "retired"]);
+const STALE_LAST_REVIEWED_FALLBACK = "1970-01-01T00:00:00.000Z";
+
+function normalizeLoopField(value: string | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return undefined;
+  return trimmed.replace(/\s+/g, " ");
+}
+
+function isValidIso(value: string): boolean {
+  const ts = Date.parse(value);
+  return Number.isFinite(ts);
+}
+
+function normalizeContinuityLoop(
+  input: ContinuityLoopUpsertInput | ContinuityImprovementLoop,
+  nowIso: string,
+): ContinuityImprovementLoop | null {
+  const id = normalizeLoopField(input.id);
+  const cadence = normalizeLoopField(input.cadence) as ContinuityLoopCadence | undefined;
+  const status = normalizeLoopField(input.status) as ContinuityLoopStatus | undefined;
+  const purpose = normalizeLoopField(input.purpose);
+  const killCondition = normalizeLoopField(input.killCondition);
+  const notes = normalizeLoopField(input.notes);
+  const lastReviewedRaw =
+    "lastReviewed" in input && typeof input.lastReviewed === "string" ? input.lastReviewed : undefined;
+  const lastReviewed = normalizeLoopField(lastReviewedRaw) ?? nowIso;
+
+  if (!id || !cadence || !status || !purpose || !killCondition) return null;
+  if (!LOOP_CADENCES.has(cadence)) return null;
+  if (!LOOP_STATUSES.has(status)) return null;
+  if (!isValidIso(lastReviewed)) return null;
+
+  return {
+    id,
+    cadence,
+    purpose,
+    status,
+    killCondition,
+    lastReviewed,
+    notes,
+  };
+}
+
+function serializeContinuityLoopSection(loop: ContinuityImprovementLoop): string {
+  const lines = [
+    `## ${loop.id}`,
+    `cadence: ${loop.cadence}`,
+    `purpose: ${loop.purpose}`,
+    `status: ${loop.status}`,
+    `killCondition: ${loop.killCondition}`,
+    `lastReviewed: ${loop.lastReviewed}`,
+  ];
+  if (loop.notes) lines.push(`notes: ${loop.notes}`);
+  return lines.join("\n");
+}
+
+type MarkdownSection = {
+  title: string;
+  body: string;
+};
+
+function splitLoopMarkdown(raw: string | null): { header: string; sections: MarkdownSection[] } {
+  const text = (raw ?? "").replace(/\r/g, "");
+  const lines = text.split("\n");
+  const headerLines: string[] = [];
+  const sections: MarkdownSection[] = [];
+  let current: MarkdownSection | null = null;
+
+  for (const line of lines) {
+    const sectionMatch = line.match(/^##\s+(.+?)\s*$/);
+    if (sectionMatch) {
+      if (current) sections.push({ title: current.title, body: current.body.trimEnd() });
+      current = { title: sectionMatch[1].trim(), body: "" };
+      continue;
+    }
+    if (!current) {
+      headerLines.push(line);
+      continue;
+    }
+    current.body += current.body.length > 0 ? `\n${line}` : line;
+  }
+  if (current) sections.push({ title: current.title, body: current.body.trimEnd() });
+
+  const headerRaw = headerLines.join("\n").trim();
+  const header = headerRaw.length > 0 ? headerRaw : LOOP_HEADER;
+  return { header, sections };
+}
+
+function parseLoopFromSection(section: MarkdownSection, nowIso: string): ContinuityImprovementLoop | null {
+  const fields: Record<string, string> = {};
+  for (const line of section.body.split("\n")) {
+    const kv = line.match(/^([A-Za-z][A-Za-z0-9_]*):\s*(.+?)\s*$/);
+    if (!kv) continue;
+    fields[kv[1]] = kv[2];
+  }
+  const parsedLastReviewed = normalizeLoopField(fields.lastReviewed);
+  const safeLastReviewed =
+    parsedLastReviewed && isValidIso(parsedLastReviewed) ? parsedLastReviewed : STALE_LAST_REVIEWED_FALLBACK;
+  return normalizeContinuityLoop(
+    {
+      id: section.title,
+      cadence: (fields.cadence ?? "") as ContinuityLoopCadence,
+      purpose: fields.purpose ?? "",
+      status: (fields.status ?? "") as ContinuityLoopStatus,
+      killCondition: fields.killCondition ?? "",
+      lastReviewed: safeLastReviewed,
+      notes: fields.notes,
+    },
+    nowIso,
+  );
+}
+
+function joinLoopMarkdown(header: string, sections: MarkdownSection[]): string {
+  const lines: string[] = [header.trim(), ""];
+  for (const section of sections) {
+    lines.push(`## ${section.title}`);
+    if (section.body.trim().length > 0) {
+      lines.push(section.body.trimEnd());
+    }
+    lines.push("");
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+}
+
+export function parseContinuityImprovementLoops(raw: string): ContinuityImprovementLoop[] {
+  const parsed = splitLoopMarkdown(raw);
+  const nowIso = new Date().toISOString();
+  return parsed.sections
+    .map((section) => parseLoopFromSection(section, nowIso))
+    .filter((loop): loop is ContinuityImprovementLoop => loop !== null);
+}
+
+export function upsertContinuityLoopInMarkdown(
+  raw: string | null,
+  input: ContinuityLoopUpsertInput,
+  nowIso: string,
+): { markdown: string; loop: ContinuityImprovementLoop } {
+  const normalized = normalizeContinuityLoop(input, nowIso);
+  if (!normalized) {
+    throw new Error("Invalid continuity loop input");
+  }
+
+  const parsed = splitLoopMarkdown(raw);
+  let replaced = false;
+  const nextSections = parsed.sections.map((section) => {
+    if (normalizeLoopField(section.title) !== normalized.id) return section;
+    replaced = true;
+    return { title: normalized.id, body: serializeContinuityLoopSection(normalized).split("\n").slice(1).join("\n") };
+  });
+
+  if (!replaced) {
+    nextSections.push({
+      title: normalized.id,
+      body: serializeContinuityLoopSection(normalized).split("\n").slice(1).join("\n"),
+    });
+  }
+
+  return { markdown: joinLoopMarkdown(parsed.header, nextSections), loop: normalized };
+}
+
+export function reviewContinuityLoopInMarkdown(
+  raw: string | null,
+  id: string,
+  input: ContinuityLoopReviewInput,
+  nowIso: string,
+): { markdown: string; loop: ContinuityImprovementLoop | null } {
+  const parsed = splitLoopMarkdown(raw);
+  const normalizedId = normalizeLoopField(id);
+  if (!normalizedId) {
+    return { markdown: joinLoopMarkdown(parsed.header, parsed.sections), loop: null };
+  }
+  let updatedLoop: ContinuityImprovementLoop | null = null;
+  const nextSections = parsed.sections.map((section) => {
+    if (normalizeLoopField(section.title) !== normalizedId) return section;
+    const existing = parseLoopFromSection(section, nowIso);
+    if (!existing) return section;
+    const reviewed = applyContinuityLoopReview(existing, input, nowIso);
+    updatedLoop = reviewed;
+    return { title: reviewed.id, body: serializeContinuityLoopSection(reviewed).split("\n").slice(1).join("\n") };
+  });
+
+  return { markdown: joinLoopMarkdown(parsed.header, nextSections), loop: updatedLoop };
+}
+
+function applyContinuityLoopReview(
+  existing: ContinuityImprovementLoop,
+  input: ContinuityLoopReviewInput,
+  nowIso: string,
+): ContinuityImprovementLoop {
+  const nextStatus = normalizeLoopField(input.status) as ContinuityLoopStatus | undefined;
+  const nextNotes = normalizeLoopField(input.notes);
+  const reviewedAt = normalizeLoopField(input.reviewedAt) ?? nowIso;
+
+  return {
+    ...existing,
+    status: nextStatus && LOOP_STATUSES.has(nextStatus) ? nextStatus : existing.status,
+    notes: nextNotes ?? existing.notes,
+    lastReviewed: isValidIso(reviewedAt) ? reviewedAt : nowIso,
+  };
+}

package/src/importance.ts

@@ -0,0 +1,328 @@
+/**
+ * Local Importance Scoring (Phase 1B)
+ *
+ * Zero-LLM heuristic system that evaluates each memory's significance.
+ * Analyzes content for markers like explicit importance statements,
+ * personal information, instructions, emotional content, and factual density.
+ */
+
+import type { ImportanceLevel, ImportanceScore, MemoryCategory, MemoryFile } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Marker patterns for each tier
+// ---------------------------------------------------------------------------
+
+/** Critical importance markers (0.9-1.0) */
+const CRITICAL_PATTERNS = [
+  // Explicit importance
+  /\b(critical|crucial|essential|must|always|never)\b/i,
+  /\b(important|remember this|don't forget)\b/i,
+  // Personal identity
+  /\b(my name is|i am|i'm called)\b/i,
+  /\b(my (birthday|phone|email|address|ssn|password))\b/i,
+  // Strong preferences
+  /\b(i (hate|love|despise|adore))\b/i,
+  /\b(absolutely|definitely|certainly) (not|must|should)\b/i,
+  // Corrections (high weight)
+  /\b(actually|no,? that's wrong|correction:?|let me correct)\b/i,
+  /\b(i said|i meant|i was wrong)\b/i,
+];
+
+/** High importance markers (0.7-0.9) */
+const HIGH_PATTERNS = [
+  // Decisions
+  /\b(decided|decision|chose|choosing|picked|selected)\b/i,
+  /\b(we('ll| will) (go with|use|implement))\b/i,
+  // Instructions
+  /\b(make sure|ensure|always|don't|do not|never|avoid)\b/i,
+  /\b(you (should|must|need to))\b/i,
+  // Temporal references (deadlines, schedules)
+  /\b(by (monday|tuesday|wednesday|thursday|friday|saturday|sunday))\b/i,
+  /\b(deadline|due (date|by)|by (end of|next))\b/i,
+  /\b(tomorrow|next week|this week|today)\b/i,
+  // Preferences
+  /\b(i (prefer|like|want|need|dislike))\b/i,
+  /\b(my (preference|style|approach|way))\b/i,
+  // Commitments
+  /\b(i('ll| will)|promise|commit|guarantee)\b/i,
+  /\b(scheduled|appointment|meeting|call)\b/i,
+];
+
+/** Normal importance markers (0.4-0.7) */
+const NORMAL_PATTERNS = [
+  // Factual content
+  /\b(is|are|was|were|has|have|does|do)\b/i,
+  /\b(because|since|therefore|thus|so)\b/i,
+  // Emotional content
+  /\b(happy|sad|frustrated|excited|worried|anxious)\b/i,
+  /\b(feel|feeling|felt)\b/i,
+  // Technical details
+  /\b(version|api|endpoint|database|server|config)\b/i,
+  /\b(function|class|method|variable|parameter)\b/i,
+];
+
+/** Low importance markers (0.2-0.4) */
+const LOW_PATTERNS = [
+  // Uncertainty
+  /\b(maybe|perhaps|possibly|might|could be)\b/i,
+  /\b(i think|i guess|not sure|uncertain)\b/i,
+  /\b(probably|likely|seems like)\b/i,
+  // Hedging
+  /\b(kind of|sort of|somewhat|a bit)\b/i,
+  /\b(in a way|to some extent)\b/i,
+];
+
+/** Trivial content markers (0.0-0.2) */
+const TRIVIAL_PATTERNS = [
+  // Greetings and filler
+  /^(hi|hello|hey|yo|sup|greetings)[.!,]?\s*$/i,
+  /^(ok|okay|k|sure|yes|no|yep|nope|yeah|nah)[.!]?\s*$/i,
+  /^(thanks|thank you|thx|ty|cheers)[.!]?\s*$/i,
+  /^(got it|understood|roger|copy|noted)[.!]?\s*$/i,
+  /^(bye|goodbye|later|see ya|ttyl)[.!]?\s*$/i,
+  /^(lol|haha|hehe|lmao|rofl)[.!]?\s*$/i,
+  /^(hmm+|uhh*|ahh*|err*|umm*)[.!]?\s*$/i,
+  // Very short content
+  /^.{1,10}$/,
+];
+
+// ---------------------------------------------------------------------------
+// Category-based importance boosts
+// ---------------------------------------------------------------------------
+
+const CATEGORY_BOOSTS: Record<MemoryCategory, number> = {
+  correction: 0.15,        // Corrections are always important
+  principle: 0.12,         // Durable rules/values
+  rule: 0.11,              // Causal IF→THEN rules
+  procedure: 0.10,         // Repeatable workflows (issue #519)
+  preference: 0.10,        // User preferences matter
+  commitment: 0.10,        // Promises/obligations
+  reasoning_trace: 0.09,   // Stored reasoning chains (issue #564)
+  decision: 0.08,          // Decisions with rationale
+  relationship: 0.05,      // Entity relationships
+  skill: 0.05,             // Capabilities
+  moment: 0.03,            // Emotional milestones
+  entity: 0.02,            // Entity facts
+  fact: 0.00,              // Base facts, no boost
+};
+
+// ---------------------------------------------------------------------------
+// Keyword extraction
+// ---------------------------------------------------------------------------
+
+/** Common stop words to filter out */
+const STOP_WORDS = new Set([
+  "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+  "have", "has", "had", "do", "does", "did", "will", "would", "could",
+  "should", "may", "might", "must", "shall", "can", "need", "dare",
+  "ought", "used", "to", "of", "in", "for", "on", "with", "at", "by",
+  "from", "as", "into", "through", "during", "before", "after", "above",
+  "below", "between", "under", "again", "further", "then", "once",
+  "here", "there", "when", "where", "why", "how", "all", "each", "few",
+  "more", "most", "other", "some", "such", "no", "nor", "not", "only",
+  "own", "same", "so", "than", "too", "very", "just", "and", "but",
+  "or", "if", "because", "until", "while", "this", "that", "these",
+  "those", "i", "me", "my", "myself", "we", "our", "ours", "ourselves",
+  "you", "your", "yours", "yourself", "yourselves", "he", "him", "his",
+  "himself", "she", "her", "hers", "herself", "it", "its", "itself",
+  "they", "them", "their", "theirs", "themselves", "what", "which",
+  "who", "whom", "whose", "am", "been", "being", "about", "against",
+]);
+
+/**
+ * Extract salient keywords from content.
+ * Returns top N keywords sorted by relevance.
+ */
+function extractKeywords(content: string, maxKeywords: number = 5): string[] {
+  // Tokenize and normalize
+  const words = content
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length >= 3 && !STOP_WORDS.has(w));
+
+  // Count frequencies
+  const freq = new Map<string, number>();
+  for (const word of words) {
+    freq.set(word, (freq.get(word) ?? 0) + 1);
+  }
+
+  // Sort by frequency, take top N
+  return [...freq.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxKeywords)
+    .map(([word]) => word);
+}
+
+// ---------------------------------------------------------------------------
+// Main scoring function
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate importance score for a memory.
+ * Pure local heuristics, zero LLM calls.
+ */
+export function scoreImportance(
+  content: string,
+  category: MemoryCategory,
+  tags: string[] = [],
+): ImportanceScore {
+  const reasons: string[] = [];
+  let score = 0.5; // Start at normal baseline
+
+  const lowerContent = content.toLowerCase();
+  const contentLength = content.length;
+
+  // Check for trivial content first (short-circuit)
+  for (const pattern of TRIVIAL_PATTERNS) {
+    if (pattern.test(content)) {
+      return {
+        score: 0.1,
+        level: "trivial",
+        reasons: ["Trivial content (greeting, filler, or very short)"],
+        keywords: [],
+      };
+    }
+  }
+
+  // Check critical patterns
+  for (const pattern of CRITICAL_PATTERNS) {
+    if (pattern.test(content)) {
+      score += 0.20;
+      reasons.push(`Critical marker: ${pattern.source.slice(0, 30)}`);
+      break; // Only count once per tier
+    }
+  }
+
+  // Check high patterns
+  for (const pattern of HIGH_PATTERNS) {
+    if (pattern.test(content)) {
+      score += 0.12;
+      reasons.push(`High importance marker detected`);
+      break;
+    }
+  }
+
+  // Check low patterns (reduces score)
+  for (const pattern of LOW_PATTERNS) {
+    if (pattern.test(content)) {
+      score -= 0.15;
+      reasons.push(`Uncertainty/hedging detected`);
+      break;
+    }
+  }
+
+  // Category boost
+  const categoryBoost = CATEGORY_BOOSTS[category] ?? 0;
+  if (categoryBoost > 0) {
+    score += categoryBoost;
+    reasons.push(`Category boost: ${category}`);
+  }
+
+  // Length bonus (longer = more substance, capped)
+  if (contentLength > 200) {
+    const lengthBonus = Math.min((contentLength - 200) / 1000, 0.1);
+    score += lengthBonus;
+    if (lengthBonus > 0.05) {
+      reasons.push("Substantial content length");
+    }
+  }
+
+  // Check for personal pronouns (signals personal relevance)
+  if (/\b(my|mine|i|i'm|i've|i'd|i'll)\b/i.test(content)) {
+    score += 0.05;
+    reasons.push("Personal reference");
+  }
+
+  // Check for numbers/specifics (concrete details)
+  if (/\b\d{2,}\b/.test(content) || /\b(version|v\d|api|config)\b/i.test(content)) {
+    score += 0.03;
+    reasons.push("Contains specific details");
+  }
+
+  // Tag-based boosts
+  const importantTags = tags.filter((t) =>
+    ["important", "critical", "preference", "decision", "rule", "principle"].includes(t.toLowerCase())
+  );
+  if (importantTags.length > 0) {
+    score += 0.05 * importantTags.length;
+    reasons.push(`Important tags: ${importantTags.join(", ")}`);
+  }
+
+  // Clamp score to 0-1 range
+  score = Math.max(0, Math.min(1, score));
+
+  // Determine level from score
+  let level: ImportanceLevel;
+  if (score >= 0.9) {
+    level = "critical";
+  } else if (score >= 0.7) {
+    level = "high";
+  } else if (score >= 0.4) {
+    level = "normal";
+  } else if (score >= 0.2) {
+    level = "low";
+  } else {
+    level = "trivial";
+  }
+
+  // Extract keywords
+  const keywords = extractKeywords(content);
+
+  return {
+    score: Math.round(score * 100) / 100, // Round to 2 decimal places
+    level,
+    reasons: reasons.slice(0, 5), // Cap at 5 reasons
+    keywords,
+  };
+}
+
+/**
+ * Recompute importance for an existing memory file using current local heuristics.
+ */
+export function rescoreMemoryImportance(memory: MemoryFile): ImportanceScore {
+  return scoreImportance(memory.content, memory.frontmatter.category, memory.frontmatter.tags ?? []);
+}
+
+/**
+ * Get importance level from numeric score.
+ */
+export function importanceLevel(score: number): ImportanceLevel {
+  if (score >= 0.9) return "critical";
+  if (score >= 0.7) return "high";
+  if (score >= 0.4) return "normal";
+  if (score >= 0.2) return "low";
+  return "trivial";
+}
+
+// ---------------------------------------------------------------------------
+// Importance threshold helper (issue #372)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ordering for importance levels used by the extraction write gate.
+ * Higher indices mean more important.
+ */
+const IMPORTANCE_LEVEL_RANK: Record<ImportanceLevel, number> = {
+  trivial: 0,
+  low: 1,
+  normal: 2,
+  high: 3,
+  critical: 4,
+};
+
+/**
+ * Return true if `candidate` meets or exceeds `threshold`. Used by the
+ * extraction write gate in orchestrator.persistExtraction() to drop trivial
+ * content before it is written to the memory store.
+ *
+ * Note: callers should pass the ALREADY-BOOSTED level returned by
+ * scoreImportance(), because category boosts (e.g. corrections) are applied
+ * inside scoreImportance() before the level is derived.
+ */
+export function isAboveImportanceThreshold(
+  candidate: ImportanceLevel,
+  threshold: ImportanceLevel,
+): boolean {
+  return IMPORTANCE_LEVEL_RANK[candidate] >= IMPORTANCE_LEVEL_RANK[threshold];
+}