ei-tui 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "author": "Flare576",
   "repository": {
     "type": "git",
@@ -58,6 +58,7 @@
   },
   "type": "module",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentui/core": "^0.1.79",
     "@opentui/solid": "^0.1.79",
     "fastembed": "^2.1.0",

package/src/cli/README.md

@@ -11,7 +11,8 @@ ei topics -n 5 "query string"  # Return up to 5 topics
 ei quotes -n 5 "query string"  # Return up to 5 quotes
 ei --id <id>                   # Look up a specific entity by ID
 echo <id> | ei --id            # Look up entity by ID from stdin
-ei --install                   # Install the Ei tool for OpenCode
+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).
@@ -32,7 +33,87 @@ ei "memory leak" | jq '.[0].id' | ei --id
 ei --install
 ```
 
-This writes `~/.config/opencode/tools/ei.ts` with a complete tool definition. Restart OpenCode to activate.
+This registers Ei with every supported agent environment it detects:
+
+- **OpenCode**: writes `~/.config/opencode/tools/ei.ts`
+- **Claude Code**: runs `claude mcp add` (or writes `~/.claude.json` as fallback)
+- **Cursor**: writes `~/.cursor/mcp.json`
+
+Restart your agent tool after running to activate.
+
+### MCP Server
+
+Claude Code and Cursor call `ei mcp` to start the MCP stdio server. You can run it directly to test:
+
+```sh
+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. 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
+from a previous session.
+```
+
+### Claude Code
+
+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.
+
+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
+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).
+
+**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).
+- 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; optionally filter by
+   `type`: facts, people, topics, quotes.
+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.
+```
 
 ## What the Tool Provides
 

package/src/cli/commands/facts.ts

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

package/src/cli/commands/people.ts

@@ -1,7 +1,7 @@
 import { loadLatestState, retrieve } from "../retrieval";
 import type { PersonResult } from "../retrieval";
 
-export async function execute(query: string, limit: number): Promise<PersonResult[]> {
+export async function execute(query: string, limit: number, options: { recent?: boolean } = {}): Promise<PersonResult[]> {
   const state = await loadLatestState();
   if (!state) {
     console.error("No saved state found. Is EI_DATA_PATH set correctly?");
@@ -13,7 +13,7 @@ export async function execute(query: string, limit: number): Promise<PersonResul
     return [];
   }
 
-  const results = await retrieve(people, query, limit);
+  const results = await retrieve(people, query, limit, options);
   
   return results.map(person => ({
     id: person.id,

package/src/cli/commands/quotes.ts

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

package/src/cli/commands/topics.ts

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

package/src/cli/mcp.ts

@@ -0,0 +1,94 @@
+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";
+
+// Exported so tests can inject their own transport
+export function createMcpServer(): McpServer {
+  const server = new McpServer({
+    name: "ei",
+    version: "1.0.0",
+  });
+
+  server.registerTool(
+    "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.",
+      inputSchema: {
+        query: z.string().describe("Search text. Supports natural language."),
+        type: z
+          .enum(["facts", "people", "topics", "quotes"])
+          .optional()
+          .describe(
+            "Filter to a specific data type. Omit to search all types (balanced across all 4)."
+          ),
+        limit: z
+          .number()
+          .optional()
+          .default(10)
+          .describe("Maximum number of results to return."),
+        recent: z
+          .boolean()
+          .optional()
+          .describe("If true, sort by most recently mentioned."),
+      },
+    },
+    async ({ query, type, limit, recent }) => {
+      const options = { recent: recent ?? false };
+      const effectiveLimit = limit ?? 10;
+
+      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);
+      } else {
+        result = await retrieveBalanced(query, effectiveLimit, options);
+      }
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+      };
+    }
+  );
+
+  server.registerTool(
+    "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.",
+      inputSchema: {
+        id: z.string().describe("The entity ID to look up."),
+      },
+    },
+    async ({ id }) => {
+      const result = await lookupById(id);
+      const text =
+        result === null
+          ? `No entity found with ID: ${id}`
+          : JSON.stringify(result, null, 2);
+
+      return {
+        content: [{ type: "text" as const, text }],
+      };
+    }
+  );
+
+  return server;
+}
+
+export async function handleMcpCommand(_args: string[]): Promise<void> {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  process.stderr.write("Ei MCP server running on stdio\n");
+
+  // Block until the client disconnects (stdin closes), otherwise
+  // the caller's process.exit(0) fires immediately and kills the server
+  // before it can process any messages.
+  await new Promise<void>((resolve) => {
+    process.stdin.once("end", resolve);
+    process.stdin.once("close", resolve);
+  });
+}

