ei-tui 1.4.1 → 1.6.0

package/README.md

@@ -6,7 +6,7 @@ You can access the Web version at [ei.flare576.com](https://ei.flare576.com).
 
 You can run the local version via `bunx ei-tui` — no install needed, always current (see [### TUI](#tui) for details).
 
-If you're here to give your coding tools (OpenCode, Claude Code, Cursor) persistent memory, jump over to [TUI README.md](./tui/README.md) to learn how to get information _into_ Ei, and [CLI README.md](./src/cli/README.md) to get it back _out_.
+If you're here to give your coding tools (OpenCode, Claude Code, Cursor) persistent memory, jump over to [TUI README.md](./tui/README.md) to learn how to get information _into_ Ei, and [CLI README.md](./src/cli/README.md) to wire up automatic context injection so your agents receive relevant memory before every message — no tool calls required.
 
 ## What Does "Local First" Mean?
 
@@ -140,7 +140,7 @@ opencode:
 
 OpenCode saves sessions as JSON or SQLite (depending on version). Ei reads them, extracts context per-agent (each agent like Sisyphus gets its own persona), and keeps everything current as sessions accumulate.
 
-OpenCode can also *read* Ei's knowledge back out via the [CLI tool](src/cli/README.md) — making it a dynamic, perpetual RAG. That's why it always has context from your other projects.
+OpenCode can also *read* Ei's knowledge back out via the [CLI tool](src/cli/README.md). Run `ei --install` to wire up automatic context injection — relevant topics are injected before every message, and (with [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode)) each agent's Ei persona record is loaded into the system prompt at session start. The agent knows who it is *to you* before it reads your first message.
 
 #### Claude Code
 

package/package.json

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

package/src/cli/README.md

@@ -15,7 +15,7 @@ ei --recent                            # Most recently mentioned items (no query
 ei --persona "Beta" --recent           # Most recently mentioned items Beta has learned
 ei --id <id>                   # Look up entity by ID — or fetch a message by FQ ID
 echo <id> | ei --id            # Look up entity by ID from stdin
-ei --install                   # Register Ei with OpenCode, Claude Code, and Cursor
+ei --install                   # Wire Ei into Claude Code, Cursor, and OpenCode (MCP + hooks + persona plugin)
 ei mcp                         # Start the Ei MCP stdio server (for Cursor/Claude Desktop)
 ```
 
@@ -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,19 @@ 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, context injection hooks, and (for OpenCode) a persona identity plugin so agents know who they are before the first message:
 
-- **Claude Code**: writes `~/.claude.json` with an MCP server entry
-- **Cursor**: writes `~/.cursor/mcp.json` with an MCP server entry
+| Tool | MCP | Context Hook | Persona Plugin |
+|------|-----|-------------|----------------|
+| **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) | Via Oh My OpenCode compatibility layer (reads `~/.claude/settings.json`) | `~/.config/opencode/plugins/ei-persona.ts` |
 
-**OpenCode**: add the MCP server manually to `~/.config/opencode/opencode.jsonc`:
+**Context hook**: fires before every message, searches Ei for topics relevant to what you just asked, injects them silently. No tool call required.
+
+**Persona plugin** (OpenCode + [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode) only): injects the agent's Ei relationship record directly into the system prompt at session start — traits, working style, shared context. The agent knows who it is *to you* before it reads a word of your message.
+
+**OpenCode MCP**: add manually to `~/.config/opencode/opencode.jsonc`:
 
 ```json
 {
@@ -79,82 +86,14 @@ Claude Code and Cursor call `ei mcp` to start the MCP stdio server. You can run
 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.
-
-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.
-
-### OpenCode
-
-Add to `~/.config/opencode/AGENTS.md` (applies to all projects):
-
-```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.
-```
-
-### Claude Code
+## How Automatic Context Injection Works
 
-Add to `~/.claude/CLAUDE.md` (user-level) or `CLAUDE.md` at project root:
+After `ei --install`, agents receive Ei context without any manual tool calls:
 
-```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 `type: "personas"` to search for personas by name.
+1. **Before each message** — the hook searches Ei using your prompt + recent conversation history as the query, then injects relevant topics into the conversation as `[Ei Memory Context]`. You won't see this in your chat view; the agent does.
+2. **At session start** (OpenCode + OMO only) — the persona plugin finds the agent's Ei persona record and appends it to the system prompt as `<ei-relationship>`. The agent knows its working style, traits, and shared history with you before the session begins.
 
-Use Ei when the user references past decisions, mentions people or preferences, asks
-"how did we do X," or needs to look up a person by any name, handle, or account — people
-results include an `identifiers` array (GitHub username, Discord handle, email, nickname, etc.)
-covering all known accounts and aliases. Query again when they correct you or reference
-something from a previous session.
-```
-
-### Cursor
-
-Create `.cursor/rules/ei-mcp.mdc` in your project (or `~/.cursor/rules/` for user-level):
-
-```markdown
----
-description: When to use the Ei MCP for user memory and context
-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, personas).
-
-**Use it when:**
-- The user refers to past decisions, fixes, or "how we did X" and current chat/codebase
-  doesn't have that context.
-- You need the user's preferences, contacts, or project conventions (e.g. who to ask for
-  access, how something was fixed).
-- You need to look up a person by any name, handle, or account — people results include an
-  `identifiers` array (GitHub username, Discord handle, email, nickname, etc.) covering all
-  known accounts and aliases for that person.
-- The question is about the user personally (people, workflow, prior discussions) rather
-  than only code.
-
-**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.
-
-Prefer querying Ei before asking the user for context they may have already shared.
-```
+The `ei_search`, `ei_lookup`, and `ei_fetch_message` MCP tools are still available for targeted mid-session queries — use them when you want to look something up explicitly.
 
 ## MCP Tools Reference
 
@@ -162,20 +101,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 +124,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]+$/;