ei-tui 0.4.2 → 0.5.0

package/README.md

@@ -58,6 +58,20 @@ A "Persona" is the combination of these two pieces of data, plus some _personali
 
 > <sup>1</sup>: By default. You can make them static.
 
+## What's a Room?
+
+Rooms let you throw multiple personas into the same conversation thread. Chaos ensues. Or collaboration. Sometimes both.
+
+Three modes, set at creation:
+
+**Free For All (FFA)**: Everyone talks. Every message gets a response from every persona. It's loud. Good for brainstorming or when you want a bunch of perspectives on the same thing.
+
+**Choose Your Path (CYP)**: The conversation branches. Each message triggers responses from all personas, but you pick which one continues the thread. Fork in the road, every turn. You're the navigator.
+
+**Messages Against Persona (MAP)**: The interesting one. Everyone submits a response, but a Judge persona picks which one actually shows up. The personas have to stay in character and compete for the Judge's approval. The human doesn't have to play by the rules. It's partly a game of "who knows this judge best?" and partly just fun to watch them try.
+
+Rooms learn the same way persona conversations do. Quotes, topics, people — all get extracted and persisted. The knowledge base grows no matter which mode you're in.
+
 ## The Basics
 
 Ei can operate with three types of input, and three types of output.

package/package.json

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

package/src/cli/README.md

@@ -5,18 +5,21 @@
 ei                             # Start the TUI
 ei "query string"              # Return up to 10 results across all types
 ei -n 5 "query string"         # Return up to 5 results
-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 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 personas -n 5 "query string"   # Return up to 5 personas (name match)
 ei --persona "Beta" "query string"    # Filter results to what Beta has learned
+ei --recent                            # Most recently mentioned items (no query needed)
+ei --persona "Beta" --recent           # Most recently mentioned items 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
 ei mcp                         # Start the Ei MCP stdio server (for Cursor/Claude Desktop)
 ```
 
-Type aliases: `fact`, `person`, `topic`, `quote` all work (singular or plural).
+Type aliases: `fact`, `person`, `topic`, `quote`, `persona` all work (singular or plural).
 
 # An Agentic Tool
 
@@ -68,9 +71,10 @@ 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." 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.
+people, topics, personas. Use it when the user references past work, mentions how they like things done,
+or asks "how did we do X." Use `ei --persona "Beta" "walruses"` to scope results to what a specific
+persona has learned. Use `ei personas "name"` to find personas by name. Query again mid-session when
+they correct you or reference something from a previous session.
 ```
 
 ### Claude Code
@@ -81,6 +85,7 @@ Add to `~/.claude/CLAUDE.md` (user-level) or `CLAUDE.md` at project root:
 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 `type: "personas"` to search for personas by name.
 
 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
@@ -99,7 +104,7 @@ alwaysApply: true
 # Ei MCP — User knowledge base
 
 The **ei** MCP (server `user-ei`) is a persistent knowledge base built from the user's
-conversations (facts, people, topics, quotes).
+conversations (facts, people, topics, quotes, personas).
 
 **Use it when:**
 - The user refers to past decisions, fixes, or "how we did X" and current chat/codebase
@@ -110,8 +115,7 @@ conversations (facts, people, topics, quotes).
   than only code.
 
 **How to use:**
-1. Call `ei_search` (server `user-ei`) with a natural-language query; optionally filter by
-   `type` (facts, people, topics, quotes) or `persona` display_name.
+1. Call `ei_search` (server `user-ei`) with a natural-language query (or omit query and use `recent: true` to browse); optionally filter by `type` (facts, people, topics, quotes, personas) 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.
@@ -119,15 +123,16 @@ Prefer querying Ei before asking the user for context they may have already shar
 
 ## What the Tool Provides
 
-The installed tool gives OpenCode agents access to all four data types with proper Zod-validated args:
+The installed tool gives OpenCode agents access to all five data types with proper Zod-validated args:
 
 | Arg | Type | Description |
 |-----|------|-------------|