package/src/cli/retrieval.ts

@@ -30,18 +30,43 @@ export async function loadLatestState(): Promise<StorageState | null> {
     return null;
 }
 
-export async function retrieve<T extends { id: string; embedding?: number[] }>(
+export async function retrieve<T extends { id: string; embedding?: number[]; last_updated?: string; last_mentioned?: string }>(
   items: T[],
   query: string,
-  limit: number = 10
+  limit: number = 10,
+  options: { recent?: boolean } = {}
 ): Promise<T[]> {
-  if (items.length === 0 || !query) {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const { recent } = options;
+
+  const sortByRecent = (a: T, b: T): number => {
+    const aDate = a.last_mentioned ?? (a as Record<string, unknown>).last_updated as string ?? "";
+    const bDate = b.last_mentioned ?? (b as Record<string, unknown>).last_updated as string ?? "";
+    return bDate.localeCompare(aDate);
+  };
+
+  if (recent && !query) {
+    return [...items].sort(sortByRecent).slice(0, limit);
+  }
+
+  if (!query) {
     return [];
   }
 
   const embeddingService = getEmbeddingService();
   const queryVector = await embeddingService.embed(query);
 
+  if (recent) {
+    const topK = Math.max(limit * 5, 50);
+    const results = findTopK(queryVector, items, topK)
+      .filter(({ similarity }) => similarity >= EMBEDDING_MIN_SIMILARITY)
+      .map(({ item }) => item);
+    return results.sort(sortByRecent).slice(0, limit);
+  }
+
   const results = findTopK(queryVector, items, limit);
 
   return results
@@ -159,7 +184,8 @@ function mapTopic(topic: Topic): TopicResult {
 
 export async function retrieveBalanced(
   query: string,
-  limit: number = 10
+  limit: number = 10,
+  options: { recent?: boolean } = {}
 ): Promise<BalancedResult[]> {
   const state = await loadLatestState();
   if (!state) {
@@ -167,6 +193,24 @@ export async function retrieveBalanced(
     return [];
   }
 
+  const { recent } = options;
+
+  type AnyItem = { id: string; embedding?: number[]; last_updated?: string; last_mentioned?: string };
+  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 }> = [
+      ...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) })),
+    ];
+    return allItems
+      .sort((a, b) => recentDate(b.item).localeCompare(recentDate(a.item)))
+      .slice(0, limit)
+      .map(({ type, mapped }) => ({ type, ...mapped }) as BalancedResult);
+  }
+
   const embeddingService = getEmbeddingService();
   const queryVector = await embeddingService.embed(query);
 
@@ -183,6 +227,22 @@ export async function retrieveBalanced(
     { type: "topic", items: state.human.topics, mapper: mapTopic },
   ];
 
