ei-tui 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Scherer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Ei
+
+A local-first AI companion system with persistent personas and Opencode Integration.
+
+You can access the Web version at [ei.flare576.com](https://ei.flare576.com).
+
+You can install the local version via `npm install -g ei-tui` (see [### TUI](#tui) for details).
+
+If you're here to give Opencode perpetual memory (yes), 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_.
+
+## What Does "Local First" Mean?
+
+All of the data Ei learns about you from your conversations is stored on your device (LocalStorage on the Web, and `$EI_DATA_PATH` or `~/.local/share/ei` in the TUI).
+
+Unless you enable Syncing, that's where it stays.
+
+If you have a local LLM, literally no data leaves your system(s) by default. If you don't, you'll need to provide an LLM for Ei to use. I tried to make that as easy as possible via adding Providers via API Key.
+
+There's no other usage, debugging, analytics, tracking, or history information stored or transmitted - anonymized or otherwise.
+
+If there's a problem with the system, you need to tell me here on GitHub, or on Bluesky, or Discord, or whatever. There's no "report a bug" button, no "DONATE" link in the app.
+
+Don't get me wrong -I absolutely want to fix whatever problem you run into, or hear about the feature you want - but your Ei system, and the data you build with it, is yours.
+
+That's what "Local First" means.
+
+### What Does Sync Do?
+
+Optionally, you can choose to "Sync" to flare576.com. The only reason you would do this is if you wanted to easily move between two or more devices.
+
+If you just want data back-ups, there's an "Backup & Restore" feature built into the system on the same page as "Sync" (actually, above Sync, because I honestly don't think anyone besides me wants to use Ei enough to use two devices...).
+
+After you enable it, Sync kicks in when you close the TUI, or if you click "Save and Exit" in the web app. It sends a single, encrypted file to a file store for Ei...
+
+That I can't decrypt.
+
+Even if I wanted to (I definitely do not), I wouldn't be able to divulge your information because **You** are the only one that can generate the key. It's not a public/private keypair, it's not a "handshake".
+
+It's your data - I have no right to it, and neither does anyone else except you.
+
+## What's a Persona?
+
+At the core of the technology, LLM "Agents" are made up of two or three components, depending on who you ask:
+
+1. System Prompt
+2. User Prompt
+    a. Which can be broken into "Messages", but they're still basically the User Prompt
+
+The "System Prompt" is the part where you usually say
+
+> You are a pirate
+
+The "User Prompt" is the part where you put your messages
+
+> user: "OMG ARE YOU REALLY A PIRATE?!"
+> assistant: "Yar."
+
+A "Persona" is the combination of these two pieces of data, plus some _personality_. The reason I didn't call it an "Agent" is because Personas aren't static<sup>1</sup> - they'll grow and adapt as you talk to them. See the [Core Readme](core/README.md) for more information!
+
+> <sup>1</sup>: By default. You can make them static.
+
+## The Basics
+
+Ei can operate with three types of input, and three types of output.
+
+```
+[TUI] -User Messages-> Ei <-User Messages- [Web]
+                       ^
+                    Sessions
+                       |
+                   [OpenCode]
+```
+
+```
+[TUI] <-Persona Messages- Ei -Persona Messages-> [Web]
+                          |
+                       CLI Data
+                          v
+                      [OpenCode]
+```
+
+Optionally, users can opt into a server-side data sync. This is ideal for users who want to use multiple devices or switch between TUI and Web throughout the day. All data is encrypted _before_ being sent to the server, using a key that only the user can generate (your `username` and `passphrase` never leave your device - I couldn't decrypt your data if I wanted to).
+
+### Web
+
+When you access Ei via https://ei.flare576.com, your browser will download the assets and walk you through onboarding. If you're running a Local LLM on port :1234 it will auto-detect it, otherwise it will  allowing you to enter it.
+
+Then you'll land on the chat interface. As you enter messages, they'll go to *YOUR* server. As Ei discovers information about you, summaries will be built with *YOUR* server, and data will be stored to *YOUR* LocalStorage in *YOUR* browser.
+
+When you leave, it simply stays in LocalStorage. When you come back, it loads it from LocalStorage.
+
+More information can be found in the [Web Readme](web/README.md)
+
+### TUI
+
+```
+npm install -g ei-tui
+```
+
+When you install Ei, you pull down this package and it's dependencies.
+
+If you have a Local LLM, that's the first and last set of signals that leave your machine for Ei unless you tell it otherwise.
+
+Regardless, Running `ei` pops open the TUI interface and, just like on the web, all messages and summary requests flow to your LLM provider, but the core data stays on your device.
+
+More information (including commands) can be found in the [TUI Readme](tui/README.md)
+
+### Opencode
+
+Opencode saves all of its sessions locally, either in a JSON structure or, if you're running the latest version, in a SQLite DB. If you enable the integration, Ei will pull all of the conversational parts of those sessions and summarize them, pulling out details, quotes, and keeping the summaries up-to-date.
+
+Then, Opencode can call into Ei and pull those details back out.
+
+Yes, I did make a dynamic, perpetual RAG. No, I didn't do it on purpose; that's why you always have a side-project or two going. See [TUI Readme](tui/README.md)
+
+## Technical Details
+
+This project is separated into five (5) logical parts:
+
+1. Ei Core
+    a. Location: `/src`
+    b. Purpose: Shared between TUI and Web, it's The event-driven core of Ei, housing:
+        i. Business logic
+        ii. Prompts
+        iii. Integrations
+2. Ei Online
+    a. Location: `/web`
+    b. Purpose: Provides a web interface for Ei.
+    c. Deployed to: https://ei.flare576.com
+3. Ei Terminal User Interface (TUI)
+    a. Location: `/tui`
+    b. Purpose: Provides a TUI interface for Ei
+    c. Deployed to: NPM for you to install
+4. Ei API
+    a. Location: `/api`
+    b. Purpose: Provides remote sync for Ei.
+    c. Deployed to: https://ei.flare576.com/api
+5. Ei Command Line Interface (CLI)
+    a. Location: `/src/cli`
+    b. Purpose: Provides a CLI interface for Opencode to use as a tool
+    c. Technically, ships with the TUI
+
+## Requirements
+ [Bun](https://bun.sh) runtime (>=1.0.0)
+ Local LLM provider (LM Studio, Ollama, etc.)
+    * OR API access to a remote LLM host (Anthropic, OpenAI, Bedrock, your uncle's LLM farm, etc.)
+
+## LM Studio Setup
+
+**Important**: You must enable CORS in LM Studio for browser-based EI to work.
+
+1. Open LM Studio
+2. Go to **Local Server** tab (left sidebar)
+3. Enable **"Enable CORS"** toggle
+4. Start/restart the server
+
+Without this setting, browser security policies will block API calls.
+
+## Development
+
+```bash
+npm install
+npm run dev      # Watch mode
+npm run build    # Compile TypeScript
+npm run test     # Run tests
+```
+
+## Project Structure
+
+See `AGENTS.md` for detailed architecture and contribution guidelines.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "ei-tui",
+  "version": "0.1.3",
+  "author": "Flare576",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "src/",
+    "tui/src/",
+    "tui/bunfig.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@playwright/test": "^1.58.0",
+    "@types/bun": "latest",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.10",
+    "@vitest/coverage-v8": "^2.1.9",
+    "express": "^5.2.1",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "bin": {
+    "ei": "./src/cli.ts"
+  },
+  "description": "Ei - Local-first AI companion with persistent personas",
+  "keywords": [
+    "ai",
+    "llm",
+    "personas",
+    "tui",
+    "cli",
+    "companion"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "test": "vitest run && npm run test:tui",
+    "test:src": "vitest run",
+    "test:tui": "cd tui && npm run test",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:tui": "cd tui && npm run test:e2e",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:debug": "playwright test --debug",
+    "test:all": "npm run test && npm run test:e2e && npm run test:e2e:tui",
+    "typecheck": "tsc --noEmit",
+    "web": "cd web && npm run dev",
+    "tui": "cd tui && npm run dev"
+  },
+  "type": "module",
+  "dependencies": {
+    "@opentui/core": "^0.1.79",
+    "@opentui/solid": "^0.1.79",
+    "fastembed": "^2.1.0",
+    "solid-js": "1.9.9",
+    "yaml": "^2.8.2"
+  }
+}

package/src/README.md

@@ -0,0 +1,96 @@
+# Behind The Curtain
+
+Welcome to the Core of Ei. If you're reading this, you're probably interested about the inner-workings of the system.
+
+Or you're lost. That's ok, too.
+
+# Data Models
+
+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.
+
+As the user uses the system, it tries to keep track of several data points for these elements:
+
+- Sentiment: How much the system thinks the user likes or dislikes the idea or concept
+    * 1.0 means that there is nothing in the world that the user loves more than this thing
+    * -1.0 means that, as far as the user is concerned, the universe never needed this thing
+- Exposure: Topics and People have an "Exposure" measure, gauging how frequently they're discussed
+    * Desired: How much the user *wants* to talk about a subject, where:
+        + 0.0: The user never EVER wants to talk about or hear about the subject
+        + 1.0: Every message to and from the user should be about this person, place, or thing
+    * 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
+
+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:
+
+```
+if(Person.newMessages > count_of_human_[type]) {
+ run extract[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.
+
+## Persona
+
+The Persona data is designed with two goals: Consistency (Traits) and Growth (Topics)
+
+### Consistency (Traits)
+
+"One-Eyed-Willy talks like a pirate" is an example of a Persona Trait - you can assign it a Sentiment ("He LOVES talking like a pirate") as well as a Strength ("He does it ALL THE TIME"). These are things that you can set during creation, or that you can add over time with direct requests "Please talk like a pirate less often" or directly in the Persona editor. These don't "gradually" change over time.
+
+### Growth (Topics)
+
+"Pirate Treasure Procurement" is an example of a Persona Topic. These grow and adapt over time, and have four characteristics:
+
+- Perspective: "It's a pirates duty to plunder booty"
+- Approach: "Full sail ahead, take what you can, give nothing back"
+- Personal Stake: "A ship sails not on hunger and wont."
+- Sentiment: 0.9 // The only thing One-Eyed-Willy likes more than Pirate Treasure Procurement is ~rum~ Baby Ruth
+
+Each Topic will have an "exposure" rating similar to those on Human Data points.
+
+# Ceremony Intent
+
+Every 24 hours, we want to freshen up the system. We do this in 4 parts: Exposure, Decay, Expire, Explore
+
+## Exposure
+
+I also frequently refer to this as "Extract," but this is the first step where we determine what the human and that Persona talked about that day. It serves two purposes:
+
+### Detail Extraction
+
+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.
+
+Adjusting the values is different for Human Topics/People than Persona Topics. The Human subjects are actually adjusted during the previous step, while extracting details.
+
+The Persona Topic update only happens during the Ceremony, and really this step only increases exposure IF the subject was discussed, bumping the last_updated field accordingly.
+
+## Decay
+
+After we determine if topics were discussed (increasing exposure), we adjust exposure the _other_ way. Based on some heuristics (like current level, desired level, and time-since-discussion), we decrease the current exposure levels down.
+
+## Expire
+
+This and the following step (Explore) are exclusive to Persona Topics right now. In Expire, we analyze the Person Topics to determine if any of them have
+- Lost their meaning to the Persona
+- Been ignored or dismissed by the user
+
+This is largely tracked by exposure, but expiration is dictated by an Agent.
+
+## Explore
+
+After we've removed irrelevant topics, this is the Agent's opportunity to add NEW topics that might be of interest to the Persona (and the user). Again, it's a prompt to an agent if the Persona doesn't have its full capacity of Topics.
+

package/src/cli/README.md

@@ -0,0 +1,47 @@
+# The CLI
+
+It's actually super straight-forward
+
+```sh
+ei                             # Start the TUI
+ei "query string"              # Return up to 10 "query string" 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
+```
+
+# An Agentic Tool
+
+
+The `--id` flag is designed for piping. For example, search for a topic and then fetch the full entity:
+
+```sh
+ei "memory leak" | jq '.[0].id' | ei --id
+```
+
+To register Ei as an explicit OpenCode tool (optional — agents can also just call `ei` via shell):
+
+```bash
+mkdir -p ~/.config/opencode/tools
+```
+
+Create `~/.config/opencode/tools/ei.ts`:
+
+```typescript
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Search the user's Ei knowledge base for facts, people, topics, traits, and quotes",
+  args: {
+    query: tool.schema.string().describe("Search query"),
+  },
+  async execute(args) {
+    return await Bun.$`ei ${args.query}`.text()
+  },
+})
+```

package/src/cli/commands/facts.ts

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

package/src/cli/commands/people.ts

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

package/src/cli/commands/quotes.ts

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

package/src/cli/commands/topics.ts

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

package/src/cli/commands/traits.ts

@@ -0,0 +1,25 @@
+import { loadLatestState, retrieve } from "../retrieval";
+import type { TraitResult } from "../retrieval";
+
+export async function execute(query: string, limit: number): Promise<TraitResult[]> {
+  const state = await loadLatestState();
+  if (!state) {
+    console.error("No saved state found. Is EI_DATA_PATH set correctly?");
+    return [];
+  }
+
+  const traits = state.human.traits;
+  if (traits.length === 0) {
+    return [];
+  }
+
+  const results = await retrieve(traits, query, limit);
+  
+  return results.map(trait => ({
+    id: trait.id,
+    name: trait.name,
+    description: trait.description,
+    strength: trait.strength ?? 0.5,
+    sentiment: trait.sentiment,
+  }));
+}