ei-tui 0.1.25 → 0.3.1

package/src/cli.ts

@@ -20,8 +20,6 @@ const TYPE_ALIASES: Record<string, string> = {
   quotes: "quotes",
   fact: "facts",
   facts: "facts",
-  trait: "traits",
-  traits: "traits",
   person: "people",
   people: "people",
   topic: "topics",
@@ -38,28 +36,33 @@ Usage:
   ei -n 5 "search text"         Limit results
   ei <type> "search text"       Search a specific data type
   ei <type> -n 5 "search text"  Type-specific with limit
+  ei --recent                   Return most recently mentioned items
+  ei --recent "query"           Filter recent items by query
+  ei <type> --recent "query"    Type-specific recent search
   ei --id <id>                  Look up a specific entity by ID
   echo <id> | ei --id           Look up entity by ID from stdin
+  ei mcp                        Start the Ei MCP stdio server (for Cursor/Claude Desktop)
 
 Types:
   quote / quotes    Quotes from conversation history
   fact / facts      Facts about the user
-  trait / traits    Personality traits
   person / people   People from the user's life
   topic / topics    Topics of interest
 
 Options:
   --number, -n     Maximum number of results (default: 10)
+  --recent, -r     Sort by last_mentioned date (most recent first)
   --id             Look up entity by ID (accepts value or stdin)
-  --install        Write the Ei tool file to ~/.config/opencode/tools/
+  --install        Register Ei with OpenCode, Claude Code, and Cursor
   --help, -h       Show this help message
 
 Examples:
   ei "debugging"                         # Search everything
   ei -n 5 "API design"                   # Top 5 across all types
   ei quote "you guessed it"              # Search quotes only
-  ei trait -n 3 "problem solving"        # Top 3 matching traits
-  ei --id abc-123                          # Look up entity by ID
+  ei --recent                            # Most recently mentioned items
+  ei topics --recent "work"              # Recent work-related topics
+  ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
 `);
 }
@@ -71,7 +74,7 @@ function buildOpenCodeToolContent(): string {
     'export default tool({',
     '  description: [',
     '    "Search the user\'s Ei knowledge base \u2014 a persistent memory store built from conversations.",',
-    '    "Returns facts, personality traits, people, topics of interest, and quotes.",',
+    '    "Returns facts, people, topics of interest, and quotes.",',
     '    "Use this to recall anything about the user: preferences, relationships, or past discussions.",',
     '    "Results include entity IDs that can be passed back with lookup=true to get full detail.",',
     '  ].join(" "),',
@@ -80,10 +83,10 @@ function buildOpenCodeToolContent(): string {
     '      "Search text, or an entity ID when lookup=true. Supports natural language."',
     '    ),',
     '    type: tool.schema',
-    '      .enum(["facts", "traits", "people", "topics", "quotes"])',
+    '      .enum(["facts", "people", "topics", "quotes"])',
     '      .optional()',
     '      .describe(',
-    '        "Filter to a specific data type. Omit to search all types (balanced across all 5)."',
+    '        "Filter to a specific data type. Omit to search all types (balanced across all 4).",',
     '      ),',
     '    limit: tool.schema',
     '      .number()',
@@ -126,7 +129,7 @@ async function installOpenCodeTool(): Promise<void> {
   console.log(`  Restart OpenCode to activate.`);
 }
 
-async function installClaudeCodeMcp(): Promise<void> {
+async function installClaudeCode(): Promise<void> {
   const home = process.env.HOME || "~";
   const claudeJsonPath = join(home, ".claude.json");
 
@@ -136,7 +139,7 @@ async function installClaudeCodeMcp(): Promise<void> {
     const which = Bun.spawnSync(["which", "claude"], { stdout: "pipe", stderr: "pipe" });
     if (which.exitCode === 0) {
       const result = Bun.spawnSync(
-        ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "ei", "--", "ei"],
+        ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "ei", "--", "ei", "mcp"],
         { stdout: "pipe", stderr: "pipe" }
       );
       if (result.exitCode === 0) {
@@ -159,17 +162,11 @@ async function installClaudeCodeMcp(): Promise<void> {
     // File doesn't exist or isn't valid JSON — start fresh
   }
 
-  // Resolve the ei binary: if running as compiled binary, argv[1] is our path;
-  // if running as 'bun src/cli.ts', fall back to 'ei' (assumed on PATH after npm install -g)
-  const isBunScript = process.argv[1]?.endsWith("/cli.ts") || process.argv[1]?.endsWith("/cli.js");
-  const command = isBunScript ? "ei" : (process.argv[1] ?? "ei");
-
   const mcpServers = (config.mcpServers ?? {}) as Record<string, unknown>;
   mcpServers["ei"] = {
     type: "stdio",
-    command,
-    args: [],
-    env: {},
+    command: "ei",
+    args: ["mcp"],
   };
   config.mcpServers = mcpServers;
 
@@ -183,6 +180,41 @@ async function installClaudeCodeMcp(): Promise<void> {
   console.log(`  Restart Claude Code to activate.`);
 }
 
+async function installCursor(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const cursorJsonPath = join(home, ".cursor", "mcp.json");
+
+  let config: Record<string, unknown> = {};
+  try {
+    const text = await Bun.file(cursorJsonPath).text();
+    config = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+  }
+
+  const mcpServers = (config.mcpServers ?? {}) as Record<string, unknown>;
+  mcpServers["ei"] = {
+    type: "stdio",
+    command: "ei",
+    args: ["mcp"],
+  };
+  config.mcpServers = mcpServers;
+
+  await Bun.$`mkdir -p ${join(home, ".cursor")}`;
+  const tmpPath = `${cursorJsonPath}.ei-install.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(config, null, 2) + "\n");
+  const { rename } = await import(/* @vite-ignore */ "fs/promises");
+  await rename(tmpPath, cursorJsonPath);
+
+  console.log(`✓ Installed Ei MCP server to ${cursorJsonPath}`);
+  console.log(`  Restart Cursor to activate.`);
+}
+
+async function installMcpClients(): Promise<void> {
+  await installClaudeCode();
+  await installCursor();
+}
+
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
 