+  if (recent) {
+    for (const { type, items, mapper } of typeConfigs) {
+      const topK = Math.max(limit * 5, 50);
+      const scored = findTopK(queryVector, items, topK);
+      for (const { item, similarity } of scored) {
+        if (similarity >= EMBEDDING_MIN_SIMILARITY) {
+          allScored.push({ type, similarity, mapped: mapper(item), itemId: item.id });
+        }
+      }
+    }
+    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);
+  }
+
   for (const { type, items, mapper } of typeConfigs) {
     const scored = findTopK(queryVector, items, items.length);
     for (const { item, similarity } of scored) {
@@ -195,7 +255,6 @@ export async function retrieveBalanced(
   const result: ScoredEntry[] = [];
   const used = new Set<string>();
 
-  // Floor: at least 1 result per type (if available and meets threshold)
   for (const type of DATA_TYPES) {
     if (result.length >= limit) break;
     const best = allScored
@@ -207,7 +266,6 @@ export async function retrieveBalanced(
     }
   }
 
-  // Fill remaining slots with highest-similarity results across all types
   const remaining = allScored
     .filter(r => !used.has(r.itemId))
     .sort((a, b) => b.similarity - a.similarity);

package/src/cli.ts

@@ -36,8 +36,12 @@ Usage:
   ei -n 5 "search text"         Limit results
   ei <type> "search text"       Search a specific data type
   ei <type> -n 5 "search text"  Type-specific with limit
+  ei --recent                   Return most recently mentioned items
+  ei --recent "query"           Filter recent items by query
+  ei <type> --recent "query"    Type-specific recent search
   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)
 
 Types:
   quote / quotes    Quotes from conversation history
@@ -47,15 +51,18 @@ Types:
 
 Options:
   --number, -n     Maximum number of results (default: 10)
+  --recent, -r     Sort by last_mentioned date (most recent first)
   --id             Look up entity by ID (accepts value or stdin)
-  --install        Write the Ei tool file to ~/.config/opencode/tools/
+  --install        Register Ei with OpenCode, Claude Code, and Cursor
   --help, -h       Show this help message
 
 Examples:
   ei "debugging"                         # Search everything
   ei -n 5 "API design"                   # Top 5 across all types
   ei quote "you guessed it"              # Search quotes only
-  ei --id abc-123                          # Look up entity by ID
+  ei --recent                            # Most recently mentioned items
+  ei topics --recent "work"              # Recent work-related topics
+  ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
 `);
 }
@@ -122,7 +129,7 @@ async function installOpenCodeTool(): Promise<void> {
   console.log(`  Restart OpenCode to activate.`);
 }
 
-async function installClaudeCodeMcp(): Promise<void> {
+async function installClaudeCode(): Promise<void> {
   const home = process.env.HOME || "~";
   const claudeJsonPath = join(home, ".claude.json");
 
@@ -132,7 +139,7 @@ async function installClaudeCodeMcp(): Promise<void> {
     const which = Bun.spawnSync(["which", "claude"], { stdout: "pipe", stderr: "pipe" });
     if (which.exitCode === 0) {
       const result = Bun.spawnSync(
-        ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "ei", "--", "ei"],
+        ["claude", "mcp", "add", "--scope", "user", "--transport", "stdio", "ei", "--", "ei", "mcp"],
         { stdout: "pipe", stderr: "pipe" }
       );
       if (result.exitCode === 0) {
@@ -155,17 +162,11 @@ async function installClaudeCodeMcp(): Promise<void> {
     // File doesn't exist or isn't valid JSON — start fresh
   }
 
-  // Resolve the ei binary: if running as compiled binary, argv[1] is our path;
-  // if running as 'bun src/cli.ts', fall back to 'ei' (assumed on PATH after npm install -g)
-  const isBunScript = process.argv[1]?.endsWith("/cli.ts") || process.argv[1]?.endsWith("/cli.js");
-  const command = isBunScript ? "ei" : (process.argv[1] ?? "ei");
-
   const mcpServers = (config.mcpServers ?? {}) as Record<string, unknown>;
   mcpServers["ei"] = {
     type: "stdio",
-    command,
-    args: [],
-    env: {},
+    command: "ei",
+    args: ["mcp"],
   };
   config.mcpServers = mcpServers;
 
@@ -179,6 +180,41 @@ async function installClaudeCodeMcp(): Promise<void> {
   console.log(`  Restart Claude Code to activate.`);
 }
 
+async function installCursor(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const cursorJsonPath = join(home, ".cursor", "mcp.json");
+
+  let config: Record<string, unknown> = {};
+  try {
+    const text = await Bun.file(cursorJsonPath).text();
+    config = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+  }
+
+  const mcpServers = (config.mcpServers ?? {}) as Record<string, unknown>;
+  mcpServers["ei"] = {
+    type: "stdio",
+    command: "ei",
+    args: ["mcp"],
+  };
+  config.mcpServers = mcpServers;
+
+  await Bun.$`mkdir -p ${join(home, ".cursor")}`;
+  const tmpPath = `${cursorJsonPath}.ei-install.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(config, null, 2) + "\n");
+  const { rename } = await import(/* @vite-ignore */ "fs/promises");
+  await rename(tmpPath, cursorJsonPath);
+
+  console.log(`✓ Installed Ei MCP server to ${cursorJsonPath}`);
+  console.log(`  Restart Cursor to activate.`);
+}
+
+async function installMcpClients(): Promise<void> {
+  await installClaudeCode();
+  await installCursor();
+}
+
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
 
