ei-tui 1.0.1 → 1.1.0

package/src/core/tools/index.ts

@@ -18,6 +18,77 @@ import { webFetchExecutor } from "./builtin/web-fetch.js";
 /** Hard upper limit on total tool calls per interaction, regardless of individual limits. */
 export const HARD_TOOL_CALL_LIMIT = 10;
 
+/**
+ * System tools — injected unconditionally into every LLM call that uses tools.
+ * NOT stored in state.json. NOT user-configurable. Do NOT count against HARD_TOOL_CALL_LIMIT.
+ * Enforce their own per-tool limits via max_calls_per_interaction.
+ */
+export const SYSTEM_TOOLS: ToolDefinition[] = [
+  {
+    id: "builtin-find-memory",
+    provider_id: "ei",
+    name: "find_memory",
+    display_name: "Find Memory",
+    description: "Semantic search of your personal memory — facts, topics, people, and quotes learned across ALL conversations over time, not just this one. Use when the human references something from the past, mentions a person, or asks about a topic you might have learned about. Supports optional filters: types (array of 'facts', 'topics', 'people', 'quotes'), limit (1-20, default 10), recent (true = sort by recency), persona (filter to what a specific persona has learned — use display name).",
+    input_schema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "What to search for" },
+        types: { type: "array", items: { type: "string", enum: ["facts", "topics", "people", "quotes"] }, description: "Filter to specific types" },
+        limit: { type: "number", description: "Max results (1-20, default 10)" },
+        recent: { type: "boolean", description: "Sort by most recently mentioned instead of relevance" },
+        persona: { type: "string", description: "Filter to what a specific persona has learned. Use their display name." },
+      },
+      required: ["query"],
+    },
+    runtime: "any",
+    builtin: true,
+    enabled: true,
+    created_at: new Date(0).toISOString(),
+    max_calls_per_interaction: 3,
+  },
+  {
+    id: "builtin-fetch-memory",
+    provider_id: "ei",
+    name: "fetch_memory",
+    display_name: "Fetch Memory",
+    description: "Retrieve the full record for a specific memory by its ID. Use when find_memory returns an item and you need its complete details, or when a system prompt references a memory ID. Returns the full Fact, Topic, Person, or Quote record.",
+    input_schema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The ID of the memory to retrieve" },
+      },
+      required: ["id"],
+    },
+    runtime: "any",
+    builtin: true,
+    enabled: true,
+    created_at: new Date(0).toISOString(),
+    max_calls_per_interaction: 3,
+  },
+  {
+    id: "builtin-fetch-message",
+    provider_id: "ei",
+    name: "fetch_message",
+    display_name: "Fetch Message",
+    description: "Retrieve a specific message by its ID, with optional surrounding context. Use when find_memory returns a quote with a message_id and you want to read the original conversation, or when a temporal anchor references a message ID. The 'before' and 'after' parameters return that many additional messages for context (default 0).",
+    input_schema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The message ID to retrieve" },
+        before: { type: "number", description: "Number of preceding messages to include for context (default 0)" },
+        after: { type: "number", description: "Number of following messages to include for context (default 0)" },
+      },
+      required: ["id"],
+    },
+    runtime: "any",
+    builtin: true,
+    enabled: true,
+    created_at: new Date(0).toISOString(),
+    max_calls_per_interaction: 5,
+  },
+];
+
 /** Default max calls per tool if not set on the ToolDefinition. */
 const DEFAULT_MAX_CALLS = 3;
 
@@ -32,7 +103,7 @@ export function registerExecutor(executor: ToolExecutor): void {
   executorRegistry.set(executor.name, executor);
 }
 
-// Register builtins. read_memory is registered lazily via registerReadMemoryExecutor()
+// Register builtins. find_memory is registered lazily via registerFindMemoryExecutor()
 // because it requires Processor.searchHumanData injection.
 registerExecutor(tavilyWebSearchExecutor);
 registerExecutor(tavilyNewsSearchExecutor);
@@ -42,10 +113,18 @@ registerExecutor(webFetchExecutor);
 // file_read and list_directory are registered lazily via registerFileReadExecutor() — Node/TUI only.
 
 /**
- * Register the read_memory executor — called by Processor after it's initialized,
+ * Register the find_memory executor — called by Processor after it's initialized,
  * injecting its own searchHumanData method to avoid circular imports.
  */
