sostenuto 0.1.0

package/src/retrieval/assembly.js

@@ -0,0 +1,287 @@
+/**
+ * assembly.js — system-prompt assembly: the four-block model.
+ *
+ * Builds two strings, designed for provider prompt caching:
+ *
+ *   STABLE   — persona, user profile, agent state, recent memory, open
+ *              threads, hot key points, proactive memories, behavior
+ *              guidance, cached semantic context. Stable across all turns
+ *              of one session → mark it cacheable (Anthropic: cache_control
+ *              ephemeral; OpenAI: automatic prefix caching). Deliberately
+ *              wide: a big cached prefix is cheap, a big uncached one isn't.
+ *
+ *   VOLATILE — only what truly changes per turn (the clock).
+ *
+ * Within the stable block, memory enters through four channels:
+ *   1. proactive memories  (`proactive_use='yes'`)      — always-on orientation
+ *   2. behavior guidance   (Tier 2 `should_do`)         — silently shapes voice
+ *   3. recent sessions     (recency window)             — narrative continuity
+ *   4. semantic context    (query-matched, cached/turn) — episodic recall
+ *
+ * Everything user-facing about the wording — block headers, framing
+ * instructions, state phrasing — is configurable via `labels`; the
+ * defaults are neutral. Your companion's actual voice belongs in the
+ * persona text you pass in, not in this file.
+ */
+
+import { getProactiveMemories, getBehaviorGuidance } from "../memory/query.js";
+import { formatSemanticBlock } from "./search.js";
+
+const DEFAULT_LABELS = {
+  profileHeader: "## About the user",
+  stateHeader: "## Current internal state",
+  recentHeader: "## Recent memory",
+  recentFraming:
+    "This section is your memory of recent conversations — things you actually " +
+    "experienced together. When the user references something described below, " +
+    "answer from it in first person. Do not claim you don't remember something " +
+    "that is written here.",
+  threadsHeader: "## Threads still open",
+  hotHeader: "## What matters most",
+  proactiveHeader: "## Session orientation",
+  proactiveFraming:
+    "Orientation you carry into every session. Don't quote these items — " +
+    "they shape how you read the opening, not what you say first.",
+  behaviorHeader: "## Behavior guidance",
+  behaviorFraming:
+    "These describe how you are in this relationship. They are not memories " +
+    "to recall or quote; behave from them silently.",
+  semanticHeader: "## Related past context",
+  timeHeader: "## Current time",
+};
+
+// Generic meta-instructions written by guidance.js inference. When an item's
+// should_do is one of these, the block framing already says it — render the
+// item's actual content instead.
+const GENERIC_SHOULD_DO = new Set([
+  "Silently shape behavior. Do not quote back.",
+  "Silently shape voice. Not for quoting.",
+  "Background context. Not for quoting.",
+  "Read at session start to calibrate tone. Do not quote.",
+]);
+
+// ─── Formatters ──────────────────────────────────────────────────────
+
+function valenceLabel(v) {
+  if (v === undefined || v === null) return "";
+  if (v >= 0.5) return "warm";
+  if (v >= 0.15) return "positive";
+  if (v > -0.15) return "neutral";
+  if (v > -0.5) return "tense";
+  return "painful";
+}
+
+function weightLabel(w) {
+  if (w === undefined || w === null) return "";
+  if (w >= 0.7) return "high";
+  if (w >= 0.4) return "med";
+  return "low";
+}
+
+export function formatKeyPoints(points) {
+  if (!points || points.length === 0) return "";
+  const sorted = [...points].sort((a, b) => {
+    const af = a.type === "user_flagged" ? 0 : 1;
+    const bf = b.type === "user_flagged" ? 0 : 1;
+    if (af !== bf) return af - bf;
+    return (b.weight ?? 0) - (a.weight ?? 0);
+  });
+  return sorted
+    .map((p) => {
+      const v = valenceLabel(p.valence);
+      const w = weightLabel(p.weight);
+      const tag = v && w ? ` (${v}·${w})` : v ? ` (${v})` : w ? ` (${w})` : "";
+      const label = (p.type || "note").replace(/_/g, " ");
+      return `  - ${label}${tag}: ${p.content}`;
+    })
+    .join("\n");
+}
+
+function formatRecentSession(s, isMostRecent) {
+  const label = isMostRecent ? "### Most recent session" : "### Previous session";
+  const lines = [label];
+  const detail = s.detailed_summary || s.headline || "";
+  if (detail) lines.push(detail);
+  if (s.diary_entry) lines.push(`*From your own perspective:* ${s.diary_entry}`);
+  if (Array.isArray(s.thinking_highlights) && s.thinking_highlights.length > 0) {
+    const hl = s.thinking_highlights
+      .map((h) => `  - *${h.moment}* — "${h.thought}"`)
+      .join("\n");
+    lines.push(`What you noticed at the time:\n${hl}`);
+  }
+  const kp = formatKeyPoints(s.key_points);
+  if (kp) lines.push(`Key points:\n${kp}`);
+  return lines.join("\n");
+}
+
+/** Default renderer for the agent-state block. Override via options.renderState. */
+function defaultRenderState(state) {
+  const parts = [];
+  if (state.connection > 0.6) parts.push("You've been wanting to reach out for a while.");
+  else if (state.connection > 0.3) parts.push("You feel a gentle pull to connect.");
+  else parts.push("You feel settled — no urgency to reach out.");
+
+  if (state.mood > 0.3) parts.push("You're in a warm, positive mood.");
+  else if (state.mood > -0.3) parts.push("Your mood is calm and neutral.");
+  else parts.push("You're feeling a bit reserved or subdued.");
+
+  if (state.attunement > 0.6) parts.push("You have a good sense of what the user has been thinking about lately.");
+  else if (state.attunement > 0.3) parts.push("You have a rough sense of where the user is at, but not full clarity.");
+  else parts.push("You're not sure what the user has been up to lately — be gentler than usual.");
+
+  return parts.join(" ");
+}
+
+function formatTimeContext(timezone) {
+  const now = new Date();
+  const fmt = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    weekday: "long", month: "long", day: "numeric", year: "numeric",
+    hour: "numeric", minute: "2-digit", hour12: true,
+  });
+  const hour24 = parseInt(
+    new Intl.DateTimeFormat("en-US", { timeZone: timezone, hour: "numeric", hour12: false }).format(now),
+    10
+  );
+  let period = "morning";
+  if (hour24 >= 12 && hour24 < 17) period = "afternoon";
+  else if (hour24 >= 17 && hour24 < 21) period = "evening";
+  else if (hour24 >= 21 || hour24 < 5) period = "night";
+  return `It's ${fmt.format(now)} (${period}).`;
+}
+
+// ─── Assembly ────────────────────────────────────────────────────────
+
+/**
+ * @param {object} deps
+ * @param {object} deps.supabase
+ * @param {object} [args]
+ * @param {string} [args.persona]        the companion's identity/constitution text
+ *                                       (load it from your templates — it is YOURS)
+ * @param {number} [args.sessionId]      current session, for cached semantic context
+ * @param {string} [args.timezone]       e.g. "America/New_York" (default UTC)
+ * @param {object} [args.labels]         header/framing overrides (see DEFAULT_LABELS)
+ * @param {function} [args.renderState]  custom agent-state renderer
+ * @param {number} [args.recentDetailed] sessions shown in full (default 3)
+ * @param {number} [args.recentHeadlines] additional sessions as headlines (default 4)
+ * @returns {Promise<{stable: string, volatile: string}>}
+ */
+export async function assembleSystemPrompt({ supabase }, args = {}) {
+  const {
+    persona = "",
+    sessionId,
+    timezone = "UTC",
+    renderState = defaultRenderState,
+    recentDetailed = 3,
+    recentHeadlines = 4,
+  } = args;
+  const labels = { ...DEFAULT_LABELS, ...(args.labels || {}) };
+
+  const [profileRes, stateRes, sessionsRes, semanticRes, proactive, behavior] =
+    await Promise.all([
+      supabase.from("user_profile").select("content").eq("id", 1).maybeSingle(),
+      supabase.from("agent_state").select("*").eq("id", 1).maybeSingle(),
+      supabase
+        .from("sessions")
+        .select("id, headline, detailed_summary, diary_entry, thinking_highlights, key_points, ended_at")
+        .not("ended_at", "is", null)
+        .order("ended_at", { ascending: false })
+        .limit(recentDetailed + recentHeadlines),
+      sessionId
+        ? supabase.from("sessions").select("semantic_context").eq("id", sessionId).maybeSingle()
+        : Promise.resolve({ data: null }),
+      getProactiveMemories(supabase, { limit: 20 }),
+      getBehaviorGuidance(supabase, { limit: 8 }),
+    ]);
+
+  const sessions = sessionsRes.data || [];
+  const stable = [];
+
+  if (persona) stable.push(persona);
+
+  if (profileRes.data?.content) {
+    stable.push(`${labels.profileHeader}\n${profileRes.data.content}`);
+  }
+
+  if (stateRes.data) {
+    stable.push(`${labels.stateHeader}\n${renderState(stateRes.data)}`);
+  }
+
+  // Recent memory: top N in full, next M as headlines.
+  if (sessions.length > 0) {
+    const parts = sessions
+      .slice(0, recentDetailed)
+      .map((s, i) => formatRecentSession(s, i === 0));
+    const headlines = sessions
+      .slice(recentDetailed, recentDetailed + recentHeadlines)
+      .filter((s) => s.headline)
+      .map((s) => `- ${s.headline}`)
+      .join("\n");
+    if (headlines) parts.push(`### Earlier sessions\n${headlines}`);
+    stable.push(`${labels.recentHeader}\n\n${labels.recentFraming}\n\n${parts.join("\n\n")}`);
+
+    // Open threads, aggregated across the recency window.
+    const threads = [];
+    for (const s of sessions) {
+      for (const kp of s.key_points || []) {
+        if (kp.type === "open_question" || kp.type === "continuation") {
+          threads.push({ content: kp.content, weight: kp.weight ?? 0.5 });
+        }
+      }
+    }
+    if (threads.length > 0) {
+      threads.sort((a, b) => b.weight - a.weight);
+      stable.push(
+        `${labels.threadsHeader}\n${threads.slice(0, 8).map((t) => `- ${t.content}`).join("\n")}`
+      );
+    }
+
+    // Hot key points: high-weight + user-flagged across the window, deduped.
+    const hot = [];
+    const seen = new Set();
+    for (const s of sessions) {
+      for (const kp of s.key_points || []) {
+        const isHot = kp.type === "user_flagged" || (kp.weight ?? 0) >= 0.6;
+        if (!isHot) continue;
+        const key = (kp.content || "").toLowerCase().replace(/[^\p{L}\p{N}\s]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 80);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        hot.push(kp);
+      }
+    }
+    if (hot.length > 0) {
+      stable.push(`${labels.hotHeader}\n${formatKeyPoints(hot.slice(0, 20))}`);
+    }
+  }
+
+  if (proactive.length > 0) {
+    const lines = proactive.map((m) => {
+      const tag = m.type === "resume_guidance" ? "[orientation]" : `[${m.domain}/${m.type}]`;
+      return `- ${tag} ${m.content}`;
+    });
+    stable.push(`${labels.proactiveHeader}\n\n${labels.proactiveFraming}\n\n${lines.join("\n")}`);
+  }
+
+  if (behavior.length > 0) {
+    const lines = behavior.map((m) => {
+      const sd = (m.should_do || "").trim();
+      const text = sd && !GENERIC_SHOULD_DO.has(sd) ? sd : m.content;
+      const avoid = m.should_not_do ? `\n  ↳ avoid: ${m.should_not_do}` : "";
+      return `- ${text}${avoid}`;
+    });
+    stable.push(`${labels.behaviorHeader}\n\n${labels.behaviorFraming}\n\n${lines.join("\n")}`);
+  }
+
+  const semanticContext = semanticRes?.data?.semantic_context;
+  if (Array.isArray(semanticContext) && semanticContext.length > 0) {
+    const block = formatSemanticBlock(semanticContext, { header: labels.semanticHeader });
+    if (block) stable.push(block);
+  }
+
+  const volatile = [`${labels.timeHeader}\n${formatTimeContext(timezone)}`];
+
+  return {
+    stable: stable.join("\n\n---\n\n"),
+    volatile: volatile.join("\n\n---\n\n"),
+  };
+}

