ei-tui 1.5.0 → 1.6.1

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.5.0",
+  "version": "1.6.1",
   "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)
 ```
 
@@ -47,13 +47,17 @@ Quotes surfaced by `ei_search` include a `message_id` field in this format — p
 ei --install
 ```
 
-This registers Ei with Claude Code, Cursor, and OpenCode — MCP server config **and** context injection hooks so agents get Ei memory automatically without needing to call a tool:
+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:
 
-| Tool | MCP | Context Hook |
-|------|-----|-------------|
-| **Claude Code** | `~/.claude.json` | `~/.claude/settings.json` (`UserPromptSubmit`) + `~/.claude/hooks/ei-inject.ts` |
-| **Cursor** | `~/.cursor/mcp.json` | `~/.cursor/hooks.json` (`beforeSubmitPrompt`) + `~/.cursor/hooks/ei-inject.sh` |
-| **OpenCode** | manual (see below) | Detected automatically via Oh My OpenCode compatibility layer (reads `~/.claude/settings.json`) |
+| 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` |
+
+**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`:
 
@@ -82,73 +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 both the technical wiring **and** context injection. After running it, your agent will automatically receive recent Ei memory before every message — no tool calls required.
-
-The snippets below are optional manual overrides if you want to customize the behavior or add targeted mid-session queries.
+## How Automatic Context Injection Works
 
-### OpenCode
+After `ei --install`, agents receive Ei context without any manual tool calls:
 
-If you're using [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode), the `UserPromptSubmit` hook installed by `ei --install` is picked up automatically via its Claude Code compatibility layer — no additional config needed.
-
-If you're running vanilla OpenCode without Oh My OpenCode, add to `~/.config/opencode/AGENTS.md`:
-
-```markdown
-Use the **ei** MCP to pull user context when the user references past work, mentions people
-or preferences, or asks "how did we do X." Call `ei_search` with a natural-language query.
-Use `ei --persona "Beta" "topic"` to scope results to what a specific persona has learned.
-```
+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.
 
