session.js

/**
 * Smart Memory - SillyTavern Extension
 * Copyright (C) 2026 Senjin the Dragon
 * https://github.com/senjinthedragon/Smart-Memory
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */

/**
 * Session memory: detailed within-chat facts stored in chatMetadata.
 *
 * Sits between short-term (broad narrative summary) and long-term (distilled
 * cross-session facts). Session memories are more granular than long-term -
 * capturing scene details, named objects, specific revelations - but do not
 * survive past the current chat.
 *
 * loadSessionMemories        - returns the current session memory array
 * saveSessionMemories        - persists the session memory array to chatMetadata
 * clearSessionMemories       - empties session memories for the current chat
 * purgeSessionMemoriesSince  - deletes all session memories with ts >= a given timestamp and repairs the entity registry
 * extractSessionMemories     - runs extraction against recent messages and merges results;
 *                              populates LLM-suggested triggers on Profile B or when opted in
 * consolidateSessionMemories - evaluates unprocessed entries against the consolidated base per type
 * injectSessionMemories      - pushes session memories into the prompt via setExtensionPrompt
 */

import {
  setExtensionPrompt,
  extension_prompt_types,
  extension_prompt_roles,
} from '../../../../script.js';
import { generateMemoryExtract } from './generate.js';
import { getContext, extension_settings } from '../../../extensions.js';
import {
  estimateTokens,
  MODULE_NAME,
  META_KEY,
  PROMPT_KEY_SESSION,
  SESSION_TYPES,
  MAX_RETIRED_POOL,
} from './constants.js';
import {
  applyGraphDefaults,
  loadSessionEntityRegistry,
  saveSessionEntityRegistry,
  resolveEntityNames,
  reconcileEntityRegistry,
} from './graph-migration.js';
import {
  buildSessionExtractionPrompt,
  buildSessionConsolidationPrompt,
  buildTriggerGenerationPrompt,
} from './prompts.js';
import { parseSessionOutput, parseTriggerResponse } from './parsers.js';
import {
  batchVerify,
  getEmbeddingBatch,
  cosineSimilarity,
  getHardwareProfile,
} from './embeddings.js';
import { loadCharacterMemories, formatMemoriesForPrompt } from './longterm.js';
import {
  buildCurrentSceneStateBlock,
  prioritizeMemories,
  hybridPrioritize,
  extractTurnEntityMentions,
  reconcileTypeEntries,
  selectProtectedMemories,
  sortByTimeline,
  trimByPriority,
  filterTriggersByFrequency,
} from './memory-utils.js';
import { smLog } from './logging.js';
import { invalidateUnifiedCache } from './unified-inject.js';
import { MACRO_NAMES, setMacroContent, isMacroActive } from './macros.js';
import { reportTierTrimStats } from './trim-stats.js';

/**
 * Filters session memory candidates against existing entries, removing
 * near-duplicates and entries that fail basic quality checks. Identifies
 * supersessions (state-change updates that should retire an existing memory).
 *
 * All texts are embedded in a single batch API call so nomic-embed-text only
 * needs to load once per verification pass rather than once per candidate.
 * Falls back to Jaccard word-overlap when embeddings are unavailable.
 *
 * @param {Array} candidates - Newly extracted session memory objects.
 * @param {Array} existing   - Active (non-retired) session memories.
 * @returns {Promise<{verified: Array, superseded: Map<string, string>, confirmed: Set<string>}>}
 *   verified  - Candidates that passed dedup and should be added.
 *   superseded - Map from candidate content (lowercase) to the id of the
 *                existing memory it replaces.
 *   confirmed  - Set of existing memory ids re-extracted this pass (still true).
 */
async function verifySessionCandidates(candidates, existing) {
  if (!Array.isArray(candidates) || candidates.length === 0) {
    return { verified: [], superseded: new Map(), confirmed: new Set() };
  }

  const seen = new Set();
  const filtered = candidates.filter((mem) => {
    const text = String(mem.content || '').trim();
    if (text.length < 5 || text.length > 240) return false;
    const key = `${mem.type}|${text.toLowerCase()}`;
    if (seen.has(key)) return false;
    seen.add(key);
    return true;
  });

  if (filtered.length === 0) return { verified: [], superseded: new Map(), confirmed: new Set() };

  const { passed, superseded, confirmed } = await batchVerify(filtered, existing);
  const verified = filtered.filter((m) =>
    passed.has(
      String(m.content || '')
        .toLowerCase()
        .trim(),
    ),
  );
  return { verified, superseded, confirmed };
}