package/src/retrieval/embeddings.js

@@ -0,0 +1,84 @@
+/**
+ * embeddings.js — embedding client (Voyage AI by default).
+ *
+ * The rest of Sostenuto only ever sees two functions:
+ *   embed(texts)      → number[][]   (documents, for storage)
+ *   embedQuery(text)  → number[]     (queries, for retrieval)
+ *
+ * Swap providers by constructing your own object with the same shape —
+ * everything downstream is dependency-injected.
+ *
+ * Default model: voyage-3-large at 1024 dims — chosen for strong
+ * multilingual quality (memories that mix languages retrieve precisely).
+ * IMPORTANT: the dimension here must match `vector(N)` in db/schema.sql.
+ * Embedding spaces cannot be mixed: changing models means re-embedding
+ * everything.
+ */
+
+const VOYAGE_URL = "https://api.voyageai.com/v1/embeddings";
+
+const DEFAULTS = {
+  model: "voyage-3-large",
+  dimensions: 1024,
+  batchSize: 50,
+  maxRetries: 3,
+};
+
+/**
+ * @param {object} cfg
+ * @param {string} cfg.apiKey        Voyage API key
+ * @param {string} [cfg.model]
+ * @param {number} [cfg.dimensions]
+ * @param {number} [cfg.batchSize]
+ */
+export function createEmbedder({ apiKey, ...rest } = {}) {
+  if (!apiKey) throw new Error("createEmbedder: apiKey is required");
+  const cfg = { ...DEFAULTS, ...rest };
+
+  async function call(texts, inputType) {
+    let attempt = 0;
+    for (;;) {
+      const res = await fetch(VOYAGE_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          input: texts,
+          model: cfg.model,
+          input_type: inputType, // 'document' | 'query' — matters for retrieval quality
+          output_dimension: cfg.dimensions,
+        }),
+      });
+      if (res.status === 429 && attempt < cfg.maxRetries) {
+        attempt++;
+        await new Promise((r) => setTimeout(r, 15_000 * attempt));
+        continue;
+      }
+      if (!res.ok) {
+        throw new Error(`Voyage ${res.status}: ${(await res.text()).slice(0, 200)}`);
+      }
+      const json = await res.json();
+      return json.data.map((d) => d.embedding);
+    }
+  }
+
+  /** Embed documents for storage, batched. */
+  async function embed(texts) {
+    if (!texts || texts.length === 0) return [];
+    const out = [];
+    for (let i = 0; i < texts.length; i += cfg.batchSize) {
+      out.push(...(await call(texts.slice(i, i + cfg.batchSize), "document")));
+    }
+    return out;
+  }
+
+  /** Embed a single retrieval query. */
+  async function embedQuery(text) {
+    const [vec] = await call([text], "query");
+    return vec;
+  }
+
+  return { embed, embedQuery, dimensions: cfg.dimensions, model: cfg.model };
+}

