ei-tui 0.1.25 → 0.2.0

package/src/core/utils/crossFind.ts

@@ -1,13 +1,12 @@
-import type { HumanEntity, PersonaEntity, Fact, Trait, Topic, Person, Quote, PersonaTopic } from "../types.ts";
+import type { HumanEntity, PersonaEntity, Fact, PersonaTrait, Topic, Person, Quote, PersonaTopic } from "../types.ts";
 export type CrossFindResult =
   | { type: "fact"        } & Fact
-  | { type: "trait"       } & Trait
   | { type: "topic"       } & Topic
   | { type: "person"      } & Person
   | { type: "quote"       } & Quote
   | { type: "persona"     } & PersonaEntity
   | { type: "personaTopic"; personaId: string } & PersonaTopic
-  | { type: "personaTrait"; personaId: string } & Trait;
+  | { type: "personaTrait"; personaId: string } & PersonaTrait;
 
 export function crossFind(
   id: string,
@@ -18,8 +17,6 @@ export function crossFind(
   const fact  = human.facts.find(f => f.id === id);
   if (fact)  return { type: "fact",   ...fact };
 
-  const trait = human.traits.find(t => t.id === id);
-  if (trait) return { type: "trait",  ...trait };
 
   const person = human.people.find(p => p.id === id);
   if (person) return { type: "person", ...person };

package/src/core/utils/event-windows.ts

@@ -0,0 +1,31 @@
+import type { Message } from "../types.js";
+
+const DEFAULT_EVENT_WINDOW_HOURS = 8;
+
+export function buildEventWindows(
+  messages: Message[],
+  gapHours: number = DEFAULT_EVENT_WINDOW_HOURS
+): Message[][] {
+  if (messages.length === 0) return [];
+
+  const gapMs = gapHours * 60 * 60 * 1000;
+  const windows: Message[][] = [];
+  let currentWindow: Message[] = [messages[0]];
+
+  for (let i = 1; i < messages.length; i++) {
+    const prev = new Date(messages[i - 1].timestamp).getTime();
+    const curr = new Date(messages[i].timestamp).getTime();
+
+    if (curr - prev >= gapMs) {
+      windows.push(currentWindow);
+      currentWindow = [];
+    }
+    currentWindow.push(messages[i]);
+  }
+
+  if (currentWindow.length > 0) {
+    windows.push(currentWindow);
+  }
+
+  return windows;
+}

package/src/integrations/claude-code/importer.ts

@@ -54,9 +54,9 @@ function convertToPreMarkedEiMessage(msg: ClaudeCodeMessage): Message {
   return {
     ...convertToEiMessage(msg),
     f: true,
-    r: true,
+    t: true,
     p: true,
-    o: true,
+    e: true,
   };
 }
 
@@ -130,7 +130,7 @@ function ensureSessionTopic(
     exposure_current: 0.5,
     exposure_desired: 0.3,
     persona_groups: CLAUDE_CODE_TOPIC_GROUPS,
-    learned_by: CLAUDE_CODE_PERSONA_NAME,
+    learned_by: stateManager.persona_getByName(CLAUDE_CODE_PERSONA_NAME)?.id ?? undefined,
     last_updated: new Date().toISOString(),
   };
 
@@ -305,7 +305,11 @@ export async function importClaudeCodeSessions(
       messages_analyze: toAnalyze,
     };
 
-    queueAllScans(context, stateManager);
+    const ccSettings = stateManager.getHuman().settings?.claudeCode;
+    queueAllScans(context, stateManager, {
+      extraction_model: ccSettings?.extraction_model,
+      extraction_token_limit: ccSettings?.extraction_token_limit,
+    });
     result.extractionScansQueued += 4;
   }
 

package/src/integrations/claude-code/types.ts

@@ -158,6 +158,8 @@ export const MIN_SESSION_AGE_MS = 20 * 60 * 1000;
 export interface ClaudeCodeSettings {
   integration?: boolean;
   polling_interval_ms?: number;  // Default: 1800000 (30 min)
+  extraction_model?: string;         // "Provider:model" for extraction. Unset = uses default_model.
+  extraction_token_limit?: number;   // Token budget for extraction chunking. Unset = resolved from model.
   last_sync?: string;            // ISO timestamp
   processed_sessions?: Record<string, string>; // sessionId → ISO timestamp of last import
 }

package/src/integrations/opencode/importer.ts

@@ -57,9 +57,9 @@ function convertToPreMarkedEiMessage(ocMsg: OpenCodeMessage): Message {
   return {
     ...convertToEiMessage(ocMsg),
     f: true,
-    r: true,
+    t: true,
     p: true,
-    o: true,
+    e: true,
   };
 }
 
@@ -229,7 +229,11 @@ export async function importOpenCodeSessions(
       };
 
       if (!signal?.aborted) {
-        queueAllScans(context, stateManager);
+        const openCodeSettings = stateManager.getHuman().settings?.opencode;
+        queueAllScans(context, stateManager, {
+          extraction_model: openCodeSettings?.extraction_model,
+          extraction_token_limit: openCodeSettings?.extraction_token_limit,
+        });
         result.extractionScansQueued += 4;
       }
     }