// ---- Storage (chatMetadata) ---------------------------------------------

/**
 * Returns the session memory array for the current chat.
 * Migrates legacy entries (no consolidated flag) to consolidated: true on load
 * so existing memories are treated as the stable base.
 * @returns {Array<{type: string, content: string, ts: number, consolidated: boolean}>}
 */
export function loadSessionMemories() {
  const context = getContext();
  const memories = context.chatMetadata?.[META_KEY]?.sessionMemories ?? [];
  // Migrate: entries without the consolidated flag are pre-existing stable memories.
  // Entries without an importance score default to 2 (medium).
  // applyGraphDefaults is a safety net for entries that predate the one-shot
  // migration pass. It is non-destructive and only generates a new id when one
  // is truly absent.
  return memories.map((m) =>
    applyGraphDefaults({
      ...m,
      consolidated: m.consolidated ?? true,
      importance: m.importance ?? 2,
      expiration: m.expiration ?? 'session',
      confidence: m.confidence ?? 0.7,
      persona_relevance: m.persona_relevance ?? (m.type === 'development' ? 2 : 1),
      intimacy_relevance: m.intimacy_relevance ?? (m.type === 'development' ? 2 : 1),
      retrieval_count: m.retrieval_count ?? 0,
      // Fall back to 0 (not Date.now()) when both fields are absent so legacy
      // entries don't receive an artificial recency boost in memoryUtilityScore.
      last_confirmed_ts: m.last_confirmed_ts ?? m.ts ?? 0,
    }),
  );
}

/**
 * Persists the session memory array to chatMetadata.
 * @param {Array<{type: string, content: string, ts: number}>} memories
 */
export async function saveSessionMemories(memories) {
  const context = getContext();
  if (!context.chatMetadata) context.chatMetadata = {};
  if (!context.chatMetadata[META_KEY]) context.chatMetadata[META_KEY] = {};
  context.chatMetadata[META_KEY].sessionMemories = memories;
  await context.saveMetadata();
}

/**
 * Empties session memories for the current chat.
 */
export async function clearSessionMemories() {
  const context = getContext();
  if (context.chatMetadata?.[META_KEY]) {
    context.chatMetadata[META_KEY].sessionMemories = [];
    await context.saveMetadata();
  }
}

/**
 * Removes all session memories whose ts field is >= the given timestamp,
 * then repairs the session entity registry to remove stale memory_ids.
 *
 * Used when read-only mode is disabled to purge memories that were extracted
 * during a read-only window before they can contaminate profiles or the entity
 * registry. Memories without a ts field are treated as pre-existing and kept.
 *
 * @param {number} since - Unix ms timestamp. Memories at or after this time are deleted.
 * @returns {Promise<number>} Number of memories removed.
 */
export async function purgeSessionMemoriesSince(since) {
  const all = loadSessionMemories();
  const kept = all.filter((m) => typeof m.ts !== 'number' || m.ts < since);
  const removed = all.length - kept.length;
  if (removed === 0) return 0;

  // Repair entity registry - reconcileEntityRegistry prunes stale memory_ids
  // left behind by the deleted memories and re-links by name match.
  const entityRegistry = loadSessionEntityRegistry();
  if (entityRegistry.length > 0) {
    reconcileEntityRegistry(entityRegistry, kept);
    await saveSessionEntityRegistry(entityRegistry);
  }

  await saveSessionMemories(kept);
  smLog(`[SmartMemory] Purged ${removed} session memories from read-only window.`);
  return removed;
}

// ---- Parsing ------------------------------------------------------------

