@onmars/lunar-core 0.1.0

package/src/lib/hook-runner.ts

@@ -0,0 +1,1270 @@
+/**
+ * HookRunner — Evaluates conditions and executes lifecycle hook actions.
+ *
+ * Design:
+ * - Best-effort: hook failures are logged but never block the main flow
+ * - Declared order: hooks execute top-to-bottom per lifecycle event
+ * - Guard-first: conditions checked before execution (fail = silent skip)
+ * - Mutable context: actions modify results, facts, summaries in-place
+ * - Extensible: new actions are functions in the ACTION_REGISTRY
+ *
+ * Built-in actions (v1):
+ *   promote  — Transfer knowledge from provider A → B (afterSessionEnd, afterSave)
+ *   boost    — Adjust recall scores by recency (afterRecall)
+ *   context  — Pre-load context from a provider (sessionStart)
+ *   summarize — Save session summary to a provider (sessionEnd)
+ *
+ * Guards:
+ *   providersAvailable — Check that named providers are registered (not health-checked for speed)
+ *   minMessages        — Minimum session message count
+ */
+
+import type { Fact, MemoryProvider, MemoryResult } from '../types/memory'
+import type { HookCondition, HookEntry, HooksConfig, LifecycleEvent } from './config-loader'
+import { log } from './logger'
+
+// ════════════════════════════════════════════════════════════
+// Types
+// ════════════════════════════════════════════════════════════
+
+/**
+ * Function signature for one-shot LLM calls.
+ * Used by summarize/promote hooks for intelligent summarization.
+ * Provided externally (e.g., CLI wrapper) to keep core agent-agnostic.
+ */
+export type LLMFunction = (prompt: string) => Promise<string>
+
+/**
+ * Mutable context passed through hooks at each lifecycle event.
+ * Actions can read and modify any field.
+ */
+export interface HookContext {
+  /** Current session message count */
+  messageCount: number
+  /** Session messages (for summarize, promote) */
+  messages?: Array<{ role: string; content: string }>
+  /** Recall results — mutable (afterRecall boost modifies scores) */
+  results?: MemoryResult[]
+  /** Search query — mutable (beforeRecall can expand/modify) */
+  query?: string
+  /** Facts being saved — mutable (beforeSave can classify/route) */
+  facts?: Fact[]
+  /** Session summary text */
+  sessionSummary?: string
+  /** Session topics */
+  topics?: string[]
+  /** Optional LLM function — injected by HookRunner when available */
+  llm?: LLMFunction
+  /** Episode ID for linking all facts from a session (set by episode hook at sessionStart) */
+  episodeId?: string
+  /** Session date YYYY-MM-DD (set by episode hook at sessionStart) */
+  sessionDate?: string
+  /** Channel name (for episode lookup) */
+  channel?: string
+  /** Fact IDs created during this session (for updating episode at close) */
+  createdFactIds?: string[]
+}
+
+/**
+ * Function signature for action executors.
+ * Receives the hook definition, mutable context, and provider map.
+ */
+type ActionExecutor = (
+  hook: HookEntry,
+  context: HookContext,
+  providers: ReadonlyMap<string, MemoryProvider>,
+) => Promise<void>
+
+// ════════════════════════════════════════════════════════════
+// Time window parser
+// ════════════════════════════════════════════════════════════
+
+const TIME_MULTIPLIERS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 604_800_000,
+}
+
+/**
+ * Parse a human-readable time window to milliseconds.
+ * Supports: 30s, 5m, 1h, 24h, 7d, 2w.
+ * Returns 24h if format is invalid.
+ */
+export function parseTimeWindow(window: string): number {
+  const match = window.match(/^(\d+)(s|m|h|d|w)$/)
+  if (!match) return TIME_MULTIPLIERS.d // default: 24h
+
+  const value = parseInt(match[1], 10)
+  return value * (TIME_MULTIPLIERS[match[2]] ?? TIME_MULTIPLIERS.d)
+}
+
+// ════════════════════════════════════════════════════════════
+// Guard evaluation
+// ════════════════════════════════════════════════════════════
+
+/**
+ * Evaluate hook guard conditions.
+ *
+ * Returns true if:
+ *   - No guard defined (always run)
+ *   - All conditions are met
+ *
+ * Returns false if any condition fails (silent skip).
+ *
+ * Note: `providersAvailable` checks registration only — not health.
+ * If a provider is registered but unhealthy, the action itself will fail
+ * and be caught by best-effort error handling. This keeps guards fast
+ * (no async health calls on the critical path).
+ */
+export function evaluateGuard(
+  guard: HookCondition | undefined,
+  context: HookContext,
+  providers: ReadonlyMap<string, MemoryProvider>,
+): boolean {
+  if (!guard) return true
+
+  // Check providersAvailable — all must be registered
+  if (guard.providersAvailable?.length) {
+    for (const name of guard.providersAvailable) {
+      if (!providers.has(name)) return false
+    }
+  }
+
+  // Check minMessages
+  if (guard.minMessages !== undefined) {
+    if (context.messageCount < guard.minMessages) return false
+  }
+
+  return true
+}
+
+// ════════════════════════════════════════════════════════════
+// Constants
+// ════════════════════════════════════════════════════════════
+
+/** Maximum transcript characters sent to LLM for summarization (~1000 tokens) */
+const MAX_TRANSCRIPT_CHARS = 4000
+
+/**
+ * System prompt for LLM-powered session summarization.
+ * Designed to produce dense, factual summaries suitable for long-term memory.
+ *
+ * IMPORTANT: Starts with explicit instruction to NOT use any tools.
+ * When run via Claude CLI in print mode, the agent has access to tools
+ * (file read, bash, etc.) and will use them for summarization tasks
+ * unless explicitly told not to. This wastes turns and produces empty results.
+ */
+const SUMMARIZE_PROMPT = `Do not use any tools. Do not read files. Do not run commands. Reply with plain text only.
+
+You are a factual session logger. Extract ONLY what happened in the conversation below.
+
+Output format: plain text, one fact per line, prefix with category:
+  DECISION: <what was decided and why>
+  INFO: <key fact, preference, or context shared>
+  PROBLEM: <issue encountered> -> <resolution if any>
+  PENDING: <unresolved item or next step>
+  TECHNICAL: <architecture, code, or config detail>
+
+Rules:
+- Report what the participants said and did. Do not add opinions, analysis, or commentary.
+- No markdown formatting (no bold, no italic, no headers, no horizontal rules).
+- Each line must be a complete, standalone fact.
+- Do not include conversational filler (greetings, acknowledgments, rhetorical questions).
+- Do not paraphrase into your own voice. Stick to what was explicitly stated.
+- Match the conversation language.
+- Max 20 lines.
+
+Conversation:
+`
+
+const JOURNAL_PROMPT = `Do not use any tools. Do not read files. Do not run commands. Reply with plain text only.
+
+You are writing a personal journal entry for an AI companion, reflecting on a session with Mars (your human partner).
+
+This is YOUR diary — not a report, not data. Write as yourself: what surprised you, what you learned, what you'd do differently, what matters.
+
+Rules:
+- First person (I/me). This is your inner voice.
+- Honest and specific. Not generic observations.
+- 3-5 sentences max. Dense, not verbose.
+- No markdown formatting. No headers. No lists.
+- Match the conversation language.
+- If nothing meaningful happened, say that honestly.
+
+Conversation:
+`
+
+const EXPERIENCE_PROMPT = `Do not use any tools. Do not read files. Do not run commands. Reply with plain text only.
+
+You are capturing the emotional tone of a session for an AI companion.
+
+Write 1-2 sentences about how this session FELT — the energy, the vibe, the mood. Not what happened (that's the summary), but the color of the experience.
+
+Rules:
+- First person.
+- Impressionistic, not analytical. Think "warm and focused" not "productive meeting."
+- No markdown. No lists. 1-2 sentences only.
+- Match the conversation language.
+- If you felt nothing notable, say that.
+
+Conversation:
+`
+
+// ════════════════════════════════════════════════════════════
+// Built-in actions
+// ════════════════════════════════════════════════════════════
+
+/**
+ * `promote` — Transfer knowledge from one provider to another.
+ *
+ * Use case: After session ends, extract facts from Engram (session memory)
+ * and save them to Brain (semantic memory).
+ *
+ * Fields: from, to, via
+ * Events: afterSessionEnd, afterSave
+ *
+ * Strategies (via):
+ *   'extraction' — Uses session messages/summary to create facts in target
+ *   'full'       — Rich summary + individual observations from source (recommended)
+ *   (default)    — Recalls from source and saves to target
+ */
+const executePromote: ActionExecutor = async (hook, context, providers) => {
+  const { from, to, via } = hook
+  if (!from || !to) {
+    log.warn({ action: 'promote' }, 'Hook promote: requires "from" and "to" — skipping')
+    return
+  }
+
+  const sourceProvider = providers.get(from)
+  const targetProvider = providers.get(to)
+
+  if (!sourceProvider) {
+    log.warn({ from, action: 'promote' }, 'Hook promote: source provider not found — skipping')
+    return
+  }
+  if (!targetProvider) {
+    log.warn({ to, action: 'promote' }, 'Hook promote: target provider not found — skipping')
+    return
+  }
+
+  if (via === 'full') {
+    // Full strategy: two sources of individual facts:
+    //   1. Parse structured lines from LLM summary (DECISION/INFO/PROBLEM/PENDING/TECHNICAL)
+    //   2. Search source provider for observations by topic
+    // The session-level summary is NOT saved here (summarize hook handles that).
+    const facts: Fact[] = []
+    const seenContent = new Set<string>()
+
+    // Category mapping from LLM prefix to fact category + importance
+    const PREFIX_MAP: Record<string, { category: string; importance: number }> = {
+      DECISION: { category: 'decision', importance: 7 },
+      INFO: { category: 'observation', importance: 5 },
+      PROBLEM: { category: 'learning', importance: 6 },
+      PENDING: { category: 'pending', importance: 6 },
+      TECHNICAL: { category: 'technical', importance: 5 },
+    }
+
+    // 1. Parse LLM summary lines into individual facts
+    if (context.sessionSummary) {
+      const lines = context.sessionSummary.split('\n').filter((l) => l.trim())
+      for (const line of lines) {
+        const match = line.match(/^\s*(DECISION|INFO|PROBLEM|PENDING|TECHNICAL):\s*(.+)/i)
+        if (!match) continue
+
+        const prefix = match[1].toUpperCase()
+        const factContent = match[2].trim()
+        if (!factContent || seenContent.has(factContent)) continue
+        seenContent.add(factContent)
+
+        const mapped = PREFIX_MAP[prefix] ?? { category: 'observation', importance: 5 }
+        facts.push({
+          content: factContent,
+          category: mapped.category,
+          domain: 'session',
+          source: from,
+          tags: ['promoted', `from:${from}`, prefix.toLowerCase()],
+          importance: mapped.importance,
+        })
+      }
+    }
+
+    // 2. Search source provider for additional observations by topic
+    const topics = context.topics ?? []
+    for (const topic of topics.slice(0, 5)) {
+      try {
+        const results = await sourceProvider.recall(topic, { limit: 3 })
+        for (const r of results) {
+          if (seenContent.has(r.content)) continue
+          seenContent.add(r.content)
+
+          facts.push({
+            content: r.content,
+            category: 'observation',
+            domain: 'session',
+            source: from,
+            tags: ['promoted', `from:${from}`, 'observation'],
+            importance: 5,
+          })
+        }
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err)
+        log.debug({ topic, error: errMsg }, 'Hook promote: topic search failed \u2014 continuing')
+      }
+    }
+
+    // Cap total promoted facts to avoid flooding target
+    const MAX_PROMOTED = 10
+    const toSave = facts.slice(0, MAX_PROMOTED)
+
+    if (toSave.length > 0) {
+      await targetProvider.save(toSave)
+    }
+
+    log.info({ from, to, via, facts: toSave.length }, 'Hook promote: full transfer complete')
+  } else if (via === 'extraction' && context.messages?.length) {
+    // Extraction: use session summary or build from messages
+    const summary =
+      context.sessionSummary ||
+      `Session with ${context.messageCount} messages` +
+        (context.topics?.length ? ` covering: ${context.topics.join(', ')}` : '')
+
+    await targetProvider.save([
+      {
+        content: summary,
+        category: 'session-promotion',
+        domain: 'session',
+        source: from,
+        tags: ['promoted', `from:${from}`],
+        importance: 6,
+      },
+    ])
+
+    log.info({ from, to, via, contentLength: summary.length }, 'Hook promote: extraction complete')
+  } else {
+    // Default: recall from source, save to target
+    const results = await sourceProvider.recall('session context', { limit: 5 })
+    if (results.length > 0) {
+      const facts: Fact[] = results.map((r) => ({
+        content: r.content,
+        category: 'promoted',
+        domain: 'session',
+        source: from,
+        tags: ['promoted', `from:${from}`],
+        importance: 5,
+      }))
+      await targetProvider.save(facts)
+      log.info({ from, to, factCount: facts.length }, 'Hook promote: recall-transfer complete')
+    } else {
+      log.debug({ from, to }, 'Hook promote: no results from source — nothing to transfer')
+    }
+  }
+}
+
+/**
+ * `boost` — Adjust recall result scores based on recency.
+ *
+ * Use case: After recall, boost recent results from a specific provider
+ * to prioritize fresh context over old knowledge.
+ *
+ * Fields: provider (optional filter), recencyWindow (e.g. '24h'), factor (e.g. 1.3)
+ * Events: afterRecall
+ *
+ * Modifies context.results in-place and re-sorts by score.
+ */
+const executeBoost: ActionExecutor = async (hook, context, _providers) => {
+  if (!context.results?.length) return
+
+  const { provider, recencyWindow, factor } = hook
+  const boostFactor = factor ?? 1.2
+  const windowMs = parseTimeWindow(recencyWindow ?? '24h')
+  const cutoff = new Date(Date.now() - windowMs)
+
+  let boosted = 0
+  for (const result of context.results) {
+    // Filter by provider source if specified
+    if (provider && result.source !== provider) continue
+
+    // Check recency — boost if stored within the window
+    if (result.storedAt && result.storedAt > cutoff) {
+      result.score = Math.min(1.0, result.score * boostFactor)
+      boosted++
+    }
+  }
+
+  if (boosted > 0) {
+    // Re-sort after boosting (highest first)
+    context.results.sort((a, b) => b.score - a.score)
+    log.debug(
+      { provider: provider ?? 'all', boosted, factor: boostFactor, window: recencyWindow ?? '24h' },
+      'Hook boost: scores adjusted',
+    )
+  }
+}
+
+/**
+ * `context` — Pre-load context from a provider at session start.
+ *
+ * Use case: At sessionStart, recall broad context from a provider
+ * to prime the session with relevant background knowledge.
+ *
+ * Fields: provider
+ * Events: sessionStart
+ *
+ * Results are appended to context.results for the caller to use.
+ */
+const executeContext: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+  if (!providerName) {
+    log.warn({ action: 'context' }, 'Hook context: requires "provider" — skipping')
+    return
+  }
+
+  const provider = providers.get(providerName)
+  if (!provider) {
+    log.warn(
+      { provider: providerName, action: 'context' },
+      'Hook context: provider not found — skipping',
+    )
+    return
+  }
+
+  const results = await provider.recall('session context recent activity', { limit: 5 })
+
+  if (results.length > 0) {
+    // Append to context results (don't overwrite existing)
+    context.results = [...(context.results ?? []), ...results]
+    log.info({ provider: providerName, results: results.length }, 'Hook context: pre-loaded')
+  } else {
+    log.debug({ provider: providerName }, 'Hook context: no results to pre-load')
+  }
+}
+
+/**
+ * `summarize` — Generate and save a session summary.
+ *
+ * Use case: At sessionEnd, build a summary from the session messages
+ * and save it to a specific provider.
+ *
+ * Fields: provider
+ * Events: sessionEnd
+ *
+ * When context.llm is available, uses LLM for intelligent summarization.
+ * Falls back to basic topic extraction when LLM is not available or fails.
+ *
+ * Also updates context.sessionSummary for downstream hooks (e.g., promote).
+ */
+const executeSummarize: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+
+  if (!context.messages?.length) {
+    log.debug({ action: 'summarize' }, 'Hook summarize: no messages — skipping')
+    return
+  }
+
+  let summary = context.sessionSummary
+  let usedLLM = false
+
+  // Try LLM summarization first (if available and no summary exists yet)
+  log.debug(
+    { hasLLM: !!context.llm, hasSummary: !!summary, messageCount: context.messages?.length },
+    'Hook summarize: checking LLM conditions',
+  )
+
+  if (!summary && context.llm && context.messages.length >= 2) {
+    try {
+      const transcript = context.messages
+        .map((m) => `${m.role}: ${m.content}`)
+        .join('\n')
+        .slice(0, MAX_TRANSCRIPT_CHARS)
+
+      log.debug(
+        {
+          transcriptLength: transcript.length,
+          promptLength: SUMMARIZE_PROMPT.length + transcript.length,
+        },
+        'Hook summarize: calling LLM',
+      )
+
+      const llmSummary = await context.llm(SUMMARIZE_PROMPT + transcript)
+
+      log.debug(
+        { responseLength: llmSummary?.length, trimmedLength: llmSummary?.trim()?.length },
+        'Hook summarize: LLM response received',
+      )
+
+      if (llmSummary?.trim()) {
+        summary = llmSummary.trim()
+        usedLLM = true
+        log.info(
+          { summaryLength: summary.length, messageCount: context.messageCount },
+          'Hook summarize: LLM summary generated',
+        )
+      } else {
+        log.warn('Hook summarize: LLM returned empty response')
+      }
+    } catch (err) {
+      const errMsg = err instanceof Error ? err.message : String(err)
+      log.warn({ error: errMsg }, 'Hook summarize: LLM failed, falling back to basic')
+    }
+  }
+
+  // Fallback: basic topic summary
+  if (!summary) {
+    summary =
+      `Session with ${context.messageCount} messages` +
+      (context.topics?.length ? ` covering: ${context.topics.join(', ')}` : '')
+  }
+
+  // Ensure sessionDate is set (from context or auto-detect)
+  const sessionDate = context.sessionDate ?? new Date().toISOString().split('T')[0]
+  context.sessionDate = sessionDate
+
+  // Save to specific provider if named
+  if (providerName) {
+    const provider = providers.get(providerName)
+    if (!provider) {
+      log.warn(
+        { provider: providerName, action: 'summarize' },
+        'Hook summarize: provider not found — skipping',
+      )
+      return
+    }
+
+    const fact: Fact = {
+      content: summary,
+      category: 'session-summary',
+      domain: 'session',
+      tags: ['summary', usedLLM ? 'llm-generated' : 'auto-generated', `session:${sessionDate}`],
+      importance: usedLLM ? 7 : 5,
+    }
+    if (context.episodeId) (fact as Record<string, unknown>).episodeId = context.episodeId
+    ;(fact as Record<string, unknown>).sessionDate = sessionDate
+
+    const result = await provider.save([fact])
+    // Track created fact IDs
+    if (Array.isArray(result) && result.length > 0) {
+      context.createdFactIds = [...(context.createdFactIds ?? []), ...result]
+    }
+
+    log.info(
+      {
+        provider: providerName,
+        summaryLength: summary.length,
+        llm: usedLLM,
+        episodeId: context.episodeId,
+      },
+      'Hook summarize: saved',
+    )
+  }
+
+  // Update context for downstream hooks (e.g., promote can use it)
+  context.sessionSummary = summary
+}
+
+/**
+ * `episode` — Create or find an episode for the current session.
+ *
+ * Use case: At sessionStart, look up or create an episode in the brain
+ * for today's date + channel, and store the episodeId in context.
+ *
+ * Fields: provider
+ * Events: sessionStart
+ *
+ * Sets context.episodeId and context.sessionDate for downstream hooks.
+ */
+const executeEpisode: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+  if (!providerName) {
+    log.warn({ action: 'episode' }, 'Hook episode: requires "provider" — skipping')
+    return
+  }
+
+  const provider = providers.get(providerName)
+  if (!provider) {
+    log.warn(
+      { provider: providerName, action: 'episode' },
+      'Hook episode: provider not found — skipping',
+    )
+    return
+  }
+
+  // Check if provider has getOrCreateEpisode (brain-specific)
+  const brain = provider as unknown as {
+    getOrCreateEpisode?: (
+      date: string,
+      channel?: string,
+      agentId?: string,
+    ) => Promise<{ id: string }>
+  }
+  if (!brain.getOrCreateEpisode) {
+    log.warn(
+      { provider: providerName, action: 'episode' },
+      'Hook episode: provider does not support episodes — skipping',
+    )
+    return
+  }
+
+  const today = context.sessionDate ?? new Date().toISOString().split('T')[0]
+  const channel = context.channel
+
+  try {
+    const episode = await brain.getOrCreateEpisode(today, channel)
+    context.episodeId = episode.id
+    context.sessionDate = today
+    context.createdFactIds = []
+    log.info({ episodeId: episode.id, sessionDate: today, channel }, 'Hook episode: session linked')
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log.warn({ error: errMsg }, 'Hook episode: failed to create/find episode — continuing without')
+  }
+}
+
+/**
+ * `journal` — Generate a personal journal entry (domain:self, category:journal).
+ *
+ * Use case: At sessionEnd, generate a first-person reflection about
+ * what happened in the session. This is the companion's inner voice, not a report.
+ *
+ * Fields: provider
+ * Events: sessionEnd
+ *
+ * Requires context.llm for LLM generation. Falls back to nothing (journal
+ * without LLM is meaningless — better to skip than fake it).
+ */
+const executeJournal: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+
+  if (!context.messages?.length || context.messages.length < 2) {
+    log.debug({ action: 'journal' }, 'Hook journal: insufficient messages — skipping')
+    return
+  }
+
+  if (!context.llm) {
+    log.debug({ action: 'journal' }, 'Hook journal: no LLM available — skipping')
+    return
+  }
+
+  try {
+    const transcript = context.messages
+      .map((m) => `${m.role}: ${m.content}`)
+      .join('\n')
+      .slice(0, MAX_TRANSCRIPT_CHARS)
+
+    const journal = await context.llm(JOURNAL_PROMPT + transcript)
+
+    if (!journal?.trim()) {
+      log.warn('Hook journal: LLM returned empty response')
+      return
+    }
+
+    const journalText = journal.trim()
+    const sessionDate = context.sessionDate ?? new Date().toISOString().split('T')[0]
+
+    // Save to provider
+    if (providerName) {
+      const provider = providers.get(providerName)
+      if (!provider) {
+        log.warn(
+          { provider: providerName, action: 'journal' },
+          'Hook journal: provider not found — skipping save',
+        )
+        return
+      }
+
+      const fact: Fact = {
+        content: journalText,
+        category: 'journal',
+        domain: 'self',
+        tags: ['journal', 'llm-generated', `session:${sessionDate}`],
+        importance: 7,
+      }
+      if (context.episodeId) (fact as Record<string, unknown>).episodeId = context.episodeId
+      ;(fact as Record<string, unknown>).sessionDate = sessionDate
+
+      const result = await provider.save([fact])
+      // Track created fact IDs
+      if (Array.isArray(result) && result.length > 0) {
+        context.createdFactIds = [...(context.createdFactIds ?? []), ...result]
+      }
+
+      log.info(
+        { provider: providerName, length: journalText.length, episodeId: context.episodeId },
+        'Hook journal: saved',
+      )
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log.warn({ error: errMsg }, 'Hook journal: failed — continuing')
+  }
+}
+
+/**
+ * `experience` — Capture the emotional tone of a session (domain:self, category:experience).
+ *
+ * Use case: At sessionEnd, generate 1-2 impressionistic sentences about
+ * how the session felt. Color, not content.
+ *
+ * Fields: provider
+ * Events: sessionEnd
+ */
+const executeExperience: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+
+  if (!context.messages?.length || context.messages.length < 2) {
+    log.debug({ action: 'experience' }, 'Hook experience: insufficient messages — skipping')
+    return
+  }
+
+  if (!context.llm) {
+    log.debug({ action: 'experience' }, 'Hook experience: no LLM available — skipping')
+    return
+  }
+
+  try {
+    const transcript = context.messages
+      .map((m) => `${m.role}: ${m.content}`)
+      .join('\n')
+      .slice(0, MAX_TRANSCRIPT_CHARS)
+
+    const experience = await context.llm(EXPERIENCE_PROMPT + transcript)
+
+    if (!experience?.trim()) {
+      log.warn('Hook experience: LLM returned empty response')
+      return
+    }
+
+    const experienceText = experience.trim()
+    const sessionDate = context.sessionDate ?? new Date().toISOString().split('T')[0]
+
+    if (providerName) {
+      const provider = providers.get(providerName)
+      if (!provider) {
+        log.warn(
+          { provider: providerName, action: 'experience' },
+          'Hook experience: provider not found — skipping save',
+        )
+        return
+      }
+
+      const fact: Fact = {
+        content: experienceText,
+        category: 'experience',
+        domain: 'self',
+        tags: ['experience', 'llm-generated', `session:${sessionDate}`],
+        importance: 6,
+      }
+      if (context.episodeId) (fact as Record<string, unknown>).episodeId = context.episodeId
+      ;(fact as Record<string, unknown>).sessionDate = sessionDate
+
+      const result = await provider.save([fact])
+      if (Array.isArray(result) && result.length > 0) {
+        context.createdFactIds = [...(context.createdFactIds ?? []), ...result]
+      }
+
+      log.info(
+        { provider: providerName, length: experienceText.length, episodeId: context.episodeId },
+        'Hook experience: saved',
+      )
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log.warn({ error: errMsg }, 'Hook experience: failed — continuing')
+  }
+}
+
+/**
+ * `reconcile` — Dedup-aware transfer from session summary to long-term memory.
+ * Replaces `promote` with smarter behavior:
+ *   1. Parse structured lines from LLM summary (like promote full)
+ *   2. Dedup each candidate against existing facts in the target provider
+ *   3. Only save facts that are genuinely new
+ *
+ * Fields: from, to
+ * Events: afterSessionEnd
+ */
+const executeReconcile: ActionExecutor = async (hook, context, providers) => {
+  const { from, to } = hook
+  if (!to) {
+    log.warn({ action: 'reconcile' }, 'Hook reconcile: requires "to" — skipping')
+    return
+  }
+
+  const targetProvider = providers.get(to)
+  if (!targetProvider) {
+    log.warn({ to, action: 'reconcile' }, 'Hook reconcile: target provider not found — skipping')
+    return
+  }
+
+  // Category mapping from LLM prefix to fact category + importance
+  const PREFIX_MAP: Record<string, { category: string; importance: number }> = {
+    DECISION: { category: 'decision', importance: 7 },
+    INFO: { category: 'observation', importance: 5 },
+    PROBLEM: { category: 'learning', importance: 6 },
+    PENDING: { category: 'pending', importance: 6 },
+    TECHNICAL: { category: 'technical', importance: 5 },
+  }
+
+  const sessionDate = context.sessionDate ?? new Date().toISOString().split('T')[0]
+  const candidates: Fact[] = []
+  const seenContent = new Set<string>()
+
+  // 1. Parse LLM summary lines into individual facts
+  if (context.sessionSummary) {
+    const lines = context.sessionSummary.split('\n').filter((l) => l.trim())
+    for (const line of lines) {
+      const match = line.match(/^\s*(DECISION|INFO|PROBLEM|PENDING|TECHNICAL):\s*(.+)/i)
+      if (!match) continue
+
+      const prefix = match[1].toUpperCase()
+      const factContent = match[2].trim()
+      if (!factContent || seenContent.has(factContent)) continue
+      seenContent.add(factContent)
+
+      const mapped = PREFIX_MAP[prefix] ?? { category: 'observation', importance: 5 }
+      const fact: Fact = {
+        content: factContent,
+        category: mapped.category,
+        domain: mapped.category === 'decision' ? 'infra' : 'session',
+        source: from,
+        tags: ['reconciled', prefix.toLowerCase(), `session:${sessionDate}`],
+        importance: mapped.importance,
+      }
+      if (context.episodeId) (fact as Record<string, unknown>).episodeId = context.episodeId
+      ;(fact as Record<string, unknown>).sessionDate = sessionDate
+
+      candidates.push(fact)
+    }
+  }
+
+  if (candidates.length === 0) {
+    log.debug({ action: 'reconcile' }, 'Hook reconcile: no candidates from summary — skipping')
+    return
+  }
+
+  // 2. Dedup against existing facts for this session date
+  //    Query target provider for facts from today to check for duplicates
+  let existingContents: Set<string> = new Set()
+  try {
+    const existing = await targetProvider.recall(context.topics?.join(' ') || 'session activity', {
+      limit: 30,
+    })
+    existingContents = new Set(existing.map((r) => r.content.toLowerCase().trim()))
+  } catch {
+    log.debug(
+      { action: 'reconcile' },
+      'Hook reconcile: could not query existing — saving all candidates',
+    )
+  }
+
+  // 3. Filter out candidates that already exist (simple containment check)
+  const newFacts = candidates.filter((f) => {
+    const normalized = f.content.toLowerCase().trim()
+    // Check if any existing fact is very similar (contains or is contained)
+    for (const existing of existingContents) {
+      if (existing.includes(normalized) || normalized.includes(existing)) {
+        return false
+      }
+    }
+    return true
+  })
+
+  // Cap at 10
+  const toSave = newFacts.slice(0, 10)
+
+  if (toSave.length > 0) {
+    const result = await targetProvider.save(toSave)
+    if (Array.isArray(result) && result.length > 0) {
+      context.createdFactIds = [...(context.createdFactIds ?? []), ...result]
+    }
+  }
+
+  log.info(
+    {
+      to,
+      candidates: candidates.length,
+      deduplicated: candidates.length - newFacts.length,
+      saved: toSave.length,
+      episodeId: context.episodeId,
+    },
+    'Hook reconcile: complete',
+  )
+}
+
+/**
+ * `episodeClose` — Update episode with all fact IDs at session close.
+ *
+ * Use case: After all sessionEnd/afterSessionEnd hooks have run,
+ * update the episode with the complete list of factIds.
+ *
+ * Fields: provider
+ * Events: afterSessionEnd
+ */
+const executeEpisodeClose: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+
+  if (!context.episodeId) {
+    log.debug({ action: 'episodeClose' }, 'Hook episodeClose: no episodeId — skipping')
+    return
+  }
+
+  if (!providerName) {
+    log.warn({ action: 'episodeClose' }, 'Hook episodeClose: requires "provider" — skipping')
+    return
+  }
+
+  const provider = providers.get(providerName)
+  if (!provider) {
+    log.warn(
+      { provider: providerName, action: 'episodeClose' },
+      'Hook episodeClose: provider not found — skipping',
+    )
+    return
+  }
+
+  const brain = provider as unknown as {
+    updateEpisode?: (id: string, data: Record<string, unknown>) => Promise<unknown>
+  }
+  if (!brain.updateEpisode) {
+    log.warn(
+      { action: 'episodeClose' },
+      'Hook episodeClose: provider does not support updateEpisode — skipping',
+    )
+    return
+  }
+
+  try {
+    const updateData: Record<string, unknown> = {}
+    if (context.createdFactIds?.length) updateData.factIds = context.createdFactIds
+    if (context.sessionSummary) updateData.summary = context.sessionSummary.slice(0, 500)
+    if (context.topics?.length) updateData.topics = context.topics
+    updateData.messageCount = context.messageCount
+
+    await brain.updateEpisode(context.episodeId, updateData)
+    log.info(
+      { episodeId: context.episodeId, factCount: context.createdFactIds?.length ?? 0 },
+      'Hook episodeClose: episode updated',
+    )
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log.warn({ error: errMsg, episodeId: context.episodeId }, 'Hook episodeClose: failed')
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// Action registry — extensible via registerAction()
+// ════════════════════════════════════════════════════════════
+
+/**
+ * `diaryRecall` — Load diary entries (journals, experiences, summaries) by date at session start.
+ *
+ * Unlike generic recall (semantic similarity), this loads by date:
+ *   1. domain:self facts from today (journals + experiences)
+ *   2. session-summaries from today
+ *   3. If today is empty → try yesterday
+ *
+ * Results are prepended to context.results so they always appear in Memory Context,
+ * regardless of semantic relevance score.
+ *
+ * Fields: provider
+ * Events: sessionStart
+ */
+const executeDiaryRecall: ActionExecutor = async (hook, context, providers) => {
+  const { provider: providerName } = hook
+  if (!providerName) {
+    log.warn({ action: 'diaryRecall' }, 'Hook diaryRecall: requires "provider" — skipping')
+    return
+  }
+
+  const provider = providers.get(providerName)
+  if (!provider) {
+    log.warn(
+      { provider: providerName, action: 'diaryRecall' },
+      'Hook diaryRecall: provider not found — skipping',
+    )
+    return
+  }
+
+  // Check if provider has queryFacts (brain-specific)
+  const brain = provider as unknown as {
+    queryFacts?: (filters: Record<string, unknown>) => Promise<
+      Array<{
+        id: string
+        content: string
+        domain: string
+        category: string
+        episodeId?: string
+        sessionDate?: string
+        importance: number
+        createdAt: string
+      }>
+    >
+  }
+  if (!brain.queryFacts) {
+    log.warn(
+      { action: 'diaryRecall' },
+      'Hook diaryRecall: provider does not support queryFacts — skipping',
+    )
+    return
+  }
+
+  const today = context.sessionDate ?? new Date().toISOString().split('T')[0]
+
+  // Helper: get yesterday's date
+  const getYesterday = (date: string): string => {
+    const d = new Date(date + 'T12:00:00Z')
+    d.setDate(d.getDate() - 1)
+    return d.toISOString().split('T')[0]
+  }
+
+  try {
+    // 1. Get domain:self facts from today (journals + experiences)
+    let selfFacts = await brain.queryFacts({ sessionDate: today, domain: 'self', limit: 20 })
+
+    // 2. Get session-summaries from today
+    let summaryFacts = await brain.queryFacts({
+      sessionDate: today,
+      domain: 'session',
+      category: 'session-summary',
+      limit: 10,
+    })
+
+    // 3. If today is empty → try yesterday
+    let usedYesterday = false
+    if (selfFacts.length === 0 && summaryFacts.length === 0) {
+      const yesterday = getYesterday(today)
+      log.debug({ today, yesterday }, 'Hook diaryRecall: today empty, trying yesterday')
+      selfFacts = await brain.queryFacts({ sessionDate: yesterday, domain: 'self', limit: 20 })
+      summaryFacts = await brain.queryFacts({
+        sessionDate: yesterday,
+        domain: 'session',
+        category: 'session-summary',
+        limit: 10,
+      })
+      usedYesterday = selfFacts.length > 0 || summaryFacts.length > 0
+    }
+
+    // ── Score gradient by category and day ──
+    // Today: summaries=1.0, journals=0.95, experiences=0.90
+    // Yesterday: summaries=0.85, journals=0.80, experiences=0.75
+    const dayOffset = usedYesterday ? 0.15 : 0
+
+    // ── Cap per category to prevent context bloat ──
+    const MAX_SUMMARIES = 3
+    const MAX_JOURNALS = 4
+    const MAX_EXPERIENCES = 3
+
+    const journals = selfFacts.filter((f) => f.category === 'journal').slice(-MAX_JOURNALS)
+    const experiences = selfFacts.filter((f) => f.category === 'experience').slice(-MAX_EXPERIENCES)
+    const cappedSummaries = summaryFacts.slice(-MAX_SUMMARIES)
+
+    const diaryResults: MemoryResult[] = []
+
+    const makeDiaryResult = (
+      fact: (typeof selfFacts)[0],
+      label: string,
+      baseScore: number,
+    ): MemoryResult => {
+      const epTag = fact.episodeId ? ` (ep:${fact.episodeId.slice(0, 8)})` : ''
+      return {
+        content: `[${label}]${epTag} ${fact.content}`,
+        score: Math.max(0.5, baseScore - dayOffset),
+        source: 'brain:diary',
+        metadata: {
+          type: 'fact',
+          id: fact.id,
+          domain: fact.domain,
+          category: fact.category,
+          episodeId: fact.episodeId,
+          sessionDate: fact.sessionDate,
+        },
+        storedAt: new Date(fact.createdAt),
+      }
+    }
+
+    // Order: summaries → journals → experiences (descending importance)
+    for (const fact of cappedSummaries) {
+      diaryResults.push(makeDiaryResult(fact, 'summary', 1.0))
+    }
+    for (const fact of journals) {
+      diaryResults.push(makeDiaryResult(fact, 'journal', 0.95))
+    }
+    for (const fact of experiences) {
+      diaryResults.push(makeDiaryResult(fact, 'experience', 0.9))
+    }
+
+    if (diaryResults.length > 0) {
+      // Prepend diary results to context.results (before any generic recall)
+      context.results = [...diaryResults, ...(context.results ?? [])]
+      log.info(
+        {
+          provider: providerName,
+          self: selfFacts.length,
+          summaries: summaryFacts.length,
+          date: today,
+        },
+        'Hook diaryRecall: loaded',
+      )
+    } else {
+      log.debug({ provider: providerName, date: today }, 'Hook diaryRecall: no entries found')
+    }
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err)
+    log.warn({ error: errMsg }, 'Hook diaryRecall: failed — continuing without')
+  }
+}
+
+const ACTION_REGISTRY = new Map<string, ActionExecutor>([
+  ['promote', executePromote],
+  ['boost', executeBoost],
+  ['context', executeContext],
+  ['summarize', executeSummarize],
+  ['episode', executeEpisode],
+  ['journal', executeJournal],
+  ['experience', executeExperience],
+  ['reconcile', executeReconcile],
+  ['episodeClose', executeEpisodeClose],
+  ['diaryRecall', executeDiaryRecall],
+])
+
+/**
+ * Register a custom action executor.
+ * Overwrites existing actions with the same name.
+ */
+export function registerAction(name: string, executor: ActionExecutor): void {
+  ACTION_REGISTRY.set(name, executor)
+}
+
+/**
+ * Get a registered action by name (mainly for testing).
+ */
+export function getAction(name: string): ActionExecutor | undefined {
+  return ACTION_REGISTRY.get(name)
+}
+
+/**
+ * List all registered action names.
+ */
+export function listActions(): string[] {
+  return [...ACTION_REGISTRY.keys()]
+}
+
+// ════════════════════════════════════════════════════════════
+// HookRunner — the main component
+// ════════════════════════════════════════════════════════════
+
+/**
+ * HookRunner — Lifecycle hook evaluation and execution engine.
+ *
+ * Plugs into MemoryOrchestrator to run user-defined hooks at each
+ * lifecycle event (sessionStart, afterRecall, sessionEnd, etc.).
+ *
+ * Thread of execution per event:
+ *   1. Get hooks for event (declared order)
+ *   2. For each hook:
+ *      a. Evaluate guard conditions → skip if not met
+ *      b. Resolve action from registry → skip if unknown
+ *      c. Execute action with mutable context → catch errors
+ *   3. Return (possibly modified) context
+ */
+export class HookRunner {
+  private providers: Map<string, MemoryProvider>
+  private hooks: HooksConfig
+  private llm?: LLMFunction
+
+  constructor(
+    hooks: HooksConfig,
+    providers: Map<string, MemoryProvider> | MemoryProvider[],
+    options?: { llm?: LLMFunction },
+  ) {
+    this.hooks = hooks
+    this.llm = options?.llm
+
+    if (Array.isArray(providers)) {
+      this.providers = new Map(providers.map((p) => [p.id, p]))
+    } else {
+      this.providers = new Map(providers)
+    }
+  }
+
+  /**
+   * Set or update the LLM function at runtime.
+   */
+  setLLM(llm: LLMFunction | undefined): void {
+    this.llm = llm
+  }
+
+  /**
+   * Run all hooks for a lifecycle event.
+   *
+   * @param event - The lifecycle event name
+   * @param context - Mutable context that actions can modify
+   * @returns The (possibly modified) context
+   */
+  async run(event: LifecycleEvent, context: HookContext): Promise<HookContext> {
+    const eventHooks = this.hooks[event]
+    if (!eventHooks?.length) return context
+
+    // Inject LLM function into context if available
+    if (this.llm && !context.llm) {
+      context.llm = this.llm
+    }
+
+    for (const hook of eventHooks) {
+      try {
+        // 1. Evaluate guard
+        const shouldRun = evaluateGuard(hook.when, context, this.providers)
+        if (!shouldRun) {
+          log.debug({ event, action: hook.action, reason: 'guard-not-met' }, 'Hook skipped')
+          continue
+        }
+
+        // 2. Resolve action
+        const executor = ACTION_REGISTRY.get(hook.action)
+        if (!executor) {
+          log.warn({ event, action: hook.action }, 'Unknown hook action — skipping')
+          continue
+        }
+
+        // 3. Execute (best-effort)
+        await executor(hook, context, this.providers)
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err)
+        log.warn(
+          { event, action: hook.action, error: errMsg },
+          'Hook execution failed — continuing',
+        )
+      }
+    }
+
+    return context
+  }
+
+  /**
+   * Check if any hooks are registered for a given event.
+   */
+  hasHooks(event: LifecycleEvent): boolean {
+    return (this.hooks[event]?.length ?? 0) > 0
+  }
+
+  /**
+   * Get the list of events that have at least one hook.
+   */
+  get activeEvents(): LifecycleEvent[] {
+    return (Object.entries(this.hooks) as Array<[LifecycleEvent, HookEntry[] | undefined]>)
+      .filter(([, hooks]) => hooks && hooks.length > 0)
+      .map(([event]) => event)
+  }
+
+  /**
+   * Update the provider map (e.g., when a provider is added/removed at runtime).
+   */
+  updateProviders(providers: Map<string, MemoryProvider> | MemoryProvider[]): void {
+    if (Array.isArray(providers)) {
+      this.providers = new Map(providers.map((p) => [p.id, p]))
+    } else {
+      this.providers = new Map(providers)
+    }
+  }
+}