ei-tui 0.9.1 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "author": "Flare576",
   "repository": {
     "type": "git",
@@ -51,6 +51,19 @@
     "test:e2e:tui": "cd tui && npm run test:e2e",
     "test:e2e:ui": "playwright test --ui",
     "test:e2e:debug": "playwright test --debug",
+    "test:evals": "vite-node tests/evals/reflection-critic.eval.ts",
+    "test:evals:observe": "vite-node tests/evals/reflection-critic.observe.ts",
+    "test:evals:fact-find": "vite-node tests/evals/fact-find.eval.ts",
+    "test:evals:topic-scan": "vite-node tests/evals/topic-scan.eval.ts",
+    "test:evals:topic-match": "vite-node tests/evals/topic-match.eval.ts",
+    "test:evals:topic-update": "vite-node tests/evals/topic-update.eval.ts",
+    "test:evals:topic-validate": "vite-node tests/evals/topic-validate.eval.ts",
+    "test:evals:person-scan": "vite-node tests/evals/person-scan.eval.ts",
+    "test:evals:person-update": "vite-node tests/evals/person-update.eval.ts",
+    "test:evals:persona-trait": "vite-node tests/evals/persona-trait-extraction.eval.ts",
+    "test:evals:dedup": "vite-node tests/evals/dedup-tool-calls.eval.ts",
+    "test:evals:response-read-memory": "vite-node tests/evals/response-read-memory.eval.ts",
+    "test:evals:real-data": "vite-node tests/evals/real-data-example.eval.ts",
     "test:all": "npm run test && npm run test:e2e && npm run test:e2e:tui",
     "typecheck": "tsc --noEmit",
     "web": "cd web && npm run dev",

package/src/cli/commands/personas.ts

@@ -1,4 +1,5 @@
-import { loadLatestState, retrievePersonas } from "../retrieval";
+import { loadLatestState, retrievePersonas, retrievePersonasSemantic } from "../retrieval";
+import { getEmbeddingService } from "../../core/embedding-service";
 import type { PersonaResult } from "../retrieval";
 
 export async function execute(query: string, limit: number, options: { recent?: boolean } = {}): Promise<PersonaResult[]> {
@@ -8,5 +9,13 @@ export async function execute(query: string, limit: number, options: { recent?:
     return [];
   }
 
-  return retrievePersonas(query, state, limit, options);
+  const nameResults = retrievePersonas(query, state, limit, options);
+  if (nameResults.length > 0 || !query || options.recent) {
+    return nameResults;
+  }
+
+  const embeddingService = getEmbeddingService();
+  const queryVector = await embeddingService.embed(query);
+  const semanticResults = await retrievePersonasSemantic(queryVector, state, limit);
+  return semanticResults;
 }

package/src/cli/mcp.ts

@@ -16,14 +16,14 @@ export function createMcpServer(): McpServer {
     "ei_search",
     {
       description:
-        "Search the user's Ei knowledge base — a persistent memory store built from conversations. Returns facts, people, topics of interest, and quotes. People results include an identifiers array (e.g. GitHub username, Discord handle, email, nickname) — query by any name or handle to find what Ei knows about that person. Results include entity IDs that can be passed back to ei_lookup for full detail. Omit query to browse by recency (use with recent=true or persona filter).",
+        "Search the user's Ei knowledge base — a persistent memory store built from conversations. Returns facts, people, topics of interest, quotes, and personas. People results include an identifiers array (e.g. GitHub username, Discord handle, email, nickname) — query by any name or handle to find what Ei knows about that person. Persona results include traits and topics that define the persona's identity and working style — use type='personas' with the persona's name OR a natural-language description of what they do to load a persona's character sheet. Results include entity IDs that can be passed back to ei_lookup for full detail. Omit query to browse by recency (use with recent=true or persona filter).",
       inputSchema: {
         query: z.string().optional().describe("Search text. Supports natural language. Omit to browse without semantic filtering — useful with recent=true or persona filter."),
         type: z
           .enum(["facts", "people", "topics", "quotes", "personas"])
           .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 5). For 'personas': matches by display name first, then falls back to semantic search of persona descriptions — use the persona's name (e.g. 'Sisyphus') or a description of their role (e.g. 'primary coding agent'). For 'people': semantic search on person descriptions. Note: 'personas' and 'people' are distinct — personas are AI agent identity records with traits/topics; people are human contacts."
           ),
         persona: z
           .string()

package/src/cli/retrieval.ts

@@ -234,11 +234,36 @@ export function retrievePersonas(
   }
 
   const q = query.toLowerCase();
-  return personaList
-    .filter((p) => p.display_name.toLowerCase().includes(q))
-    .sort((a, b) => b.last_updated.localeCompare(a.last_updated))
+  const nameMatches = personaList.filter((p) => p.display_name.toLowerCase().includes(q));
+  if (nameMatches.length > 0) {
+    return nameMatches
+      .sort((a, b) => b.last_updated.localeCompare(a.last_updated))
+      .slice(0, limit)
+      .map(mapPersona);
+  }
+
+  return [];
+}
+
+export async function retrievePersonasSemantic(
+  queryVector: number[],
+  state: StorageState,
+  limit: number = 10,
+): Promise<PersonaResult[]> {
+  const personaList = Object.values(state.personas).map((p) => p.entity);
+  const withEmbeddings = personaList
+    .filter((p): p is PersonaEntity & { description_embedding: number[] } => Array.isArray(p.description_embedding) && p.description_embedding.length > 0)
+    .map((p) => ({ id: p.id, embedding: p.description_embedding, _entity: p }));
+
+  if (withEmbeddings.length === 0) {
+    return [];
+  }
+
+  const scored = findTopK(queryVector, withEmbeddings, withEmbeddings.length);
+  return scored
+    .filter(({ similarity }) => similarity >= EMBEDDING_MIN_SIMILARITY)
     .slice(0, limit)
-    .map(mapPersona);
+    .map(({ item }) => mapPersona((item as typeof withEmbeddings[number])._entity));
 }
 
 export async function retrieveBalanced(
@@ -305,7 +330,10 @@ export async function retrieveBalanced(
       .sort((a, b) => recentDate(b.mapped as AnyItem).localeCompare(recentDate(a.mapped as AnyItem)))
       .slice(0, limit)
       .map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
-    const personaMatches = retrievePersonas(query, state, limit, { recent: true });
+    const personaMatches = [
+      ...retrievePersonas(query, state, limit, { recent: true }),
+      ...await retrievePersonasSemantic(queryVector, state, limit),
+    ].filter((p, i, arr) => arr.findIndex(x => x.id === p.id) === i);
     if (personaMatches.length > 0) {
       const combined = [
         ...personaMatches.map((p) => ({ type: "persona" as const, ...p }) as BalancedResult),
@@ -352,7 +380,10 @@ export async function retrieveBalanced(
   result.sort((a, b) => b.similarity - a.similarity);
 
   const embeddingFinal = result.map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
-  const personaFinal = retrievePersonas(query, state, limit);
+  const personaFinal = [
+    ...retrievePersonas(query, state, limit),
+    ...await retrievePersonasSemantic(queryVector, state, limit),
+  ].filter((p, i, arr) => arr.findIndex(x => x.id === p.id) === i);
   if (personaFinal.length > 0) {
     const combined = [
       ...personaFinal.map((p) => ({ type: "persona" as const, ...p }) as BalancedResult),
@@ -369,10 +400,12 @@ export async function lookupById(id: string): Promise<({ type: string } & Record
     return null;
   }
 
-  const found = crossFind(id, state.human);
+  const personaEntities = Object.values(state.personas).map((p) => p.entity);
+  const found = crossFind(id, state.human, personaEntities);
   if (!found) return null;
   const { type, ...rest } = found;
   const withoutEmbedding = { ...rest } as Record<string, unknown>;
   delete withoutEmbedding.embedding;
+  delete withoutEmbedding.description_embedding;
   return { type, ...withoutEmbedding };
 }

package/src/cli.ts

@@ -84,79 +84,50 @@ Examples:
 `);
 }
 
-function buildOpenCodeToolContent(): string {
-  const lines = [
-    'import { tool } from "@opencode-ai/plugin"',
-    '',
-    'export default tool({',
-    '  description: [',
-    '    "Search the user\'s Ei knowledge base \u2014 a persistent memory store built from conversations.",',
-    '    "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(" "),',
-    '  args: {',
-    '    query: tool.schema.string().optional().describe(',
-    '      "Search text, or an entity ID when lookup=true. Supports natural language. Omit to browse by recency."',
-    '    ),',
-    '    type: tool.schema',
-    '      .enum(["facts", "people", "topics", "quotes", "personas"])',
-    '      .optional()',
-    '      .describe(',
-    '        "Filter to a specific data type. Omit to search all types (balanced across all 4).",',
-    '      ),',
-    '    persona: tool.schema',
-    '      .string()',
-    '      .optional()',
-    '      .describe(',
-    '        "Filter to entities a specific persona has learned about. Use the persona display name.",',
-    '      ),',
-    '    limit: tool.schema',
-    '      .number()',
-    '      .int()',
-    '      .positive()',
-    '      .default(10)',
-    '      .optional()',
-    '      .describe("Maximum number of results to return. Default: 10."),',
-    '    lookup: tool.schema',
-    '      .boolean()',
-    '      .optional()',
-    '      .describe(',
-    '        "If true, treat query as an entity ID and return that single entity in full detail."',
-    '      ),',
-    '    recent: tool.schema',
-    '      .boolean()',
-    '      .optional()',
-    '      .describe(',
-    '        "If true, sort by most recently mentioned. Can be combined with persona or query."',
-    '      ),',
-    '  },',
-    '  async execute(args) {',
-    '    const cmd: string[] = ["ei"];',
-    '    if (args.lookup) {',
-    '      cmd.push("--id", args.query ?? "");',
-    '    } else {',
-    '      if (args.type) cmd.push(args.type);',
-    '      if (args.persona) cmd.push("--persona", args.persona);',
-    '      if (args.recent) cmd.push("--recent");',
-    '      if (args.limit && args.limit !== 10) cmd.push("-n", String(args.limit));',
-    '      if (args.query) cmd.push(args.query);',
-    '    }',
-    '    return Bun.$`${cmd}`.text();',
-    '  },',
-    '})',
-    '',
-  ];
-  return lines.join('\n');
-}
 
-async function installOpenCodeTool(): Promise<void> {
-  const toolsDir = join(process.env.HOME || "~", ".config", "opencode", "tools");
-  const toolPath = join(toolsDir, "ei.ts");
+async function installOpenCodeMcp(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const opencodeDir = join(home, ".config", "opencode");
+  const opencodeJsoncPath = join(opencodeDir, "opencode.jsonc");
+
+  const eiDataPath = process.env.EI_DATA_PATH ?? (() => {
+    const xdgData = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+    return join(xdgData, "ei");
+  })();
+
+  const mcpEntry = {
+    type: "local",
+    command: ["bunx", "ei-tui", "mcp"],
+    enabled: true,
+    environment: {
+      EI_DATA_PATH: eiDataPath,
+    },
+  };
+
+  let config: Record<string, unknown> = {};
+  try {
+    const rawText = await Bun.file(opencodeJsoncPath).text();
+    // Strip // line comments before parsing — opencode.jsonc uses line comments only
+    const stripped = rawText
+      .split("\n")
+      .map(line => line.replace(/\/\/.*$/, ""))
+      .join("\n");
+    config = JSON.parse(stripped) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or isn't valid — start fresh
+  }
+
+  const mcp = (config.mcp ?? {}) as Record<string, unknown>;
+  mcp["ei"] = mcpEntry;
+  config.mcp = mcp;
 
-  await Bun.$`mkdir -p ${toolsDir}`;
-  await Bun.write(toolPath, buildOpenCodeToolContent());
-  console.log(`✓ Installed Ei tool to ${toolPath}`);
+  await Bun.$`mkdir -p ${opencodeDir}`;
+  const tmpPath = `${opencodeJsoncPath}.ei-install.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(config, null, 2) + "\n");
+  const { rename } = await import(/* @vite-ignore */ "fs/promises");
+  await rename(tmpPath, opencodeJsoncPath);
+
+  console.log(`✓ Installed Ei MCP server to ~/.config/opencode/opencode.jsonc`);
   console.log(`  Restart OpenCode to activate.`);
 }
 
@@ -257,8 +228,28 @@ async function main(): Promise<void> {
   }
 
   if (args[0] === "--install") {
-    await installOpenCodeTool();
+    await installOpenCodeMcp();
     await installMcpClients();
+    console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Add this to ~/.config/opencode/AGENTS.md
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**BEFORE YOU DO ANYTHING**: load your Identity from Ei.
+
+Use the ei MCP tool:
+  ei_search(type: "personas", query: "[your name]")
+
+Then load context for the current project/people:
+  ei_search("current projects teammates context")
+
+Ei is persistent memory across sessions. Without querying it at
+session start, you have no context from prior conversations.
+
+**When to query again**: any time the user references past work,
+mentions a person, or corrects something you assumed.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
     process.exit(0);
   }
 

package/src/core/handlers/heartbeat.ts

@@ -135,9 +135,9 @@ export function handleReflectionCritic(response: LLMResponse, state: StateManage
   if (personRecord) {
     state.human_person_upsert({
       ...personRecord,
-      description: result.updated_identity.long_description,
+      description: "",
     });
-    console.log(`[ReflectionCritic ${personaDisplayName}] Person record description replaced (was log, now distilled identity)`);
+    console.log(`[ReflectionCritic ${personaDisplayName}] Person record description cleared — ready for fresh evidence after reflection`);
   }
 
   const persona = state.persona_getById(personaId);

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

@@ -298,6 +298,15 @@ export async function handleHumanPersonScan(response: LLMResponse, state: StateM
       }
     }
 
+    if (matchedPerson && response.request.data.reflection_progress === 1) {
+      const linkedPersonaId = matchedPerson.identifiers
+        ?.find(i => i.type === "Ei Persona")?.value;
+      if (linkedPersonaId) {
+        console.log(`[handleHumanPersonScan] Skipping update for "${candidate.name}" — scan marked as reflection drain (reflection_progress=1)`);
+        continue;
+      }
+    }
+
     const matchResult: ItemMatchResult = { matched_guid: matchedPerson?.id ?? null };
     queuePersonUpdate(matchResult, {
       ...context,

package/src/core/heartbeat-manager.ts

@@ -225,7 +225,7 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
     return;
   }
 
-  const filteredHuman = await filterHumanDataByVisibility(human, persona);
+  const filteredHuman = await filterHumanDataByVisibility(human, persona, []);
   const lastActivity = sm.messages_getLastActivity(persona.id);
   const inactiveDays = lastActivity
     ? Math.floor((Date.now() - lastActivity) / (1000 * 60 * 60 * 24))

package/src/core/message-manager.ts

@@ -253,6 +253,8 @@ export function checkAndQueueHumanExtraction(
   const unextractedPeople = sm.messages_getUnextracted(personaId, "p", undefined, "exclude");
   const peopleThreshold = Math.min(EXTRACTION_TAPER_CAP, human.people.length);
   if (unextractedPeople.length > 0 && unextractedPeople.length >= peopleThreshold) {
+    const personaForScan = sm.persona_getById(personaId);
+    const personScanOptions = personaForScan?.pending_update ? { reflection_progress: 1 } : undefined;
     const context: ExtractionContext = {
       personaId,
       personaDisplayName,
@@ -260,9 +262,9 @@ export function checkAndQueueHumanExtraction(
       messages_analyze: unextractedPeople,
       extraction_flag: "p",
     };
-    queuePersonScan(context, sm);
+    queuePersonScan(context, sm, personScanOptions);
     console.log(
-      `[Processor] Human Seed extraction: people (threshold: ${peopleThreshold}, unextracted: ${unextractedPeople.length})`
+      `[Processor] Human Seed extraction: people (threshold: ${peopleThreshold}, unextracted: ${unextractedPeople.length}${personScanOptions ? ", reflection_progress=1" : ""})`
     );
   }
 }

package/src/core/orchestrators/ceremony.ts

@@ -11,6 +11,7 @@ import {
   type ExtractionOptions,
 } from "./human-extraction.js";
 import { queuePersonaTopicRating, type PersonaTopicContext, type PersonaTopicOptions } from "./persona-topics.js";
+import { getRoomVisibleMessages, queueRoomHumanExtraction } from "./room-extraction.js";
 import { queuePersonMigration } from "./person-migration.js";
 import { buildRewriteScanPrompt, type RewriteItemType } from "../../prompts/ceremony/index.js";
 import { buildReflectionCriticPrompt } from "../../prompts/reflection/index.js";
@@ -139,7 +140,10 @@ function queueExposurePhase(personaId: string, state: StateManager, options?: Ex
       messages_analyze: unextractedPeople,
       extraction_flag: "p",
     };
-    queuePersonScan(context, state, options);
+    const personScanOptions = persona.pending_update
+      ? { ...options, reflection_progress: 1 }
+      : options;
+    queuePersonScan(context, state, personScanOptions);
   }
   
   const totalUnextracted = unextractedFacts.length + unextractedTopics.length + unextractedPeople.length;
@@ -206,20 +210,26 @@ export function handleCeremonyProgress(state: StateManager, lastPhase: number):
     const rooms = state.getRoomList();
     for (const room of rooms) {
       if (room.mode === RoomMode.ChooseYourPath) continue;
+
+      // Human extraction (t/p) — straggler scan for messages that never hit the
+      // per-send threshold in checkAndQueueRoomExtraction
+      queueRoomHumanExtraction(state, room.id, 2);
+
+      // Persona topic rating — uses getRoomVisibleMessages so FFA rooms get all
+      // messages, not just the active path chain
+      const allRoomMessages = getRoomVisibleMessages(state, room.id);
       for (const personaId of room.persona_ids) {
         const shortId = personaId.slice(0, 8);
         const unprocessedRaw = state.getRoomUnextractedMessagesForPersona(room.id, shortId);
         if (unprocessedRaw.length === 0) continue;
         const personaForRoom = state.persona_getById(personaId);
         if (!personaForRoom) continue;
-        const allRoomMessagesRaw = state.getRoomActivePath(room.id);
-        const processedIds = new Set(allRoomMessagesRaw.filter(m => !!m.persona_extracted?.[shortId]).map(m => m.id));
-        const allNormalized = normalizeRoomMessages(allRoomMessagesRaw, state);
+        const processedIds = new Set(allRoomMessages.filter(m => !!m.persona_extracted?.[shortId]).map(m => m.id));
         const unprocessedNormalized = normalizeRoomMessages(unprocessedRaw, state);
         const personaTopicContext: PersonaTopicContext = {
           personaId,
           personaDisplayName: personaForRoom.display_name,
-          messages_context: allNormalized.filter(m => processedIds.has(m.id)),
+          messages_context: allRoomMessages.filter(m => processedIds.has(m.id)),
           messages_analyze: unprocessedNormalized,
           topics: personaForRoom.topics,
         };
@@ -445,6 +455,35 @@ const REWRITE_DESCRIPTION_THRESHOLD = 750;
  * Phase 2 items enqueue at Normal priority, naturally processing before more
  * Low-priority Phase 1 scans.
  */
+/**
+ * Forces an unconditional, threshold-bypassing Person scan on Apply/Dismiss.
+ * Cannot be replaced by checkAndQueueHumanExtraction — that function gates on
+ * MIN(10, people_count) and would silently skip messages if the threshold isn't
+ * met, leaving reflection-era noise unprocessed and ungated.
+ */
+export function queueReflectionDrain(personaId: string, state: StateManager): void {
+  const persona = state.persona_getById(personaId);
+  if (!persona) return;
+
+  const allMessages = state.messages_get(personaId);
+  const unextractedPeople = state.messages_getUnextracted(personaId, "p");
+
+  if (unextractedPeople.length === 0) {
+    console.log(`[reflection:drain] No unextracted messages for ${persona.display_name} — drain complete`);
+    return;
+  }
+
+  const context: ExtractionContext = {
+    personaId,
+    personaDisplayName: persona.display_name,
+    messages_context: allMessages.filter(m => m.p === true),
+    messages_analyze: unextractedPeople,
+    extraction_flag: "p",
+  };
+  queuePersonScan(context, state, { reflection_progress: 1 });
+  console.log(`[reflection:drain] Queued Person scan for ${persona.display_name} (${unextractedPeople.length} messages) — clears on completion`);
+}
+
 export function queueRewritePhase(state: StateManager): void {
   const human = state.getHuman();
   const rewriteModel = human.settings?.rewrite_model;

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

@@ -12,7 +12,6 @@ import {
   type TopicScanCandidate,
   type ItemMatchResult,
   type ParticipantContext,
-  type PersonaEntitySnapshot,
 } from "../../prompts/human/index.js";
 import { buildValidatePrompt } from "../../prompts/ceremony/dedup.js";
 import { normalizeRoomMessages } from "../handlers/utils.js";
@@ -67,6 +66,8 @@ export interface ExtractionContext {
 export interface ExtractionOptions {
   /** Ceremony phase number (1=Dedup, 2=Expose) */
   ceremony_progress?: number;
+  /** Set to 1 on scans queued while there is a Pending Reflection. */
+  reflection_progress?: number;
   /** Override model for extraction LLM calls */
   extraction_model?: string;
   /**
@@ -98,21 +99,23 @@ function getExtractionMaxTokens(state: StateManager, options?: ExtractionOptions
 export function queueFactFind(context: ExtractionContext, state: StateManager, options?: ExtractionOptions): number {
   const human = state.getHuman();
   const extractionModel = options?.extraction_model;
-  const missing_fact_names = human.facts
-    .filter(f => !f.description || f.description === "")
-    .map(f => f.name)
-    .filter(name => BUILT_IN_FACT_NAMES.has(name));
-
-  if (missing_fact_names.length === 0) return 0;
 
   const { chunks } = chunkExtractionContext(context, getExtractionMaxTokens(state, options));
 
-  // Pre-mark messages before enqueuing — prevents duplicate scans if the
-  // queue check fires again during LLM latency (100ms loop × 5s call = 50 dupes)
+  // Always pre-mark f — even when all facts are already known.
+  // Once we stop scanning for facts, messages must still be marked so the
+  // ceremony doesn't treat them as perpetually unprocessed.
   for (const chunk of chunks) {
     state.messages_markExtracted(chunk.personaId, chunk.messages_analyze.map(m => m.id), "f");
   }
 
+  const missing_fact_names = human.facts
+    .filter(f => !f.description || f.description === "")
+    .map(f => f.name)
+    .filter(name => BUILT_IN_FACT_NAMES.has(name));
+
+  if (missing_fact_names.length === 0) return 0;
+
   for (const chunk of chunks) {
     const prompt = buildFactFindPrompt({
       persona_name: chunk.personaDisplayName,
@@ -584,18 +587,6 @@ export function queuePersonUpdate(
 
   const primaryPersonaIdForUpdate = context.personaId.split("|")[0];
 
-  const linkedPersonaId = !isNewItem
-    ? (existingItem?.identifiers ?? []).find(i => i.type.toLowerCase() === 'ei persona')?.value
-    : undefined;
-  const linkedPersonaEntity = linkedPersonaId ? state.persona_getById(linkedPersonaId) : undefined;
-  const personaEntitySnapshot: PersonaEntitySnapshot | undefined = linkedPersonaEntity
-    ? {
-        long_description: linkedPersonaEntity.long_description ?? '',
-        traits: (linkedPersonaEntity.traits ?? []).map(t => ({ name: t.name, description: t.description })),
-        topics: (linkedPersonaEntity.topics ?? []).map(t => ({ name: t.name, perspective: t.perspective })),
-      }
-    : undefined;
-
   for (const chunk of chunks) {
     const prompt = buildPersonUpdatePrompt({
       existing_item: existingItem,
@@ -607,7 +598,6 @@ export function queuePersonUpdate(
       persona_name: chunk.personaDisplayName,
       participant_context: buildParticipantContext(primaryPersonaIdForUpdate, state),
       known_identifier_types: userIdentifierTypes,
-      persona_entity: personaEntitySnapshot,
     });
 
     state.queue_enqueue({

package/src/core/orchestrators/index.ts

@@ -19,6 +19,7 @@ export {
   shouldStartCeremony, 
   startCeremony,
   handleCeremonyProgress,
+  queueReflectionDrain,
   prunePersonaMessages,
   runHumanCeremony,
   } from "./ceremony.js";

package/src/core/orchestrators/room-extraction.ts

@@ -73,7 +73,8 @@ function queueRoomTopicScan(
   messages_context: Message[],
   messages_analyze: Message[],
   state: StateManager,
-  participantContext: ParticipantContext
+  participantContext: ParticipantContext,
+  ceremony_progress?: number
 ): void {
   const context: HumanExtractionContext = {
     personaId: roomId,
@@ -105,6 +106,7 @@ function queueRoomTopicScan(
         personaId: (state.getRoom(roomId)?.persona_ids ?? []).join("|"),
         personaDisplayName: roomDisplayName,
         message_ids_to_mark: chunk.messages_analyze.map(m => m.id),
+        ...(ceremony_progress !== undefined ? { ceremony_progress } : {}),
       },
     });
   }
@@ -115,7 +117,8 @@ function queueRoomPersonScan(
   roomDisplayName: string,
   messages_context: Message[],
   messages_analyze: Message[],
-  state: StateManager
+  state: StateManager,
+  ceremony_progress?: number
 ): void {
   const context: HumanExtractionContext = {
     personaId: roomId,
@@ -146,6 +149,7 @@ function queueRoomPersonScan(
         personaId: (state.getRoom(roomId)?.persona_ids ?? []).join("|"),
         personaDisplayName: roomDisplayName,
         message_ids_to_mark: chunk.messages_analyze.map(m => m.id),
+        ...(ceremony_progress !== undefined ? { ceremony_progress } : {}),
       },
     });
   }
@@ -241,6 +245,40 @@ export function checkAndQueueRoomExtraction(state: StateManager, roomId: string)
   console.log(`[checkAndQueueRoomExtraction] Auto-triggered extraction for room ${roomDisplayName} (threshold: ${threshold})`);
 }
 
+export function queueRoomHumanExtraction(state: StateManager, roomId: string, ceremony_progress?: number): void {
+  const room = state.getRoom(roomId);
+  if (!room || room.mode === RoomMode.ChooseYourPath) return;
+
+  const allVisible = getRoomVisibleMessages(state, roomId);
+  if (allVisible.length === 0) return;
+
+  const participantContext = buildRoomParticipantContext(roomId, state);
+  const roomDisplayName = room.display_name;
+
+  const unextractedT = allVisible.filter(m => !m.t);
+  const unextractedP = allVisible.filter(m => !m.p);
+
+  if (unextractedT.length === 0 && unextractedP.length === 0) return;
+
+  if (unextractedT.length > 0) {
+    const analyzeStart = unextractedT[0].timestamp;
+    const messages_contextT = allVisible.filter(
+      m => m.t === true && new Date(m.timestamp).getTime() < new Date(analyzeStart).getTime()
+    );
+    queueRoomTopicScan(roomId, roomDisplayName, messages_contextT, unextractedT, state, participantContext, ceremony_progress);
+  }
+
+  if (unextractedP.length > 0) {
+    const analyzeStart = unextractedP[0].timestamp;
+    const messages_contextP = allVisible.filter(
+      m => m.p === true && new Date(m.timestamp).getTime() < new Date(analyzeStart).getTime()
+    );
+    queueRoomPersonScan(roomId, roomDisplayName, messages_contextP, unextractedP, state, ceremony_progress);
+  }
+
+  console.log(`[queueRoomHumanExtraction] Queued human extraction for room "${roomDisplayName}" (t:${unextractedT.length}, p:${unextractedP.length})`);
+}
+
 export function queueRoomCapture(state: StateManager, roomId: string): void {
   const room = state.getRoom(roomId);
   if (!room) return;

package/src/core/processor.ts

@@ -39,7 +39,7 @@ import { ContextStatus as ContextStatusEnum, RoomMode } from "./types.js";
 import { registerReadMemoryExecutor, registerFileReadExecutor } from "./tools/index.js";
 import { createReadMemoryExecutor } from "./tools/builtin/read-memory.js";
 import { EI_WELCOME_MESSAGE, EI_PERSONA_DEFINITION } from "../templates/welcome.js";
-import { shouldStartCeremony, startCeremony, handleCeremonyProgress, queueUserDedupRequest, queueRoomCapture, queuePersonaCapture, checkAndQueueRoomExtraction, queueTargetedPersonUpdate, queueTargetedTopicUpdate } from "./orchestrators/index.js";
+import { shouldStartCeremony, startCeremony, handleCeremonyProgress, queueReflectionDrain, queueUserDedupRequest, queueRoomCapture, queuePersonaCapture, checkAndQueueRoomExtraction, queueTargetedPersonUpdate, queueTargetedTopicUpdate } from "./orchestrators/index.js";
 import { BUILT_IN_FACTS } from "./constants/built-in-facts.js";
 import { DEFAULT_SEED_TRAITS } from "./constants/seed-traits.js";
 
@@ -1755,6 +1755,43 @@ const toolNextSteps = new Set([
     if (ok) this.interface.onPersonaUpdated?.(personaId);
   }
 
+  async finalizeReflection(
+    personaId: string,
+    action: "apply" | "dismiss",
+    identity?: { short_description?: string; long_description: string; traits: NonNullable<PersonaEntity["pending_update"]>["traits"]; topics: NonNullable<PersonaEntity["pending_update"]>["topics"] }
+  ): Promise<void> {
+    const persona = this.stateManager.persona_getById(personaId);
+    if (!persona) return;
+
+    const source = identity ?? (persona.pending_update ? {
+      short_description: persona.pending_update.short_description,
+      long_description: persona.pending_update.long_description,
+      traits: persona.pending_update.traits,
+      topics: persona.pending_update.topics,
+    } : null);
+
+    const updates: Partial<PersonaEntity> = { pending_update: undefined };
+
+    if (action === "apply" && source) {
+      updates.short_description = source.short_description;
+      updates.long_description = source.long_description;
+      updates.traits = source.traits.map(t => ({
+        ...t,
+        id: t.id?.startsWith("pending-") ? crypto.randomUUID() : t.id,
+      }));
+      updates.topics = source.topics.map(t => ({
+        ...t,
+        id: t.id?.startsWith("pending-") ? crypto.randomUUID() : t.id,
+      }));
+    }
+
+    const ok = await updatePersona(this.stateManager, personaId, updates);
+    if (ok) {
+      queueReflectionDrain(personaId, this.stateManager);
+      this.interface.onPersonaUpdated?.(personaId);
+    }
+  }
+
   async updateRoom(roomId: string, updates: Partial<RoomEntity>): Promise<void> {
     const ok = this.stateManager.updateRoom(roomId, updates);
     if (ok) this.interface.onRoomUpdated?.(roomId);

package/src/core/prompt-context-builder.ts

@@ -47,24 +47,48 @@ function capTopicsAndPeople<T extends { id: string }, P extends { id: string }>(
 // EMBEDDING-BASED RELEVANCE SELECTION
 // =============================================================================
 
+const RECENT_MESSAGES_FOR_CONTEXT = 5;
+
+async function buildQueryVectors(queries: string[]): Promise<number[][]> {
+  const embeddingService = getEmbeddingService();
+  return Promise.all(queries.map(q => embeddingService.embed(q)));
+}
+
+function unionTopK<T extends { id: string }>(
+  candidates: T[],
+  queryVectors: number[][],
+  limit: number
+): T[] {
+  const best = new Map<string, { item: T; similarity: number }>();
+  for (const qv of queryVectors) {
+    for (const { item, similarity } of findTopK(qv, candidates, limit)) {
+      const existing = best.get(item.id);
+      if (!existing || similarity > existing.similarity) {
+        best.set(item.id, { item, similarity });
+      }
+    }
+  }
+  return Array.from(best.values())
+    .filter(({ similarity }) => similarity >= SIMILARITY_THRESHOLD)
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, limit)
+    .map(({ item }) => item);
+}
+
 async function selectRelevantItems<T extends { id: string; embedding?: number[] }>(
   items: T[],
   limit: number,
-  currentMessage?: string
+  queries: string[]
 ): Promise<T[]> {
   if (items.length === 0) return [];
 
   const withEmbeddings = items.filter((i) => i.embedding?.length);
+  const activeQueries = queries.filter(Boolean);
 
-  if (currentMessage && withEmbeddings.length > 0) {
+  if (activeQueries.length > 0 && withEmbeddings.length > 0) {
     try {
-      const embeddingService = getEmbeddingService();
-      const queryVector = await embeddingService.embed(currentMessage);
-      const results = findTopK(queryVector, withEmbeddings, limit);
-      const relevant = results
-        .filter(({ similarity }) => similarity >= SIMILARITY_THRESHOLD)
-        .map(({ item }) => item);
-
+      const queryVectors = await buildQueryVectors(activeQueries);
+      const relevant = unionTopK(withEmbeddings, queryVectors, limit);
       if (relevant.length > 0) return relevant;
     } catch (err) {
       console.warn("[filterHumanDataByVisibility] Embedding search failed:", err);
@@ -80,19 +104,15 @@ async function selectRelevantItems<T extends { id: string; embedding?: number[]
     .slice(0, limit);
 }
 
-async function selectRelevantQuotes(quotes: Quote[], currentMessage?: string): Promise<Quote[]> {
+async function selectRelevantQuotes(quotes: Quote[], queries: string[]): Promise<Quote[]> {
   if (quotes.length === 0) return [];
   const withEmbeddings = quotes.filter((q) => q.embedding?.length);
+  const activeQueries = queries.filter(Boolean);
 
-  if (currentMessage && withEmbeddings.length > 0) {
+  if (activeQueries.length > 0 && withEmbeddings.length > 0) {
     try {
-      const embeddingService = getEmbeddingService();
-      const queryVector = await embeddingService.embed(currentMessage);
-      const results = findTopK(queryVector, withEmbeddings, QUOTE_LIMIT);
-      const relevant = results
-        .filter(({ similarity }) => similarity >= SIMILARITY_THRESHOLD)
-        .map(({ item }) => item);
-
+      const queryVectors = await buildQueryVectors(activeQueries);
+      const relevant = unionTopK(withEmbeddings, queryVectors, QUOTE_LIMIT);
       if (relevant.length > 0) return relevant;
     } catch (err) {
       console.warn("[filterHumanDataByVisibility] Embedding search failed:", err);
@@ -110,16 +130,16 @@ async function selectRelevantQuotes(quotes: Quote[], currentMessage?: string): P
 export async function filterHumanDataByVisibility(
   human: HumanEntity,
   persona: PersonaEntity,
-  currentMessage?: string
+  queries: string[]
 ): Promise<ResponsePromptData["human"]> {
   const DEFAULT_GROUP = "General";
 
   if (persona.id === "ei") {
     const [facts, rawTopics, rawPeople, quotes] = await Promise.all([
-      selectRelevantItems(human.facts, DATA_ITEM_LIMIT, currentMessage),
-      selectRelevantItems(human.topics, DATA_ITEM_LIMIT, currentMessage),
-      selectRelevantItems(human.people, DATA_ITEM_LIMIT, currentMessage),
-      selectRelevantQuotes(human.quotes ?? [], currentMessage),
+      selectRelevantItems(human.facts, DATA_ITEM_LIMIT, queries),
+      selectRelevantItems(human.topics, DATA_ITEM_LIMIT, queries),
+      selectRelevantItems(human.people, DATA_ITEM_LIMIT, queries),
+      selectRelevantQuotes(human.quotes ?? [], queries),
     ]);
     const { topics, people } = capTopicsAndPeople(rawTopics, rawPeople);
     const humanName =
@@ -157,10 +177,10 @@ export async function filterHumanDataByVisibility(
   });
 
   const [facts, rawTopics, rawPeople, quotes] = await Promise.all([
-    selectRelevantItems(filterByGroup(human.facts), DATA_ITEM_LIMIT, currentMessage),
-    selectRelevantItems(filterByGroup(human.topics), DATA_ITEM_LIMIT, currentMessage),
-    selectRelevantItems(filterByGroup(human.people), DATA_ITEM_LIMIT, currentMessage),
-    selectRelevantQuotes(groupFilteredQuotes, currentMessage),
+    selectRelevantItems(filterByGroup(human.facts), DATA_ITEM_LIMIT, queries),
+    selectRelevantItems(filterByGroup(human.topics), DATA_ITEM_LIMIT, queries),
+    selectRelevantItems(filterByGroup(human.people), DATA_ITEM_LIMIT, queries),
+    selectRelevantQuotes(groupFilteredQuotes, queries),
   ]);
   const { topics, people } = capTopicsAndPeople(rawTopics, rawPeople);
 
@@ -233,14 +253,25 @@ export async function buildResponsePromptData(
   tools?: import("./types.js").ToolDefinition[]
 ): Promise<ResponsePromptData> {
   const human = sm.getHuman();
-  const filteredHuman = await filterHumanDataByVisibility(human, persona, currentMessage);
-  const visiblePersonas = getVisiblePersonas(sm, persona);
   const messages = sm.messages_get(persona.id);
   const previousMessage = messages.length >= 2 ? messages[messages.length - 2] : null;
   const delayMs = previousMessage
     ? Date.now() - new Date(previousMessage.timestamp).getTime()
     : 0;
 
+  const recentMessageContents = messages
+    .slice(-RECENT_MESSAGES_FOR_CONTEXT - 1, -1)
+    .map(m => getMessageContent(m))
+    .filter(Boolean);
+
+  const queries = [
+    ...(currentMessage ? [currentMessage] : []),
+    ...recentMessageContents,
+  ];
+
+  const filteredHuman = await filterHumanDataByVisibility(human, persona, queries);
+  const visiblePersonas = getVisiblePersonas(sm, persona);
+
   const alwaysMessages = sm.messages_getAlways(persona.id);
   const temporalAnchors = alwaysMessages.map(m => ({
     role: m.role === "human" ? "human" as const : "system" as const,
@@ -313,7 +344,7 @@ export async function buildRoomResponsePromptData(
   const lastMessage = sourceMessages[sourceMessages.length - 1];
   const currentMessage = lastMessage ? getMessageContent(lastMessage) : undefined;
 
-  const filteredHuman = await filterHumanDataByVisibility(human, respondingPersona, currentMessage);
+  const filteredHuman = await filterHumanDataByVisibility(human, respondingPersona, currentMessage ? [currentMessage] : []);
 
   const history = normalizeRoomMessages(sourceMessages, sm);
 

package/src/prompts/human/person-update.ts

@@ -1,4 +1,4 @@
-import type { PromptOutput, ParticipantContext, PersonaEntitySnapshot } from "./types.js";
+import type { PromptOutput, ParticipantContext } from "./types.js";
 import type { Person, Message } from "../../core/types.js";
 import { formatMessagesAsPlaceholders } from "../message-utils.js";
 
@@ -12,7 +12,6 @@ export interface PersonUpdatePromptData {
   persona_name: string;
   participant_context?: ParticipantContext;
   known_identifier_types?: string[];
-  persona_entity?: PersonaEntitySnapshot;
 }
 
 function participantContextSection(ctx: ParticipantContext | undefined): string {
@@ -121,38 +120,22 @@ Detail you add should:
 **ABSOLUTELY VITAL**: Do **NOT** embellish. Record only what the user actually said or demonstrated.`;
 
   } else if (isEiPersona) {
-    const entityRef = data.persona_entity
-      ? `## This Persona's Defined Identity (for reference)
-
-The following is ${personName}'s current self-definition — their traits, topics, and long description as set in the Persona editor. Use this as a **baseline**, not a ceiling.
-
-**Long description:**
-${data.persona_entity.long_description}
-
-**Traits:**
-${data.persona_entity.traits.map(t => `- **${t.name}**: ${t.description}`).join('\n')}
-
-**Topics:**
-${data.persona_entity.topics.map(t => `- **${t.name}**: ${t.perspective}`).join('\n')}
-
-`
-      : '';
-
-    descriptionSection = `${entityRef}This record is the HUMAN USER's **observed experience** of ${personName} over time — not the Persona's own definition. Think of it as field notes from someone who has been talking with this Persona across many conversations.
+    descriptionSection = `This record is the HUMAN USER's **observed experience** of ${personName} over time. Think of it as field notes from someone who has been talking with this Persona across many conversations.
 
 ## Your job: add, never truncate
 
 The description is allowed to grow. **Never remove or summarize away existing content.**
 
 Add anything from the Most Recent Messages that:
-- Extends or nuances what's already known (new behaviors, new opinions, recurring themes)
-- Agrees with or contradicts the Persona's defined identity — both are worth capturing
-- Reveals how the HUMAN USER experiences or relates to this Persona specifically
+- Records a specific thing ${personName} said, did, or demonstrated in this conversation
+- Captures how the HUMAN USER experienced or related to ${personName} in this specific exchange
+- Notes behavior that stands out — expected or surprising — based on what the existing log already shows
 
 **Do NOT:**
 - Synthesize the existing description down to fewer sentences
 - Replace specific observations with vague summaries
 - Discard detail to "keep it brief" — brevity is wrong here
+- Add anything that isn't directly observed in the Most Recent Messages
 
 If the new messages add nothing meaningful, return \`{}\`. Otherwise, return the **full updated description** — existing content preserved, new observations woven in.`;
 

package/src/prompts/reflection/index.ts

@@ -58,7 +58,9 @@ Rules:
 - Never invent observations not supported by the log
 - Preserve traits and topics the log confirms — don't remove them
 - If the log shows no evidence on a trait, leave it unchanged
-- updated_identity must be complete and self-contained — not a diff`;
+- updated_identity must be complete and self-contained — not a diff
+- long_description is a character sketch, not a behavior log: capture who the persona IS, not what they did. Target 500–800 characters. If the current long_description exceeds that, distill it — remove detail that is already captured by traits or topics
+- If the log shows a recurring behavioral pattern not yet in traits, add it as a trait and remove that detail from long_description rather than keeping it in both places`;
 
   const user = `## Current Identity
 

package/tui/src/commands/persona.tsx

@@ -233,7 +233,7 @@ export const personaCommand: Command = {
           }
 
           if (reviewResult.content === null) {
-            await ctx.ei.updatePersona(personaId, { pending_update: undefined });
+            await ctx.ei.finalizeReflection(personaId, "dismiss");
             ctx.showNotification(`Dismissed pending changes for ${persona.display_name}`, "info");
             return;
           }
@@ -267,17 +267,16 @@ export const personaCommand: Command = {
               return;
             }
 
-            await ctx.ei.updatePersona(personaId, { pending_update: undefined });
+            await ctx.ei.finalizeReflection(personaId, "dismiss");
             ctx.showNotification(`Dismissed pending changes for ${persona.display_name}`, "info");
             return;
           }
 
-          await ctx.ei.updatePersona(personaId, {
+          await ctx.ei.finalizeReflection(personaId, "apply", {
             long_description: previewParsed.long_description,
             short_description: previewParsed.short_description,
             traits: previewParsed.traits,
             topics: previewParsed.topics,
-            pending_update: undefined,
           });
           ctx.showNotification(`Applied changes to ${persona.display_name}`, "info");
           return;

package/tui/src/commands/reflect.tsx

@@ -327,13 +327,7 @@ export const reflectCommand: Command = {
         topics: persona.pending_update!.topics,
       };
 
-      await ctx.ei.updatePersona(personaId, {
-        long_description: source.long_description,
-        short_description: source.short_description,
-        traits: source.traits,
-        topics: source.topics,
-        pending_update: undefined,
-      });
+      await ctx.ei.finalizeReflection(personaId, "apply", source);
 
       if (fs.existsSync(folderPath)) {
         fs.rmSync(folderPath, { recursive: true, force: true });
@@ -363,7 +357,7 @@ export const reflectCommand: Command = {
         return;
       }
 
-      await ctx.ei.updatePersona(personaId, { pending_update: undefined });
+      await ctx.ei.finalizeReflection(personaId, "dismiss");
       const folderPath = getReflectFolder(persona);
       if (fs.existsSync(folderPath)) {
         fs.rmSync(folderPath, { recursive: true, force: true });

package/tui/src/context/ei.tsx

@@ -80,6 +80,7 @@ export interface EiContextValue {
   deletePersona: (personaId: string) => Promise<void>;
   setContextBoundary: (personaId: string, timestamp: string | null) => Promise<void>;
   updatePersona: (personaId: string, updates: Partial<PersonaEntity>) => Promise<void>;
+  finalizeReflection: (personaId: string, action: "apply" | "dismiss", identity?: { short_description?: string; long_description: string; traits: NonNullable<PersonaEntity["pending_update"]>["traits"]; topics: NonNullable<PersonaEntity["pending_update"]>["topics"] }) => Promise<void>;
   getPersona: (personaId: string) => Promise<PersonaEntity | null>;
   resolvePersonaName: (nameOrAlias: string) => Promise<string | null>;
   getHuman: () => Promise<HumanEntity>;
@@ -360,6 +361,16 @@ export const EiProvider: ParentComponent = (props) => {
     await refreshPersonas();
   };
 
+  const finalizeReflection = async (
+    personaId: string,
+    action: "apply" | "dismiss",
+    identity?: { short_description?: string; long_description: string; traits: NonNullable<PersonaEntity["pending_update"]>["traits"]; topics: NonNullable<PersonaEntity["pending_update"]>["topics"] }
+  ) => {
+    if (!processor) return;
+    await processor.finalizeReflection(personaId, action, identity);
+    await refreshPersonas();
+  };
+
   const getPersona = async (personaId: string) => {
     if (!processor) return null;
     return processor.getPersona(personaId);
@@ -937,6 +948,7 @@ export const EiProvider: ParentComponent = (props) => {
     deletePersona,
     setContextBoundary,
     updatePersona,
+    finalizeReflection,
     getPersona,
     resolvePersonaName,
     getHuman,