ei-tui 0.3.5 → 0.3.7

package/README.md

@@ -124,7 +124,7 @@ Personas can use tools. Not just read-from-memory tools — *actual* tools. Web
 
 | Tool | What it does |
 |------|-------------|
-| `read_memory` | Semantic search of your personal memory — facts, traits, topics, people, quotes. Personas call this automatically when the conversation touches something they might know about you. |
+| `read_memory` | Semantic search of your personal memory — facts, traits, topics, people, quotes. Personas call this automatically when the conversation touches something they might know about you. Supports the `persona` filter to scope results to what a specific persona has learned. |
 | `file_read` | Read a file from your local filesystem *(TUI only)* |
 | `list_directory` | Explore folder structure *(TUI only)* |
 | `directory_tree` | Recursive directory tree *(TUI only)* |
@@ -188,11 +188,21 @@ Without this setting, browser security policies will block API calls.
 
 ## Development
 
+To run the full test suite on a new machine:
+
 ```bash
+nvm install 20
+nvm use 20
+npm install
+cd web && npm install && npx playwright install && cd ..
+cd tui
+bun install
+npm install
+npm rebuild   # compile native PTY module for Node 20 (one-time, new machine only)
+cd ..
+nvm use default
 npm install
-npm run dev      # Watch mode
-npm run build    # Compile TypeScript
-npm run test     # Run tests
+npm run test:all
 ```
 
 ## Releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "author": "Flare576",
   "repository": {
     "type": "git",

package/src/cli/README.md

@@ -9,6 +9,7 @@ ei facts -n 5 "query string"   # Return up to 5 facts
 ei people -n 5 "query string"  # Return up to 5 people
 ei topics -n 5 "query string"  # Return up to 5 topics
 ei quotes -n 5 "query string"  # Return up to 5 quotes
+ei --persona "Beta" "query string"    # Filter results to what Beta has learned
 ei --id <id>                   # Look up a specific entity by ID
 echo <id> | ei --id            # Look up entity by ID from stdin
 ei --install                   # Register Ei with OpenCode, Claude Code, and Cursor
@@ -68,7 +69,7 @@ ei "What are the user's current preferences, active projects, and workflow?"
 
 Ei is a persistent knowledge base built from the user's conversations — facts, preferences,
 people, topics. Use it when the user references past work, mentions how they like things done,
-or asks "how did we do X." Query again mid-session when they correct you or reference something
+or asks "how did we do X." Use `ei --persona "Beta" "walruses"` to scope results to what a specific persona has learned. Query again mid-session when they correct you or reference something
 from a previous session.
 ```
 
@@ -79,6 +80,7 @@ Add to `~/.claude/CLAUDE.md` (user-level) or `CLAUDE.md` at project root:
 ```markdown
 At session start, use the **ei** MCP to pull user context: call `ei_search` with a
 natural-language query about the user's preferences, active projects, and workflow.
+A `persona` filter is available to scope results to what a specific persona has learned.
 
 Use Ei when the user references past decisions, mentions people or preferences, or asks
 "how did we do X." Query again when they correct you or reference something from a previous
@@ -109,7 +111,7 @@ conversations (facts, people, topics, quotes).
 
 **How to use:**
 1. Call `ei_search` (server `user-ei`) with a natural-language query; optionally filter by
-   `type`: facts, people, topics, quotes.
+   `type` (facts, people, topics, quotes) or `persona` display_name.
 2. If you need full detail for a result, call `ei_lookup` with the entity `id` from step 1.
 
 Prefer querying Ei before asking the user for context they may have already shared.
@@ -122,6 +124,7 @@ The installed tool gives OpenCode agents access to all four data types with prop
 | Arg | Type | Description |
 |-----|------|-------------|
 | `query` | string (required) | Search text, or entity ID when `lookup=true` |
+| `persona` | string (optional) | Persona display_name to filter results — only returns entities that persona has extracted |
 | `type` | enum (optional) | `facts` \| `people` \| `topics` \| `quotes` — omit for balanced results |
 | `limit` | number (optional) | Max results, default 10 |
 | `lookup` | boolean (optional) | If true, fetch single entity by ID |

package/src/cli/mcp.ts

@@ -1,7 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { retrieveBalanced, lookupById } from "./retrieval.js";
+import { retrieveBalanced, lookupById, loadLatestState, type BalancedResult } from "./retrieval.js";
+import type { StorageState } from "../core/types/index.js";
+import { resolvePersonaId, filterByPersona, filterTypeSpecificByPersona } from "./persona-filter.js";
 
 // Exported so tests can inject their own transport
 export function createMcpServer(): McpServer {
@@ -23,6 +25,12 @@ export function createMcpServer(): McpServer {
           .describe(
             "Filter to a specific data type. Omit to search all types (balanced across all 4)."
           ),
+        persona: z
+          .string()
+          .optional()
+          .describe(
+            "Filter to entities a specific persona has learned about. Use the persona display name."
+          ),
         limit: z
           .number()
           .optional()
@@ -34,16 +42,36 @@ export function createMcpServer(): McpServer {
           .describe("If true, sort by most recently mentioned."),
       },
     },
-    async ({ query, type, limit, recent }) => {
+    async ({ query, type, persona, limit, recent }) => {
       const options = { recent: recent ?? false };
       const effectiveLimit = limit ?? 10;
 
+      let state: StorageState | null = null;
+      let personaId: string | undefined;
+      if (persona) {
+        state = await loadLatestState();
+        if (state) {
+          personaId = resolvePersonaId(state, persona) ?? undefined;
+          if (!personaId) {
+            return {
+              content: [{ type: "text" as const, text: `Persona "${persona}" not found.` }],
+            };
+          }
+        }
+      }
+
       let result: unknown;
       if (type) {
         const module = await import(`./commands/${type}.js`);
         result = await (module.execute as (q: string, l: number, o: { recent: boolean }) => Promise<unknown>)(query, effectiveLimit, options);
+        if (personaId && state) {
+          result = filterTypeSpecificByPersona(result as { id: string }[], state, personaId, type);
+        }
       } else {
         result = await retrieveBalanced(query, effectiveLimit, options);
+        if (personaId && state) {
+          result = filterByPersona(result as BalancedResult[], state, personaId);
+        }
       }
 
       return {

package/src/cli/persona-filter.ts

@@ -0,0 +1,54 @@
+import type { StorageState } from "../core/types/index.js";
+import type { BalancedResult } from "./retrieval.js";
+
+export function resolvePersonaId(state: StorageState, name: string): string | null {
+  const lowerName = name.toLowerCase();
+  for (const { entity } of Object.values(state.personas)) {
+    if (entity.display_name.toLowerCase() === lowerName) {
+      return entity.id;
+    }
+  }
+  return null;
+}
+
+export function filterByPersona(results: BalancedResult[], state: StorageState, personaId: string): BalancedResult[] {
+  return results.filter((result) => {
+    if (result.type === "quote") {
+      return false;
+    }
+    const { id } = result;
+    let original: { interested_personas?: string[] } | undefined;
+    if (result.type === "fact") {
+      original = state.human.facts.find((f) => f.id === id);
+    } else if (result.type === "topic") {
+      original = state.human.topics.find((t) => t.id === id);
+    } else if (result.type === "person") {
+      original = state.human.people.find((p) => p.id === id);
+    }
+    return original?.interested_personas?.includes(personaId) ?? false;
+  });
+}
+
+export function filterTypeSpecificByPersona<T extends { id: string }>(
+  results: T[],
+  state: StorageState,
+  personaId: string,
+  targetType: string
+): T[] {
+  if (targetType === "quotes") {
+    return [];
+  }
+  const collection =
+    targetType === "facts"
+      ? state.human.facts
+      : targetType === "topics"
+        ? state.human.topics
+        : targetType === "people"
+          ? state.human.people
+          : null;
+  if (!collection) return results;
+  return results.filter((r) => {
+    const original = collection.find((item) => item.id === r.id) as { interested_personas?: string[] } | undefined;
+    return original?.interested_personas?.includes(personaId) ?? false;
+  });
+}

package/src/cli.ts

@@ -13,7 +13,9 @@
 
 import { parseArgs } from "util";
 import { join } from "path";
-import { retrieveBalanced, lookupById } from "./cli/retrieval";
+import { retrieveBalanced, lookupById, loadLatestState } from "./cli/retrieval";
+import type { StorageState } from "./core/types";
+import { resolvePersonaId, filterByPersona, filterTypeSpecificByPersona } from "./cli/persona-filter.js";
 
 const TYPE_ALIASES: Record<string, string> = {
   quote: "quotes",
@@ -39,6 +41,7 @@ Usage:
   ei --recent                   Return most recently mentioned items
   ei --recent "query"           Filter recent items by query
   ei <type> --recent "query"    Type-specific recent search
+  ei --persona "Name" "query"   Filter results to what a persona has learned
   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)
@@ -52,6 +55,7 @@ Types:
 Options:
   --number, -n     Maximum number of results (default: 10)
   --recent, -r     Sort by last_mentioned date (most recent first)
+  --persona, -p    Filter to entities a specific persona has learned about
   --id             Look up entity by ID (accepts value or stdin)
   --install        Register Ei with OpenCode, Claude Code, and Cursor
   --help, -h       Show this help message
@@ -62,6 +66,7 @@ Examples:
   ei quote "you guessed it"              # Search quotes only
   ei --recent                            # Most recently mentioned items
   ei topics --recent "work"              # Recent work-related topics
+  ei --persona "Architect" "work stuff"  # What Architect knows about work
   ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
 `);
@@ -88,6 +93,12 @@ function buildOpenCodeToolContent(): string {
     '      .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()',
@@ -108,6 +119,7 @@ function buildOpenCodeToolContent(): string {
     '      cmd.push("--id", args.query);',
     '    } else {',
     '      if (args.type) cmd.push(args.type);',
+    '      if (args.persona) cmd.push("--persona", args.persona);',
     '      if (args.limit && args.limit !== 10) cmd.push("-n", String(args.limit));',
     '      cmd.push(args.query);',
     '    }',
@@ -292,6 +304,7 @@ async function main(): Promise<void> {
       options: {
         number: { type: "string", short: "n" },
         recent: { type: "boolean", short: "r" },
+        persona: { type: "string", short: "p" },
         help: { type: "boolean", short: "h" },
       },
       allowPositionals: true,
@@ -310,6 +323,7 @@ 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;
+  const personaName = parsed.values.persona?.trim();
 
   if (!query && !recent) {
     if (targetType) {
@@ -325,14 +339,35 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  let state: StorageState | null = null;
+  let personaId: string | undefined;
+  if (personaName) {
+    state = await loadLatestState();
+    if (!state) {
+      console.error("No saved state found. Is EI_DATA_PATH set correctly?");
+      process.exit(1);
+    }
+    personaId = resolvePersonaId(state, personaName) ?? undefined;
+    if (!personaId) {
+      console.error(`Persona "${personaName}" not found.`);
+      process.exit(1);
+    }
+  }
+
   const options = { recent };
 
   let result;
   if (targetType) {
     const module = await import(`./cli/commands/${targetType}.js`);
     result = await module.execute(query, limit, options);
+    if (personaId && state) {
+      result = filterTypeSpecificByPersona(result, state, personaId, targetType);
+    }
   } else {
     result = await retrieveBalanced(query, limit, options);
+    if (personaId && state) {
+      result = filterByPersona(result, state, personaId);
+    }
   }
 
   console.log(JSON.stringify(result, null, 2));

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

@@ -72,6 +72,7 @@ export async function handleFactFind(response: LLMResponse, state: StateManager)
       last_mentioned: now,
       learned_by: existingFact.learned_by ?? context.personaId,
       last_changed_by: context.personaId,
+      interested_personas: [...new Set([...(existingFact.interested_personas ?? []), context.personaId])],
       embedding,
     };
 

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

@@ -165,6 +165,9 @@ export async function handleTopicUpdate(response: LLMResponse, state: StateManag
     last_mentioned: now,
     learned_by: isNewItem ? personaId : existingTopic?.learned_by,
     last_changed_by: personaId,
+    interested_personas: isNewItem
+      ? [personaId]
+      : [...new Set([...(existingTopic?.interested_personas ?? []), personaId])],
     persona_groups: mergeGroups(personaGroup, isNewItem, existingTopic?.persona_groups),
     embedding,
   };
@@ -232,6 +235,9 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
     last_mentioned: now,
     learned_by: isNewItem ? personaId : existingPerson?.learned_by,
     last_changed_by: personaId,
+    interested_personas: isNewItem
+      ? [personaId]
+      : [...new Set([...(existingPerson?.interested_personas ?? []), personaId])],
     persona_groups: mergeGroups(personaGroup, isNewItem, existingPerson?.persona_groups),
     embedding,
   };

package/src/core/handlers/rewrite.ts

@@ -36,7 +36,15 @@ export async function handleRewriteScan(response: LLMResponse, state: StateManag
 
   const subjects = response.parsed as RewriteScanResult | undefined;
   if (!subjects || !Array.isArray(subjects) || subjects.length === 0) {
-    console.log(`[handleRewriteScan] No extra subjects found for ${itemType} "${itemId}" — item is cohesive`);
+    console.log(`[handleRewriteScan] No extra subjects found for ${itemType} "${itemId}" — marking rewrite_checked`);
+    const human = state.getHuman();
+    if (itemType === "topic") {
+      const topic = human.topics.find(t => t.id === itemId);
+      if (topic) state.human_topic_upsert({ ...topic, rewrite_checked: true });
+    } else if (itemType === "person") {
+      const person = human.people.find(p => p.id === itemId);
+      if (person) state.human_person_upsert({ ...person, rewrite_checked: true });
+    }
     return;
   }
 
@@ -246,5 +254,14 @@ export async function handleRewriteRewrite(response: LLMResponse, state: StateMa
     newCount++;
   }
 
+  const updatedHuman = state.getHuman();
+  if (itemType === "topic") {
+    const original = updatedHuman.topics.find(t => t.id === itemId);
+    if (original) state.human_topic_upsert({ ...original, rewrite_checked: true });
+  } else if (itemType === "person") {
+    const original = updatedHuman.people.find(p => p.id === itemId);
+    if (original) state.human_person_upsert({ ...original, rewrite_checked: true });
+  }
+
   console.log(`[handleRewriteRewrite] Complete for ${itemType} "${itemId}": ${existingCount} existing updated, ${newCount} new created`);
 }

package/src/core/human-data-manager.ts

@@ -145,14 +145,14 @@ export async function getQuotesForMessage(sm: StateManager, messageId: string):
 export async function searchHumanData(
   sm: StateManager,
   query: string,
-  options: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean } = {}
+  options: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean; persona_filter?: string } = {}
 ): Promise<{
   facts: Fact[];
   topics: Topic[];
   people: Person[];
   quotes: Quote[];
 }> {
-  const { types = ["fact", "topic", "person", "quote"], limit = 10, recent } = options;
+  const { types = ["fact", "topic", "person", "quote"], limit = 10, recent, persona_filter } = options;
   const human = sm.getHuman();
   const SIMILARITY_THRESHOLD = 0.3;
 
@@ -214,18 +214,30 @@ export async function searchHumanData(
   };
 
   if (types.includes("fact")) {
-    result.facts = searchItems(human.facts, (f) => `${f.name} ${f.description || ""}`).map(
+    let facts = human.facts;
+    if (persona_filter) {
+      facts = facts.filter(f => f.interested_personas?.includes(persona_filter));
+    }
+    result.facts = searchItems(facts, (f) => `${f.name} ${f.description || ""}`).map(
       stripDataItemEmbedding
     );
   }
   if (types.includes("topic")) {
-    result.topics = searchItems(human.topics, (t) => `${t.name} ${t.description || ""}`).map(
+    let topics = human.topics;
+    if (persona_filter) {
+      topics = topics.filter(t => t.interested_personas?.includes(persona_filter));
+    }
+    result.topics = searchItems(topics, (t) => `${t.name} ${t.description || ""}`).map(
       stripDataItemEmbedding
     );
   }
   if (types.includes("person")) {
+    let people = human.people;
+    if (persona_filter) {
+      people = people.filter(p => p.interested_personas?.includes(persona_filter));
+    }
     result.people = searchItems(
-      human.people,
+      people,
       (p) => `${p.name} ${p.description || ""} ${p.relationship}`
     ).map(stripDataItemEmbedding);
   }

package/src/core/orchestrators/ceremony.ts

@@ -617,12 +617,12 @@ export function queueRewritePhase(state: StateManager): void {
   const itemsToScan: Array<{ item: DataItemBase; type: RewriteItemType }> = [];
 
   for (const topic of human.topics) {
-    if ((topic.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD) {
+    if ((topic.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD && !topic.rewrite_checked) {
       itemsToScan.push({ item: topic, type: "topic" });
     }
   }
   for (const person of human.people) {
-    if ((person.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD) {
+    if ((person.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD && !person.rewrite_checked) {
       itemsToScan.push({ item: person, type: "person" });
     }
   }

package/src/core/processor.ts

@@ -203,7 +203,7 @@ export class Processor {
     this.bootstrapTools();
     this.seedBuiltinFacts();
     this.seedSettings();
-    registerReadMemoryExecutor(createReadMemoryExecutor(this.searchHumanData.bind(this)));
+    registerReadMemoryExecutor(createReadMemoryExecutor(this.searchHumanData.bind(this), this.getPersonaList.bind(this)));
     if (this.isTUI) {
       await registerFileReadExecutor();
     }
@@ -1485,7 +1485,7 @@ const toolNextSteps = new Set([
 
   async searchHumanData(
     query: string,
-    options: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean } = {}
+    options: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean; persona_filter?: string } = {}
   ): Promise<{
     facts: Fact[];
     topics: Topic[];

package/src/core/state-manager.ts

@@ -46,6 +46,7 @@ export class StateManager {
       this.migrateLearnedByToIds();
       this.migrateFactValidation();
       this.migrateMessageFlags();
+      this.migrateInterestedPersonas();
     } else {
       this.humanState.load(createDefaultHumanEntity());
     }
@@ -191,6 +192,29 @@ export class StateManager {
     }
   }
 
+  /**
+   * Migration: interested_personas was added to DataItemBase.
+   * On load, backfill from learned_by + last_changed_by for any item missing the field.
+   */
+  private migrateInterestedPersonas(): void {
+    const human = this.humanState.get();
+    let dirty = false;
+
+    const migrateItem = (item: { learned_by?: string; last_changed_by?: string; interested_personas?: string[] }) => {
+      if (item.interested_personas === undefined || item.interested_personas === null) {
+        item.interested_personas = [...new Set([item.learned_by, item.last_changed_by].filter(Boolean) as string[])];
+        dirty = true;
+      }
+    };
+
+    [...human.facts, ...human.topics, ...human.people].forEach(migrateItem);
+
+    if (dirty) {
+      this.humanState.set(human);
+      console.log("[StateManager] Migrated interested_personas fields from learned_by + last_changed_by");
+    }
+  }
+
   /**
    * Returns true if value looks like a persona ID (UUID or the special "ei" id).
    * Display names are free-form strings that won't match UUID format.

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

@@ -1,19 +1,27 @@
 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 }
+  options?: { types?: Array<"fact" | "topic" | "person" | "quote">; limit?: number; recent?: boolean; persona_filter?: string }
 ) => Promise<{ facts: Fact[]; topics: Topic[]; people: Person[]; quotes: Quote[] }>;
 
-export function createReadMemoryExecutor(searchHumanData: SearchHumanData): ToolExecutor {
+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;
-      console.log(`[read_memory] called with query="${query}", types=${JSON.stringify(args.types ?? null)}, limit=${args.limit ?? 10}, recent=${recent}`);
+      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");
@@ -28,7 +36,20 @@ export function createReadMemoryExecutor(searchHumanData: SearchHumanData): Tool
 
       const limit = typeof args.limit === "number" && args.limit > 0 ? Math.min(args.limit, 20) : 10;
 
-      const results = await searchHumanData(query, { types, limit, recent });
+      // 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})`);

package/src/core/types/data-items.ts

@@ -13,8 +13,10 @@ export interface DataItemBase {
   last_mentioned?: string;        // Set by extraction only, never ceremony. Used for --recent sorting.
   learned_by?: string;           // Persona ID that originally learned this item (stable UUID)
   last_changed_by?: string;      // Persona ID that most recently updated this item (stable UUID)
+  interested_personas?: string[]; // Persona IDs that have extracted/touched this item (accumulated)
   persona_groups?: string[];
   embedding?: number[];
+  rewrite_checked?: boolean;     // True after rewrite scan finds no changes. Cleared automatically when extraction upserts a fresh item.
 }
 
 export interface Fact extends DataItemBase {