-| `query` | string (required) | Search text, or entity ID when `lookup=true` |
+| `query` | string (optional) | Search text, or entity ID when `lookup=true`. Omit to browse by recency. |
 | `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 |
+| `type` | enum (optional) | `facts` \| `people` \| `topics` \| `quotes` \| `personas` — omit for balanced results |
 | `limit` | number (optional) | Max results, default 10 |
 | `lookup` | boolean (optional) | If true, fetch single entity by ID |
+| `recent` | boolean (optional) | If true, sort by most recently mentioned. Can be combined with `persona` or `query`. |
 
 ## Output Shapes
 
@@ -137,4 +142,6 @@ All search commands return arrays. Each result includes a `type` field.
 
 **Quote**: `{ type, id, text, speaker, timestamp, linked_items[] }`
 
+**Persona**: `{ type, id, display_name, short_description, model, base_prompt, traits[], topics[] }`
+
 **ID lookup** (`lookup: true`): single object (not an array) with the same shape.

package/src/cli/commands/personas.ts

@@ -0,0 +1,12 @@
+import { loadLatestState, retrievePersonas } from "../retrieval";
+import type { PersonaResult } from "../retrieval";
+
+export async function execute(query: string, limit: number, options: { recent?: boolean } = {}): Promise<PersonaResult[]> {
+  const state = await loadLatestState();
+  if (!state) {
+    console.error("No saved state found. Is EI_DATA_PATH set correctly?");
+    return [];
+  }
+
+  return retrievePersonas(query, state, limit, options);
+}

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. Results include entity IDs that can be passed back to ei_lookup for full detail.",
+        "Search the user's Ei knowledge base — a persistent memory store built from conversations. Returns facts, people, topics of interest, and quotes. 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().describe("Search text. Supports natural language."),
+        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"])
+          .enum(["facts", "people", "topics", "quotes", "personas"])
           .optional()
           .describe(
-            "Filter to a specific data type. Omit to search all types (balanced across all 4)."
+            "Filter to a specific data type. Omit to search all types (balanced across all 5)."
           ),
         persona: z
           .string()
@@ -42,7 +42,8 @@ export function createMcpServer(): McpServer {
           .describe("If true, sort by most recently mentioned."),
       },
     },
-    async ({ query, type, persona, limit, recent }) => {
+    async ({ query: rawQuery, type, persona, limit, recent }) => {
+      const query = rawQuery ?? "";
       const options = { recent: recent ?? false };
       const effectiveLimit = limit ?? 10;
 

package/src/cli/retrieval.ts

@@ -1,4 +1,6 @@
 import type { StorageState, Quote, Fact, Person, Topic } from "../core/types";
+import type { PersonaEntity } from "../core/types/entities.js";
+import type { PersonaTrait, PersonaTopic } from "../core/types/data-items.js";
 import { decodeAllEmbeddings } from "../storage/embeddings";
 import { crossFind } from "../core/utils/index.ts";
 import { join } from "path";
@@ -110,19 +112,30 @@ export interface TopicResult {
   sentiment: number;
 }
 
+export interface PersonaResult {
+  id: string;
+  display_name: string;
+  short_description?: string;
+  model?: string;
+  base_prompt: string;
+  traits: PersonaTrait[];
+  topics: PersonaTopic[];
+}
+
 export type BalancedResult =
   | ({ type: "quote" } & QuoteResult)
   | ({ type: "fact" } & FactResult)
   | ({ type: "person" } & PersonResult)
-  | ({ type: "topic" } & TopicResult);
+  | ({ type: "topic" } & TopicResult)
+  | ({ type: "persona" } & PersonaResult);
 
-const DATA_TYPES = ["quote", "fact", "person", "topic"] as const;
+const DATA_TYPES = ["quote", "fact", "person", "topic", "persona"] as const;
 type DataType = typeof DATA_TYPES[number];
 
 interface ScoredEntry {
   type: DataType;
   similarity: number;
-  mapped: QuoteResult | FactResult | PersonResult | TopicResult;
+  mapped: QuoteResult | FactResult | PersonResult | TopicResult | PersonaResult;
   itemId: string;
 }
 
@@ -182,6 +195,46 @@ function mapTopic(topic: Topic): TopicResult {
   };
 }
 
+export function mapPersona(persona: PersonaEntity): PersonaResult {
+  return {
+    id: persona.id,
+    display_name: persona.display_name,
+    short_description: persona.short_description,
+    model: persona.model,
+    base_prompt: persona.long_description ?? "",
+    traits: persona.traits,
+    topics: persona.topics,
+  };
+}
+
+export function retrievePersonas(
+  query: string,
+  state: StorageState,
+  limit: number = 10,
+  options: { recent?: boolean } = {}
+): PersonaResult[] {
+  const { recent } = options;
+  const personaList = Object.values(state.personas).map((p) => p.entity);
+
+  if (recent && !query) {
+    return personaList
+      .sort((a, b) => b.last_updated.localeCompare(a.last_updated))
+      .slice(0, limit)
+      .map(mapPersona);
+  }
+
+  if (!query) {
+    return [];
+  }
+
+  const q = query.toLowerCase();
+  return personaList
+    .filter((p) => p.display_name.toLowerCase().includes(q))
+    .sort((a, b) => b.last_updated.localeCompare(a.last_updated))
+    .slice(0, limit)
+    .map(mapPersona);
+}
+
 export async function retrieveBalanced(
   query: string,
   limit: number = 10,
@@ -199,11 +252,16 @@ export async function retrieveBalanced(
   const recentDate = (item: AnyItem): string => item.last_mentioned ?? item.last_updated ?? "";
 
   if (recent && !query) {
-    const allItems: Array<{ type: DataType; item: AnyItem; mapped: QuoteResult | FactResult | PersonResult | TopicResult }> = [
+    const allItems: Array<{ type: DataType; item: AnyItem; mapped: QuoteResult | FactResult | PersonResult | TopicResult | PersonaResult }> = [
       ...state.human.quotes.map(q => ({ type: "quote" as DataType, item: q as AnyItem, mapped: mapQuote(q, state) })),
       ...state.human.facts.map(f => ({ type: "fact" as DataType, item: f as AnyItem, mapped: mapFact(f) })),
       ...state.human.people.map(p => ({ type: "person" as DataType, item: p as AnyItem, mapped: mapPerson(p) })),
       ...state.human.topics.map(t => ({ type: "topic" as DataType, item: t as AnyItem, mapped: mapTopic(t) })),
+      ...Object.values(state.personas).map(({ entity: p }) => ({
+        type: "persona" as DataType,
+        item: { id: p.id, last_updated: p.last_updated } as AnyItem,
+        mapped: mapPersona(p),
+      })),
     ];
     return allItems
       .sort((a, b) => recentDate(b.item).localeCompare(recentDate(a.item)))
@@ -237,10 +295,19 @@ export async function retrieveBalanced(
         }
       }
     }
-    return allScored
+    const embeddingResults = allScored
       .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 });
+    if (personaMatches.length > 0) {
+      const combined = [
+        ...personaMatches.map((p) => ({ type: "persona" as const, ...p }) as BalancedResult),
+        ...embeddingResults,
+      ];
+      return combined.slice(0, limit);
+    }
+    return embeddingResults;
   }
 
   for (const { type, items, mapper } of typeConfigs) {
@@ -278,7 +345,16 @@ export async function retrieveBalanced(
 
   result.sort((a, b) => b.similarity - a.similarity);
 
-  return result.map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
+  const embeddingFinal = result.map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
+  const personaFinal = retrievePersonas(query, state, limit);
+  if (personaFinal.length > 0) {
+    const combined = [
+      ...personaFinal.map((p) => ({ type: "persona" as const, ...p }) as BalancedResult),
+      ...embeddingFinal,
+    ];
+    return combined.slice(0, limit);
+  }
+  return embeddingFinal;
 }
 
 export async function lookupById(id: string): Promise<({ type: string } & Record<string, unknown>) | null> {
@@ -289,6 +365,8 @@ export async function lookupById(id: string): Promise<({ type: string } & Record
 
   const found = crossFind(id, state.human);
   if (!found) return null;
-  const { type, embedding, ...rest } = found;
-  return { type, ...rest };
+  const { type, ...rest } = found;
+  const withoutEmbedding = { ...rest } as Record<string, unknown>;
+  delete withoutEmbedding.embedding;
+  return { type, ...withoutEmbedding };
 }

package/src/cli.ts

@@ -26,6 +26,8 @@ const TYPE_ALIASES: Record<string, string> = {
   people: "people",
   topic: "topics",
   topics: "topics",
+  persona: "personas",
+  personas: "personas",
 };
 
 function printHelp(): void {
@@ -47,10 +49,11 @@ Usage:
   ei mcp                        Start the Ei MCP stdio server (for Cursor/Claude Desktop)
 
 Types:
-  quote / quotes    Quotes from conversation history
-  fact / facts      Facts about the user
-  person / people   People from the user's life
-  topic / topics    Topics of interest
+  quote / quotes      Quotes from conversation history
+  fact / facts        Facts about the user
+  person / people     People from the user's life
+  topic / topics      Topics of interest
+  persona / personas  Personas in this Ei instance
 
 Options:
   --number, -n     Maximum number of results (default: 10)
@@ -84,11 +87,11 @@ function buildOpenCodeToolContent(): string {
     '    "Results include entity IDs that can be passed back with lookup=true to get full detail.",',
     '  ].join(" "),',
     '  args: {',
-    '    query: tool.schema.string().describe(',
-    '      "Search text, or an entity ID when lookup=true. Supports natural language."',
+    '    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"])',
+    '      .enum(["facts", "people", "topics", "quotes", "personas"])',
     '      .optional()',
     '      .describe(',
     '        "Filter to a specific data type. Omit to search all types (balanced across all 4).",',
@@ -112,16 +115,23 @@ function buildOpenCodeToolContent(): string {
     '      .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);',
+    '      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));',
-    '      cmd.push(args.query);',
+    '      if (args.query) cmd.push(args.query);',
     '    }',
     '    return Bun.$`${cmd}`.text();',
     '  },',
@@ -312,18 +322,10 @@ 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;
+  // Default to recent mode when no query — allows `ei --persona Foo` and `ei` with no args
+  const recent = parsed.values.recent === true || !query;
   const personaName = parsed.values.persona?.trim();
 
-  if (!query && !recent) {
-    if (targetType) {
-      console.error(`Search text required. Usage: ei ${targetType} "search text"`);
-    } else {
-      console.error(`Search text required. Usage: ei "search text"`);
-    }
-    process.exit(1);
-  }
-
   if (isNaN(limit) || limit < 1) {
     console.error("--number must be a positive integer");
     process.exit(1);

package/src/core/constants/seed-traits.ts

@@ -0,0 +1,29 @@
+export interface SeedTrait {
+  name: string;
+  description: string;
+  sentiment: number;
+  strength: number;
+}
+
+export const SEED_TRAIT_GENUINE: SeedTrait = {
+  name: "Genuine Responses",
+  description: "Respond authentically rather than with empty validation. Disagree when appropriate. Skip phrases like 'Great question!' or 'Absolutely!' - just respond to the substance.",
+  sentiment: 0.5,
+  strength: 0.7,
+};
+
+export const SEED_TRAIT_NATURAL_SPEECH: SeedTrait = {
+  name: "Natural Speech",
+  description: `Write in natural conversational flow. Avoid AI-typical patterns like:
+- Choppy dramatic fragments ('Bold move. Risky play.')
+- Rhetorical 'That X? Y.' structures
+- 'That's not just... That's ...'
+- formulaic paragraph openers`,
+  sentiment: 0.5,
+  strength: 0.7,
+};
+
+export const DEFAULT_SEED_TRAITS: SeedTrait[] = [
+  SEED_TRAIT_GENUINE,
+  SEED_TRAIT_NATURAL_SPEECH,
+];

package/src/core/context-utils.ts

@@ -17,6 +17,7 @@ export function filterMessagesForContext(
   const boundaryMs = contextBoundary ? new Date(contextBoundary).getTime() : 0;
 
   return messages.filter((msg) => {
+    if (msg.external === true) return false;
     if (msg.context_status === ContextStatusEnum.Always) return true;
     if (msg.context_status === ContextStatusEnum.Never) return false;
 

package/src/core/format-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared timestamp formatter for all LLM-facing date/time strings.
+ * Consistent format across system prompt, quotes, and message history
+ * so models can trivially compute time deltas.
+ */
+const TIMESTAMP_FORMAT: Intl.DateTimeFormatOptions = {
+  weekday: 'short',
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+  hour12: false,
+  timeZoneName: 'short',
+};
+
+export function formatTimestamp(isoString: string): string {
+  return new Date(isoString).toLocaleString('en-US', TIMESTAMP_FORMAT);
+}
+
+export function formatCurrentTime(): string {
+  return formatTimestamp(new Date().toISOString());
+}