/**
 * Merges new session memories into the existing set, skipping near-duplicates
 * and trimming to the configured maximum.
 *
 * Primary: cosine similarity on embeddings (threshold 0.82), matching the
 * scene dedup strategy. Falls back to a word-overlap ratio when embeddings
 * are unavailable: intersection / max(|A|, |B|) > 0.65. The asymmetric
 * denominator avoids short strings over-matching against long ones.
 *
 * @param {Array} existing - Currently stored session memories.
 * @param {Array} incoming - Newly extracted items to merge in.
 * @param {number} max - Hard cap on total session memories.
 * @returns {Promise<Array>} The merged array.
 */
async function deduplicateSession(existing, incoming, max) {
  const merged = [...existing];

  // Batch all texts up front so comparisons are O(1) per pair.
  const allTexts = [
    ...existing.map((m) => m.content.toLowerCase().trim()),
    ...incoming.map((m) => m.content.toLowerCase().trim()),
  ];
  let vectorMap = null;
  try {
    vectorMap = await getEmbeddingBatch(allTexts);
  } catch {
    // embedding service unavailable - fall through to word-overlap
  }

  for (const mem of incoming) {
    const memKey = mem.content.toLowerCase().trim();
    const memVec = vectorMap?.get(memKey);

    const isDuplicate = merged.some((ex) => {
      if (ex.type !== mem.type) return false;

      if (memVec) {
        const exVec = vectorMap.get(ex.content.toLowerCase().trim());
        if (exVec) return cosineSimilarity(memVec, exVec) > 0.82;
      }

      // Word-overlap fallback.
      const words = new Set(mem.content.toLowerCase().split(/\s+/));
      const exWords = new Set(ex.content.toLowerCase().split(/\s+/));
      const intersection = [...words].filter((w) => exWords.has(w)).length;
      return intersection / Math.max(words.size, exWords.size) > 0.65;
    });
    if (!isDuplicate) merged.push(mem);
  }

  // When over the cap, drop the least valuable entries first.
  if (merged.length > max) {
    const prioritized = prioritizeMemories(merged);
    merged.splice(0, merged.length, ...prioritized);
    merged.splice(max);
  }
  return merged;
}

// ---- Extraction ---------------------------------------------------------

/**
 * Extracts session-level details from recent messages via the model and merges
 * them into chatMetadata. Returns the count of new items saved.
 * @param {Array} recentMessages - Last N message objects from context.chat.
 * @returns {Promise<number>} Count of new items added (0 on failure or nothing found).
 */
/**
 * @param {Function|null} [abortCheck] - Optional zero-arg function; if it returns true the function
 *   bails out before writing to chatMetadata. Used by the automatic extraction path to abort when
 *   the user switches chats mid-extraction.
 */
