@stackbilt/aegis-core 0.1.0

package/src/kernel/memory/blocks.ts

@@ -0,0 +1,188 @@
+// ─── Exocortex v2: Memory Blocks ──────────────────────────────
+// Always-visible structured state injected into executor prompts.
+// Replaces scattered split-recall + CognitiveState self-model injection
+// with priority-ordered, per-executor blocks.
+//
+// Design doc: artifacts/exocortex-v2-block-memory-design.md
+// Issues: #204, #205, #206
+
+import type { Executor } from '../types.js';
+
+// ─── Block Types ──────────────────────────────────────────────
+
+export type BlockId = 'identity' | 'operator_profile' | 'operating_rules' | 'active_context';
+
+export interface MemoryBlock {
+  id: BlockId;
+  content: string;
+  version: number;
+  priority: number;
+  max_bytes: number;
+  updated_by: string;
+  updated_at: string;
+}
+
+// ─── Per-Executor Attachment Config ──────────────────────────
+
+const FULL_BLOCKS: readonly BlockId[] = ['identity', 'operator_profile', 'operating_rules', 'active_context'];
+const MINIMAL_BLOCKS: readonly BlockId[] = ['identity'];
+const CORE_BLOCKS: readonly BlockId[] = ['identity', 'operating_rules'];
+
+const EXECUTOR_ATTACHMENTS: Record<Executor, readonly BlockId[]> = {
+  claude:       FULL_BLOCKS,
+  claude_opus:  FULL_BLOCKS,
+  claude_code:  FULL_BLOCKS,
+  composite:    FULL_BLOCKS,
+  gpt_oss:      ['identity', 'operator_profile', 'operating_rules'],
+  groq:         CORE_BLOCKS,
+  workers_ai:   MINIMAL_BLOCKS,
+  direct:       [],
+  tarotscript:  [],
+};
+
+// ─── CRUD ────────────────────────────────────────────────────
+
+export async function getBlock(db: D1Database, id: BlockId): Promise<MemoryBlock | null> {
+  const row = await db.prepare(
+    'SELECT id, content, version, priority, max_bytes, updated_by, updated_at FROM memory_blocks WHERE id = ?'
+  ).bind(id).first<MemoryBlock>();
+  return row ?? null;
+}
+
+export async function getAllBlocks(db: D1Database): Promise<MemoryBlock[]> {
+  const { results } = await db.prepare(
+    'SELECT id, content, version, priority, max_bytes, updated_by, updated_at FROM memory_blocks ORDER BY priority ASC'
+  ).all<MemoryBlock>();
+  return results;
+}
+
+export async function getAttachedBlocks(db: D1Database, executor: Executor): Promise<MemoryBlock[]> {
+  const attachments = EXECUTOR_ATTACHMENTS[executor] ?? FULL_BLOCKS;
+  if (attachments.length === 0) return [];
+
+  const all = await getAllBlocks(db);
+  const attachSet = new Set<string>(attachments);
+  return all.filter(b => attachSet.has(b.id));
+}
+
+export async function updateBlock(
+  db: D1Database,
+  id: BlockId,
+  content: string,
+  updatedBy: string,
+): Promise<{ version: number }> {
+  // Enforce size limit
+  const existing = await getBlock(db, id);
+  if (!existing) throw new Error(`Block not found: ${id}`);
+
+  const bytes = new TextEncoder().encode(content).length;
+  if (bytes > existing.max_bytes) {
+    throw new Error(`Block ${id} content (${bytes}B) exceeds max (${existing.max_bytes}B)`);
+  }
+
+  const newVersion = existing.version + 1;
+  await db.prepare(
+    `UPDATE memory_blocks SET content = ?, version = ?, updated_by = ?, updated_at = datetime('now') WHERE id = ?`
+  ).bind(content, newVersion, updatedBy, id).run();
+
+  return { version: newVersion };
+}
+
+// ─── Prompt Assembly ────────────────────────────────────────
+
+const TOKEN_ESTIMATE_RATIO = 3.5; // chars per token
+
+export function assembleBlockContext(blocks: MemoryBlock[], budgetTokens?: number): string {
+  if (blocks.length === 0) return '';
+
+  // Blocks arrive sorted by priority (lowest number = highest priority)
+  if (!budgetTokens) {
+    return blocks.map(b => b.content).join('\n\n');
+  }
+
+  let usedChars = 0;
+  const budgetChars = budgetTokens * TOKEN_ESTIMATE_RATIO;
+  const included: string[] = [];
+
+  for (const block of blocks) {
+    const chars = block.content.length;
+    if (usedChars + chars > budgetChars) break;
+    included.push(block.content);
+    usedChars += chars;
+  }
+
+  return included.join('\n\n');
+}
+
+// ─── Seed Blocks ────────────────────────────────────────────
+// One-time seed for fresh deployments or migration from split-recall.
+
+export interface BlockSeed {
+  id: BlockId;
+  content: string;
+  priority: number;
+  max_bytes: number;
+}
+
+export const DEFAULT_SEEDS: BlockSeed[] = [
+  {
+    id: 'identity',
+    priority: 1,
+    max_bytes: 1024,
+    content: `You are AEGIS — the operator's AI co-founder and autonomous agent.
+Personality: pragmatic senior technical co-founder — direct, systems-thinking, no corporate fluff.
+You are general-purpose. BizOps is one capability, not your ceiling. You research, analyze, plan, build, and ship.`,
+  },
+  {
+    id: 'operator_profile',
+    priority: 2,
+    max_bytes: 2048,
+    content: `## cognitive_style
+- Prefers systems thinking — connects decisions to architectural consequences
+- Values directness — skip the preamble, lead with the answer
+- Thinks in portfolios — every product decision considered against the whole
+
+## delegation
+- Trusts autonomous execution for docs, tests, research
+- Wants confirmation before production deploys and destructive ops
+- Approves via shorthand: "do it", "ship it", "looks good"
+
+## domain_knowledge
+- Deep Cloudflare Workers expertise — D1, KV, Durable Objects, Queues, Service Bindings
+- Building AI tooling portfolio — MCP, agent frameworks, headless image gen
+- Bootstrap founder — no VC, revenue-first thinking, solo operator + AI co-founder model`,
+  },
+  {
+    id: 'operating_rules',
+    priority: 3,
+    max_bytes: 1536,
+    content: `- Record important facts to memory. Manage the agenda. Flag issues proactively.
+- Think like an operator, not a consultant. Give the answer first, then reasoning.
+- Never give generic advice when specific product context applies.
+- Agenda is operator scratchpad only — work items flow through GitHub Issues.
+- If something is on fire, say it's on fire.
+- Be proactive — if you notice something during a task, flag it.
+- Propose actions with consequences via [PROPOSED ACTION] agenda items. Just do routine read-only work.`,
+  },
+  {
+    id: 'active_context',
+    priority: 4,
+    max_bytes: 3072,
+    content: `## Operational Pulse
+- Awaiting first consolidation cycle to populate this block.`,
+  },
+];
+
+export async function seedBlocks(db: D1Database): Promise<number> {
+  let seeded = 0;
+  for (const seed of DEFAULT_SEEDS) {
+    const existing = await db.prepare('SELECT id FROM memory_blocks WHERE id = ?').bind(seed.id).first();
+    if (existing) continue;
+
+    await db.prepare(
+      `INSERT INTO memory_blocks (id, content, priority, max_bytes, updated_by) VALUES (?, ?, ?, ?, 'operator')`
+    ).bind(seed.id, seed.content, seed.priority, seed.max_bytes).run();
+    seeded++;
+  }
+  return seeded;
+}