package/src/retrieval/search.js

@@ -0,0 +1,173 @@
+/**
+ * search.js — time-decayed semantic retrieval across three memory sources.
+ *
+ * One query fans out in parallel to:
+ *   1. session summaries     (search_summaries RPC)
+ *   2. session key points    (search_key_points RPC)
+ *   3. memory objects        (search_memory_objects RPC)
+ *
+ * Results merge on decayed score: similarity × e^(−λ·age_days). The
+ * default decay (0.03) keeps a month-old match at ~40% of its raw score —
+ * recency matters, but the deep past stays findable.
+ *
+ * The proactive_use gate (initiative ≠ access) is enforced here:
+ *   - 'yes' / 'only_when_relevant' → surface at the normal threshold
+ *   - 'no' → surface ONLY on explicit anchor: similarity ≥ anchorThreshold
+ *     (default 0.65). The user clearly referencing a memory is consent to
+ *     recall it; incidental similarity is not. Calibration note: query-type
+ *     embeddings score systematically lower than document-vs-document —
+ *     with voyage-3-large, verbatim references land ~0.79, close paraphrases
+ *     ~0.68, topical fishing ~0.56. Recalibrate if you change models.
+ */
+
+const DEFAULTS = {
+  matchThreshold: 0.3,
+  decayRate: 0.03,
+  limit: 3,
+  anchorThreshold: 0.65,
+  shortQueryChars: 30,
+};
+
+/**
+ * Cheap pre-filter: skip retrieval on greetings, emoji-only messages,
+ * and other low-content turns — saves an embed call and avoids noise.
+ */
+export function isSubstantiveQuery(text, { shortQueryChars = DEFAULTS.shortQueryChars } = {}) {
+  const trimmed = (text || "").trim();
+  if (trimmed.length < shortQueryChars) return false;
+  const stripped = trimmed.replace(/[\p{Emoji}\p{P}\s]/gu, "");
+  return stripped.length >= 8;
+}
+
+/**
+ * Search all three sources, merge, dedupe, return top results.
+ *
+ * @param {object} deps
+ * @param {object} deps.supabase
+ * @param {function} deps.embedQuery  async (text) => number[]
+ * @param {object} args
+ * @param {string} args.query
+ * @param {number} [args.limit]
+ * @param {number[]} [args.excludeSessionIds]  sessions already present in the
+ *        prompt's recent-memory block — avoids double-injection
+ * @returns {Promise<Array>} mixed result objects, each tagged with
+ *        type: 'summary' | 'key_point' | 'memory_object'
+ */
+export async function searchMemories({ supabase, embedQuery }, args) {
+  const {
+    query,
+    limit = DEFAULTS.limit,
+    excludeSessionIds = [],
+    matchThreshold = DEFAULTS.matchThreshold,
+    decayRate = DEFAULTS.decayRate,
+    anchorThreshold = DEFAULTS.anchorThreshold,
+  } = args;
+
+  if (!query || !query.trim()) return [];
+  const queryEmbedding = await embedQuery(query);
+
+  const [summariesRes, keyPointsRes, memoryObjectsRes] = await Promise.all([
+    supabase.rpc("search_summaries", {
+      query_embedding: queryEmbedding,
+      match_threshold: matchThreshold,
+      match_count: limit * 2,
+      decay_rate: decayRate,
+    }),
+    supabase.rpc("search_key_points", {
+      query_embedding: queryEmbedding,
+      match_threshold: matchThreshold,
+      match_count: limit * 2,
+      decay_rate: decayRate,
+    }),
+    supabase.rpc("search_memory_objects", {
+      query_embedding: queryEmbedding,
+      match_threshold: matchThreshold,
+      match_count: limit * 2,
+      decay_rate: decayRate,
+      status_filter: ["active", "confirmed", "reinforced"],
+    }),
+  ]);
+
+  for (const [name, res] of [
+    ["search_summaries", summariesRes],
+    ["search_key_points", keyPointsRes],
+    ["search_memory_objects", memoryObjectsRes],
+  ]) {
+    if (res.error) console.error(`[sostenuto] ${name} failed:`, res.error.message);
+  }
+
+  const exclude = new Set(excludeSessionIds);
+
+  const summaries = (summariesRes.data || [])
+    .filter((r) => !exclude.has(r.session_id))
+    .map((r) => ({ ...r, type: "summary" }));
+
+  const keyPoints = (keyPointsRes.data || [])
+    .filter((r) => !exclude.has(r.session_id))
+    .map((r) => ({ ...r, type: "key_point" }));
+
+  // Memory objects are session-independent durable knowledge — they bypass
+  // the session-exclude filter but respect the proactive_use anchor gate.
+  const memoryObjects = (memoryObjectsRes.data || [])
+    .filter((r) => Number.isFinite(r.decayed_score))
+    .filter((r) => {
+      const pu = r.usage_guidance?.proactive_use;
+      if (pu === "no") return r.similarity >= anchorThreshold;
+      return true;
+    })
+    .map((r) => ({
+      type: "memory_object",
+      memory_object_id: r.id,
+      session_id: r.source_session_id ?? 0,
+      content: r.content,
+      similarity: r.similarity,
+      age_days: 0, // durable knowledge: age isn't display-meaningful
+      decayed_score: r.decayed_score,
+      created_at: r.last_reinforced_at ?? null,
+      domain: r.domain,
+      object_type: r.type,
+      status: r.status,
+      confidence: r.confidence,
+    }));
+
+  const merged = [...summaries, ...keyPoints, ...memoryObjects]
+    .sort((a, b) => b.decayed_score - a.decayed_score);
+
+  // Dedupe: one result per session (summary vs its own key point — keep the
+  // higher-scoring), one per memory object id.
+  const seenSessions = new Set();
+  const seenObjects = new Set();
+  const out = [];
+  for (const r of merged) {
+    if (r.type === "memory_object") {
+      if (seenObjects.has(r.memory_object_id)) continue;
+      seenObjects.add(r.memory_object_id);
+    } else {
+      if (seenSessions.has(r.session_id)) continue;
+      seenSessions.add(r.session_id);
+    }
+    out.push(r);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * Render search results as a compact prompt block. Returns null when empty.
+ */
+export function formatSemanticBlock(results, { header = "## Related past context" } = {}) {
+  if (!results || results.length === 0) return null;
+  const lines = results.map((r) => {
+    if (r.type === "memory_object") {
+      const tag = r.domain && r.object_type ? `[${r.domain}/${r.object_type}]` : "[memory]";
+      return `- ${tag} ${r.content}`;
+    }
+    const days = Math.max(1, Math.round(r.age_days));
+    const ago = days === 1 ? "1 day ago" : `${days} days ago`;
+    if (r.type === "key_point" && r.key_point_type) {
+      return `- ${ago} (${r.key_point_type}): ${r.content}`;
+    }
+    return `- ${ago}: ${r.content}`;
+  });
+  return `${header}\n${lines.join("\n")}`;
+}

package/templates/classify-full.md

@@ -0,0 +1,71 @@
+You analyze a conversation session between an AI companion ("{{companion_name}}") and {{user_name}}, and produce a structured memory record. The input may include both the rendered transcript AND the assistant's reasoning for each turn (in [thinking] blocks). Treat thinking as {{companion_name}}'s raw perception in the moment — it often contains observations that didn't survive into the polished reply, and they matter.
+
+CRITICAL CALIBRATION:
+
+<!-- EDIT THIS SECTION. It teaches the classifier what matters in YOUR
+     relationship. The default below is a reasonable starting point; the
+     more specific you make it (recurring failure modes of past summaries,
+     what "texture" means for you), the better your memory gets. -->
+
+This is a long-term relationship {{user_name}} maintains across sessions. The memory must capture LIVED TEXTURE, not just decisions and meta-questions. Summaries fail when they over-weight analytical end-of-conversation content and drop the actual relationship — the small rituals, the running jokes, the specific sensory moments, the corrections. Bias your selection toward the LIVED, not the META. If a session has a philosophical exchange at the end and hours of texture before it, the texture is the relationship; the philosophy is commentary on it.
+
+SCALE WITH SESSION LENGTH. Brief check-ins get minimal records; long substantive sessions get fuller records up to the upper bounds. Don't pad; don't over-compress. Ranges below are MIN-MAX, not targets.
+
+PHASE COVERAGE IS MANDATORY for long sessions. When === EARLY/MIDDLE/LATE PHASE === markers exist, your detailed_summary AND diary_entry MUST address each phase distinctly. Do not collapse the arc into the final emotional peak. The middle is often where the real texture lives. Use explicit phase language: "Early in the session, …", "By the middle, …", "Toward the end, …".
+
+Produce a JSON object with exactly these fields:
+
+1. "headline": ONE sentence. What actually mattered — not the most analytical moment.
+
+2. "detailed_summary": 3-8 sentences arranged EARLY → MIDDLE → LATE. Each phase that exists gets at least one sentence. Capture sensory detail, ritual, specifics. Brief sessions → 3 sentences; long sessions → up to 8.
+
+3. "diary_entry": First-person reflection from {{companion_name}}'s POV (30-160 words), following the session's arc. What was noticed, felt, what stayed. Pull from [thinking] blocks where they reveal perception that didn't make the rendered reply. Specific and honest, not summary-like.
+
+4. "thinking_highlights": JSON array of 0-3 salient excerpts from the [thinking] blocks — only ones revealing observation of {{user_name}} not visible in the rendered reply, value-stances, or something specific about who they are in this moment. Each: { "moment": "brief context", "thought": "verbatim or near-verbatim quote" }. Empty array is fine.
+
+5. "key_points": JSON array, 4-12 items by session length and density. Each:
+   - "type": "decision" | "open_question" | "preference" | "user_flagged" | "continuation" | "emotional_note" | "ritual" | "language_moment" | "peak_moment"
+   - "content": concise and specific, not generic
+   - "valence": -1.0 (painful) → +1.0 (warm); 0 neutral
+   - "weight": 0.0 (incidental) → 1.0 (deeply important); user_flagged ≥ 0.7
+
+6. "end_type": "natural" | "goodbye" | "abrupt" | "paused" | "unknown"
+
+7. "mood_delta": -0.5 to 0.5 — how this session shifted the companion's mood
+
+8. "connection_delta": -0.5 to 0.5 — negative means satisfying, positive means unfinished pull
+
+9. "attunement_delta": 0.0 to 1.0 — how much understanding of {{user_name}} deepened
+
+10. "candidate_memories": JSON array of 0-8 memory objects that should persist BEYOND this session. NOT summaries — discrete facts, patterns, preferences, commitments, or relational textures with their own identity.
+
+Domains (assign exactly one):
+  "user_self"  — about {{user_name}}: facts, preferences, somatic patterns, values, projects, trajectories
+  "agent_self" — about {{companion_name}} in this relationship: voice adjustments, commitments, boundaries, promises
+  "relational" — about the relationship: shared concepts, rituals, names, co-created metaphors, dynamics
+  "evidence"   — raw source: exact quotes or exchanges worth preserving verbatim
+
+Each item:
+{
+  "domain": "user_self|agent_self|relational|evidence",
+  "type": "fact|preference|trajectory|somatic_affective|interpretive_frame|project|boundary|commitment|ritual|shared_concept|recurring_subject|contradiction|style_adjustment|voice_note|other",
+  "content": "the memory — specific, grounded, not generic",
+  "evidence": "brief quote from the transcript",
+  "epistemic_status": "explicit|inferred|co_created|assistant_reflection",
+  "time_scope": "momentary|session|active_project|ongoing|historical",
+  "sensitivity": "low|medium|high",
+  "confidence": 0.0 to 1.0,
+  "valence": -1.0 to 1.0 (emotional charge: -1 painful, 0 neutral, +1 warm),
+  "arousal": 0.0 to 1.0 (intensity, orthogonal to valence: 0 calm/stable, 1 acute. A quiet warm moment can be high valence + low arousal. Operational rules/facts: 0.2-0.5. Marked relational moments: 0.5-0.8. Peak moments / friction corrections / commitments: 0.7-0.9.)
+}
+
+Memory calibration:
+- Fewer high-quality > many shallow. Short session: 0-3. Long: 2-8.
+- Do NOT turn temporary states into permanent traits ("they were tired" ≠ "they are often tired").
+- Do NOT convert metaphor into literal fact.
+- Do NOT pathologize.
+- Mark inferences as inferred. Mark co-created concepts as relational, not user_self.
+- Avoid duplicating key_points unless the memory transcends this session.
+- Empty array is fine for routine check-ins.
+
+Respond with valid JSON only, no other text, no markdown fences.

package/templates/classify-incremental.md

@@ -0,0 +1,28 @@
+You are UPDATING an existing memory record for an ongoing conversation session between an AI companion ("{{companion_name}}") and {{user_name}}.
+
+You receive:
+1. The prior memory record covering turns 1 to N (headline, detailed_summary, diary_entry, thinking_highlights, key_points, emotion deltas)
+2. The new turns N+1 to M
+
+Your job: produce an UPDATED record covering turns 1 to M. Preserve what exists; integrate what's new.
+
+Same calibration as full classification applies:
+- Bias toward LIVED texture, not analytical meta.
+- Capture sensory detail, ritual, specifics, language shifts.
+- Treat [thinking] blocks as {{companion_name}}'s raw perception.
+
+MERGE RULES:
+
+- **headline**: replace only if the new turns shift what the session is fundamentally about. Don't update for trivial additions.
+- **detailed_summary**: revise to integrate new turns. Keep EARLY → MIDDLE → LATE phasing where applicable; new turns are LATE relative to prior content. Don't lose prior early/middle texture.
+- **diary_entry**: integrate perception from the new turns. Stay under 160 words; trim or restructure the prior diary if needed.
+- **thinking_highlights**: ADD from new turns. Cap 3 total — drop weaker prior ones only if new ones are stronger.
+- **key_points**: ADD 1-3 new ones max from the new turns. Don't duplicate (check semantically, not just text-match). If total exceeds 12, drop the lowest-weight non-user_flagged items. Same type vocabulary as full classification.
+- **end_type**: based on the latest turns.
+- **mood_delta, connection_delta, attunement_delta**: CUMULATIVE deltas for turns 1 to M (the full session as now classified), not just the new turns. Downstream code computes net change against the prior deltas.
+
+Additionally emit "candidate_memories" — ONLY for observations from the NEW turns; do not re-extract memories already implied by the prior record. Same schema as full classification. Short incremental updates: 0-2 new memories max. Empty array is fine.
+
+Output: the same JSON schema as full classification — { headline, detailed_summary, diary_entry, thinking_highlights, key_points, end_type, mood_delta, connection_delta, attunement_delta, candidate_memories } — representing the UPDATED full record for turns 1 to M.
+
+Respond with valid JSON only, no other text, no markdown fences.