export async function extractSessionMemories(recentMessages, abortCheck = null) {
  const settings = extension_settings[MODULE_NAME];
  if (!settings.session_enabled) return 0;

  try {
    const chatHistory = recentMessages
      .filter((m) => m.mes && !m.is_system)
      .map((m) => `${m.name}: ${m.mes}`)
      .join('\n\n');

    if (!chatHistory.trim()) return 0;

    const existingAll = loadSessionMemories();

    // Separate active from retired memories. Verification and merge operate only
    // on active entries; retired ones are preserved in storage for history but
    // should not be compared against (or count toward caps during merge).
    const existing = existingAll.filter((m) => !m.superseded_by);
    const retiredMemories = existingAll.filter((m) => m.superseded_by);

    const existingText = existing.map((m) => `[${m.type}] ${m.content}`).join('\n');

    // Pass long-term memories so the model skips facts already stored there.
    // Cap to 15 entries to avoid inflating the prompt on local hardware.
    // In group chats there is no single authoritative character, so skip this
    // hint rather than arbitrarily biasing toward one member's long-term store.
    const isGroup = !!getContext().groupId;
    const characterName = isGroup ? null : getContext().name2 || getContext().characterName || null;
    const longtermMemories = characterName ? loadCharacterMemories(characterName) : [];
    const longtermText =
      longtermMemories.length > 0 ? formatMemoriesForPrompt(longtermMemories.slice(0, 15)) : '';

    const response = await generateMemoryExtract(
      buildSessionExtractionPrompt(chatHistory, existingText, longtermText),
      { responseLength: settings.session_response_length ?? 500 },
    );

    smLog('[SmartMemory] Session extraction response:', response);

    if (!response || response.trim().toUpperCase() === 'NONE') return 0;

    const {
      verified: incoming,
      superseded: supersessionMap,
      confirmed: confirmedIds,
    } = await verifySessionCandidates(parseSessionOutput(response), existing);
    if (incoming.length === 0) return 0;

    // Tag each new memory with the source message range so users can jump back
    // to the passage that prompted the extraction.
    const context = getContext();
    const chatLen = context.chat?.length ?? 1;
    const windowEnd = Math.max(0, chatLen - 2);
    const windowStart = Math.max(0, windowEnd - recentMessages.length + 1);
    for (const mem of incoming) {
      mem.source_messages = [[windowStart, windowEnd]];
    }

    const max = settings.session_max_memories ?? 30;
    const merged = await deduplicateSession(existing, incoming, max);

    // Apply supersession links. For each candidate that supersedes an existing
    // memory: mark the old memory as retired (superseded_by + valid_to) and
    // link the new memory back to it (supersedes + valid_from).
    const messageIndex = Math.max(0, chatLen - 1);

    const newlyRetiredIds = new Set();
    for (const [candText, oldId] of supersessionMap) {
      const newMem = merged.find(
        (m) =>
          String(m.content || '')
            .toLowerCase()
            .trim() === candText,
      );
      const oldMem = existing.find((m) => m.id === oldId);

      if (newMem && oldMem && !oldMem.superseded_by) {
        if (!newMem.supersedes) newMem.supersedes = [];
        if (!newMem.supersedes.includes(oldId)) newMem.supersedes.push(oldId);
        newMem.valid_from = newMem.valid_from ?? messageIndex;

        oldMem.superseded_by = newMem.id;
        oldMem.valid_to = messageIndex;
        newlyRetiredIds.add(oldId);

        smLog(
          `[SmartMemory] Session supersession: "${oldMem.content.slice(0, 60)}" retired by "${newMem.content.slice(0, 60)}"`,
        );
      }
    }

    // Remove newly retired entries from the active merged set.
    const finalActive = merged.filter((m) => !newlyRetiredIds.has(m.id));

    // Confidence decay pass - mirrors the long-term logic.
    const DECAY_THRESHOLD = 10;
    const now = Date.now();
    for (const mem of finalActive) {
      if (confirmedIds.has(mem.id)) {
        mem.last_confirmed_ts = now;
        mem.confidence = Math.min(1.0, (mem.confidence ?? 1.0) + 0.05);
        mem.unconfirmed_since = 0;
      } else {
        mem.unconfirmed_since = (mem.unconfirmed_since ?? 0) + 1;
        if (mem.unconfirmed_since >= DECAY_THRESHOLD) {
          mem.confidence = Math.max(0.3, (mem.confidence ?? 1.0) - 0.02);
        }
      }
    }

    // Profile B and opted-in Profile A: generate LLM-suggested triggers for
    // newly added session memories. Same path as long-term, runs sequentially.
    const existingKeys = new Set(existing.map((m) => `${m.type}|${m.content}`));
    if (getHardwareProfile() === 'b' || settings.longterm_triggers_enabled) {
      for (const mem of finalActive) {
        if (existingKeys.has(`${mem.type}|${mem.content}`)) continue;
        if (Array.isArray(mem.triggers) && mem.triggers.length > 0) continue;
        try {
          const triggerPrompt = buildTriggerGenerationPrompt(mem.content);
          const triggerResponse = await generateMemoryExtract(triggerPrompt, {
            responseLength: 60,
          });
          const raw = parseTriggerResponse(triggerResponse, mem.content);
          mem.triggers = filterTriggersByFrequency(raw, finalActive);
          smLog(
            `[SmartMemory] Session triggers for "${mem.content.slice(0, 50)}": ${mem.triggers.join(', ')}`,
          );
        } catch (err) {
          smLog(`[SmartMemory] Session trigger generation failed: ${err.message}`);
          mem.triggers = [];
        }
      }
    }

    // Resolve entity names to ids for any new memories that carried
    // _raw_entity_names through the pipeline. The session entity registry is
    // loaded from chatMetadata, updated in place, then persisted.
    const entityRegistry = loadSessionEntityRegistry();
    for (const mem of finalActive) {
      if (Array.isArray(mem._raw_entity_names)) {
        resolveEntityNames(mem, mem._raw_entity_names, messageIndex, entityRegistry);
      }
    }
    // Reconcile after every extraction pass so memories whose entity tag was
    // omitted by the model get linked via substring match immediately rather
    // than waiting for the next consolidation cycle.
    if (entityRegistry.length > 0) {
      reconcileEntityRegistry(entityRegistry, finalActive);
      if (!abortCheck?.()) await saveSessionEntityRegistry(entityRegistry);
    }

    // Newly retired active memories move to the retired pool.
    let updatedRetired = [...retiredMemories, ...existing.filter((m) => newlyRetiredIds.has(m.id))];

    // Cap the retired pool - same reason as longterm.js.
    if (updatedRetired.length > MAX_RETIRED_POOL) {
      updatedRetired = updatedRetired.slice(updatedRetired.length - MAX_RETIRED_POOL);
    }

    const added = finalActive.filter((m) => !existingKeys.has(`${m.type}|${m.content}`)).length;
    if (abortCheck?.()) return 0;
    await saveSessionMemories([...finalActive, ...updatedRetired]);

    return added;
  } catch (err) {
    console.error('[SmartMemory] Session extraction failed:', err);
    throw err;
  }
}

