ei-tui 1.4.0 → 1.5.0

package/package.json

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

package/src/cli/README.md

@@ -37,7 +37,7 @@ ei --id "claudecode:my-machine:session-uuid:message-uuid"
 ei --id "cursor:my-machine:composer-uuid:bubble-uuid"
 ```
 
-Quotes surfaced by `ei_search` or `ei_find_memory` include a `message_id` field in this format — pipe it to `ei --id` to read the original conversation.
+Quotes surfaced by `ei_search` include a `message_id` field in this format — pipe it to `ei --id` to read the original conversation.
 
 # OpenCode Integration
 
@@ -47,12 +47,15 @@ Quotes surfaced by `ei_search` or `ei_find_memory` include a `message_id` field
 ei --install
 ```
 
-This registers Ei with Claude Code and Cursor via MCP:
+This registers Ei with Claude Code, Cursor, and OpenCode — MCP server config **and** context injection hooks so agents get Ei memory automatically without needing to call a tool:
 
-- **Claude Code**: writes `~/.claude.json` with an MCP server entry
-- **Cursor**: writes `~/.cursor/mcp.json` with an MCP server entry
+| Tool | MCP | Context Hook |
+|------|-----|-------------|
+| **Claude Code** | `~/.claude.json` | `~/.claude/settings.json` (`UserPromptSubmit`) + `~/.claude/hooks/ei-inject.ts` |
+| **Cursor** | `~/.cursor/mcp.json` | `~/.cursor/hooks.json` (`beforeSubmitPrompt`) + `~/.cursor/hooks/ei-inject.sh` |
+| **OpenCode** | manual (see below) | Detected automatically via Oh My OpenCode compatibility layer (reads `~/.claude/settings.json`) |
 
-**OpenCode**: add the MCP server manually to `~/.config/opencode/opencode.jsonc`:
+**OpenCode MCP**: add manually to `~/.config/opencode/opencode.jsonc`:
 
 ```json
 {
@@ -81,28 +84,20 @@ ei mcp
 
 ## Activating Ei in Your Agent
 
-`ei --install` handles the technical wiring. This step tells your agent *when* and *how* to reach for it.
+`ei --install` handles both the technical wiring **and** context injection. After running it, your agent will automatically receive recent Ei memory before every message — no tool calls required.
 
-Without this, your agent has Ei available but may never call it. Add a snippet to your tool's config and it'll start querying Ei at the start of each session — and whenever you reference past context.
+The snippets below are optional manual overrides if you want to customize the behavior or add targeted mid-session queries.
 
 ### OpenCode
 
-Add to `~/.config/opencode/AGENTS.md` (applies to all projects):
+If you're using [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode), the `UserPromptSubmit` hook installed by `ei --install` is picked up automatically via its Claude Code compatibility layer — no additional config needed.
+
+If you're running vanilla OpenCode without Oh My OpenCode, add to `~/.config/opencode/AGENTS.md`:
 
 ```markdown
-At session start, query Ei for user context:
-
-\```bash
-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, personas. Use it when the user references past work, mentions how they like things done,
-asks "how did we do X," or needs to look up a person by any name, handle, or account (GitHub username,
-Discord handle, email, nickname, etc.) — people results include an `identifiers` array covering all
-known accounts and aliases for that person. 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.
+Use the **ei** MCP to pull user context when the user references past work, mentions people
+or preferences, or asks "how did we do X." Call `ei_search` with a natural-language query.
+Use `ei --persona "Beta" "topic"` to scope results to what a specific persona has learned.
 ```
 
 ### Claude Code
@@ -149,9 +144,8 @@ conversations (facts, people, topics, quotes, personas).
 
 **How to use:**
 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 human entity (fact, topic, person, quote), call `ei_fetch_memory` with the entity `id`.