@@ -201,10 +237,15 @@ async function main(): Promise<void> {
 
   if (args[0] === "--install") {
     await installOpenCodeTool();
-    await installClaudeCodeMcp();
+    await installMcpClients();
     process.exit(0);
   }
 
+  if (args[0] === "mcp") {
+    const { handleMcpCommand } = await import("./cli/mcp.js");
+    await handleMcpCommand(args.slice(1));
+    process.exit(0);
+  }
 
   // Handle --id flag: look up entity by ID
   const idFlagIndex = args.indexOf("--id");
@@ -250,6 +291,7 @@ async function main(): Promise<void> {
       args: parseableArgs,
       options: {
         number: { type: "string", short: "n" },
+        recent: { type: "boolean", short: "r" },
         help: { type: "boolean", short: "h" },
       },
       allowPositionals: true,
@@ -267,8 +309,9 @@ 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;
 
-  if (!query) {
+  if (!query && !recent) {
     if (targetType) {
       console.error(`Search text required. Usage: ei ${targetType} "search text"`);
     } else {
@@ -282,12 +325,14 @@ async function main(): Promise<void> {
     process.exit(1);
   }
 
+  const options = { recent };
+
   let result;
   if (targetType) {
     const module = await import(`./cli/commands/${targetType}.js`);
-    result = await module.execute(query, limit);
+    result = await module.execute(query, limit, options);
   } else {
-    result = await retrieveBalanced(query, limit);
+    result = await retrieveBalanced(query, limit, options);
   }
 
   console.log(JSON.stringify(result, null, 2));

package/src/core/handlers/dedup.ts

@@ -24,7 +24,7 @@ export async function handleDedupCurate(
   const state = stateManager.getHuman();
   
   // Validate entity_type
-  if (!entity_type || !['fact', 'topic', 'person'].includes(entity_type)) {
+  if (!entity_type || !['topic', 'person'].includes(entity_type)) {
     console.error(`[Dedup] Invalid entity_type: "${entity_type}" (from request data)`, response.request.data);
     return;
   }
@@ -206,10 +206,6 @@ export async function handleDedupCurate(
       last_changed_by: "ei",
       embedding,
       // Type-specific fields with defaults
-      ...(entity_type === 'fact' && { 
-        confidence: addition.confidence ?? 0.5,
-        validated_date: ''
-      }),
       ...((entity_type === 'topic' || entity_type === 'person') && {
         exposure_current: addition.exposure_current ?? 0.0,
         exposure_desired: addition.exposure_desired ?? 0.5,
@@ -220,9 +216,7 @@ export async function handleDedupCurate(
     };
     
     // Type-safe cast based on entity_type
-    if (entity_type === 'fact') {
-      stateManager.human_fact_upsert(newEntity as Fact);
-    } else if (entity_type === 'topic') {
+    if (entity_type === 'topic') {
       stateManager.human_topic_upsert(newEntity as Topic);
     } else if (entity_type === 'person') {
       stateManager.human_person_upsert(newEntity as Person);

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

@@ -69,6 +69,7 @@ export async function handleFactFind(response: LLMResponse, state: StateManager)
       ...existingFact,
       description: factResult.value,
       last_updated: now,
+      last_mentioned: now,
       learned_by: existingFact.learned_by ?? context.personaId,
       last_changed_by: context.personaId,
       embedding,

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

@@ -162,6 +162,7 @@ export async function handleTopicUpdate(response: LLMResponse, state: StateManag
     exposure_current: calculateExposureCurrent(exposureImpact),
     exposure_desired: result.exposure_desired ?? 0.5,
     last_updated: now,
+    last_mentioned: now,
     learned_by: isNewItem ? personaId : existingTopic?.learned_by,
     last_changed_by: personaId,
     persona_groups: mergeGroups(personaGroup, isNewItem, existingTopic?.persona_groups),
@@ -228,6 +229,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
     exposure_current: calculateExposureCurrent(exposureImpact),
     exposure_desired: result.exposure_desired ?? 0.5,
     last_updated: now,
+    last_mentioned: now,
     learned_by: isNewItem ? personaId : existingPerson?.learned_by,
     last_changed_by: personaId,
     persona_groups: mergeGroups(personaGroup, isNewItem, existingPerson?.persona_groups),