package/src/prompts/AGENTS.md

@@ -29,7 +29,7 @@ interface PromptBuilder<T> {
 
 **Rules**:
 1. **Synchronous** - No async, no fetching
-2. **Pure** - Same input → same output
+2. **Pure** - Same input → same output. No state reads, no side effects.
 3. **Pre-processed data** - Processor fetches/filters before calling
 4. **Minimal logic** - String interpolation, not computation
 
@@ -60,3 +60,75 @@ interface PromptBuilder<T> {
 **Prompt engineering lives here. Code logic lives in Processor.**
 
 When modifying persona behavior, check prompts first—the "personality" is in the English, not the TypeScript.
+
+---
+
+## VIOLATIONS
+
+These are wrong. If you see them, fix them.
+
+### Prompt strings defined outside `src/prompts/`
+
+**Violation:**
+```typescript
+// ❌ In src/core/handlers/something.ts
+const system = `You are an expert at JSON. Return only valid JSON with no commentary.`;
+const user = `Fix this broken JSON: ${badJson}`;
+const response = await llmClient.call({ system, user });
+```
+
+**Correct:** Move the prompt to `src/prompts/[purpose]/index.ts`. The handler calls the builder with pre-fetched data; the builder returns `{ system, user }`.
+
+### Exception: JSON recovery prompt in `queue-processor.ts`
+
+There is one deliberate exception to the "all prompts live in `src/prompts/`" rule: the JSON repair retry prompt in `queue-processor.ts`.
+
+**Why it's an exception**: This is a *repair heuristic* — it fires after a JSON parse failure to ask the LLM to fix its own malformed output. It has no domain knowledge, no persona data, and no human data. It's infrastructure-level error recovery, not a domain prompt. Moving it to `src/prompts/` would create a degenerate prompt builder with a one-line body and no meaningful data contract.
+
+**Criteria for a legitimate exception** (all must be true):
+1. The prompt contains zero domain knowledge (no persona names, no human data, no Ei concepts)
+2. It's error recovery or infrastructure glue, not business logic
+3. Moving it to `src/prompts/` would produce a builder with no real `types.ts` (no input data shape worth naming)
+
+If your use case doesn't meet all three criteria, it belongs in `src/prompts/`.
+
+### Prompt builders that do computation
+
+**Violation:**
+```typescript
+// ❌ Prompt builder filtering its own data
+function buildResponsePrompt(data: ResponsePromptData) {
+  const relevantFacts = data.facts.filter(f => f.sentiment > 0.5);  // ← WRONG
+  const recentTopics = data.topics.slice(-5);                        // ← WRONG
+  return { system: `...${relevantFacts}...`, user: `...` };
+}
+```
+
+**Correct:** The Processor filters and slices before calling the builder. The builder receives already-filtered data and does string interpolation only.
+
+> If you're writing a loop, a `.filter()`, or a `.map()` inside a prompt builder for anything other than formatting a string — stop. That logic belongs in the Processor or a pre-processing utility.
+
+### Async prompt builders
+
+**Violation:**
+```typescript
+// ❌ Async prompt builder
+async function buildHeartbeatPrompt(personaId: string) {
+  const persona = await stateManager.getPersona(personaId);  // ← WRONG
+  return { system: `...`, user: `...` };
+}
+```
+
+**Correct:** Processor calls `stateManager.getPersona()` first, then passes the result to the synchronous builder.
+
+---
+
+## Prompt Creep Warning
+
+Prompt builders are the most-edited files in the codebase. Watch for these failure modes:
+
+- **Logic creep**: A builder that started as pure string interpolation slowly accumulates conditionals, date math, or data filtering. Each addition seems small. After six changes it's a 200-line function that requires mocking to test. If you're adding branching logic to a prompt builder — reconsider. Move it to the Processor.
+
+- **Data shape expansion**: A builder's input type grows to include things it doesn't actually use in the prompt string. This means the Processor is fetching data the prompt doesn't need. Audit `types.ts` when the data shape grows.
+
+- **Responsibility leakage**: A prompt builder that calls another prompt builder, or calls a utility that reads from state, or has a side effect on logging that depends on runtime context. Builders must be standalone: same input, same output, every time, in any order.

package/src/prompts/ceremony/rewrite.ts

@@ -59,10 +59,9 @@ Rules:
 - The original record (id: "${data.item.id}") MUST appear in "existing", slimmed down.
 - Descriptions should be concise — ideally under 300 characters, never over 500.
 - Preserve sentiment, strength, confidence, and other numeric values from the source record where applicable.
-- "type" must be one of: "fact", "trait", "topic", "person".
-- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project.
+- "type" must be one of: "fact", "topic", "person".
+- Topics MUST include "category" — one of: Interest, Goal, Dream, Conflict, Concern, Fear, Hope, Plan, Project, Event. For Event topics, the description should be a narrative account of a specific moment, not a general summary.
 - People MUST include "relationship" — a short label like "coworker", "friend", "mentor", etc.
-- Traits MUST include "strength" (0.0-1.0).
 - Do NOT invent information. Only redistribute what exists in the original record.`;
 
   const subjects = data.subjects.map(s => ({
@@ -100,15 +99,6 @@ function buildExistingExamples(): string {
   "description": "Updated description with incorporated data"
 }
 
-Trait:
-{
-  "id": "existing-uuid",
-  "type": "trait",
-  "name": "Trait Name",
-  "description": "Updated trait description",
-  "strength": 0.7
-}
-
 Topic:
 {
   "id": "existing-uuid",
@@ -137,22 +127,13 @@ function buildNewExamples(): string {
   "sentiment": 0.0
 }
 
-Trait:
-{
-  "type": "trait",
-  "name": "New Trait Name",
-  "description": "Concise trait description",
-  "sentiment": 0.0,
-  "strength": 0.5
-}
-
 Topic:
 {
   "type": "topic",
   "name": "New Topic Name",
   "description": "Concise topic description",
   "sentiment": 0.0,
-  "category": "Interest"
+  "category": "Interest|Goal|Dream|Conflict|Concern|Fear|Hope|Plan|Project|Event"
 }
 
 Person:

package/src/prompts/ceremony/types.ts

@@ -1,4 +1,4 @@
-import type { Trait, PersonaTopic, DataItemBase } from "../../core/types.js";
+import type { PersonaTrait, PersonaTopic, DataItemBase } from "../../core/types.js";
 
 export interface PersonaExpirePromptData {
   persona_name: string;
@@ -11,7 +11,7 @@ export interface PersonaExpireResult {
 
 export interface PersonaExplorePromptData {
   persona_name: string;
-  traits: Trait[];
+  traits: PersonaTrait[];
   remaining_topics: PersonaTopic[];
   recent_conversation_themes: string[];
 }
@@ -32,7 +32,7 @@ export interface DescriptionCheckPromptData {
   persona_name: string;
   current_short_description?: string;
   current_long_description?: string;
-  traits: Trait[];
+  traits: PersonaTrait[];
   topics: PersonaTopic[];
 }
 

package/src/prompts/generation/descriptions.ts

@@ -1,7 +1,7 @@
 import type { PersonaDescriptionsPromptData, PromptOutput } from "./types.js";
-import type { Trait, PersonaTopic } from "../../core/types.js";
+import type { PersonaTrait, PersonaTopic } from "../../core/types.js";
 
-function formatTraitsForPrompt(traits: Trait[]): string {
+function formatTraitsForPrompt(traits: PersonaTrait[]): string {
   if (traits.length === 0) return "(No traits defined)";
   
   return traits.map(t => {

package/src/prompts/generation/types.ts

@@ -1,4 +1,4 @@
-import type { Trait, PersonaTopic } from "../../core/types.js";
+import type { PersonaTrait, PersonaTopic } from "../../core/types.js";
 
 export interface PromptOutput {
   system: string;
@@ -36,7 +36,7 @@ export interface PersonaGenerationResult {
 export interface PersonaDescriptionsPromptData {
   name: string;
   aliases: string[];
-  traits: Trait[];
+  traits: PersonaTrait[];
   topics: PersonaTopic[];
 }
 

package/src/prompts/heartbeat/types.ts

@@ -3,7 +3,7 @@
  * Based on CONTRACTS.md specifications
  */
 
-import type { Trait, Topic, Person, Message, PersonaTopic } from "../../core/types.js";
+import type { PersonaTrait, Topic, Person, Message, PersonaTopic } from "../../core/types.js";
 
 /**
  * Common prompt output structure
@@ -19,7 +19,7 @@ export interface PromptOutput {
 export interface HeartbeatCheckPromptData {
   persona: {
     name: string;
-    traits: Trait[];
+    traits: PersonaTrait[];
     topics: PersonaTopic[];
   };
   human: {

package/src/prompts/human/event-scan.ts

@@ -0,0 +1,122 @@
+import type { PromptOutput, ParticipantContext } from "./types.js";
+import type { Message } from "../../core/types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+function participantContextSection(ctx: ParticipantContext | undefined): string {
+  if (!ctx) return "";
+  const lines: string[] = ["# Participant Context", "The following may help you understand what themes and moments are meaningful in this conversation.", ""];
+  lines.push(`## Persona: ${ctx.persona_name}`);
+  if (ctx.persona_description) lines.push(ctx.persona_description);
+  lines.push("");
+  lines.push("## Human");
+  if (ctx.human_name) lines.push(`Name: ${ctx.human_name}`);
+  if (ctx.human_age !== undefined) lines.push(`Age: ${ctx.human_age}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+export interface EventScanPromptData {
+  persona_name: string;
+  messages_context: Message[];
+  messages_analyze: Message[];
+  window_start?: string;
+  window_end?: string;
+  participant_context?: ParticipantContext;
+}
+
+export function buildEventScanPrompt(data: EventScanPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildEventScanPrompt: persona_name is required");
+  }
+
+  const personaName = data.persona_name;
+
+  const system = `# Task
+
+You are scanning a conversation window to identify EPIC EVENTS worth preserving as long-term memories.
+
+An EPIC EVENT is a significant, bounded moment — something either participant would reference months later with recognition. Not a topic. Not a theme. A specific thing that happened.
+
+## The Test
+
+Ask yourself: "Would this moment get a section heading in a campaign recap document?"
+
+- "The Night We Debugged Beta's CPU" → YES
+- "First session with filesystem access" → YES
+- "The time the health check cached the API response forever" → YES
+- "We talked about AI" → NO (that's a Topic) return empty
+- "Flare asked some questions" → NO (too vague) return empty
+- Normal conversation without a notable arc → NO (not epic) return empty
+
+## What Makes an EPIC EVENT
+
+- A conflict encountered and (possibly) resolved
+- A discovery or breakthrough moment
+- A memorable failure or unexpected outcome
+- A significant "first" in the relationship
+- A pivotal decision or turning point
+- A moment either party would say "oh THAT session" about
+
+## What Is NOT an EPIC EVENT
+
+- Ongoing themes or interests (those are Topics)
+- Casual check-ins without a notable arc
+- Technical facts without a story around them
+- Anything that's already an ongoing trend rather than a bounded moment
+
+## Output Format
+
+\`\`\`json
+{
+  "events": [
+    {
+      "name": "Short evocative label (5-50 characters)",
+      "description": "1-2 sentences: what happened, why it mattered. Write it like a friend describing the moment to someone who wasn't there.",
+      "reason": "Evidence from the conversation — what made this rise to Epic Event level"
+    }
+  ]
+}
+\`\`\`
+
+Return an empty array if nothing qualifies. An empty array is the most common expected response.
+
+**Return JSON only. Be conservative. One memorable moment per window is the norm.**
+
+ONLY ANALYZE the "Most Recent Messages". The "Earlier Conversation" is provided for context only — it has already been processed.
+
+${participantContextSection(data.participant_context)}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation Window
+${earlierSection}${recentSection}
+
+---
+
+Scan this conversation window for EPIC EVENTS — specific, memorable moments worth preserving long-term.
+
+**Return JSON:**
+\`\`\`json
+{
+  "events": [
+    {
+      "name": "Short evocative label",
+      "description": "What happened and why it mattered",
+      "reason": "Evidence from the conversation"
+    }
+  ]
+}
+\`\`\`
+
+Return empty array if nothing qualifies. Be conservative.`;
+
+  return { system, user };
+}

package/src/prompts/human/fact-find.ts

@@ -0,0 +1,106 @@
+import type { FactFindPromptData, PromptOutput } from "./types.js";
+import { formatMessagesAsPlaceholders } from "../message-utils.js";
+
+export function buildFactFindPrompt(data: FactFindPromptData): PromptOutput {
+  if (!data.persona_name) {
+    throw new Error("buildFactFindPrompt: persona_name is required");
+  }
+  if (!data.missing_fact_names || data.missing_fact_names.length === 0) {
+    throw new Error("buildFactFindPrompt: missing_fact_names is required and must not be empty");
+  }
+
+  const personaName = data.persona_name;
+
+  const taskFragment = `# Task
+
+The system is missing some facts about the user. The user is not obligated to EVER provide ANY facts, so it is very likely that these facts are NOT present in this conversation. Your ONLY job is to search for EXPLICIT statements of fact for these SPECIFIC items, and return any matches in the provided JSON format.`;
+
+  const missingFactsFragment = `## Missing Facts
+
+The system is looking for the following facts:
+
+${data.missing_fact_names.map(name => `- ${name}`).join('\n')}
+
+Again - 99.99999% of the time, you will return no data — don't try to force it.`;
+
+  const guidelinesFragment = `# Guidelines
+
+1.  **Explicitness:**
+    *   **Focus only on what the user *explicitly states*.** Do not infer, assume, or guess based on context or general knowledge.
+    *   **Prioritize direct statements.** "I was born in 1985" is a fact. "I feel old now that it's 3030" isn't an explicit statement of their birth year.
+2.  **Objectivity and Verifiability:**
+    *   **Facts are objective and generally verifiable.** They are not subjective opinions, feelings, or temporary states.
+    *   **Focus on unchangeable or enduring attributes/events.**
+3.  **Specificity over Generality:**
+    *   If the user says "I live in a big city," do not extract "Current Location: big city." If they say "I live in New York," extract "Current Location: New York."
+4.  **Avoid Inference:**
+    *   If a user talks extensively about cooking, it's an interest, not a Fact like "Current Job Title: Chef" unless they explicitly state they ARE a chef.
+5.  **CRITICAL - Entity Attribution:**
+    *   ONLY extract facts about THE HUMAN USER THEMSELVES, not facts about other people they mention.
+    *   **Extract**: "I was born in 1984" → User's birthday
+    *   **Extract**: "I'm a software engineer" → User's job
+    *   **DO NOT Extract**: "My wife was a theater major" → This is about the wife, NOT the user
+    *   **DO NOT Extract**: "My daughter is 10 years old" → This is about the daughter, NOT the user
+    *   **DO NOT Extract**: "My brother lives in Texas" → This is about the brother, NOT the user
+    *   If the user shares information about someone else, that is NOT a fact about the user.`;
+
+  const criticalFragment = `# CRITICAL INSTRUCTIONS
+
+ONLY ANALYZE the "Most Recent Messages" in the following conversation. The "Earlier Conversation" is provided for your context and has already been processed!
+
+The JSON format is:
+
+\`\`\`json
+{
+  "facts": [
+    {
+      "name": "One of the missing fact names from above",
+      "value": "The exact value of the fact",
+      "evidence": "Direct quote or reference showing where this fact was stated"
+    }
+  ]
+}
+\`\`\`
+
+**Return JSON only.**`;
+
+  const system = `${taskFragment}
+
+${missingFactsFragment}
+
+${guidelinesFragment}
+
+${criticalFragment}`;
+
+  const earlierSection = data.messages_context.length > 0
+    ? `## Earlier Conversation
+${formatMessagesAsPlaceholders(data.messages_context, personaName)}
+
+`
+    : '';
+
+  const recentSection = `## Most Recent Messages
+${formatMessagesAsPlaceholders(data.messages_analyze, personaName)}`;
+
+  const user = `# Conversation
+${earlierSection}${recentSection}
+
+---
+
+Scan the "Most Recent Messages" for FACTS about the human user.
+
+**Return JSON:**
+\`\`\`json
+{
+  "facts": [
+    {
+      "name": "One of the missing fact names from above",
+      "value": "The exact value of the fact",
+      "evidence": "Direct quote or reference showing where this fact was stated"
+    }
+  ]
+}
+\`\`\``;
+
+  return { system, user };
+}

package/src/prompts/human/fact-scan.ts

@@ -75,8 +75,6 @@ Your job is to quickly identify:
 > They are details OF facts (e.g., { "type_of_fact": "Birthday", "value_of_fact": "August 15th" }).
 
 **FACTS ARE NOT**
-- Trait: Personality patterns, communication style, behavioral tendencies
-  - These are tracked separately
 - General Topic: Interests, hobbies, general subjects
   - These are tracked separately
 - Relationships: Wife, Husband, Daughter, Son, etc.

package/src/prompts/human/index.ts

@@ -1,32 +1,39 @@
 export { buildHumanFactScanPrompt } from "./fact-scan.js";
-export { buildHumanTraitScanPrompt } from "./trait-scan.js";
+export { buildFactFindPrompt } from "./fact-find.js";
 export { buildHumanTopicScanPrompt } from "./topic-scan.js";
 export { buildHumanPersonScanPrompt } from "./person-scan.js";
-export { buildHumanItemMatchPrompt } from "./item-match.js";
-export { buildHumanItemUpdatePrompt } from "./item-update.js";
+export { buildTopicMatchPrompt } from "./topic-match.js";
+export { buildTopicUpdatePrompt } from "./topic-update.js";
+export { buildPersonMatchPrompt } from "./person-match.js";
+export { buildPersonUpdatePrompt } from "./person-update.js";
+export { buildEventScanPrompt } from "./event-scan.js";
+export type { EventScanPromptData } from "./event-scan.js";
+
+export type { TopicMatchPromptData } from "./topic-match.js";
+export type { TopicUpdatePromptData } from "./topic-update.js";
+export type { PersonMatchPromptData } from "./person-match.js";
+export type { PersonUpdatePromptData } from "./person-update.js";
 
 export type {
   PromptOutput,
+  ParticipantContext,
   FactScanPromptData,
-  TraitScanPromptData,
   TopicScanPromptData,
   PersonScanPromptData,
+  FactFindPromptData,
   FactScanCandidate,
-  TraitScanCandidate,
   TopicScanCandidate,
   PersonScanCandidate,
   FactScanResult,
-  TraitScanResult,
+  FactFindResult,
   TopicScanResult,
   PersonScanResult,
-  ItemMatchPromptData,
+  EventScanCandidate,
+  EventScanResult,
   ItemMatchResult,
-  ItemUpdatePromptData,
   ExposureImpact,
   ItemUpdateResultBase,
   FactUpdateResult,
-  TraitUpdateResult,
-  TopicUpdateResult,
   PersonUpdateResult,
   ItemUpdateResult,
 } from "./types.js";