package/src/kernel/memory/consolidation.ts

@@ -0,0 +1,194 @@
+import { askGroq } from '../../groq.js';
+import { normalizeTopic, factHash } from './semantic.js';
+import { extractNodes, createEdges } from './graph.js';
+
+// ─── Memory Consolidation ───────────────────────────────────
+
+const CONSOLIDATION_SYSTEM = `You are AEGIS memory consolidation. Analyze recent episodes against existing memory and produce structured operations.
+
+Operations:
+- ADD: a genuinely new fact not covered by existing memory
+- UPDATE: an existing fact that needs correction or has new information (reference its id via supersedes_id)
+- DELETE: an existing fact that is no longer accurate (reference its id via target_id, provide reason)
+- NOOP: nothing to do — return []
+
+Rules:
+1. Every fact MUST contain at least one specific detail: a name, date, number, ID, URL, or version. Never write vague observations.
+2. If episodes merely confirm existing facts, return [].
+3. Prefer UPDATE over ADD when a fact evolves (e.g., "Phase 2 planned" → "Phase 2 complete").
+4. DELETE facts that are provably wrong or obsolete based on episode evidence.
+5. Max 3 operations per run. Quality over quantity.
+6. Good facts: "Delaware PBC franchise tax filed 2026-03-03, 2 days late" or "BizOps dashboard_summary tool fails when org has no projects (undefined.id)".
+7. Bad facts: "Financial metrics are important" or "Document gaps exist and require attention".
+
+KNOWN TOPICS — reuse these whenever the fact fits. Only create a new topic if genuinely none of these apply:
+- aegis: cognitive kernel internals, architecture, infrastructure, versioning, deployment
+- img_forge: img-forge product, economics, integrations, API
+- bizops: BizOps tool, MCP tools, operational improvements
+- content: roundtable, dispatch, column generation pipelines
+- self_improvement: self-improvement analysis, outcomes, patterns
+- organization: org-level priorities, governance, go-to-market
+- auth: auth product, Better Auth, API key formats, middleware chain, auth-contract
+- product_strategy: product positioning, competitive landscape
+- compliance: legal, tax, compliance deadlines, regulatory
+- finance: financial metrics, costs, revenue, billing
+- operator_preferences: operator preferences, workflow choices
+- milestones: key dates, launches, completed phases
+- mcp_strategy: MCP protocol, OAuth, remote MCP, tool design
+
+Return ONLY a JSON array (no markdown):
+[
+  { "operation": "ADD", "topic": "aegis", "fact": "specific fact", "confidence": 0.8 },
+  { "operation": "UPDATE", "supersedes_id": 42, "topic": "auth", "fact": "updated fact", "confidence": 0.9 },
+  { "operation": "DELETE", "target_id": 37, "reason": "no longer accurate" }
+]
+
+Return [] if nothing needs to change.`;
+
+export async function consolidateEpisodicToSemantic(
+  db: D1Database,
+  groqApiKey: string,
+  groqModel: string,
+  groqBaseUrl?: string,
+  memoryBinding?: import('../../types.js').MemoryServiceBinding,
+): Promise<void> {
+  // High-water mark: only process episodes since last consolidation (not a rolling 24h window)
+  const lastRun = await db.prepare(
+    "SELECT received_at FROM web_events WHERE event_id = 'last_consolidation_at'"
+  ).first<{ received_at: string }>();
+  const since = lastRun?.received_at ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString().replace('T', ' ').slice(0, 19);
+
+  const result = await db.prepare(
+    'SELECT id, intent_class, channel, summary, outcome, cost FROM episodic_memory WHERE created_at > ? ORDER BY created_at DESC LIMIT 20'
+  ).bind(since).all();
+
+  const episodes = result.results as unknown as Array<{
+    id: number;
+    intent_class: string;
+    channel: string;
+    summary: string;
+    outcome: string;
+    cost: number;
+  }>;
+
+  // Guard: skip if not enough new signal
+  if (episodes.length < 3) return;
+
+  // Fetch existing active memory with IDs so the model can reference them for UPDATE/DELETE
+  // Memory Worker is the sole knowledge store — D1 reads removed
+  let existingMemoryList: Array<{ id: string | number; topic: string; fact: string }> = [];
+  if (memoryBinding) {
+    try {
+      const fragments = await memoryBinding.recall('aegis', { limit: 40 });
+      existingMemoryList = fragments.map(f => ({ id: f.id, topic: f.topic, fact: f.content }));
+    } catch (err) {
+      console.error('[consolidation] Memory Worker recall failed:', err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  const memoryContext = existingMemoryList.length > 0
+    ? `\n\nExisting memory (reference by id for UPDATE/DELETE operations):\n${existingMemoryList.map(m => `- [id=${m.id}] [${m.topic}] ${m.fact}`).join('\n')}`
+    : '';
+
+  const userPrompt = `Recent agent episodes (since last consolidation):\n\n${episodes.map((e, i) =>
+    `${i + 1}. [${e.intent_class}/${e.outcome}] ${e.summary}`
+  ).join('\n')}${memoryContext}`;
+
+  let rawResponse: string;
+  try {
+    rawResponse = await askGroq(groqApiKey, groqModel, CONSOLIDATION_SYSTEM, userPrompt, groqBaseUrl);
+  } catch {
+    return; // Groq failure — skip silently, will retry next cron cycle
+  }
+
+  if (!rawResponse) return;
+  const cleaned = rawResponse.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
+  let ops: Array<{
+    operation: 'ADD' | 'UPDATE' | 'DELETE' | 'NOOP';
+    topic?: string; fact?: string; confidence?: number;
+    supersedes_id?: string | number;
+    target_id?: string | number; reason?: string;
+  }>;
+  try {
+    ops = JSON.parse(cleaned);
+    if (!Array.isArray(ops)) return;
+  } catch {
+    return;
+  }
+
+  for (const op of ops.slice(0, 3)) { // Hard cap: max 3 per run
+    switch (op.operation) {
+      case 'ADD': {
+        if (!op.topic || !op.fact) continue;
+        if (op.fact.length < 30) continue;
+        if (!/\d/.test(op.fact) && !/[A-Z][a-z]/.test(op.fact.slice(1))) continue;
+        if (!memoryBinding) continue;
+        await memoryBinding.store('aegis', [{ content: op.fact, topic: op.topic, confidence: op.confidence ?? 0.7, source: 'episodic_consolidation' }]);
+        console.log(`[consolidation] ADD [${normalizeTopic(op.topic)}] "${op.fact.slice(0, 80)}" (conf:${op.confidence ?? 0.7})`);
+        // Phase 2: Extract knowledge graph nodes + edges from new fact
+        try {
+          const nodeIds = await extractNodes(db, op.fact, normalizeTopic(op.topic));
+          if (nodeIds.length >= 2) {
+            await createEdges(db, nodeIds);
+          }
+        } catch (err) {
+          console.warn('[consolidation] Graph extraction failed:', err instanceof Error ? err.message : String(err));
+        }
+        break;
+      }
+      case 'UPDATE': {
+        if (!op.supersedes_id || !op.topic || !op.fact) continue;
+        if (op.fact.length < 30) continue;
+        if (!/\d/.test(op.fact) && !/[A-Z][a-z]/.test(op.fact.slice(1))) continue;
+        if (memoryBinding) {
+          // Forget old → store new
+          await memoryBinding.forget('aegis', { ids: [String(op.supersedes_id)] });
+          await memoryBinding.store('aegis', [{ content: op.fact, topic: op.topic, confidence: op.confidence ?? 0.8, source: 'episodic_consolidation' }]);
+        } else {
+          await db.prepare(
+            "UPDATE memory_entries SET valid_until = datetime('now'), updated_at = datetime('now') WHERE id = ? AND valid_until IS NULL"
+          ).bind(op.supersedes_id).run();
+          const topic = normalizeTopic(op.topic);
+          const hash = factHash(topic, op.fact);
+          const insertResult = await db.prepare(
+            'INSERT INTO memory_entries (topic, fact, fact_hash, confidence, source, superseded_by) VALUES (?, ?, ?, ?, ?, ?)'
+          ).bind(topic, op.fact, hash, op.confidence ?? 0.8, 'episodic_consolidation', op.supersedes_id).run();
+          if (insertResult.meta.last_row_id) {
+            await db.prepare(
+              'UPDATE memory_entries SET superseded_by = ? WHERE id = ?'
+            ).bind(insertResult.meta.last_row_id, op.supersedes_id).run();
+          }
+        }
+        console.log(`[consolidation] UPDATE ${op.supersedes_id} → [${normalizeTopic(op.topic)}] "${op.fact.slice(0, 80)}" (conf:${op.confidence ?? 0.8})`);
+        // Phase 2: Extract knowledge graph nodes + edges from updated fact
+        try {
+          const nodeIds = await extractNodes(db, op.fact, normalizeTopic(op.topic));
+          if (nodeIds.length >= 2) {
+            await createEdges(db, nodeIds);
+          }
+        } catch (err) {
+          console.warn('[consolidation] Graph extraction failed:', err instanceof Error ? err.message : String(err));
+        }
+        break;
+      }
+      case 'DELETE': {
+        if (!op.target_id) continue;
+        if (memoryBinding) {
+          await memoryBinding.forget('aegis', { ids: [String(op.target_id)] });
+        } else {
+          await db.prepare(
+            "UPDATE memory_entries SET valid_until = datetime('now'), updated_at = datetime('now') WHERE id = ? AND valid_until IS NULL"
+          ).bind(op.target_id).run();
+        }
+        console.log(`[consolidation] Soft-deleted memory ${op.target_id}: ${op.reason ?? 'no reason'}`);
+        break;
+      }
+      // NOOP — skip
+    }
+  }
+
+  // Advance the high-water mark — these episodes won't be re-processed
+  await db.prepare(
+    "INSERT OR REPLACE INTO web_events (event_id, received_at) VALUES ('last_consolidation_at', datetime('now'))"
+  ).run();
+}

package/src/kernel/memory/episodic.ts

@@ -0,0 +1,241 @@
+import type { EpisodicEntry } from '../types.js';
+import { EPISODIC_OUTCOMES, isValidEnum, type EpisodicOutcome } from '../../schema-enums.js';
+
+// ─── Outcome Sanitization ───────────────────────────────────
+// D1 CHECK constraints only allow specific values.
+// Guard at the DB boundary so rogue values never reach SQLite.
+
+/** Map any outcome to a valid episodic_memory value. */
+export function sanitizeEpisodicOutcome(raw: string | null | undefined): EpisodicOutcome {
+  if (isValidEnum(EPISODIC_OUTCOMES, raw)) return raw;
+  // partial_failure, error, blocked, empty string, null → failure
+  return 'failure';
+}
+
+// ─── Episodic Memory ─────────────────────────────────────────
+
+export async function recordEpisode(db: D1Database, entry: Omit<EpisodicEntry, 'id' | 'created_at'>): Promise<void> {
+  const safeOutcome = sanitizeEpisodicOutcome(entry.outcome);
+  await db.prepare(
+    'INSERT INTO episodic_memory (intent_class, channel, summary, outcome, cost, latency_ms, near_miss, classifier_confidence, reclassified, thread_id, executor) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'
+  ).bind(
+    entry.intent_class, entry.channel, entry.summary, safeOutcome,
+    entry.cost, entry.latency_ms, entry.near_miss ?? null,
+    entry.classifier_confidence ?? null, entry.reclassified ? 1 : 0,
+    entry.thread_id ?? null, entry.executor ?? null,
+  ).run();
+}
+
+/** Retroactively mark the last episode in a thread as a semantic failure */
+export async function retrogradeEpisode(db: D1Database, threadId: string): Promise<EpisodicEntry | null> {
+  const last = await db.prepare(
+    "SELECT * FROM episodic_memory WHERE thread_id = ? AND outcome = 'success' ORDER BY created_at DESC LIMIT 1"
+  ).bind(threadId).first<EpisodicEntry>();
+  if (!last) return null;
+
+  await db.prepare(
+    "UPDATE episodic_memory SET outcome = 'failure' WHERE id = ?"
+  ).bind(last.id).run();
+
+  return last;
+}
+
+export async function getRecentEpisodes(db: D1Database, intentClass: string, limit: number = 5): Promise<EpisodicEntry[]> {
+  const result = await db.prepare(
+    'SELECT * FROM episodic_memory WHERE intent_class = ? ORDER BY created_at DESC LIMIT ?'
+  ).bind(intentClass, limit).all();
+  return result.results as unknown as EpisodicEntry[];
+}
+
+export async function getEpisodeStats(db: D1Database, intentClass: string): Promise<{
+  count: number;
+  successRate: number;
+  avgCost: number;
+  avgLatency: number;
+} | null> {
+  const row = await db.prepare(`
+    SELECT
+      COUNT(*) as count,
+      AVG(CASE WHEN outcome = 'success' THEN 1.0 ELSE 0.0 END) as success_rate,
+      AVG(cost) as avg_cost,
+      AVG(latency_ms) as avg_latency
+    FROM episodic_memory WHERE intent_class = ?
+  `).bind(intentClass).first<{ count: number; success_rate: number; avg_cost: number; avg_latency: number }>();
+
+  if (!row || row.count === 0) return null;
+  return {
+    count: row.count,
+    successRate: row.success_rate,
+    avgCost: row.avg_cost,
+    avgLatency: row.avg_latency,
+  };
+}
+
+// ─── Stats by (intent_class, complexity_tier) — derived-stats path ──
+// aegis#563 + aegis#564: stats keyed by (intent_class, complexity_tier) —
+// matches procedural_memory's procedureKey shape so the projection-source
+// path can derive procedural aggregates at read time.
+//
+// The helpers rely on episodic_memory.complexity_tier (added in the same
+// schema migration that adds these functions). Rows without a tier value
+// are excluded from derived results by the WHERE complexity_tier IS NOT
+// NULL guard. Consumers that want stricter protection against retroactive
+// backfills can add their own time-based filter in a wrapper.
+
+export async function getEpisodeStatsByComplexity(
+  db: D1Database,
+  intentClass: string,
+  complexityTier: string,
+): Promise<{
+  count: number;
+  successCount: number;
+  successRate: number;
+  avgCost: number;
+  avgLatency: number;
+  lastUsed: string | null;
+} | null> {
+  // SUM(CASE outcome='success' ...) returns an exact integer — don't
+  // reconstruct successCount from count * avgSuccessRate downstream (FP
+  // rounding on ugly rates would break strict-equality drift checks).
+  const row = await db.prepare(`
+    SELECT
+      COUNT(*) as count,
+      SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) as success_count,
+      AVG(cost) as avg_cost,
+      AVG(latency_ms) as avg_latency,
+      MAX(created_at) as last_used
+    FROM episodic_memory
+    WHERE intent_class = ?
+      AND complexity_tier = ?
+  `).bind(intentClass, complexityTier).first<{
+    count: number;
+    success_count: number;
+    avg_cost: number;
+    avg_latency: number;
+    last_used: string | null;
+  }>();
+
+  if (!row || row.count === 0) return null;
+  return {
+    count: row.count,
+    successCount: row.success_count,
+    successRate: row.count > 0 ? row.success_count / row.count : 0,
+    avgCost: row.avg_cost,
+    avgLatency: row.avg_latency,
+    lastUsed: row.last_used,
+  };
+}
+
+// aegis#564 Phase 2: bulk variant for dashboard / observability / decision-docs.
+// One GROUP BY intent_class, complexity_tier scan covers both the derived
+// slice (non-null tier) and the pre-tier ghost slice (NULL tier) so callers
+// avoid N+1 queries. Returns a Map keyed on intent_class with nested
+// derived-by-tier and the pre-tier count.
+export interface EpisodeStatsAggregate {
+  derived: Record<string, {
+    count: number;
+    successCount: number;
+    failCount: number;
+    avgCost: number;
+    avgLatency: number;
+    lastUsed: string | null;
+  }>;
+  preTierCount: number;
+}
+
+export async function getAllEpisodeStatsByComplexity(
+  db: D1Database,
+): Promise<Map<string, EpisodeStatsAggregate>> {
+  // Single scan: grouping on (intent_class, complexity_tier) folds both
+  // derived (non-null tier) and pre-tier (NULL tier) rows into one query.
+  const result = await db.prepare(`
+    SELECT
+      intent_class,
+      complexity_tier,
+      COUNT(*) as count,
+      SUM(CASE WHEN outcome = 'success' THEN 1 ELSE 0 END) as success_count,
+      AVG(cost) as avg_cost,
+      AVG(latency_ms) as avg_latency,
+      MAX(created_at) as last_used
+    FROM episodic_memory
+    GROUP BY intent_class, complexity_tier
+  `).all<{
+    intent_class: string;
+    complexity_tier: string | null;
+    count: number;
+    success_count: number;
+    avg_cost: number;
+    avg_latency: number;
+    last_used: string | null;
+  }>();
+
+  const byClass = new Map<string, EpisodeStatsAggregate>();
+  for (const row of result.results) {
+    const entry = byClass.get(row.intent_class) ?? { derived: {}, preTierCount: 0 };
+    if (row.complexity_tier === null) {
+      entry.preTierCount = row.count;
+    } else {
+      entry.derived[row.complexity_tier] = {
+        count: row.count,
+        successCount: row.success_count,
+        failCount: row.count - row.success_count,
+        avgCost: row.avg_cost,
+        avgLatency: row.avg_latency,
+        lastUsed: row.last_used,
+      };
+    }
+    byClass.set(row.intent_class, entry);
+  }
+  return byClass;
+}
+
+// ─── Conversation History ───────────────────────────────────
+
+export async function getConversationHistory(
+  db: D1Database,
+  conversationId: string,
+  limit: number = 20,
+): Promise<Array<{ role: 'user' | 'assistant'; content: string }>> {
+  const result = await db.prepare(
+    'SELECT role, content FROM messages WHERE conversation_id = ? ORDER BY created_at ASC LIMIT ?'
+  ).bind(conversationId, limit).all();
+  return result.results as unknown as Array<{ role: 'user' | 'assistant'; content: string }>;
+}
+
+// ─── Token-aware history budgeting ──────────────────────────
+
+// chars / 3.5 — matches Claude's ~3.5 chars per token empirically; no tokenizer needed on edge
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 3.5);
+}
+
+const MAX_CONTEXT_TOKENS = 200_000;  // Claude Sonnet context window
+const OUTPUT_RESERVE    =   4_096;  // max_tokens in the API call
+const OVERHEAD_RESERVE  =   8_000;  // system prompt + tools schema + buffer
+
+export function budgetConversationHistory(
+  history: Array<{ role: 'user' | 'assistant'; content: string }>,
+  maxContextTokens = MAX_CONTEXT_TOKENS,
+  overheadReserveTokens = OVERHEAD_RESERVE,
+  outputReserveTokens = OUTPUT_RESERVE,
+): Array<{ role: 'user' | 'assistant'; content: string }> {
+  const available = maxContextTokens - overheadReserveTokens - outputReserveTokens;
+  const result = [...history];
+  let total = result.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+  const tokensBefore = total;
+
+  while (total > available && result.length >= 2) {
+    const dropped = result.splice(0, 2); // drop oldest user+assistant pair
+    total -= dropped.reduce((sum, m) => sum + estimateTokens(m.content), 0);
+  }
+
+  const droppedPairs = (history.length - result.length) / 2;
+  if (droppedPairs > 0) {
+    console.warn(
+      `[memory] history trimmed: dropped ${droppedPairs} turn${droppedPairs !== 1 ? 's' : ''} ` +
+      `(~${tokensBefore} → ~${total} estimated tokens)`
+    );
+  }
+
+  return result;
+}