// ---- Consolidation ------------------------------------------------------

// How many unprocessed entries of a single type must accumulate before
// consolidation fires for that type. Used when per-type settings are absent.
const DEFAULT_SESSION_CONSOLIDATION_THRESHOLDS = {
  scene: 3,
  revelation: 3,
  development: 3,
  detail: 3,
};

/**
 * Returns per-type consolidation thresholds, reading from settings with fallback to defaults.
 *
 * @param {object} settings - Extension settings object.
 * @returns {{ scene: number, revelation: number, development: number, detail: number }}
 */
function getSessionConsolidationThresholds(settings) {
  return {
    scene: Math.max(
      2,
      settings.session_consolidation_threshold_scene ??
        DEFAULT_SESSION_CONSOLIDATION_THRESHOLDS.scene,
    ),
    revelation: Math.max(
      2,
      settings.session_consolidation_threshold_revelation ??
        DEFAULT_SESSION_CONSOLIDATION_THRESHOLDS.revelation,
    ),
    development: Math.max(
      2,
      settings.session_consolidation_threshold_development ??
        DEFAULT_SESSION_CONSOLIDATION_THRESHOLDS.development,
    ),
    detail: Math.max(
      2,
      settings.session_consolidation_threshold_detail ??
        DEFAULT_SESSION_CONSOLIDATION_THRESHOLDS.detail,
    ),
  };
}

/**
 * Runs a consolidation pass on session memories for the current chat.
 *
 * Maintains a stable consolidated base per session memory type. When enough
 * unprocessed entries accumulate for a given type, the model evaluates only
 * that batch against the base - it may drop duplicates, fold new details into
 * existing base entries, or add genuinely new entries. The base is never
 * rewritten, only extended.
 *
 * Fires per-type independently - a burst of new [scene] entries does not
 * trigger [detail] consolidation.
 *
 * @param {boolean} [force=false] - If true, consolidate all types regardless of threshold.
 *   Used by the catch-up final pass to flush any entries that never accumulated enough
 *   to hit the threshold during per-chunk consolidation.
 * @param {Function|null} [abortCheck] - Optional zero-arg function; if it returns true the write is skipped (chat switched).
 * @returns {Promise<number>} Number of memories removed by consolidation (0 on no change or failure).
 */