-export function registerReadMemoryExecutor(executor: ToolExecutor): void {
+export function registerFindMemoryExecutor(executor: ToolExecutor): void {
+  executorRegistry.set(executor.name, executor);
+}
+
+export function registerFetchMemoryExecutor(executor: ToolExecutor): void {
+  executorRegistry.set(executor.name, executor);
+}
+
+export function registerFetchMessageExecutor(executor: ToolExecutor): void {
   executorRegistry.set(executor.name, executor);
 }
 
@@ -122,7 +201,9 @@ export async function executeToolCalls(
   const toolsByName = new Map(tools.map(t => [t.name, t]));
 
   for (const call of calls) {
-    if (totalCalls.count >= HARD_TOOL_CALL_LIMIT) {
+    const isSystemTool = SYSTEM_TOOLS.some(t => t.name === call.name);
+
+    if (!isSystemTool && totalCalls.count >= HARD_TOOL_CALL_LIMIT) {
       console.log(`[Tools] Hard limit (${HARD_TOOL_CALL_LIMIT}) reached — skipping remaining tool calls`);
       break;
     }
@@ -168,7 +249,9 @@ export async function executeToolCalls(
     }
 
     callCounts.set(call.name, currentCount + 1);
-    totalCalls.count++;
+    if (!isSystemTool) {
+      totalCalls.count++;
+    }
 
     const newCount = currentCount + 1;
     if (newCount >= maxCalls) {

package/src/integrations/persona-history/importer.ts

@@ -3,6 +3,7 @@ import type { Message } from "../../core/types.js";
 import {
   queueTopicScan,
   queuePersonScan,
+  queueFactFind,
   type ExtractionContext,
 } from "../../core/orchestrators/human-extraction.js";
 
@@ -101,11 +102,12 @@ export async function importPersonaHistory(
     };
 
     const extractionModel = settings?.extraction_model;
+    queueFactFind(context, stateManager, { extraction_model: extractionModel });
     queueTopicScan(context, stateManager, { extraction_model: extractionModel });
     queuePersonScan(context, stateManager, { extraction_model: extractionModel });
 
     result.personasProcessed++;
-    result.scansQueued += 2;
+    result.scansQueued += 3;
   }
 
   for (const room of Object.values((stateManager.getStorageState() as any).rooms ?? {})) {

package/src/prompts/ceremony/dedup.ts

@@ -20,7 +20,7 @@ export function buildDedupPrompt(data: DedupPromptData): { system: string; user:
 You are working with Opus 4.6 constraints. These rules prevent overthinking and ensure decisive action:
 
 ### 1. TOOL BUDGET
-- You have **6 \`read_memory\` calls** for this cluster
+- You have **6 \`find_memory\` calls** for this cluster
 - Prioritize: verify ambiguous relationships > check parent concepts > validate new entities
 - After 6 calls, make decisions with available information
 - Do NOT waste calls re-checking pairs you already examined
@@ -55,7 +55,7 @@ You are acting as the curator for a user's internal database. You have been give
 
 Your secondary directive is to ORGANIZE IT into small, non-repetitive components. The user NEEDS the data, but the data is used by AI agents, so duplication limits usefulness—agents waste tokens re-reading the same information under different names.
 
-You have access to a tool called \`read_memory\` (6 calls max — see HARD RULES above). Use it strategically to verify relationships, check for related records, or gather context before making merge decisions.
+You have access to a tool called \`find_memory\` (6 calls max — see HARD RULES above). Use it strategically to verify relationships, check for related records, or gather context before making merge decisions.
 
 ### Decision Process:
 1. **Identify true duplicates**: Examine each record. Are these genuinely the same thing with different wording (85%+ core meaning overlap), or are they distinct but related concepts?
@@ -94,7 +94,7 @@ ${buildRecordFormatExamples(data.itemType)}
 - Every removed record MUST have "replaced_by" pointing to the canonical record that absorbed its data.
 - The "update" array should contain AT LEAST ONE record (the canonical/merged one), even if all others are removed.
 - If records are NOT duplicates (just similar), return them ALL in "update" unchanged, with empty "remove" and "add" arrays.
-- Use \`read_memory\` strategically (6 calls max) to check for related records or gather context before making irreversible merge decisions.`;
+- Use \`find_memory\` strategically (6 calls max) to check for related records or gather context before making irreversible merge decisions.`;
 
   const payload = JSON.stringify({
     cluster: data.cluster.map(stripEmbedding),

package/src/prompts/ceremony/types.ts

@@ -15,7 +15,7 @@ export interface RewriteScanPromptData {
 /** Phase 1 output: array of subject strings (parsed from LLM JSON response). */
 export type RewriteScanResult = string[];
 
-/** A single subject and the read_memory matches found for it. */
+/** A single subject and the find_memory matches found for it. */
 export interface RewriteSubjectMatch {
   searchTerm: string;
   matches: DataItemBase[];  // Top 3 from searchHumanData, may be empty

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

@@ -93,6 +93,19 @@ If you are unsure of the type, use \`Nickname\` as a fallback. Do NOT invent typ
 
 Only include \`identifiers\` when explicitly mentioned in the conversation — omit it entirely if nothing qualifies.
 
+## Confidence & Relationship Type
+
+For each person, rate how important they are to the human user's life:
+
+- \`confidence\`: integer 1–5
+  - 1–2 = mentioned in passing, single event, no ongoing relevance
+  - 3 = unclear significance — may matter, may not
+  - 4–5 = clearly important, recurring presence, meaningful relationship
+- \`relationship_type\`: one of \`"family"\` | \`"friend"\` | \`"colleague"\` | \`"acquaintance"\` | \`"transactional"\` | \`"unknown"\`
+  - Use \`"transactional"\` when the person appeared only in the context of a single transaction (purchase, sale, support ticket, delivery)
+
+Use the full range. Most extractions should score 1–3. A confidence of 4–5 means this person genuinely matters to the user's life.
+
 ## Output Format
 
 \`\`\`json
@@ -105,6 +118,8 @@ Only include \`identifiers\` when explicitly mentioned in the conversation — o
       ],
       "description": "1-2 sentences: who this person is and their role in the user's life",
       "relationship": "Father|Mother|Brother|Son|Friend|Coworker|Self|etc.",
+      "relationship_type": "family|friend|colleague|acquaintance|transactional|unknown",
+      "confidence": 4,
       "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]
@@ -143,6 +158,8 @@ Scan the "Most Recent Messages" for PEOPLE in the human user's life.
       "identifiers": [{ "type": "GitHub", "value": "handle" }],
       "description": "1-2 sentences: who this person is and their role in the user's life",
       "relationship": "Father|Mother|Brother|Son|Friend|Coworker|Self|etc.",
+      "relationship_type": "family|friend|colleague|acquaintance|transactional|unknown",
+      "confidence": 4,
       "reason": "Evidence from the conversation that justified flagging this person"
     }
   ]

package/src/prompts/human/types.ts

@@ -55,11 +55,15 @@ export interface TopicScanCandidate {
   reason: string;
 }
 
+export type PersonRelationshipType = "family" | "friend" | "colleague" | "acquaintance" | "transactional" | "unknown";
+
 export interface PersonScanCandidate {
   name: string;
   identifiers?: Array<{ type: string; value: string; is_primary?: boolean }>;
   description: string;
   relationship: string;
+  relationship_type?: PersonRelationshipType;
+  confidence?: number;
   reason: string;
 }
 

package/src/prompts/response/sections.ts

@@ -464,21 +464,28 @@ export function buildTemporalAnchorsSection(anchors: TemporalAnchor[], humanName
 
   const formatted = anchors.map(a => {
     const speaker = a.role === "human" ? humanName : "You";
-    let text: string;
-    if (a._synthesis && a.content) {
-      text = `[${humanName} used your conversation to generate an image. The full prompt was: "${a.content}"]`;
+    let preview: string;
+    if (a._synthesis) {
+      const raw = a.content ?? "";
+      const firstSentenceEnd = raw.search(/\.\s/);
+      const snippet = firstSentenceEnd > 0 && firstSentenceEnd <= 120
+        ? raw.slice(0, firstSentenceEnd + 1)
+        : raw.slice(0, 100);
+      preview = `[${humanName} generated an image: "${snippet}…"]`;
     } else if (a.silence_reason) {
       const silentParty = a.role === "human" ? humanName : "You";
-      text = `${silentParty} chose not to respond because: ${a.silence_reason}`;
+      const truncated = a.silence_reason.length > 80 ? `${a.silence_reason.slice(0, 80)}…` : a.silence_reason;
+      preview = `${silentParty} chose not to respond: "${truncated}"`;
     } else {
-      text = a.content ?? "";
+      const raw = a.content ?? "";
+      preview = raw.length > 80 ? `${raw.slice(0, 80)}…` : raw;
     }
-    return `[${formatTimestamp(a.timestamp)}] ${speaker}: ${text}`;
+    return `[${formatTimestamp(a.timestamp)}] ${speaker}: ${preview}\n  → fetch_message("${a.id}") for full content`;
   }).join("\n\n");
 
   return `## Temporal Anchors
 
-These are pinned moments from your shared history — preserved across context windows as part of who you are:
+Pinned moments from your shared history. These are snapshots — use fetch_message(id) if one feels relevant to pull the full memory:
 
 ${formatted}`;
 }

package/src/prompts/response/types.ts

@@ -8,6 +8,7 @@ import type { ToolDefinition } from "../../core/types.js";
 import type { PersonaEntity } from "../../core/types/entities.js";
 
 export interface TemporalAnchor {
+  id: string;
   role: "human" | "system";
   content?: string;
   silence_reason?: string;

package/src/core/tools/builtin/read-memory.ts

@@ -1,70 +0,0 @@
-import type { ToolExecutor } from "../types.js";
-import type { Fact, Topic, Person, Quote } from "../../types.js";
-
-interface PersonaSummary {
-  id: string;
-  display_name: string;
-}
-
-type SearchHumanData = (
-  query: string,
-  options?: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean; persona_filter?: string }
-) => Promise<{ facts: Fact[]; topics: Topic[]; people: Person[]; quotes: Quote[] }>;
-
-type GetPersonaList = () => Promise<PersonaSummary[]>;
-
-export function createReadMemoryExecutor(searchHumanData: SearchHumanData, getPersonaList?: GetPersonaList): ToolExecutor {
-  return {
-    name: "read_memory",
-
-    async execute(args: Record<string, unknown>): Promise<string> {
-      const query = typeof args.query === "string" ? args.query.trim() : "";
-      const recent = args.recent === true;
-      const personaArg = typeof args.persona === "string" ? args.persona.trim() : "";
-      console.log(`[read_memory] called with query="${query}", types=${JSON.stringify(args.types ?? null)}, limit=${args.limit ?? 10}, recent=${recent}, persona="${personaArg}"`);
-
-      if (!query && !recent) {
-        console.warn("[read_memory] missing query argument");
-        return JSON.stringify({ error: "Missing required argument: query (or use recent: true)" });
-      }
-
-      const types = Array.isArray(args.types)
-        ? (args.types.filter(
-            t => typeof t === "string" && ["fact", "topic", "person", "quote"].includes(t)
-          ) as Array<"fact" | "topic" | "person" | "quote">)
-        : undefined;
-
-      const limit = typeof args.limit === "number" && args.limit > 0 ? Math.min(args.limit, 20) : 10;
-
-      // Resolve persona display_name to ID
-      let persona_filter: string | undefined;
-      if (personaArg && getPersonaList) {
-        const personas = await getPersonaList();
-        const match = personas.find(p => p.display_name.toLowerCase() === personaArg.toLowerCase());
-        if (match) {
-          persona_filter = match.id;
-          console.log(`[read_memory] resolved persona "${personaArg}" to ID "${persona_filter}"`);
-        } else {
-          console.warn(`[read_memory] persona "${personaArg}" not found, proceeding without filter`);
-        }
-      }
-
-      const results = await searchHumanData(query, { types, limit, recent, persona_filter });
-
-      const total = results.facts.length + results.topics.length + results.people.length + results.quotes.length;
-      console.log(`[read_memory] query="${query}" => ${total} results (facts=${results.facts.length}, topics=${results.topics.length}, people=${results.people.length}, quotes=${results.quotes.length})`);
-
-      const output: Record<string, unknown[]> = {};
-      if (results.facts.length > 0) output.facts = results.facts.map(f => ({ name: f.name, description: f.description }));
-      if (results.topics.length > 0) output.topics = results.topics.map(t => ({ name: t.name, description: t.description }));
-      if (results.people.length > 0) output.people = results.people.map(p => ({ name: p.name, relationship: p.relationship, description: p.description, identifiers: p.identifiers ?? [] }));
-      if (results.quotes.length > 0) output.quotes = results.quotes.map(q => ({ text: q.text, speaker: q.speaker }));
-
-      if (Object.keys(output).length === 0) {
-        return JSON.stringify({ result: "No relevant memories found for this query." });
-      }
-
-      return JSON.stringify(output);
-    },
-  };
-}