-3. If you need full detail for a result including personas, call `ei_lookup` with the entity `id` from step 1.
-4. To fetch a specific message with surrounding context, call `ei_fetch_message` with the message `id` and optional `before`/`after` counts.
+2. If you need the full record for any result, call `ei_lookup` with the entity `id` from step 1 — works for all types including personas.
+3. If a quote result has a `message_id`, call `ei_fetch_message` with that ID and optional `before`/`after` counts to read the original conversation with context.
 
 Prefer querying Ei before asking the user for context they may have already shared.
 ```
@@ -162,20 +156,18 @@ The MCP server exposes these tools to Claude Code, Cursor, and OpenCode:
 
 | Tool | Description |
 |------|-------------|
-| `ei_search` | Balanced search across all five data types (facts, topics, people, quotes, personas). Supports `type`, `persona`, `source`, `recent`, `limit` filters. |
-| `ei_lookup` | Full-record lookup for any entity by ID (facts, topics, people, quotes, personas). |
-| `ei_find_memory` | Grouped human-data search — facts, topics, people, quotes. Returns results grouped by type. Mirrors the persona `find_memory` tool interface. |
-| `ei_fetch_memory` | Full-record lookup for a human entity (Fact, Topic, Person, or Quote) by ID. Returns the complete record including all fields. |
-| `ei_fetch_message` | Retrieve a specific message by fully-qualified ID with optional `before`/`after` context window. Routes to the correct source: `ei:uuid` searches Ei state, `opencode:machine:session:id` queries the OpenCode SQLite DB, `claudecode:...` scans Claude Code JSONL files, `cursor:...` reads the Cursor global DB. Returns message content, surrounding context, and session metadata. |
+| `ei_search` | Search across all five data types (facts, topics, people, quotes, personas). Supports `type`, `persona`, `source`, `recent`, `limit` filters. Start here. |
+| `ei_lookup` | Full-record lookup for any entity by ID — facts, topics, people, quotes, or personas. Use when you need complete details beyond the search summary. |
+| `ei_fetch_message` | Retrieve a specific message by fully-qualified ID with optional `before`/`after` context window. Use when a quote result has a `message_id` and you want the original conversation. Routes to the correct source automatically. |
 
-### `ei_search` / `ei_find_memory` arguments
+### `ei_search` arguments
 
 | Arg | Type | Description |
 |-----|------|-------------|
 | `query` | string (optional) | Search text. Omit to browse by recency. |
+| `type` | enum (optional) | `facts` \| `people` \| `topics` \| `quotes` \| `personas` — omit for balanced results across all types |
 | `persona` | string (optional) | Persona display_name to scope results to what that persona has learned |
-| `type` | enum (optional, `ei_search` only) | `facts` \| `people` \| `topics` \| `quotes` \| `personas` — omit for balanced results |
-| `types` | array (optional, `ei_find_memory` only) | `["facts", "topics", "people", "quotes"]` — omit for all human types |
+| `source` | string (optional) | Prefix match against source identifiers (e.g. `opencode`, `cursor:my-machine`) |
 | `limit` | number (optional) | Max results, default 10 |
 | `recent` | boolean (optional) | Sort by most recently mentioned instead of relevance |
 
@@ -187,7 +179,7 @@ All search commands return arrays. Each result includes a `type` field.
 
 **Person**: `{ type, id, name, description, relationship, sentiment, identifiers[] }` — `identifiers` contains all known accounts and aliases (e.g. `{ type: "GitHub", value: "flare576" }`)
 
-**Quote**: `{ type, id, text, speaker, timestamp, linked_items[] }`
+**Quote**: `{ type, text, speaker, message_id, timestamp, linked_items[] }` — note: `id` is intentionally omitted; use `message_id` with `ei_fetch_message` to retrieve the original conversation
 
 **Persona**: `{ type, id, display_name, short_description, model, base_prompt, traits[], topics[] }`
 

package/src/cli/mcp.ts

@@ -18,7 +18,7 @@ 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, 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).",
+        "Search the user's Ei knowledge base — a persistent memory store built from conversations. Use at session start to load user context, and mid-session whenever the user references past work, preferences, or people. Returns facts, people, topics of interest, quotes, and personas. TYPE GUIDANCE: 'facts' are ONLY user demographics (name, age, job title, location, family structure, physical traits). For interests, opinions, hobbies, or anything the human cares about, use 'topics'. For named individuals, use 'people'. For verbatim things said, use 'quotes'. For AI agent identities with traits and working style, use '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 — use type='personas' with the persona's name OR a natural-language description of their role to load a persona's character sheet. Results include entity IDs that can be passed to ei_lookup for full detail. Omit query with recent=true to browse the most recently discussed items.",
       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
@@ -99,7 +99,7 @@ export function createMcpServer(): McpServer {
     "ei_lookup",
     {
       description:
-        "Look up a specific entity in the Ei knowledge base by ID. Returns the full entity record. Use IDs from ei_search results.",
+        "Retrieve the full record for any Ei entity by ID — facts, topics, people, quotes, or personas. Use when ei_search returns an item and you need its complete details (all fields, traits, topics, identifiers, etc.). Pass the entity id from ei_search results.",
       inputSchema: {
         id: z.string().describe("The entity ID to look up."),
         source: z
@@ -130,131 +130,11 @@ export function createMcpServer(): McpServer {
     }
   );
 
-  server.registerTool(
-    "ei_find_memory",
-    {
-      description:
-        "Search Ei's persistent knowledge base — facts, topics, people, and quotes learned across ALL conversations over time. Use when you need context about the user, their life, relationships, or interests that may not be visible in the current exchange. Returns results grouped by type. Use `recent: true` to retrieve what's been discussed recently. TYPE GUIDANCE: 'facts' are ONLY user demographics — name, age, job title, location, family structure, physical traits. For interests, opinions, hobbies, or anything the human cares about, use 'topics'. For named individuals, use 'people'. For verbatim things said, use 'quotes'.",
-      inputSchema: {
-        query: z
-          .string()
-          .optional()
-          .describe(
-            "What to search for — a person, topic, fact, or anything Ei has learned about the user. Omit with recent: true to browse recent items."
-          ),
-        types: z
-          .array(z.enum(["facts", "topics", "people", "quotes"]))
-          .optional()
-          .describe("Limit search to specific memory types (default: all types). Use 'facts' ONLY for user demographics (name, age, job, location, family). Use 'topics' for interests, opinions, and anything the human cares about."),
-        limit: z
-          .number()
-          .optional()
-          .default(10)
-          .describe("Max results per type to return (default: 10, max: 20)"),
-        recent: z
-          .boolean()
-          .optional()
-          .describe(
-            "If true, return recently-mentioned results sorted by last_mentioned date instead of relevance. Combine with a query to filter recent results by topic."
-          ),
-        persona: z
-          .string()
-          .optional()
-          .describe(
-            "Filter results to what a specific persona has learned. Use the persona display name."
-          ),
-      },
-    },
-    async ({ query: rawQuery, types, limit, recent, persona }) => {
-      const query = rawQuery ?? "";
-      const effectiveLimit = Math.min(limit ?? 10, 20);
-      const options = { recent: recent ?? false };
-
-      const humanTypes = ["facts", "topics", "people", "quotes"] as const;
-      type HumanType = (typeof humanTypes)[number];
-      const requestedTypes: HumanType[] =
-        types && types.length > 0
-          ? (types as HumanType[])
-          : [...humanTypes];
-
-      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.` }],
-            };
-          }
-        }
-      }
-
-      const grouped: Record<string, unknown[]> = {};
-      for (const t of requestedTypes) {
-        const module = await import(`./commands/${t}.js`);
-        let results = await (
-          module.execute as (
-            q: string,
-            l: number,
-            o: { recent: boolean }
-          ) => Promise<{ id: string }[]>
-        )(query, effectiveLimit, options);
-        if (personaId && state) {
-          results = filterTypeSpecificByPersona(results, state, personaId, t);
-        }
-        if (results.length > 0) {
-          grouped[t] = results;
-        }
-      }
-
-      if (Object.keys(grouped).length === 0) {
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({ result: "No relevant memories found for this query." }),
-            },
-          ],
-        };
-      }
-
-      return {
-        content: [{ type: "text" as const, text: JSON.stringify(grouped, null, 2) }],
-      };
-    }
-  );
-
-  server.registerTool(
-    "ei_fetch_memory",
-    {
-      description:
-        "Retrieve the full record for a specific memory by its ID. Use when ei_find_memory or ei_search returns an item and you need its complete details. Returns the full Fact, Topic, Person, or Quote record.",
-      inputSchema: {
-        id: z.string().describe("The ID of the memory record to retrieve"),
-      },
-    },
-    async ({ id }) => {
-      const result = await lookupById(id);
-
-      if (result === null || result.type === "persona") {
-        return {
-          content: [{ type: "text" as const, text: `No memory record found with ID: ${id}` }],
-        };
-      }
-
-      return {
-        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
-      };
-    }
-  );
-
   server.registerTool(
     "ei_fetch_message",
     {
       description:
-        "Retrieve a specific message by its ID, with optional surrounding context. Use when ei_find_memory returns a quote with a message_id and you want to read the original conversation. The 'before' and 'after' parameters return that many additional messages for context (default 0).",
+        "Retrieve a specific message by its fully-qualified ID, with optional surrounding conversation context. Use when ei_search returns a quote with a message_id and you want to read the original exchange. The 'before' and 'after' parameters expand the context window in either direction (default 0). Accepts IDs from any integrated source: 'ei:uuid' searches Ei state, 'opencode:machine:session:id' queries OpenCode SQLite, 'claudecode:...' scans Claude Code JSONL files, 'cursor:...' reads the Cursor DB.",
       inputSchema: {
         id: z.string().describe("The ID of the message to retrieve"),
         before: z

package/src/cli/retrieval.ts

@@ -84,7 +84,6 @@ export interface LinkedItem {
   type: string;
 }
 export interface QuoteResult {
-  id: string;
   text: string;
   speaker: string;
   timestamp: string;
@@ -163,7 +162,6 @@ export function resolveLinkedItems(dataItemIds: string[], state: StorageState):
 }
 export function mapQuote(quote: Quote, state: StorageState): QuoteResult {
   return {
-    id: quote.id,
     text: quote.text,
     speaker: quote.speaker,
     timestamp: quote.timestamp,
@@ -287,16 +285,11 @@ 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 | PersonaResult }> = [
+    const allItems: Array<{ type: DataType; item: AnyItem; mapped: QuoteResult | FactResult | PersonResult | TopicResult }> = [
       ...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)))
@@ -330,22 +323,10 @@ export async function retrieveBalanced(
         }
       }
     }
-    const embeddingResults = allScored
+    return 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 }),
-      ...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),
-        ...embeddingResults,
-      ];
-      return combined.slice(0, limit);
-    }
-    return embeddingResults;
   }
 
   for (const { type, items, mapper } of typeConfigs) {
@@ -383,19 +364,7 @@ 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),
-    ...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),
-      ...embeddingFinal,
-    ];
-    return combined.slice(0, limit);
-  }
-  return embeddingFinal;
+  return result.map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
 }
 
 const OPENCODE_MESSAGE_ID = /^msg_[a-zA-Z0-9]+$/;