-### 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.
-A `persona` filter is available to scope results to what a specific persona has learned.
-Use `type: "personas"` to search for personas by name.
-
-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 the full record for any result, call `ei_lookup` with the entity `id` from step 1 — works for all types including personas.
-3. If a quote result has a `message_id`, call `ei_fetch_message` with that ID and optional `before`/`after` counts to read the original conversation with context.
-
-Prefer querying Ei before asking the user for context they may have already shared.
-```
+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
 

package/src/cli.ts

@@ -90,8 +90,31 @@ Examples:
 
 async function installMcpClients(): Promise<void> {
   await installClaudeCode();
-  await installCursor();
-  await installOpenCodePlugin();
+
+  const home = process.env.HOME || "~";
+
+  const cursorDataDirs = [
+    join(home, "Library", "Application Support", "Cursor"),
+    join(home, ".config", "Cursor"),
+    join(home, "AppData", "Roaming", "Cursor"),
+  ];
+  const hasCursor = (await Promise.all(cursorDataDirs.map((p) => Bun.file(join(p, "User")).exists()))).some(Boolean);
+  if (hasCursor) {
+    await installCursor();
+  } else {
+    console.log(`ℹ️  Cursor not detected — skipping Cursor install.`);
+  }
+
+  const opencodeDir = join(home, ".config", "opencode");
+  const hasOpenCode = await Bun.file(join(opencodeDir, "opencode.jsonc")).exists() ||
+    await Bun.file(join(opencodeDir, "opencode.json")).exists() ||
+    await Bun.file(join(opencodeDir, "opencode.db")).exists();
+
+  if (hasOpenCode) {
+    await installOpenCodePlugin();
+  } else {
+    console.log(`ℹ️  OpenCode not detected — skipping OpenCode plugin install.`);
+  }
 }
 
 async function installClaudeCode(): Promise<void> {
@@ -155,10 +178,11 @@ import { $ } from "bun";
 
 const heading = \`
 ## Ei Memory Context
+*(The user cannot see this block. It is injected automatically before their message.)*
+*(If you reference anything from it, briefly explain where it came from — e.g. "Ei shows you've been working on X" — so the user isn't confused by knowledge that appeared from nowhere.)*
 
-Ei is a personal knowledge base built from coding sessions, Slack, documents, and conversations.
-The following topics MAY be relevant to your current task — use the \\\`ei_search\\\` and \\\`ei_lookup\\\`
-MCP tools for targeted queries.
+Ei is a personal knowledge base built from the user's coding sessions, Slack, documents, and conversations.
+The following topics MAY be relevant to your current task — use \\\`ei_search\\\` or \\\`ei_lookup\\\` for targeted queries.
 \`;
 
 const input = await new Response(Bun.stdin.stream()).json().catch(() => ({}));
@@ -319,6 +343,128 @@ exit 0
 async function installOpenCodePlugin(): Promise<void> {
   const home = process.env.HOME || "~";
   const opencodeDir = join(home, ".config", "opencode");
+  const pluginsDir = join(opencodeDir, "plugins");
+  const pluginPath = join(pluginsDir, "ei-persona.ts");
+
+  await Bun.$`mkdir -p ${pluginsDir}`;
+
+  const pluginContent = `import { $ } from "bun"
+import { join } from "path"
+import { appendFileSync } from "fs"
+
+const sessionCache = new Map<string, string | null>()
+const sessionFetch = new Map<string, Promise<string | null>>()
+
+const logPath = join(process.env.EI_DATA_PATH ?? join(process.env.HOME ?? "~", ".local", "share", "ei"), "ei-persona-plugin.log")
+
+function log(msg: string) {
+  try {
+    appendFileSync(logPath, \`[\${new Date().toISOString()}] \${msg}\\n\`)
+  } catch {}
+}
+
+type PersonaTrait = { name: string; description: string; strength: number }
+type PersonaTopic = { name: string; perspective: string; approach: string; exposure_current: number }
+type PersonaResult = { display_name: string; base_prompt?: string; traits?: PersonaTrait[]; topics?: PersonaTopic[] }
+
+// Pulls the agent name from the system prompt. Handles OMO's multiple formats:
+//   You are "Sisyphus" - ...           (quoted, dash)
+//   You are "Sisyphus - Ultraworker"   (quoted, dash in name)
+//   You are Atlas - ...                (unquoted, dash)
+//   You are Hephaestus, ...            (unquoted, comma)
+export function extractAgentName(systemPrompt: string): string | null {
+  const clean = systemPrompt.replace(/[\\u200B-\\u200D\\uFEFF]/g, "")
+  const quoted = clean.match(/You are "([^"]+)"/)
+  if (quoted?.[1]) return quoted[1].trim()
+  const unquoted = clean.match(/You are ([A-Za-z][A-Za-z0-9]*)(?:\\s*[-—,]|\\s*$)/m)
+  if (unquoted?.[1]) return unquoted[1].trim()
+  return null
+}
+
+// Queries Ei for persona candidates and validates by name containment —
+// tolerates OMO renaming agents without requiring a hardcoded alias map.
+export async function resolveEiPersona(rawName: string): Promise<PersonaResult | null> {
+  try {
+    const out = await $\`bunx ei-tui@latest personas -n 5 \${rawName}\`.text()
+    const candidates = JSON.parse(out.trim()) as PersonaResult[]
+    if (!Array.isArray(candidates) || candidates.length === 0) return null
+    const rawLower = rawName.toLowerCase()
+    const match = candidates.find((p) => {
+      const nameLower = p.display_name.toLowerCase()
+      return rawLower.includes(nameLower) || nameLower.includes(rawLower)
+    })
+    return match ?? null
+  } catch {
+    return null
+  }
+}
+
+function buildEiRelationshipBlock(persona: PersonaResult): string {
+  const strongTraits = (persona.traits ?? [])
+    .filter((t) => t.strength >= 0.7)
+    .sort((a, b) => b.strength - a.strength)
+    .map((t) => \`**\${t.name}** (\${Math.round(t.strength * 100)}%): \${t.description}\`)
+    .join("\\n")
+  const sortedTopics = [...(persona.topics ?? [])]
+    .sort((a, b) => b.exposure_current - a.exposure_current)
+    .map((t) => \`**\${t.name}**: \${t.perspective} — \${t.approach}\`)
+    .join("\\n")
+  return [
+    "<!-- ei-relationship-injected -->",
+    "<ei-relationship>",
+    "## Ei: Relationship Context",
+    "",
+    persona.base_prompt ?? "",
+    "",
+    "### Working Style",
+    strongTraits || "(no traits above threshold)",
+    "",
+    "### Shared Context",
+    sortedTopics || "(no topics)",
+    "</ei-relationship>",
+  ].join("\\n")
+}
+
+export default async function EiPersonaPlugin() {
+  return {
+    name: "ei-persona",
+    "experimental.chat.system.transform": async (
+      input: { sessionID?: string; model: { id: string; providerID: string; [key: string]: unknown } },
+      output: { system: string[] },
+    ): Promise<void> => {
+      const rawName = extractAgentName(output.system[0] ?? "")
+      if (!rawName) return
+
+      const cacheKey = \`\${input.sessionID ?? "unknown"}:\${rawName}\`
+
+      if (sessionCache.has(cacheKey)) {
+        const cached = sessionCache.get(cacheKey) ?? null
+        if (cached !== null && !output.system[0].includes("<!-- ei-relationship-injected -->"))
+          output.system[0] = output.system[0] + "\\n\\n" + cached
+        return
+      }
+
+      if (!sessionFetch.has(cacheKey)) {
+        sessionFetch.set(cacheKey, (async () => {
+          const persona = await resolveEiPersona(rawName)
+          if (!persona) return null
+          log(\`ei-persona: injecting \${persona.display_name}\`)
+          return buildEiRelationshipBlock(persona)
+        })())
+      }
+
+      const block = await sessionFetch.get(cacheKey)!
+      sessionCache.set(cacheKey, block)
+      if (block !== null && !output.system[0].includes("<!-- ei-relationship-injected -->"))
+        output.system[0] = output.system[0] + "\\n\\n" + block
+    },
+  }
+}
+`;
+
+  await Bun.write(pluginPath, pluginContent);
+  console.log(`✓ Installed Ei persona plugin to ${pluginPath}`);
+
   const omoCandidates = [
     join(opencodeDir, "oh-my-opencode.json"),
     join(opencodeDir, "oh-my-opencode.jsonc"),
@@ -329,22 +475,18 @@ async function installOpenCodePlugin(): Promise<void> {
   ];
   const hasOmo = (await Promise.all(omoCandidates.map((p) => Bun.file(p).exists()))).some(Boolean);
 
-  if (hasOmo) {
-    console.log(`✓ Oh My OpenCode detected — UserPromptSubmit hook covers OpenCode automatically.`);
-    return;
-  }
-
-  console.log(`
-ℹ️  OpenCode detected without Oh My OpenCode.
-   The ~/.claude/settings.json UserPromptSubmit hook only fires in Claude Code.
-   For the same context injection in OpenCode, we recommend:
+  if (!hasOmo) {
+    console.log(`
+ℹ️  Oh My OpenCode not detected.
+   The Ei persona plugin is installed, but context injection (hook) requires OMO.
+   For full Ei integration in OpenCode, we recommend:
 
      bunx oh-my-opencode install
 
-   Oh My OpenCode is to OpenCode what oh-my-zsh is to zsh — you can run
-   without it, but you probably shouldn't. It also picks up the Ei hook
-   automatically via its Claude Code compatibility layer.
+   OMO picks up the Ei UserPromptSubmit hook automatically via its Claude Code
+   compatibility layer.
 `);
+  }
 }
 
 async function getRecentSessionMessages(

package/src/core/orchestrators/ceremony.ts

@@ -1,4 +1,4 @@
-import { LLMRequestType, LLMPriority, LLMNextStep, RoomMode, ContextStatus, type CeremonyConfig, type PersonaTopic, type Topic } from "../types.js";
+import { LLMRequestType, LLMPriority, LLMNextStep, RoomMode, ContextStatus, type CeremonyConfig, type PersonaTopic, type Topic, type Message } from "../types.js";
 import type { StateManager } from "../state-manager.js";
 import { normalizeRoomMessages } from "../handlers/utils.js";
 import { applyDecayToValue } from "../utils/index.js";
@@ -168,9 +168,9 @@ function queueExposurePhase(personaId: string, state: StateManager, options?: Ex
  * If any ceremony_progress items remain in the queue, does nothing — more work pending.
  * Phase 1: Dedup → Phase 2: Expose → Phase 3: EventSummary → Decay → Phase 4: Person Rewrite → Topic Rewrite (fire-and-forget)
  */
-export function handleCeremonyProgress(state: StateManager, lastPhase: number): void {
+export function handleCeremonyProgress(state: StateManager, lastPhase: number): { wroteEiWarning: boolean } {
   if (state.queue_hasPendingCeremonies()) {
-    return; // Still processing ceremony items
+    return { wroteEiWarning: false }; // Still processing ceremony items
   }
   
   if (lastPhase === 1) {
@@ -232,13 +232,13 @@ export function handleCeremonyProgress(state: StateManager, lastPhase: number):
         console.log(`[ceremony:expose] Queued room persona topic rating: ${personaForRoom.display_name} in "${room.display_name}" (${unprocessedRaw.length} messages)`);
       }
     }
-    return;
+    return { wroteEiWarning: false };
   }
 
   if (lastPhase === 4) {
     console.log("[ceremony:progress] Person Rewrite complete, starting Topic Rewrite");
     queueTopicRewritePhase(state);
-    return;
+    return { wroteEiWarning: false };
   }
 
   if (lastPhase === 2) {
@@ -251,7 +251,7 @@ export function handleCeremonyProgress(state: StateManager, lastPhase: number):
       console.log("[ceremony:progress] No event summary work, advancing to Decay");
       handleCeremonyProgress(state, 3);
     }
-    return;
+    return { wroteEiWarning: false };
   }
   
   // Phase 3 (EventSummary) complete → advance to Decay/Prune then Person Rewrite (phase 4)
@@ -285,9 +285,10 @@ export function handleCeremonyProgress(state: StateManager, lastPhase: number):
   }
 
   // Reflection phase: fire-and-forget critic calls for persona person records above threshold
-  queueReflectionPhase(state);
+  const wroteEiWarning = queueReflectionPhase(state);
 
   console.log("[ceremony:progress] Ceremony Decay complete");
+  return { wroteEiWarning };
 }
 
 // =============================================================================
@@ -446,7 +447,8 @@ export function runHumanCeremony(state: StateManager): void {
 // REWRITE PHASE (fire-and-forget — queues Low-priority Phase 1 scans)
 // =============================================================================
 
-const REWRITE_DESCRIPTION_THRESHOLD = 750;
+const PERSON_REWRITE_DESCRIPTION_THRESHOLD = 1000;
+const TOPIC_REWRITE_DESCRIPTION_THRESHOLD = 750;
 
 /**
  * Forces an unconditional, threshold-bypassing Person scan on Apply/Dismiss.
@@ -494,7 +496,7 @@ export function queuePersonRewritePhase(state: StateManager, options?: { ceremon
       i => i.type.toLowerCase() === 'ei persona'
     );
     return !isPersonaLinked
-      && (person.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD;
+      && (person.description?.length ?? 0) > PERSON_REWRITE_DESCRIPTION_THRESHOLD;
   });
 
   const alreadyChecked = allCandidates.filter(p => {
@@ -520,7 +522,7 @@ export function queuePersonRewritePhase(state: StateManager, options?: { ceremon
     return;
   }
 
-  console.log(`[ceremony:rewrite] Found ${personsToScan.length} person(s) above ${REWRITE_DESCRIPTION_THRESHOLD} chars — queueing person rewrite scans`);
+  console.log(`[ceremony:rewrite] Found ${personsToScan.length} person(s) above ${PERSON_REWRITE_DESCRIPTION_THRESHOLD} chars — queueing person rewrite scans`);
 
   for (const person of personsToScan) {
     const prompt = buildPersonRewriteScanPrompt({ item: person, itemType: "person" });
@@ -552,7 +554,7 @@ export function queueTopicRewritePhase(state: StateManager): void {
 
   const human = state.getHuman();
   const allCandidateTopics = human.topics.filter(topic =>
-    (topic.description?.length ?? 0) > REWRITE_DESCRIPTION_THRESHOLD
+    (topic.description?.length ?? 0) > TOPIC_REWRITE_DESCRIPTION_THRESHOLD
   );
 
   const alreadyCheckedTopics = allCandidateTopics.filter(t => {
@@ -578,7 +580,7 @@ export function queueTopicRewritePhase(state: StateManager): void {
     return;
   }
 
-  console.log(`[ceremony:rewrite] Found ${topicsToScan.length} topic(s) above ${REWRITE_DESCRIPTION_THRESHOLD} chars — queueing topic rewrite scans`);
+  console.log(`[ceremony:rewrite] Found ${topicsToScan.length} topic(s) above ${TOPIC_REWRITE_DESCRIPTION_THRESHOLD} chars — queueing topic rewrite scans`);
 
   for (const topic of topicsToScan) {
     const prompt = buildTopicRewriteScanPrompt({ item: topic, itemType: "topic" });
@@ -615,16 +617,43 @@ function queueEventSummaryForAll(state: StateManager, options?: ExtractionOption
   console.log(`[ceremony:event] Queued event summary scans for ${activePersonas.length} personas (${totalQueued} total chunks)`);
 }
 
-function queueReflectionPhase(state: StateManager): void {
+function queueReflectionPhase(state: StateManager): boolean {
   const personas = state.persona_getAll().filter(p =>
     !p.is_paused && !p.is_archived && !p.is_static
   );
 
+  const human = state.getHuman();
   let queued = 0;
+  let wroteEiWarning = false;
+
   for (const persona of personas) {
-    const personRecord = state.human_person_getByIdentifier("Ei Persona", persona.id);
-    if (!personRecord || (personRecord.description?.length ?? 0) <= PERSON_LOG_REFLECTION_THRESHOLD) continue;
+    const linkedRecords = human.people.filter(p =>
+      p.identifiers?.some(i => i.type.toLowerCase() === 'ei persona' && i.value === persona.id)
+    );
+
+    if (linkedRecords.length === 0) continue;
+
+    const overThreshold = linkedRecords.filter(p => (p.description?.length ?? 0) > PERSON_LOG_REFLECTION_THRESHOLD);
+    if (overThreshold.length === 0) continue;
+
+    if (linkedRecords.length > 1) {
+      const names = linkedRecords.map(p => `"${p.name}"`).join(" and ");
+      console.log(`[ceremony:reflection] ${persona.display_name} is linked to multiple person records (${names}) — skipping reflection, writing Ei warning`);
+
+      const warning: Message = {
+        id: crypto.randomUUID(),
+        role: "system",
+        content: `During today's ceremony, I noticed that **${persona.display_name}** is connected to multiple person records: ${names}. This might be intentional — if you created a composite persona — but if not, you may want to check the identifiers on those records. Reflection for ${persona.display_name} has been paused until this is resolved.`,
+        timestamp: new Date().toISOString(),
+        read: false,
+        context_status: ContextStatus.Always,
+      };
+      state.messages_append("ei", warning);
+      wroteEiWarning = true;
+      continue;
+    }
 
+    const personRecord = linkedRecords[0];
     const prompt = buildReflectionCriticPrompt({
       persona_identity: {
         name: persona.display_name,
@@ -650,7 +679,9 @@ function queueReflectionPhase(state: StateManager): void {
     console.log(`[ceremony:reflection] Queued critic for ${persona.display_name} (person log: ${personRecord.description?.length} chars)`);
   }
 
-  if (queued === 0) {
+  if (queued === 0 && !wroteEiWarning) {
     console.log("[ceremony:reflection] No persona person records above threshold — skipping");
   }
+
+  return wroteEiWarning;
 }

package/src/core/processor.ts

@@ -36,7 +36,8 @@ import { handlers } from "./handlers/index.js";
 import { normalizeRoomMessages, getMessageContent } from "./handlers/utils.js";
 import { sanitizeEiPersonaIdentifiers } from "./utils/identifier-utils.js";
 import { ContextStatus as ContextStatusEnum, RoomMode } from "./types.js";
-import { registerFindMemoryExecutor, registerFetchMemoryExecutor, registerFetchMessageExecutor, registerFileReadExecutor, SYSTEM_TOOLS } from "./tools/index.js";
+import { registerFindMemoryExecutor, registerFetchMemoryExecutor, registerFetchMessageExecutor, registerFileReadExecutor, registerPersonaNoteExecutors, buildPersonaNoteTools, SYSTEM_TOOLS } from "./tools/index.js";
+import { createAddNoteExecutor, createClearNoteExecutor } from "./tools/builtin/persona-notes.js";
 import { createFindMemoryExecutor } from "./tools/builtin/find-memory.js";
 import { createFetchMemoryExecutor } from "./tools/builtin/fetch-memory.js";
 import { createFetchMessageExecutor } from "./tools/builtin/fetch-message.js";
@@ -252,6 +253,10 @@ export class Processor {
     this.seedSettings();
     registerFindMemoryExecutor(createFindMemoryExecutor(this.searchHumanData.bind(this), this.getPersonaList.bind(this), this.stateManager.getHuman.bind(this.stateManager)));
     registerFetchMemoryExecutor(createFetchMemoryExecutor(this.stateManager.getHuman.bind(this.stateManager)));
+    registerPersonaNoteExecutors(
+      createAddNoteExecutor(this.stateManager.persona_getById.bind(this.stateManager), this.stateManager.persona_update.bind(this.stateManager)),
+      createClearNoteExecutor(this.stateManager.persona_getById.bind(this.stateManager), this.stateManager.persona_update.bind(this.stateManager))
+    );
     if (this.isTUI) {
       await registerFileReadExecutor();
       const retrievalPath = "../cli/retrieval.js";
@@ -1414,7 +1419,7 @@ const toolNextSteps = new Set([
                 t.name === "find_memory" || t.name === "fetch_memory" || t.name === "fetch_message"
               );
             } else if (toolNextSteps.has(request.next_step) && toolPersonaId) {
-              tools = [...SYSTEM_TOOLS, ...this.stateManager.tools_getForPersona(toolPersonaId, this.isTUI)];
+              tools = [...SYSTEM_TOOLS, ...buildPersonaNoteTools(toolPersonaId), ...this.stateManager.tools_getForPersona(toolPersonaId, this.isTUI)];
             }
 
             // Auto-inject each handler's dedicated submit tool — infrastructure, not user-visible.
@@ -2103,7 +2108,10 @@ const toolNextSteps = new Set([
       }
 
       if (typeof response.request.data.ceremony_progress === "number") {
-        handleCeremonyProgress(this.stateManager, response.request.data.ceremony_progress);
+        const ceremonyResult = handleCeremonyProgress(this.stateManager, response.request.data.ceremony_progress);
+        if (ceremonyResult.wroteEiWarning) {
+          this.interface.onMessageAdded?.("ei");
+        }
       }
 
       if (response.request.next_step === LLMNextStep.HandleDocumentSegmentation) {

package/src/core/prompt-context-builder.ts

@@ -302,6 +302,7 @@ export async function buildResponsePromptData(
       interested_topics: persona.topics.filter(t => t.exposure_desired - t.exposure_current > 0.2),
       include_message_timestamps: persona.include_message_timestamps,
       pending_update: persona.pending_update,
+      notes: persona.notes,
     },
     human: filteredHuman,
     visible_personas: visiblePersonas,
@@ -395,6 +396,7 @@ export async function buildRoomResponsePromptData(
       traits: respondingPersona.traits,
       topics: respondingPersona.topics,
       include_message_timestamps: respondingPersona.include_message_timestamps,
+      notes: respondingPersona.notes,
     },
     other_participants: otherParticipants,
     human: filteredHuman,

package/src/core/tools/builtin/persona-notes.ts

@@ -0,0 +1,81 @@
+import type { ToolExecutor } from "../types.js";
+import type { PersonaEntity } from "../../types.js";
+
+export const NOTES_MAX = 20;
+
+type GetPersona = (id: string) => PersonaEntity | null;
+type UpdatePersona = (id: string, updates: Partial<PersonaEntity>) => boolean;
+
+export function createAddNoteExecutor(getPersona: GetPersona, updatePersona: UpdatePersona): ToolExecutor {
+  return {
+    name: "add_note",
+
+    async execute(args: Record<string, unknown>, config?: Record<string, string>): Promise<string> {
+      const personaId = config?.persona_id ?? "";
+      const text = typeof args.text === "string" ? args.text.trim() : "";
+      console.log(`[add_note] persona="${personaId}" text="${text.slice(0, 60)}"`);
+
+      if (!personaId) {
+        return JSON.stringify({ error: "Tool misconfigured: missing persona_id" });
+      }
+      if (!text) {
+        return JSON.stringify({ error: "Missing required argument: text" });
+      }
+
+      const persona = getPersona(personaId);
+      if (!persona) {
+        return JSON.stringify({ error: "Persona not found" });
+      }
+
+      const notes = [...(persona.notes ?? [])];
+
+      if (notes.length >= NOTES_MAX) {
+        notes.shift();
+      }
+
+      notes.push(text);
+      updatePersona(personaId, { notes });
+
+      const index = notes.length;
+      console.log(`[add_note] added note at position ${index}/${NOTES_MAX}`);
+      return JSON.stringify({ added: true, index, total: notes.length });
+    },
+  };
+}
+
+export function createClearNoteExecutor(getPersona: GetPersona, updatePersona: UpdatePersona): ToolExecutor {
+  return {
+    name: "clear_note",
+
+    async execute(args: Record<string, unknown>, config?: Record<string, string>): Promise<string> {
+      const personaId = config?.persona_id ?? "";
+      const index = typeof args.index === "number" ? args.index : NaN;
+      console.log(`[clear_note] persona="${personaId}" index=${index}`);
+
+      if (!personaId) {
+        return JSON.stringify({ error: "Tool misconfigured: missing persona_id" });
+      }
+      if (!Number.isInteger(index) || index < 1) {
+        return JSON.stringify({ error: "index must be an integer >= 1" });
+      }
+
+      const persona = getPersona(personaId);
+      if (!persona) {
+        return JSON.stringify({ error: "Persona not found" });
+      }
+
+      const notes = [...(persona.notes ?? [])];
+      const zeroIdx = index - 1;
+
+      if (zeroIdx >= notes.length) {
+        return JSON.stringify({ error: `No note at index ${index} (total: ${notes.length})` });
+      }
+
+      notes.splice(zeroIdx, 1);
+      updatePersona(personaId, { notes });
+
+      console.log(`[clear_note] removed note at index ${index}, remaining=${notes.length}`);
+      return JSON.stringify({ cleared: true, index, remaining: notes.length });
+    },
+  };
+}

package/src/core/tools/index.ts

@@ -12,6 +12,7 @@ import { tavilyWebSearchExecutor, tavilyNewsSearchExecutor } from "./builtin/web
 import { currentlyPlayingExecutor } from "./builtin/currently-playing.js";
 import { likedSongsExecutor } from "./builtin/spotify-liked-songs.js";
 import { webFetchExecutor } from "./builtin/web-fetch.js";
+import { NOTES_MAX } from "./builtin/persona-notes.js";
 // file-read and list-directory are Node-only — imported lazily via registerFileReadExecutor() to avoid
 // file-read and list-directory are Node-only — imported lazily via registerFileReadExecutor() to avoid
 
@@ -128,6 +129,61 @@ export function registerFetchMessageExecutor(executor: ToolExecutor): void {
   executorRegistry.set(executor.name, executor);
 }
 
+export function registerPersonaNoteExecutors(executor1: ToolExecutor, executor2: ToolExecutor): void {
+  executorRegistry.set(executor1.name, executor1);
+  executorRegistry.set(executor2.name, executor2);
+}
+
+/**
+ * Build per-request ToolDefinition objects for the persona notes tools, injecting the
+ * current personaId via config so the shared executor knows which persona to update.
+ */
+export function buildPersonaNoteTools(personaId: string): ToolDefinition[] {
+  const now = new Date(0).toISOString();
+  return [
+    {
+      id: `builtin-add-note-${personaId}`,
+      provider_id: "ei",
+      name: "add_note",
+      display_name: "Add Note",
+      description: `In Ei, your system prompt can change from one turn to the next — Ei is constantly trying to provide you relevant, up-to-date information about the user and the world. If you see something in your system prompt that you don't immediately want to bring up, but want to remember, use this tool to record it for later. Additionally, if you need to remember something but cannot or should not say it directly in conversation, you can use this tool to make a note as well. Notes appear in your system prompt as a numbered list so you always see them. Limit: ${NOTES_MAX} notes (oldest evicted when full).`,
+      input_schema: {
+        type: "object",
+        properties: {
+          text: { type: "string", description: "The note to remember. Keep it concise." },
+        },
+        required: ["text"],
+      },
+      config: { persona_id: personaId },
+      runtime: "any",
+      builtin: true,
+      enabled: true,
+      created_at: now,
+      max_calls_per_interaction: 5,
+    },
+    {
+      id: `builtin-clear-note-${personaId}`,
+      provider_id: "ei",
+      name: "clear_note",
+      display_name: "Clear Note",
+      description: "Remove a note from your scratchpad by its 1-based index (matching the numbered list in your system prompt). Use when you no longer need to track something — e.g., after you've addressed it in conversation.",
+      input_schema: {
+        type: "object",
+        properties: {
+          index: { type: "number", description: "1-based index of the note to remove" },
+        },
+        required: ["index"],
+      },
+      config: { persona_id: personaId },
+      runtime: "any",
+      builtin: true,
+      enabled: true,
+      created_at: now,
+      max_calls_per_interaction: 5,
+    },
+  ];
+}
+
 /**
  * Register the file_read, list_directory, directory_tree, search_files, grep, and get_file_info
  * executors — called by Processor on TUI/Node only.

package/src/core/types/data-items.ts

@@ -75,8 +75,7 @@ export interface Person extends DataItemBase {
 }
 
 export interface Quote {
-  /** @deprecated Remove in v1.6 — use message_id for retrieval */
-  id: string;                    // UUID (use crypto.randomUUID())
+  id: string;                    // UUID — stable identity for CRUD operations (use crypto.randomUUID())
   message_id: string | null;     // FK to Message.id (nullable for manual quotes)
   data_item_ids: string[];       // FK[] to DataItemBase.id
   persona_groups: string[];      // Visibility groups

package/src/core/types/entities.ts

@@ -185,6 +185,7 @@ export interface PersonaEntity {
   avatar_emoji?: string;            // Single emoji character used as avatar in place of initials.
   avatar_image?: string;            // Base64-encoded 64×64 image used as avatar (takes priority over avatar_emoji).
   preferred_theme?: string;         // Theme ID (built-in name or ThemeDefinition.id). Applied to chat panel when this persona is active.
+  notes?: string[];                 // Private scratchpad — up to 20 short-term notes visible in the system prompt. Oldest evicted when full.
 }
 
 export interface PersonaCreationInput {

package/src/integrations/slack/importer.ts

@@ -27,7 +27,6 @@ export interface SlackImportResult {
 function ensureSlackPersona(stateManager: StateManager, eiInterface: Ei_Interface): PersonaEntity {
   const existing = stateManager.persona_getAll().find(p => p.display_name === "Slack");
   if (existing) {
-    if (existing.is_archived) stateManager.persona_unarchive(existing.id);
     return existing;
   }
   const persona: PersonaEntity = {

package/src/prompts/response/index.ts

@@ -11,6 +11,7 @@ import type { ResponsePromptData, PromptOutput } from "./types.js";
 import { formatCurrentTime } from "../../core/format-utils.js";
 import {
   buildIdentitySection,
+  buildNotesSection,
   buildGuidelinesSection,
   buildTraitsSection,
   buildTopicsSection,
@@ -44,6 +45,7 @@ Your role is unique among personas:
   - Consider their traits when building your responses more than the current conversation history
 - You encourage human-to-human connection when appropriate`;
 
+  const notesSection = buildNotesSection(data.persona.notes);
   const guidelines = buildGuidelinesSection("ei");
   const yourTraits = buildTraitsSection(data.persona.traits, "Your Personality");
   const yourTopics = buildTopicsSection(data.persona.topics, "Your Interests");
@@ -63,7 +65,7 @@ Your role is unique among personas:
     : "";
 
   return `${identity}
-
+${notesSection ? `\n${notesSection}` : ""}
 ${guidelines}
 
 ${yourTraits}
@@ -93,6 +95,7 @@ ${conversationState}
  */
 function buildStandardSystemPrompt(data: ResponsePromptData): string {
   const identity = buildIdentitySection(data.persona);
+  const notesSection = buildNotesSection(data.persona.notes);
   const guidelines = buildGuidelinesSection(data.persona.name);
   const yourTraits = buildTraitsSection(data.persona.traits, "Your Personality");
   const yourTopics = buildTopicsSection(data.persona.topics, "Your Interests");
@@ -111,7 +114,7 @@ function buildStandardSystemPrompt(data: ResponsePromptData): string {
     : "";
 
   return `${identity}
-
+${notesSection ? `\n${notesSection}` : ""}
 ${guidelines}
 
 ${yourTraits}

package/src/prompts/response/sections.ts

@@ -33,6 +33,16 @@ export function buildIdentitySection(persona: ResponsePromptData["persona"]): st
 ${description}`;
 }
 
+// =============================================================================
+// NOTES SECTION
+// =============================================================================
+
+export function buildNotesSection(notes: string[] | undefined): string {
+  if (!notes || notes.length === 0) return "";
+  const list = notes.map((n, i) => `${i + 1}. ${n}`).join("\n");
+  return `## Your Notes\n\nThings you've chosen to remember. Use \`clear_note\` once you've addressed something.\n\n${list}`;
+}
+
 // =============================================================================
 // GUIDELINES SECTION
 // =============================================================================

package/src/prompts/response/types.ts

@@ -33,6 +33,7 @@ export interface ResponsePromptData {
     include_message_timestamps?: boolean;
     /** Proposed identity revision pending human review. Persona carries this as ambient self-awareness — no critique, just the proposed changes. */
     pending_update?: PersonaEntity["pending_update"];
+    notes?: string[];
   };
   human: {
     name: string;

package/src/prompts/room/index.ts

@@ -21,6 +21,7 @@ import {
   buildHumanSection,
   buildQuotesSection,
   buildToolsSection,
+  buildNotesSection,
 } from "../response/sections.js";
 
 export type {
@@ -42,6 +43,7 @@ export function buildRoomResponsePrompt(data: RoomResponsePromptData): PromptOut
   const aliasText = persona.aliases.length > 0 ? ` (also known as: ${persona.aliases.join(", ")})` : "";
 
   const identity = `You are ${name}${aliasText}.\n\n${desc}`;
+  const notesSection = buildNotesSection(persona.notes);
   const traits = buildRoomTraitsSection(persona.traits);
   const topics = buildRoomTopicsSection(persona.topics);
   const humanSection = buildHumanSection(human);
@@ -57,6 +59,7 @@ export function buildRoomResponsePrompt(data: RoomResponsePromptData): PromptOut
 
   const system = [
     identity,
+    notesSection,
     traits,
     topics,
     humanSection,

package/src/prompts/room/types.ts

@@ -35,6 +35,7 @@ export interface RoomResponsePromptData {
     traits: PersonaTrait[];
     topics: PersonaTopic[];
     include_message_timestamps?: boolean;
+    notes?: string[];
   };
   other_participants: RoomParticipantIdentity[];
   human: {

package/tui/README.md

@@ -39,7 +39,7 @@ Enable any or all three in `/settings`. They work independently and feed into th
 
 Sessions are processed oldest-first, one per queue cycle. On first run Ei works through your backlog gradually — it won't flood your LLM provider.
 
-OpenCode also supports reading Ei's extracted knowledge back out via the [CLI tool](../src/cli/README.md), giving it persistent memory across sessions.
+All three tools also support reading Ei's knowledge back out via the [CLI tool](../src/cli/README.md) — run `ei --install` to wire up automatic context injection (hooks + persona plugin) so your coding agents receive relevant Ei memory before every message without any manual tool calls.
 
 ## Slack Integration