sostenuto 0.1.0

package/src/classify/executor.js

@@ -0,0 +1,108 @@
+/**
+ * executor.js — pluggable LLM backend for classification.
+ *
+ * Everything downstream sees one interface:
+ *   executor.complete({ system, user, maxTokens }) => Promise<string>
+ *
+ * Two backends ship; bring your own by matching the shape. (A custom
+ * executor is also where cost tricks live if you have them — e.g. routing
+ * through infrastructure you already pay for. Sostenuto doesn't care how
+ * the text comes back.)
+ *
+ * Model choice: classification is a structured-extraction task — a fast,
+ * cheap model is the right default. Reserve your strongest model for the
+ * conversation itself.
+ */
+
+const DEFAULT_MAX_TOKENS = 8000;
+
+/** Anthropic Messages API backend. */
+export function createAnthropicExecutor({
+  apiKey,
+  model = "claude-haiku-4-5-20251001",
+  baseUrl = "https://api.anthropic.com",
+} = {}) {
+  if (!apiKey) throw new Error("createAnthropicExecutor: apiKey required");
+
+  async function complete({ system, user, maxTokens = DEFAULT_MAX_TOKENS }) {
+    const res = await fetch(`${baseUrl}/v1/messages`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: "user", content: user }],
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`Anthropic ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    }
+    const json = await res.json();
+    return (json.content || [])
+      .filter((b) => b.type === "text")
+      .map((b) => b.text)
+      .join("");
+  }
+
+  return { complete, model, provider: "anthropic" };
+}
+
+/**
+ * OpenAI-compatible chat-completions backend.
+ * Works with OpenAI, Gemini (OpenAI-compat endpoint), DeepSeek, Ollama,
+ * LM Studio, vLLM — anything speaking /v1/chat/completions.
+ */
+export function createOpenAICompatibleExecutor({ apiKey, model, baseUrl } = {}) {
+  if (!baseUrl) throw new Error("createOpenAICompatibleExecutor: baseUrl required");
+  if (!model) throw new Error("createOpenAICompatibleExecutor: model required");
+
+  async function complete({ system, user, maxTokens = DEFAULT_MAX_TOKENS }) {
+    const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        messages: [
+          { role: "system", content: system },
+          { role: "user", content: user },
+        ],
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`LLM ${res.status}: ${(await res.text()).slice(0, 300)}`);
+    }
+    const json = await res.json();
+    return json.choices?.[0]?.message?.content ?? "";
+  }
+
+  return { complete, model, provider: "openai-compatible" };
+}
+
+/** Build an executor from environment variables (see .env.example). */
+export function executorFromEnv(env = process.env) {
+  if (env.CLASSIFY_BASE_URL) {
+    return createOpenAICompatibleExecutor({
+      baseUrl: env.CLASSIFY_BASE_URL,
+      apiKey: env.CLASSIFY_API_KEY,
+      model: env.CLASSIFY_MODEL,
+    });
+  }
+  if (env.ANTHROPIC_API_KEY) {
+    return createAnthropicExecutor({
+      apiKey: env.ANTHROPIC_API_KEY,
+      ...(env.CLASSIFY_MODEL ? { model: env.CLASSIFY_MODEL } : {}),
+    });
+  }
+  throw new Error(
+    "No classification backend configured: set ANTHROPIC_API_KEY or CLASSIFY_BASE_URL (+ CLASSIFY_MODEL)"
+  );
+}

package/src/classify/pipeline.js

@@ -0,0 +1,121 @@
+/**
+ * pipeline.js — classification call + robust parsing + sanitization.
+ *
+ * The classifier returns JSON; models occasionally wrap it in fences,
+ * preface it with prose, or truncate mid-stream at the token limit.
+ * parseClassification() survives all three (fence-strip → outer-brace
+ * match → truncation salvage that rebalances brackets).
+ */
+
+import { clamp, safeSlice } from "../memory/guidance.js";
+
+export const VALID_KEY_POINT_TYPES = new Set([
+  "decision", "open_question", "preference", "user_flagged",
+  "continuation", "emotional_note", "ritual", "language_moment", "peak_moment",
+]);
+
+// ─── Parsing ─────────────────────────────────────────────────────────
+
+/** Attempt to repair JSON truncated mid-stream at a token limit. */
+function salvageTruncated(text) {
+  const lastBrace = text.lastIndexOf("}");
+  if (lastBrace === -1) return null;
+  let candidate = text.slice(0, lastBrace + 1);
+  // Balance any brackets/braces left open before the cut.
+  let depthCurly = 0;
+  let depthSquare = 0;
+  let inString = false;
+  let escape = false;
+  for (const ch of candidate) {
+    if (escape) { escape = false; continue; }
+    if (ch === "\\") { escape = true; continue; }
+    if (ch === '"') { inString = !inString; continue; }
+    if (inString) continue;
+    if (ch === "{") depthCurly++;
+    else if (ch === "}") depthCurly--;
+    else if (ch === "[") depthSquare++;
+    else if (ch === "]") depthSquare--;
+  }
+  if (inString) candidate += '"';
+  candidate += "]".repeat(Math.max(0, depthSquare));
+  candidate += "}".repeat(Math.max(0, depthCurly));
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    return null;
+  }
+}
+
+export function parseClassification(rawText) {
+  let text = (rawText || "").trim()
+    .replace(/^```(?:json)?\s*\n?/i, "")
+    .replace(/\n?```\s*$/, "");
+  const match = text.match(/\{[\s\S]*\}/);
+  if (match) text = match[0];
+  try {
+    return JSON.parse(text);
+  } catch {
+    const salvaged = salvageTruncated(text);
+    if (salvaged) return salvaged;
+    throw new Error(
+      `classification JSON unparseable (first 200 chars): ${text.slice(0, 200)}`
+    );
+  }
+}
+
+// ─── Sanitization ────────────────────────────────────────────────────
+
+export function sanitizeKeyPoints(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter(
+      (kp) =>
+        kp && typeof kp === "object" &&
+        typeof kp.content === "string" &&
+        VALID_KEY_POINT_TYPES.has(kp.type)
+    )
+    .map((kp) => {
+      const point = { type: kp.type, content: safeSlice(kp.content, 500) };
+      if (typeof kp.valence === "number" && !isNaN(kp.valence)) {
+        point.valence = clamp(kp.valence, -1, 1);
+      }
+      if (typeof kp.weight === "number" && !isNaN(kp.weight)) {
+        point.weight = clamp(kp.weight, 0, 1);
+      }
+      return point;
+    });
+}
+
+export function sanitizeThinkingHighlights(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter(
+      (h) =>
+        h && typeof h === "object" &&
+        typeof h.moment === "string" &&
+        typeof h.thought === "string"
+    )
+    .map((h) => ({
+      moment: safeSlice(h.moment, 200),
+      thought: safeSlice(h.thought, 600),
+    }))
+    .slice(0, 6);
+}
+
+/** Normalize a parsed classification into a stable result shape. */
+export function sanitizeClassification(parsed, { hintEndType } = {}) {
+  return {
+    headline: parsed.headline || parsed.summary || "",
+    detailed_summary: parsed.detailed_summary || "",
+    diary_entry: parsed.diary_entry || "",
+    thinking_highlights: sanitizeThinkingHighlights(parsed.thinking_highlights),
+    key_points: sanitizeKeyPoints(parsed.key_points),
+    end_type: parsed.end_type || hintEndType || "unknown",
+    mood_delta: clamp(parsed.mood_delta ?? 0, -0.5, 0.5),
+    connection_delta: clamp(parsed.connection_delta ?? 0, -0.5, 0.5),
+    attunement_delta: clamp(parsed.attunement_delta ?? 0, 0, 1),
+    candidate_memories: Array.isArray(parsed.candidate_memories)
+      ? parsed.candidate_memories
+      : [],
+  };
+}

package/src/classify/templates.js

@@ -0,0 +1,22 @@
+/**
+ * templates.js — load prompt templates with {{variable}} substitution.
+ *
+ * The classification prompts are FILES YOU EDIT, not strings in our code.
+ * Sostenuto's prompts define structure (output schema, calibration rules);
+ * your edits define voice (who the companion is, what matters in your
+ * relationship). See templates/README in the repo root.
+ */
+
+import { readFileSync } from "fs";
+
+/**
+ * Load a template file and substitute {{vars}}.
+ * Unknown {{placeholders}} are left intact (so docs can show them).
+ */
+export function loadTemplate(path, vars = {}) {
+  let text = readFileSync(path, "utf-8");
+  for (const [key, value] of Object.entries(vars)) {
+    text = text.replaceAll(`{{${key}}}`, String(value ?? ""));
+  }
+  return text;
+}

package/src/classify/transcript.js

@@ -0,0 +1,57 @@
+/**
+ * transcript.js — turn formatting for the classifier.
+ *
+ * Input is surface-agnostic: an array of turns
+ *   { role: 'user'|'assistant', content: string, thinking?: string, timestamp?: string }
+ * Surface adapters (a chat app, a CLI hook, an importer) produce turns
+ * however they like; this module only renders them.
+ *
+ * Two details matter and are deliberate:
+ *
+ * 1. [thinking] blocks. When the model's reasoning is available, it is
+ *    included per assistant turn. Reasoning often contains perception that
+ *    never survived into the rendered reply — the classifier mines it for
+ *    diary entries and thinking-highlights.
+ *
+ * 2. Phase markers. Long transcripts get explicit EARLY/MIDDLE/LATE
+ *    markers. Without them, classifier LLMs reliably collapse a session's
+ *    arc into its final emotional peak and lose the middle — which is
+ *    usually where the texture lives.
+ */
+
+const PHASE_MIN_MESSAGES = 9;
+
+export function formatTurn(t) {
+  const lines = [`${t.role}: ${t.content}`];
+  if (t.role === "assistant" && t.thinking && t.thinking.trim()) {
+    lines.push(`[thinking]\n${t.thinking}\n[/thinking]`);
+  }
+  return lines.join("\n\n");
+}
+
+/**
+ * Render a full transcript, phase-segmented when long enough.
+ */
+export function buildTranscript(turns) {
+  if (!turns || turns.length === 0) return "";
+  if (turns.length >= PHASE_MIN_MESSAGES) {
+    const third = Math.floor(turns.length / 3);
+    const early = turns.slice(0, third);
+    const middle = turns.slice(third, turns.length - third);
+    const late = turns.slice(turns.length - third);
+    return [
+      "=== EARLY PHASE ===",
+      early.map(formatTurn).join("\n\n"),
+      "=== MIDDLE PHASE ===",
+      middle.map(formatTurn).join("\n\n"),
+      "=== LATE PHASE ===",
+      late.map(formatTurn).join("\n\n"),
+    ].join("\n\n");
+  }
+  return turns.map(formatTurn).join("\n\n");
+}
+
+/** Render only turns after a watermark (incremental classification). */
+export function buildNewTurnsTranscript(turns, fromIndex) {
+  return (turns || []).slice(fromIndex).map(formatTurn).join("\n\n");
+}

package/src/memory/guidance.js

@@ -0,0 +1,225 @@
+/**
+ * guidance.js — usage-policy inference and input sanitization.
+ *
+ * Every memory object carries a `usage_guidance` policy (machine-read,
+ * never dumped into prompts). When the classifier doesn't supply policy
+ * fields directly, these deterministic rules infer sensible defaults
+ * from type + sensitivity + confidence — no extra LLM call.
+ *
+ * Design notes baked into the rules:
+ *   - `proactive_use` controls INITIATIVE, not access. 'no' items remain
+ *     retrievable when the user explicitly anchors them (high-similarity
+ *     reference); they're just never volunteered.
+ *   - Sensitivity does NOT gate retrieval. High-sensitivity memories are
+ *     part of the relationship and must stay findable when referenced.
+ *     The gate for "don't auto-surface" is proactive_use, set by policy
+ *     or curation — not a blanket sensitivity rule.
+ */
+
+// ─── Vocabularies (must match db/schema.sql CHECK constraints) ───────
+
+export const VALID_DOMAINS = new Set([
+  "user_self", "agent_self", "relational", "evidence",
+]);
+
+export const VALID_TYPES = new Set([
+  "fact", "preference", "trajectory", "somatic_affective",
+  "interpretive_frame", "project", "boundary", "commitment",
+  "ritual", "shared_concept", "recurring_subject",
+  "contradiction", "style_adjustment", "voice_note",
+  "constraint", "context_note", "brief", "resume_guidance",
+  "continuation", "other",
+]);
+
+export const VALID_EPISTEMIC = new Set([
+  "explicit", "inferred", "co_created", "assistant_reflection", "system_generated",
+]);
+
+export const VALID_TIME_SCOPE = new Set([
+  "momentary", "session", "active_project", "ongoing", "historical", "deprecated",
+]);
+
+export const VALID_SENSITIVITY = new Set(["low", "medium", "high"]);
+
+const SENSITIVITY_RANK = { low: 0, medium: 1, high: 2 };
+
+/** Higher-ranked sensitivity wins (used when merging on reinforce). */
+export function maxSensitivity(a, b) {
+  return (SENSITIVITY_RANK[a] ?? 0) >= (SENSITIVITY_RANK[b] ?? 0) ? a : b;
+}
+
+export function clamp(val, min, max) {
+  return Math.max(min, Math.min(max, val));
+}
+
+/**
+ * Truncate without leaving orphan UTF-16 surrogate halves. Raw .slice()
+ * can split an emoji/astral char in two, producing invalid JSON that
+ * Postgres JSONB rejects.
+ */
+export function safeSlice(s, n) {
+  if (!s || s.length <= n) return s || "";
+  let out = s.slice(0, n);
+  const last = out.charCodeAt(out.length - 1);
+  if (last >= 0xd800 && last <= 0xdbff) out = out.slice(0, -1);
+  return out;
+}
+
+// ─── Domain/type sanitization ────────────────────────────────────────
+// Classifier LLMs occasionally emit values outside the schema vocabulary
+// (e.g. domain:"project"). Map common drift to valid values instead of
+// failing the insert.
+
+export function sanitizeDomainType(rawDomain, rawType) {
+  let domain = rawDomain;
+  let type = rawType;
+  let sanitized = false;
+
+  if (!VALID_DOMAINS.has(domain)) {
+    sanitized = true;
+    const d = String(domain || "").toLowerCase();
+    if (["project", "infrastructure", "technical", "system", "scheduled", "upcoming", "event", "context", "background"].includes(d)) {
+      domain = "relational";
+      if (!type || !VALID_TYPES.has(type)) {
+        if (["project", "infrastructure", "technical", "system"].includes(d)) type = "project";
+        else if (["scheduled", "upcoming", "event"].includes(d)) type = "continuation";
+        else type = "context_note";
+      }
+    } else if (d === "user") domain = "user_self";
+    else if (["agent", "assistant", "ai", "companion"].includes(d)) domain = "agent_self";
+    else if (["quote", "transcript"].includes(d)) domain = "evidence";
+    else domain = "relational"; // safest default
+  }
+
+  if (!VALID_TYPES.has(type)) {
+    sanitized = true;
+    const t = String(type || "").toLowerCase();
+    if (["dynamic", "pattern", "interaction"].includes(t)) type = "shared_concept";
+    else if (["observation", "linguistic", "note"].includes(t)) type = "voice_note";
+    else if (["scheduled", "upcoming", "event", "thread", "open_loop"].includes(t)) type = "continuation";
+    else if (["principle", "rule", "guideline"].includes(t)) type = "constraint";
+    else type = "other";
+  }
+
+  return { domain, type, sanitized };
+}
+
+// ─── Arousal inference ───────────────────────────────────────────────
+// Russell-circumplex intensity, orthogonal to valence: 0 = calm/stable,
+// 1 = acute. Used to modulate decay (high-arousal memories fade slower)
+// and surfacing weight. Prefer a classifier-supplied value; this formula
+// is the fallback:
+//
+//   arousal = 0.40·typePrior + 0.40·|valence| + 0.20·salience
+
+const AROUSAL_TYPE_PRIOR = {
+  // import-taxonomy keys (from migration exports)
+  boundary: 0.6, constraint: 0.7,
+  emotional_note: 0.8, emotional_pattern: 0.75,
+  peak_moment: 0.9, relational: 0.7,
+  ritual: 0.45, language_pattern: 0.4,
+  project: 0.3, technical_decision: 0.3,
+  user_self: 0.3, preference: 0.25,
+  aesthetic: 0.35, open_loop: 0.5, episodic: 0.55,
+  // schema-type keys
+  somatic_affective: 0.7, commitment: 0.55, shared_concept: 0.55,
+  trajectory: 0.4, interpretive_frame: 0.55, recurring_subject: 0.5,
+  contradiction: 0.55, style_adjustment: 0.45, voice_note: 0.4,
+  context_note: 0.3, brief: 0.4, resume_guidance: 0.55,
+  continuation: 0.4, fact: 0.2, other: 0.3,
+};
+
+function arousalTypePrior({ type, source_memory_type }) {
+  // Non-taxonomy markers fall through to the schema type.
+  if (
+    source_memory_type &&
+    source_memory_type !== "backfill" &&
+    source_memory_type !== "manual" &&
+    AROUSAL_TYPE_PRIOR[source_memory_type] !== undefined
+  ) {
+    return AROUSAL_TYPE_PRIOR[source_memory_type];
+  }
+  return AROUSAL_TYPE_PRIOR[type] ?? 0.3;
+}
+
+export function inferArousal({ type, source_memory_type, valence, salience }) {
+  const tp = arousalTypePrior({ type, source_memory_type });
+  const vi = Math.abs(typeof valence === "number" ? valence : 0);
+  const sal = typeof salience === "number" ? salience : 0.7;
+  return Number(clamp(0.4 * tp + 0.4 * vi + 0.2 * sal, 0, 1).toFixed(3));
+}
+
+// ─── Usage-guidance inference ────────────────────────────────────────
+
+/**
+ * Infer a full usage_guidance object for a new memory.
+ *
+ * @param {object} m
+ * @param {string} m.type               schema type (already sanitized)
+ * @param {string} m.sensitivity        low | medium | high
+ * @param {number} [m.confidence]       0..1
+ * @param {string} [m.content]          used for dormancy detection on continuations
+ * @param {number} [m.valence]          -1..1, classifier-supplied
+ * @param {number} [m.llm_arousal]      0..1, classifier-supplied (preferred over formula)
+ * @param {string} [m.source_memory_type]  original taxonomy tag from an import
+ */
+export function inferUsageGuidance({
+  type, sensitivity, confidence, content, valence, llm_arousal, source_memory_type,
+}) {
+  const ug = {
+    source_memory_type: source_memory_type || type,
+    import_policy: "upgrade_on_better",
+    stability: "stable",
+    salience: clamp(confidence ?? 0.7, 0.5, 1.0),
+  };
+
+  switch (type) {
+    case "resume_guidance":
+      // How a fresh session should arrive — always-on orientation.
+      ug.proactive_use = "yes";
+      ug.live_retrieval_eligible = true;
+      ug.salience = 1.0;
+      ug.future_response_guidance = "Read at session start to calibrate tone. Do not quote.";
+      break;
+    case "boundary":
+    case "constraint":
+      ug.proactive_use = "only_when_relevant";
+      ug.live_retrieval_eligible = false; // behavior guidance, not retrieval content
+      ug.salience = 0.95;
+      ug.future_response_guidance = "Silently shape behavior. Do not quote back.";
+      break;
+    case "context_note":
+      ug.proactive_use = "no"; // background context; surfaces only on explicit anchor
+      ug.live_retrieval_eligible = false;
+      ug.salience = 0.85;
+      ug.future_response_guidance = "Background context. Not for quoting.";
+      break;
+    case "style_adjustment":
+      ug.proactive_use = "only_when_relevant";
+      ug.live_retrieval_eligible = false;
+      ug.salience = 0.9;
+      ug.future_response_guidance = "Silently shape voice. Not for quoting.";
+      break;
+    case "continuation":
+      ug.proactive_use = "only_when_relevant";
+      ug.live_retrieval_eligible = !/\[dormant\]/i.test(content || "");
+      ug.salience = ug.live_retrieval_eligible ? 0.75 : 0.5;
+      break;
+    default:
+      ug.proactive_use = "only_when_relevant";
+      // Default true regardless of sensitivity — see module header.
+      ug.live_retrieval_eligible = true;
+      break;
+  }
+
+  if (typeof valence === "number") ug.valence = clamp(valence, -1, 1);
+  if (typeof llm_arousal === "number" && llm_arousal >= 0 && llm_arousal <= 1) {
+    ug.arousal = Number(llm_arousal.toFixed(3));
+  } else {
+    ug.arousal = inferArousal({
+      type, source_memory_type, valence: ug.valence, salience: ug.salience,
+    });
+  }
+
+  return ug;
+}

package/src/memory/query.js

@@ -0,0 +1,111 @@
+/**
+ * query.js — the curated read paths over memory_objects.
+ *
+ * Two distinct always-on blocks feed prompt assembly (semantic retrieval
+ * is separate — see src/retrieval/):
+ *
+ *   1. PROACTIVE memories (`proactive_use = 'yes'`) — identity-level
+ *      orientation the companion carries into every session. Small,
+ *      curated set.
+ *
+ *   2. BEHAVIOR GUIDANCE (Tier 2) — boundaries, constraints, and style
+ *      rules with a curated `should_do` instruction. These silently shape
+ *      behavior and are never quoted back. Only items that EARNED an
+ *      instruction appear here; most memories are content-only (Tier 1)
+ *      and never enter this block — which is how the assembled prompt
+ *      stays lean instead of becoming a wall of caution.
+ */
+
+const STATUS_RANK = { reinforced: 0, active: 1, confirmed: 2 };
+const ACTIVE_STATUSES = ["active", "confirmed", "reinforced"];
+
+/**
+ * Always-on identity/orientation memories.
+ * Ranked: status (reinforced first) → confidence.
+ */
+export async function getProactiveMemories(supabase, { limit = 20 } = {}) {
+  const { data, error } = await supabase
+    .from("memory_objects")
+    .select("id, domain, type, content, status, confidence, sensitivity, should_do, usage_guidance")
+    .in("status", ACTIVE_STATUSES)
+    .eq("usage_guidance->>proactive_use", "yes")
+    .order("confidence", { ascending: false })
+    .limit(limit * 2);
+  if (error) throw new Error(`getProactiveMemories: ${error.message}`);
+
+  const sorted = (data || []).sort((a, b) => {
+    const ra = STATUS_RANK[a.status] ?? 9;
+    const rb = STATUS_RANK[b.status] ?? 9;
+    if (ra !== rb) return ra - rb;
+    return (b.confidence ?? 0) - (a.confidence ?? 0);
+  });
+  return sorted.slice(0, limit);
+}
+
+/**
+ * Tier 2 behavior guidance.
+ *
+ * Filter: instructional types, high confidence, `should_do` populated.
+ * Excludes proactive_use='yes' (those live in the proactive block —
+ * including them here would double-inject) and 'no' (explicit-anchor
+ * only). Ranked: salience → evidence_refs count (a rule reinforced
+ * across many sessions outranks a one-off correction) → status.
+ *
+ * Capped small by default (8): lean-not-cautious.
+ */
+export async function getBehaviorGuidance(
+  supabase,
+  { limit = 8, minConfidence = 0.85 } = {}
+) {
+  const { data, error } = await supabase
+    .from("memory_objects")
+    .select("id, domain, type, content, status, confidence, sensitivity, should_do, should_not_do, usage_guidance, evidence_refs")
+    .in("status", ACTIVE_STATUSES)
+    .in("type", ["boundary", "constraint", "style_adjustment", "context_note"])
+    .gte("confidence", minConfidence)
+    .not("should_do", "is", null)
+    .order("confidence", { ascending: false })
+    .limit(limit * 3);
+  if (error) throw new Error(`getBehaviorGuidance: ${error.message}`);
+
+  const filtered = (data || []).filter((m) => {
+    const pu = m.usage_guidance?.proactive_use;
+    return pu !== "yes" && pu !== "no";
+  });
+
+  filtered.sort((a, b) => {
+    const sa = a.usage_guidance?.salience ?? 0;
+    const sb = b.usage_guidance?.salience ?? 0;
+    if (sa !== sb) return sb - sa;
+    const ea = Array.isArray(a.evidence_refs) ? a.evidence_refs.length : 0;
+    const eb = Array.isArray(b.evidence_refs) ? b.evidence_refs.length : 0;
+    if (ea !== eb) return eb - ea;
+    return (STATUS_RANK[a.status] ?? 9) - (STATUS_RANK[b.status] ?? 9);
+  });
+
+  return filtered.slice(0, limit);
+}
+
+/** Soft-delete: mark a memory deprecated with a reason in version_history. */
+export async function deprecateMemory(supabase, id, reason) {
+  const { data: existing, error: fetchErr } = await supabase
+    .from("memory_objects")
+    .select("status, version_history, usage_guidance")
+    .eq("id", id)
+    .single();
+  if (fetchErr) throw new Error(`deprecateMemory fetch #${id}: ${fetchErr.message}`);
+
+  const { error } = await supabase
+    .from("memory_objects")
+    .update({
+      status: "deprecated",
+      usage_guidance: { ...(existing.usage_guidance || {}), proactive_use: "no" },
+      version_history: [
+        ...(existing.version_history || []),
+        { prev_status: existing.status, deprecated_at: new Date().toISOString(), reason: reason || null },
+      ],
+      updated_at: new Date().toISOString(),
+    })
+    .eq("id", id);
+  if (error) throw new Error(`deprecateMemory #${id}: ${error.message}`);
+}