ei-tui 0.1.25 → 0.3.1

package/README.md

@@ -116,6 +116,48 @@ Opencode saves all of its sessions locally, either in a JSON structure or, if yo
 
 Then, Opencode can call into Ei and pull those details back out. That's why you always have a side-project or two going. See [TUI Readme](tui/README.md)
 
+## Built-in Tool Integrations
+
+Personas can use tools. Not just read-from-memory tools — *actual* tools. Web search. Your music. Your filesystem. Here's what ships with Ei out of the box:
+
+### Ei Built-ins (always available, no setup)
+
+| 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. |
+| `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)* |
+| `search_files` | Find files by name pattern *(TUI only)* |
+| `grep` | Search file contents by regex *(TUI only)* |
+| `get_file_info` | File/directory metadata *(TUI only)* |
+
+The filesystem tools make Ei a legitimate coding assistant in the TUI. Ask a persona to review a file, understand a project structure, or track down where something is defined — it can actually look.
+
+### Tavily Web Search (requires free API key)
+
+| Tool | What it does |
+|------|-------------|
+| `tavily_web_search` | Real-time web search — current events, fact-checking, anything that needs up-to-date information |
+| `tavily_news_search` | Recent news articles |
+
+Get a free key at [tavily.com](https://tavily.com) (1,000 requests/month free tier). Add it in **Settings → Tool Kits → Tavily Search**.
+
+### Spotify (requires OAuth connection)
+
+| Tool | What it does |
+|------|-------------|
+| `get_currently_playing` | What's playing right now — artist, title, album, progress |
+| `get_liked_songs` | Your full liked songs library |
+
+Connect in **Settings → Tool Kits → Spotify**. Once connected, personas can ask what you're listening to and actually know. Music-aware conversations.
+
+### Assigning Tools to Personas
+
+Tools aren't global — you choose which personas get access. Edit a persona and toggle the tools it can use. A focused work persona might only have filesystem tools. A general-purpose companion might have everything.
+
+---
+
 ## Technical Details
 
 This project is separated into five (5) logical parts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ei-tui",
-  "version": "0.1.25",
+  "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/README.md

@@ -10,7 +10,7 @@ There are two distinct types of data: Human and Persona.
 
 ## Human
 
-Human data is sort of the "Global" data - Each Persona can read and write elements to the humans Facts, Traits, People, and Topics. In addition, there are "Quotes" that can tie to those four types of data.
+Human data is sort of the "Global" data - Each Persona can read and write elements to the humans Facts, People, and Topics. In addition, there are "Quotes" that can tie to those three types of data.
 
 As the user uses the system, it tries to keep track of several data points for these elements:
 
@@ -24,12 +24,9 @@ As the user uses the system, it tries to keep track of several data points for t
     * Current: How much the user has talked or heard about a subject, where:
         + 0.0: Obi-Wan Kenobi ...now that's a name I've not heard in a long time
         + 1.0: The user just spent 4 hours talking about Star Wars
-- Strength: The system will try to gauge how strongly you exhibit a Trait
-    * 1.0 on "Visual Learner" would mean that you've said or shown that it is the absolute best way for you to learn
-    * 0.0 on "Public Speaker" would mean you've said or shown that you have no desire, aptitude, or willingness to present
-- Validated: "Facts" have proven almost as hard to get right as Traits, so I added a way for Ei and you to mark the ones that are true as "Validated"
+- Validated: "Facts" have proven tricky, so I added a way for Ei and you to mark the ones that are true as "Validated"
 
-Each of those types represents a piece of what the system "knows" about the person, and all but "Traits" are kept up-to-date as the person chats with Personas, but not on always on every message. On each message to a Persona, a check is made:
+Each of those types represents a piece of what the system "knows" about the person, and they're kept up-to-date as the person chats with Personas, but not always on every message. On each message to a Persona, a check is made:
 
 ```
 if(Person.newMessages > count_of_human_[type]) {
@@ -37,9 +34,7 @@ if(Person.newMessages > count_of_human_[type]) {
 }
 ```
 
-Again, except for Traits<sup>1</sup>, this is to extract quotes, description updates, title updates, etc. for the conversations the user is having, and keep them feeling alive.
-
-> <sup>1</sup> Traits are unique because, after trying to extract them in the same way as the other pieces of data, I realized that it's sorta hard to understand a core aspect of someone in one message, or even 10. Even doing this analysis over a full 24 hours hasn't proven to be particularly effective, but it's the best we have so far.
+This extracts quotes, description updates, title updates, etc. for the conversations the user is having, and keeps them feeling alive.
 
 ## Persona
 
@@ -72,8 +67,6 @@ I also frequently refer to this as "Extract," but this is the first step where w
 
 Since we also pull out details during normal discourse (see above), this is the less-important step at this point, but still vital for catching up with the last few messages, or Personas that only received a few messages during the day and may not have hit the current limit for natural extraction.
 
-Additionally, this is the ONLY time when Human Traits are created or updated - after (hopefully) enough messages have been exchanged for an agent to analyze it and say "Yup, Flare is _definitely_ verbose."
-
 ### Exposure Adjustment
 
 Exposure is calculated by two metrics - `desired` and `current`. If an entity REALLY likes talking about a subject, their `desired` will be very high (1.0 max), ranging down to 0.0 for subjects which that entity does NOT wish to discuss. You may have guessed already, but `current` is how much they've recently talked about a topic.

package/src/cli/README.md

@@ -6,16 +6,16 @@ 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 traits -n 5 "query string"  # Return up to 5 traits
 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 --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`, `trait`, `person`, `topic`, `quote` all work (singular or plural).
+Type aliases: `fact`, `person`, `topic`, `quote` all work (singular or plural).
 
 # An Agentic Tool
 
@@ -33,16 +33,96 @@ 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
 
-The installed tool gives OpenCode agents access to all five data types with proper Zod-validated args:
+The installed tool gives OpenCode agents access to all four data types with proper Zod-validated args:
 
 | Arg | Type | Description |
 |-----|------|-------------|
 | `query` | string (required) | Search text, or entity ID when `lookup=true` |
-| `type` | enum (optional) | `facts` \| `traits` \| `people` \| `topics` \| `quotes` — omit for balanced results |
+| `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 |
 
@@ -50,7 +130,7 @@ The installed tool gives OpenCode agents access to all five data types with prop
 
 All search commands return arrays. Each result includes a `type` field.
 
-**Fact / Trait / Person / Topic**: `{ type, id, name, description, sentiment, ...type-specific fields }`
+**Fact / Person / Topic**: `{ type, id, name, description, sentiment, ...type-specific fields }`
 
 **Quote**: `{ type, id, text, speaker, timestamp, linked_items[] }`
 

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

@@ -1,4 +1,4 @@
-import type { StorageState, Quote, Fact, Trait, Person, Topic } from "../core/types";
+import type { StorageState, Quote, Fact, Person, Topic } from "../core/types";
 import { decodeAllEmbeddings } from "../storage/embeddings";
 import { crossFind } from "../core/utils/index.ts";
 import { join } from "path";
@@ -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
@@ -67,15 +92,6 @@ export interface FactResult {
   name: string;
   description: string;
   sentiment: number;
-  validated: string;
-}
-
-export interface TraitResult {
-  id: string;
-  name: string;
-  description: string;
-  strength: number;
-  sentiment: number;
 }
 
 export interface PersonResult {
@@ -97,17 +113,16 @@ export interface TopicResult {
 export type BalancedResult =
   | ({ type: "quote" } & QuoteResult)
   | ({ type: "fact" } & FactResult)
-  | ({ type: "trait" } & TraitResult)
   | ({ type: "person" } & PersonResult)
   | ({ type: "topic" } & TopicResult);
 
-const DATA_TYPES = ["quote", "fact", "trait", "person", "topic"] as const;
+const DATA_TYPES = ["quote", "fact", "person", "topic"] as const;
 type DataType = typeof DATA_TYPES[number];
 
 interface ScoredEntry {
   type: DataType;
   similarity: number;
-  mapped: QuoteResult | FactResult | TraitResult | PersonResult | TopicResult;
+  mapped: QuoteResult | FactResult | PersonResult | TopicResult;
   itemId: string;
 }
 
@@ -117,7 +132,6 @@ export function resolveLinkedItems(dataItemIds: string[], state: StorageState):
     { type: "topic", source: state.human.topics },
     { type: "person", source: state.human.people },
     { type: "fact", source: state.human.facts },
-    { type: "trait", source: state.human.traits },
   ];
   for (const { type, source } of collections) {
     for (const entity of source) {
@@ -144,19 +158,9 @@ function mapFact(fact: Fact): FactResult {
     name: fact.name,
     description: fact.description,
     sentiment: fact.sentiment,
-    validated: fact.validated,
   };
 }
 
-function mapTrait(trait: Trait): TraitResult {
-  return {
-    id: trait.id,
-    name: trait.name,
-    description: trait.description,
-    strength: trait.strength ?? 0.5,
-    sentiment: trait.sentiment,
-  };
-}
 
 function mapPerson(person: Person): PersonResult {
   return {
@@ -180,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) {
@@ -188,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);
 
@@ -200,11 +223,26 @@ export async function retrieveBalanced(
   }> = [
     { type: "quote", items: state.human.quotes, mapper: (q: Quote) => mapQuote(q, state) },
     { type: "fact", items: state.human.facts, mapper: mapFact },
-    { type: "trait", items: state.human.traits, mapper: mapTrait },
     { type: "person", items: state.human.people, mapper: mapPerson },
     { 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) {
@@ -217,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
@@ -229,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);