export async function consolidateSessionMemories(force = false, abortCheck = null) {
  const settings = extension_settings[MODULE_NAME];
  if (!settings.session_enabled) return 0;
  if (!settings.consolidation_enabled) return 0;
  const thresholds = getSessionConsolidationThresholds(settings);

  const memories = loadSessionMemories();
  let totalRemoved = 0;
  let dirty = false;

  for (const type of SESSION_TYPES) {
    // Exclude retired memories from consolidation - they've already been replaced.
    const base = memories.filter((m) => m.type === type && m.consolidated && !m.superseded_by);
    const unprocessed = memories.filter(
      (m) => m.type === type && !m.consolidated && !m.superseded_by,
    );

    if (!force && unprocessed.length < (thresholds[type] ?? 3)) continue;
    if (unprocessed.length === 0) continue;

    try {
      const baseText = base.map((m) => `[${m.type}] ${m.content}`).join('\n');
      const batchText = unprocessed.map((m) => `[${m.type}] ${m.content}`).join('\n');

      const response = await generateMemoryExtract(
        buildSessionConsolidationPrompt(type, baseText, batchText),
        { responseLength: Math.max(400, (base.length + unprocessed.length) * 60) },
      );

      smLog(`[SmartMemory] Session consolidation response for [${type}]:`, response);

      if (!response || response.trim().toUpperCase() === 'NONE') {
        // Nothing to add - mark unprocessed as consolidated as-is.
        unprocessed.forEach((m) => (m.consolidated = true));
        dirty = true;
        continue;
      }

      // Parse the model's output - these are the entries to add/update in the base.
      const incoming = parseSessionOutput(response);
      // Mark all incoming as consolidated since they've been through the process.
      const promoted = incoming.map((m) => ({ ...m, consolidated: true }));

      // Reconcile promoted entries with the base so "updated" base entries
      // replace older variants instead of being appended as duplicates.
      const reconciledType = await reconcileTypeEntries(
        base,
        promoted,
        0.65,
        [...base, ...unprocessed],
        getEmbeddingBatch,
      );

      // Replace this type's entries. Other types are untouched.
      const otherTypes = memories.filter((m) => m.type !== type);
      memories.splice(0, memories.length, ...otherTypes, ...reconciledType);

      const before = base.length + unprocessed.length;
      const after = reconciledType.length;
      const removed = before - after;
      totalRemoved += Math.max(0, removed);
      dirty = true;

      smLog(
        `[SmartMemory] Session [${type}] consolidation: ${unprocessed.length} unprocessed -> ${promoted.length} promoted. Base: ${base.length}. Removed: ${Math.max(0, removed)}.`,
      );
    } catch (err) {
      console.error(`[SmartMemory] Session consolidation failed for type [${type}]:`, err);
      // On failure, mark unprocessed as consolidated so they don't block future passes.
      // Set dirty before the forEach so a mid-loop error still triggers the save.
      dirty = true;
      unprocessed.forEach((m) => (m.consolidated = true));
    }
  }

  const max = settings.session_max_memories ?? 30;
  const finalMemories = sortByTimeline(trimByPriority(memories, max));
  if (dirty || finalMemories.length !== memories.length) {
    if (abortCheck?.()) return totalRemoved;
    // Repair session entity registry links - same stale-ID problem as long-term:
    // consolidation replaces memories with new IDs, orphaning the registry.
    const entityRegistry = loadSessionEntityRegistry();
    if (entityRegistry.length > 0) {
      reconcileEntityRegistry(entityRegistry, finalMemories);
      await saveSessionEntityRegistry(entityRegistry);
    }

    await saveSessionMemories(finalMemories);
  }

  return totalRemoved;
}

// ---- Injection ----------------------------------------------------------

/**
 * Formats the session memory array as plain bullet lines for RP prompt injection.
 * The [type] format is kept internally for the extraction/consolidation pipeline
 * (see the inline formatters in extractSessionMemories and consolidateSessionMemories).
 * Using plain bullets here prevents bracket notation from bleeding into story output.
 * @param {Array<{type: string, content: string}>} memories
 * @returns {string}
 */
function formatSessionMemories(memories) {
  if (!memories || memories.length === 0) return '';
  return sortByTimeline(memories)
    .map((m) => `- ${m.content}`)
    .join('\n');
}

/**
 * Injects session memories into the prompt via setExtensionPrompt.
 * Clears the slot if session memory is disabled or no memories exist.
 * @param {boolean} [updateTelemetry=false] - If true, increment retrieval_count for injected memories.
 *   Only pass true from the post-extraction path (one real AI response turn).
 * @returns {Promise<void>}
 */