@@ -205,10 +237,15 @@ async function main(): Promise<void> {
 
   if (args[0] === "--install") {
     await installOpenCodeTool();
-    await installClaudeCodeMcp();
+    await installMcpClients();
     process.exit(0);
   }
 
+  if (args[0] === "mcp") {
+    const { handleMcpCommand } = await import("./cli/mcp.js");
+    await handleMcpCommand(args.slice(1));
+    process.exit(0);
+  }
 
   // Handle --id flag: look up entity by ID
   const idFlagIndex = args.indexOf("--id");
@@ -254,6 +291,7 @@ async function main(): Promise<void> {
       args: parseableArgs,
       options: {
         number: { type: "string", short: "n" },
+        recent: { type: "boolean", short: "r" },
         help: { type: "boolean", short: "h" },
       },
       allowPositionals: true,
@@ -271,8 +309,9 @@ async function main(): Promise<void> {
 
   const query = parsed.positionals.join(" ").trim();
   const limit = parsed.values.number ? parseInt(parsed.values.number, 10) : 10;
+  const recent = parsed.values.recent === true;
 
-  if (!query) {
+  if (!query && !recent) {
     if (targetType) {
       console.error(`Search text required. Usage: ei ${targetType} "search text"`);
     } else {
@@ -286,12 +325,14 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  const options = { recent };
+
   let result;
   if (targetType) {
     const module = await import(`./cli/commands/${targetType}.js`);
-    result = await module.execute(query, limit);
+    result = await module.execute(query, limit, options);
   } else {
-    result = await retrieveBalanced(query, limit);
+    result = await retrieveBalanced(query, limit, options);
   }
 
   console.log(JSON.stringify(result, null, 2));

package/src/core/AGENTS.md

@@ -10,7 +10,7 @@ core/
 ├── state-manager.ts    # In-memory state + persistence
 ├── queue-processor.ts  # LLM request queue with priorities
 ├── llm-client.ts       # Multi-provider LLM abstraction
-├── types.ts            # All core types (source: CONTRACTS.md)
+├── types.ts            # All core types (canonical source — CONTRACTS.md defers to these)
 ├── handlers/           # LLM response handlers
 ├── orchestrators/      # Multi-step workflows
 ├── personas/           # Persona loading logic

package/src/core/constants/built-in-facts.ts

@@ -0,0 +1,49 @@
+/**
+ * Built-in biographical fact categories that Ei tracks.
+ *
+ * BUILT_IN_FACTS: Array of fact objects (name field only) for iteration/display.
+ * BUILT_IN_FACT_NAMES: Set<string> for O(1) lookup (is this fact built-in?).
+ */
+
+export const BUILT_IN_FACTS: { name: string }[] = [
+  // Core Identity
+  { name: "Full Name" },
+  { name: "Nickname/Preferred Name" },
+  { name: "Birthday" },
+  { name: "Birthplace" },
+  { name: "Hometown" },
+  { name: "Current Location" },
+
+  // Professional
+  { name: "Current Job Title" },
+  { name: "Current Employer" },
+  { name: "Industry/Field" },
+  { name: "Years of Experience" },
+
+  // Personal
+  { name: "Marital Status" },
+  { name: "Spouse Name" },
+  { name: "Spouse Birthday" },
+  { name: "Date of Marriage" },
+  { name: "Children" },
+  { name: "Parents" },
+  { name: "Gender" },
+  { name: "Pronouns" },
+  { name: "Eye Color" },
+  { name: "Hair Color" },
+  { name: "Height" },
+  { name: "Weight" },
+
+  // Background
+  { name: "Nationality/Citizenship" },
+  { name: "Languages Spoken" },
+  { name: "Education Level" },
+  { name: "School/University" },
+  { name: "Field of Study" },
+  { name: "Military Service" },
+  { name: "Religious Affiliation" },
+];
+
+export const BUILT_IN_FACT_NAMES: Set<string> = new Set(
+  BUILT_IN_FACTS.map((f) => f.name)
+);

package/src/core/constants/index.ts

@@ -0,0 +1 @@
+export * from "./built-in-facts";

package/src/core/context-utils.ts

@@ -49,7 +49,6 @@ export function stripHumanEmbeddings(human: HumanEntity): HumanEntity {
   return {
     ...human,
     facts: (human.facts ?? []).map(stripDataItemEmbedding),
-    traits: (human.traits ?? []).map(stripDataItemEmbedding),
     topics: (human.topics ?? []).map(stripDataItemEmbedding),
     people: (human.people ?? []).map(stripDataItemEmbedding),
     quotes: (human.quotes ?? []).map(stripQuoteEmbedding),

package/src/core/embedding-service.ts

@@ -54,6 +54,14 @@ export function getItemEmbeddingText(item: { name: string; description?: string
   return item.name;
 }
 
+export function getTopicEmbeddingText(topic: { name: string; category?: string; description?: string }): string {
+  return [topic.name, topic.category, topic.description].filter(Boolean).join(' - ');
+}
+
+export function getPersonEmbeddingText(person: { name: string; relationship?: string; description?: string }): string {
+  return [person.name, person.relationship, person.description].filter(Boolean).join(' - ');
+}
+
 export function needsEmbeddingUpdate(
   existing: { name: string; description?: string } | undefined,
   incoming: { name: string; description?: string }

package/src/core/handlers/dedup.ts

@@ -1,7 +1,7 @@
 import { StateManager } from "../state-manager.js";
 import { LLMResponse } from "../types.js";
 import type { DedupResult } from "../../prompts/ceremony/types.js";
-import type { DataItemType, Fact, Trait, Topic, Person, Quote } from "../types/data-items.js";
+import type { DataItemType, Fact, Topic, Person, Quote } from "../types/data-items.js";
 import { getEmbeddingService } from "../embedding-service.js";
 
 /**
@@ -24,7 +24,7 @@ export async function handleDedupCurate(
   const state = stateManager.getHuman();
   
   // Validate entity_type
-  if (!entity_type || !['fact', 'trait', 'topic', 'person'].includes(entity_type)) {
+  if (!entity_type || !['topic', 'person'].includes(entity_type)) {
     console.error(`[Dedup] Invalid entity_type: "${entity_type}" (from request data)`, response.request.data);
     return;
   }
@@ -50,9 +50,8 @@ export async function handleDedupCurate(
   console.log(`[Dedup] Processing cluster: ${decisions.update.length} updates, ${decisions.remove.length} removals, ${decisions.add.length} additions`);
   
   // Map entity_type to pluralized state property name
-  const pluralMap: Record<DataItemType, 'facts' | 'traits' | 'topics' | 'people'> = {
+  const pluralMap: Record<string, 'facts' | 'topics' | 'people'> = {
     fact: 'facts',
-    trait: 'traits',
     topic: 'topics',
     person: 'people'
   };
@@ -65,15 +64,14 @@ export async function handleDedupCurate(
       entity_ids,
       stateKeys: Object.keys(state),
       factsExists: !!state.facts,
-      traitsExists: !!state.traits,
       topicsExists: !!state.topics,
       peopleExists: !!state.people
     });
     return;
   }
   const entities = entity_ids
-    .map((id: string) => entityList.find((e: Fact | Trait | Topic | Person) => e.id === id))
-    .filter((e: Fact | Trait | Topic | Person | undefined): e is (Fact | Trait | Topic | Person) => e !== undefined);
+    .map((id: string) => entityList.find((e: Fact | Topic | Person) => e.id === id))
+    .filter((e: Fact | Topic | Person | undefined): e is (Fact | Topic | Person) => e !== undefined);
   
   if (entities.length === 0) {
     console.warn(`[Dedup] No entities found for cluster (already merged?)`);
@@ -109,7 +107,7 @@ export async function handleDedupCurate(
   // =========================================================================
   
   for (const update of decisions.update) {
-    const entity = entityList.find((e: Fact | Trait | Topic | Person) => e.id === update.id);
+    const entity = entityList.find((e: Fact | Topic | Person) => e.id === update.id);
     
     if (!entity) {
       console.warn(`[Dedup] Entity ${update.id} not found (already merged?)`);
@@ -148,8 +146,6 @@ export async function handleDedupCurate(
     // Type-safe cast based on entity_type
     if (entity_type === 'fact') {
       stateManager.human_fact_upsert(updatedEntity as Fact);
-    } else if (entity_type === 'trait') {
-      stateManager.human_trait_upsert(updatedEntity as Trait);
     } else if (entity_type === 'topic') {
       stateManager.human_topic_upsert(updatedEntity as Topic);
     } else if (entity_type === 'person') {
@@ -163,7 +159,7 @@ export async function handleDedupCurate(
   // =========================================================================
   
   for (const removal of decisions.remove) {
-    const entity = entityList.find((e: Fact | Trait | Topic | Person) => e.id === removal.to_be_removed);
+    const entity = entityList.find((e: Fact | Topic | Person) => e.id === removal.to_be_removed);
     
     if (!entity) {
       console.warn(`[Dedup] Entity ${removal.to_be_removed} already deleted`);
@@ -172,7 +168,7 @@ export async function handleDedupCurate(
     
     // Remove via StateManager (also cleans up quote references)
     const removeMethod = `human_${entity_type}_remove` as 
-      'human_fact_remove' | 'human_trait_remove' | 'human_topic_remove' | 'human_person_remove';
+      'human_fact_remove' | 'human_topic_remove' | 'human_person_remove';
     
     const removed = stateManager[removeMethod](removal.to_be_removed);
     if (removed) {
@@ -206,14 +202,10 @@ export async function handleDedupCurate(
       description: addition.description,
       sentiment: addition.sentiment ?? 0.0,
       last_updated: new Date().toISOString(),
+      learned_by: "ei",
+      last_changed_by: "ei",
       embedding,
       // Type-specific fields with defaults
-      ...(entity_type === 'trait' && { strength: addition.strength ?? 0.5 }),
-      ...(entity_type === 'fact' && { 
-        confidence: addition.confidence ?? 0.5,
-        validated: 'unknown' as import("../types/enums.js").ValidationLevel,
-        validated_date: ''
-      }),
       ...((entity_type === 'topic' || entity_type === 'person') && {
         exposure_current: addition.exposure_current ?? 0.0,
         exposure_desired: addition.exposure_desired ?? 0.5,
@@ -224,11 +216,7 @@ export async function handleDedupCurate(
     };
     
     // Type-safe cast based on entity_type
-    if (entity_type === 'fact') {
-      stateManager.human_fact_upsert(newEntity as Fact);
-    } else if (entity_type === 'trait') {
-      stateManager.human_trait_upsert(newEntity as Trait);
-    } else if (entity_type === 'topic') {
+    if (entity_type === 'topic') {
       stateManager.human_topic_upsert(newEntity as Topic);
     } else if (entity_type === 'person') {
       stateManager.human_person_upsert(newEntity as Person);

package/src/core/handlers/heartbeat.ts

@@ -1,7 +1,6 @@
 import {
   ContextStatus,
   LLMNextStep,
-  ValidationLevel,
   type LLMResponse,
   type Message,
 } from "../types.js";
@@ -77,13 +76,13 @@ export function handleEiHeartbeat(response: LLMResponse, state: StateManager): v
     timestamp: now,
     read: false,
     context_status: ContextStatus.Default,
-    f: true, r: true, p: true, o: true,
+    f: true, t: true, p: true,
   });
 
   if (found.type === "fact") {
     const factsNav = isTUI ? "using /me facts" : "using \u2630 \u2192 My Data";
     sendMessage(`Another persona updated a fact called "${found.name}" to "${found.description}". If that's right, you can lock it from further changes by ${factsNav}.`);
-    state.human_fact_upsert({ ...found, validated: ValidationLevel.Ei, validated_date: now });
+    state.human_fact_upsert({ ...found, validated_date: now });
     console.log(`[handleEiHeartbeat] Notified about fact "${found.name}"`);
     return;
   }

package/src/core/handlers/human-extraction.ts

@@ -1,57 +1,92 @@
-import type { LLMResponse } from "../types.js";
+import type { LLMResponse, Fact } from "../types.js";
 import type { StateManager } from "../state-manager.js";
 import type {
-  FactScanResult,
-  TraitScanResult,
+  FactFindResult,
   TopicScanResult,
   PersonScanResult,
+  TopicScanCandidate,
 } from "../../prompts/human/types.js";
-import { queueItemMatch, type ExtractionContext } from "../orchestrators/index.js";
+import { queueTopicMatch, queuePersonMatch, type ExtractionContext } from "../orchestrators/index.js";
 import { markMessagesExtracted } from "./utils.js";
+import { BUILT_IN_FACT_NAMES } from "../constants/built-in-facts.js";
+import { getEmbeddingService, getItemEmbeddingText } from "../embedding-service.js";
 
-export async function handleHumanFactScan(response: LLMResponse, state: StateManager): Promise<void> {
-  const result = response.parsed as FactScanResult | undefined;
+export async function handleFactFind(response: LLMResponse, state: StateManager): Promise<void> {
+  const result = response.parsed as FactFindResult | undefined;
   
   // Mark messages as scanned regardless of whether facts were found
   markMessagesExtracted(response, state, "f");
   
   if (!result?.facts || !Array.isArray(result.facts)) {
-    console.log("[handleHumanFactScan] No facts detected or invalid result");
+    console.log("[handleFactFind] No facts detected or invalid result");
     return;
   }
 
   const context = response.request.data as unknown as ExtractionContext;
   if (!context?.personaId) return;
 
-  for (const candidate of result.facts) {
-    await queueItemMatch("fact", candidate, context, state);
-  }
-  console.log(`[handleHumanFactScan] Queued ${result.facts.length} fact(s) for matching`);
-}
+  const human = state.getHuman();
+  const now = new Date().toISOString();
+  let upsertCount = 0;
 
-export async function handleHumanTraitScan(response: LLMResponse, state: StateManager): Promise<void> {
-  const result = response.parsed as TraitScanResult | undefined;
-  
-  markMessagesExtracted(response, state, "r");
-  
-  if (!result?.traits || !Array.isArray(result.traits)) {
-    console.log("[handleHumanTraitScan] No traits detected or invalid result");
-    return;
-  }
+  for (const factResult of result.facts) {
+    // Only upsert facts that match a built-in name
+    if (!BUILT_IN_FACT_NAMES.has(factResult.name)) {
+      console.log(`[handleFactFind] Skipping non-built-in fact: "${factResult.name}"`);
+      continue;
+    }
 
-  const context = response.request.data as unknown as ExtractionContext;
-  if (!context?.personaId) return;
+    // Find the existing fact in state
+    const existingFact = human.facts.find(f => f.name === factResult.name);
+    if (!existingFact) {
+      console.log(`[handleFactFind] Skipping unknown fact: "${factResult.name}"`);
+      continue;
+    }
 
-  for (const candidate of result.traits) {
-    await queueItemMatch("trait", candidate, context, state);
+    // Skip facts that already have descriptions (only fill empty ones)
+    if (existingFact.description && existingFact.description !== "") {
+      console.log(`[handleFactFind] Skipping fact with existing description: "${factResult.name}"`);
+      continue;
+    }
+
+    // Skip if the LLM returned a null/empty value — don't store null descriptions
+    if (!factResult.value) {
+      console.log(`[handleFactFind] Skipping fact with null/empty value: "${factResult.name}"`);
+      continue;
+    }
+
+    // Compute embedding for the updated fact
+    let embedding: number[] | undefined;
+    try {
+      const embeddingService = getEmbeddingService();
+      const text = getItemEmbeddingText({ name: factResult.name, description: factResult.value });
+      embedding = await embeddingService.embed(text);
+    } catch (err) {
+      console.warn(`[handleFactFind] Failed to compute embedding for fact "${factResult.name}":`, err);
+    }
+
+    const updatedFact: Fact = {
+      ...existingFact,
+      description: factResult.value,
+      last_updated: now,
+      last_mentioned: now,
+      learned_by: existingFact.learned_by ?? context.personaId,
+      last_changed_by: context.personaId,
+      embedding,
+    };
+
+    state.human_fact_upsert(updatedFact);
+    upsertCount++;
   }
-  console.log(`[handleHumanTraitScan] Queued ${result.traits.length} trait(s) for matching`);
+
+  console.log(`[handleFactFind] Upserted ${upsertCount} fact(s)`);
 }
 
+
 export async function handleHumanTopicScan(response: LLMResponse, state: StateManager): Promise<void> {
   const result = response.parsed as TopicScanResult | undefined;
   
-  markMessagesExtracted(response, state, "p");
+  markMessagesExtracted(response, state, "t");
   
   if (!result?.topics || !Array.isArray(result.topics)) {
     console.log("[handleHumanTopicScan] No topics detected or invalid result");
@@ -61,8 +96,9 @@ export async function handleHumanTopicScan(response: LLMResponse, state: StateMa
   const context = response.request.data as unknown as ExtractionContext;
   if (!context?.personaId) return;
 
+  const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;
   for (const candidate of result.topics) {
-    await queueItemMatch("topic", candidate, context, state);
+    await queueTopicMatch(candidate, context, state, extractionModel);
   }
   console.log(`[handleHumanTopicScan] Queued ${result.topics.length} topic(s) for matching`);
 }
@@ -70,7 +106,7 @@ export async function handleHumanTopicScan(response: LLMResponse, state: StateMa
 export async function handleHumanPersonScan(response: LLMResponse, state: StateManager): Promise<void> {
   const result = response.parsed as PersonScanResult | undefined;
   
-  markMessagesExtracted(response, state, "o");
+  markMessagesExtracted(response, state, "p");
   
   if (!result?.people || !Array.isArray(result.people)) {
     console.log("[handleHumanPersonScan] No people detected or invalid result");
@@ -80,8 +116,38 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
   const context = response.request.data as unknown as ExtractionContext;
   if (!context?.personaId) return;
 
+  const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;
   for (const candidate of result.people) {
-    await queueItemMatch("person", candidate, context, state);
+    await queuePersonMatch(candidate, context, state, extractionModel);
   }
   console.log(`[handleHumanPersonScan] Queued ${result.people.length} person(s) for matching`);
 }
+
+export async function handleEventScan(response: LLMResponse, state: StateManager): Promise<void> {
+  markMessagesExtracted(response, state, "e");
+
+  const result = response.parsed as { events?: Array<{ name: string; description: string; reason: string }> } | undefined;
+
+  if (!result?.events || !Array.isArray(result.events) || result.events.length === 0) {
+    console.log("[handleEventScan] No epic events detected");
+    return;
+  }
+
+  const context = response.request.data as unknown as ExtractionContext;
+  if (!context?.personaId) return;
+
+  const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;
+
+  for (const event of result.events) {
+    const candidate: TopicScanCandidate = {
+      name: event.name,
+      description: event.description,
+      category: "Event",
+      reason: event.reason,
+    };
+    await queueTopicMatch(candidate, context, state, extractionModel);
+  }
+
+  console.log(`[handleEventScan] Queued ${result.events.length} event(s) for matching`);
+}
+