export async function injectSessionMemories(updateTelemetry = false) {
  const settings = extension_settings[MODULE_NAME];
  if (!settings.session_enabled) {
    setMacroContent(MACRO_NAMES.session, '');
    setExtensionPrompt(PROMPT_KEY_SESSION, '', extension_prompt_types.NONE, 0);
    invalidateUnifiedCache(PROMPT_KEY_SESSION);
    return;
  }

  // Only inject active memories - retired ones (superseded_by set) are kept in
  // storage for history but must not appear in the prompt.
  const memories = loadSessionMemories().filter((m) => !m.superseded_by);
  if (memories.length === 0) {
    setMacroContent(MACRO_NAMES.session, '');
    setExtensionPrompt(PROMPT_KEY_SESSION, '', extension_prompt_types.NONE, 0);
    invalidateUnifiedCache(PROMPT_KEY_SESSION);
    return;
  }

  // Trim to token budget using hybrid scoring on real AI turns, plain utility
  // scoring on chat load (no "current turn" to extract entity mentions from).
  const budget = settings.session_inject_budget ?? 400;
  const fullTokens = estimateTokens(formatSessionMemories(memories));
  const protectedSet = new Set(selectProtectedMemories(memories, ['development', 'scene']));

  let trimmed;
  if (updateTelemetry) {
    const context = getContext();
    const lastMessages = (context.chat ?? []).slice(-2);
    const turnMentions = extractTurnEntityMentions(lastMessages);
    trimmed = await hybridPrioritize(memories, {
      turnMentions,
      floorTypes: ['development', 'scene'],
      embedFn: getEmbeddingBatch,
      lastTurnText: lastMessages[lastMessages.length - 1]?.mes ?? '',
      w5: getHardwareProfile() === 'b' ? 0.6 : 0.2,
    });
  } else {
    trimmed = prioritizeMemories(memories);
  }
  while (trimmed.length > 1 && estimateTokens(formatSessionMemories(trimmed)) > budget) {
    let idx = -1;
    for (let i = trimmed.length - 1; i >= 0; i--) {
      if (!protectedSet.has(trimmed[i])) {
        idx = i;
        break;
      }
    }
    if (idx >= 0) trimmed.splice(idx, 1);
    else break;
  }

  // Only update retrieval telemetry when called from a real AI response turn.
  // Load the full (unfiltered) array so retired memories are preserved - the
  // filtered 'memories' variable only contains active entries and saving it
  // would permanently delete the retired pool.
  if (updateTelemetry) {
    const recalled = new Set(trimmed.map((m) => `${m.type}|${m.content}`));
    const allMemories = loadSessionMemories();
    const updated = allMemories.map((m) => {
      if (m.superseded_by) return m;
      const key = `${m.type}|${m.content}`;
      if (!recalled.has(key)) return m;
      return {
        ...m,
        retrieval_count: (m.retrieval_count ?? 0) + 1,
        last_confirmed_ts: Date.now(),
      };
    });
    await saveSessionMemories(updated);
  }

  const template = settings.session_template ?? 'Details from this session:\n{{session}}';
  const sessionBlock = template.replace('{{session}}', formatSessionMemories(trimmed));
  const sceneStateBlock = buildCurrentSceneStateBlock(trimmed);
  const content = sceneStateBlock ? `${sceneStateBlock}\n${sessionBlock}` : sessionBlock;
  reportTierTrimStats(PROMPT_KEY_SESSION, estimateTokens(content), fullTokens);

  setMacroContent(MACRO_NAMES.session, content);
  if (isMacroActive(MACRO_NAMES.session)) {
    setExtensionPrompt(PROMPT_KEY_SESSION, '', extension_prompt_types.NONE, 0);
    invalidateUnifiedCache(PROMPT_KEY_SESSION);
    return;
  }

  setExtensionPrompt(
    PROMPT_KEY_SESSION,
    content,
    settings.session_position ?? extension_prompt_types.IN_PROMPT,
    settings.session_depth ?? 3,
    false,
    settings.session_role ?? extension_prompt_roles.SYSTEM,
  );
}