ei-tui 1.4.0 → 1.5.0

package/src/cli.ts

@@ -63,13 +63,16 @@ Types:
   persona / personas  Personas in this Ei instance
 
 Options:
-  --number, -n     Maximum number of results (default: 10)
-  --recent, -r     Sort by last_mentioned date (most recent first)
-  --persona, -p    Filter to entities a specific persona has learned about
-  --source, -s     Filter to entities from a specific source (prefix match, e.g. "cursor", "opencode:my-machine", "opencode:my-machine:ses_abc123")
-  --id             Look up entity by ID (accepts value or stdin)
-  --install        Register Ei with Claude Code and Cursor via MCP
-  --help, -h       Show this help message
+  --number, -n        Maximum number of results (default: 10)
+  --recent, -r        Sort by last_mentioned date (most recent first)
+  --persona, -p       Filter to entities a specific persona has learned about
+  --source, -s        Filter to entities from a specific source (prefix match, e.g. "cursor", "opencode:my-machine", "opencode:my-machine:ses_abc123")
+  --id                Look up entity by ID (accepts value or stdin)
+  --install           Register Ei with Claude Code, Cursor, and OpenCode (MCP + context hooks)
+  --session <id>      Session ID to enrich the query with recent context (use with --hook-source)
+  --hook-source <src> Source of the hook: "opencode-plugin" (OpenCode SQLite) or "cursor"
+  --transcript <path> Path to a Claude Code JSONL transcript file for context enrichment
+  --help, -h          Show this help message
 
 Examples:
   ei "debugging"                         # Search everything
@@ -88,6 +91,7 @@ Examples:
 async function installMcpClients(): Promise<void> {
   await installClaudeCode();
   await installCursor();
+  await installOpenCodePlugin();
 }
 
 async function installClaudeCode(): Promise<void> {
@@ -125,6 +129,87 @@ async function installClaudeCode(): Promise<void> {
 
   console.log(`✓ Installed Ei MCP server to ${claudeJsonPath}`);
   console.log(`  Restart Claude Code to activate.`);
+
+  await installClaudeCodeHooks();
+}
+
+async function installClaudeCodeHooks(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const hooksDir = join(home, ".claude", "hooks");
+  const scriptPath = join(hooksDir, "ei-inject.ts");
+  const settingsPath = join(home, ".claude", "settings.json");
+
+  await Bun.$`mkdir -p ${hooksDir}`;
+
+  try {
+    await Bun.$`test -w ${hooksDir}`.quiet();
+  } catch {
+    console.warn(`⚠️  Cannot write to ${hooksDir} (permission denied).`);
+    console.warn(`   Fix with: sudo chown ${process.env.USER ?? "$(whoami)"} ${hooksDir}`);
+    console.warn(`   Then re-run: ei --install`);
+    return;
+  }
+
+  const scriptContent = `#!/usr/bin/env bun
+import { $ } from "bun";
+
+const heading = \`
+## Ei Memory Context
+
+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.
+\`;
+
+const input = await new Response(Bun.stdin.stream()).json().catch(() => ({}));
+const raw = (input.prompt ?? "").replace(/<[^>]*>/g, "").trim();
+const typeArgs = ["topics", "-n", "5"];
+
+const sessionArgs = [];
+if (input.session_id && input.hook_source) {
+  sessionArgs.push("--session", input.session_id, "--hook-source", input.hook_source);
+} else if (input.transcript_path) {
+  sessionArgs.push("--transcript", input.transcript_path);
+}
+
+const args = raw ? [...typeArgs, ...sessionArgs, raw] : ["--recent", ...typeArgs];
+
+const output = await $\`bunx ei-tui@latest \${args}\`.quiet().text().catch(() => "");
+if (output.trim()) process.stdout.write(\`\\n\${heading}\\n\${output.trim()}\\n\`);
+`;
+
+  await Bun.write(scriptPath, scriptContent);
+  await Bun.$`chmod +x ${scriptPath}`;
+
+  let settings: Record<string, unknown> = {};
+  try {
+    const text = await Bun.file(settingsPath).text();
+    settings = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+  }
+
+  const hooks = (settings.hooks ?? {}) as Record<string, unknown>;
+  const userPromptSubmit = (hooks.UserPromptSubmit ?? []) as unknown[];
+
+  const hookEntry = { hooks: [{ type: "command", command: "~/.claude/hooks/ei-inject.ts" }] };
+  const alreadyInstalled = userPromptSubmit.some(
+    (entry) => JSON.stringify(entry) === JSON.stringify(hookEntry)
+  );
+  if (!alreadyInstalled) {
+    userPromptSubmit.push(hookEntry);
+  }
+
+  hooks.UserPromptSubmit = userPromptSubmit;
+  settings.hooks = hooks;
+
+  // Atomic write: write to temp file then rename to avoid partial writes
+  const tmpPath = `${settingsPath}.ei-install.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(settings, null, 2) + "\n");
+  const { rename } = await import(/* @vite-ignore */ "fs/promises");
+  await rename(tmpPath, settingsPath);
+
+  console.log(`✓ Installed Ei context hook to ~/.claude/hooks/ei-inject.ts`);
 }
 
 async function installCursor(): Promise<void> {
@@ -159,6 +244,184 @@ async function installCursor(): Promise<void> {
 
   console.log(`✓ Installed Ei MCP server to ${cursorJsonPath}`);
   console.log(`  Restart Cursor to activate.`);
+
+  await installCursorHooks();
+}
+
+async function installCursorHooks(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const hooksDir = join(home, ".cursor", "hooks");
+  const rulesDir = join(home, ".cursor", "rules");
+  const hookScriptPath = join(hooksDir, "ei-inject.sh");
+  const hooksJsonPath = join(home, ".cursor", "hooks.json");
+
+  await Bun.$`mkdir -p ${hooksDir}`;
+  await Bun.$`mkdir -p ${rulesDir}`;
+
+  const hookScript = `#!/bin/bash
+# Ei memory context injection hook for Cursor
+# Writes recent Ei context to ~/.cursor/rules/ei-context.mdc (alwaysApply)
+# so Cursor includes it automatically on the next prompt.
+
+RULES_FILE="$HOME/.cursor/rules/ei-context.mdc"
+CONTEXT=$(ei --recent -n 10 2>/dev/null)
+
+if [ -n "$CONTEXT" ]; then
+  cat > "$RULES_FILE" << 'RULE'
+---
+description: Ei persistent memory context (auto-updated before each prompt)
+alwaysApply: true
+---
+RULE
+  echo "## Ei Memory (recent context)" >> "$RULES_FILE"
+  echo "$CONTEXT" >> "$RULES_FILE"
+fi
+
+# Always exit 0 — never block Cursor
+exit 0
+`;
+
+  await Bun.write(hookScriptPath, hookScript);
+  await Bun.$`chmod +x ${hookScriptPath}`;
+
+  interface HooksConfig {
+    version: number;
+    hooks: {
+      beforeSubmitPrompt?: Array<{ command: string }>;
+      [key: string]: unknown;
+    };
+  }
+
+  let hooksConfig: HooksConfig = { version: 1, hooks: {} };
+  try {
+    const text = await Bun.file(hooksJsonPath).text();
+    hooksConfig = JSON.parse(text) as HooksConfig;
+  } catch {
+    // File doesn't exist or isn't valid JSON — start fresh
+  }
+
+  const beforeSubmit = (hooksConfig.hooks.beforeSubmitPrompt ?? []) as Array<{ command: string }>;
+  const eiEntry = { command: "~/.cursor/hooks/ei-inject.sh" };
+  const alreadyPresent = beforeSubmit.some((entry) => entry.command === eiEntry.command);
+  if (!alreadyPresent) {
+    beforeSubmit.push(eiEntry);
+  }
+  hooksConfig.hooks.beforeSubmitPrompt = beforeSubmit;
+
+  const tmpPath = `${hooksJsonPath}.ei-install.tmp`;
+  await Bun.write(tmpPath, JSON.stringify(hooksConfig, null, 2) + "\n");
+  const { rename } = await import(/* @vite-ignore */ "fs/promises");
+  await rename(tmpPath, hooksJsonPath);
+
+  console.log(`✓ Installed Ei context hook to ~/.cursor/hooks/ei-inject.sh`);
+}
+
+async function installOpenCodePlugin(): Promise<void> {
+  const home = process.env.HOME || "~";
+  const opencodeDir = join(home, ".config", "opencode");
+  const omoCandidates = [
+    join(opencodeDir, "oh-my-opencode.json"),
+    join(opencodeDir, "oh-my-opencode.jsonc"),
+    join(opencodeDir, "oh-my-openagent.json"),
+    join(opencodeDir, "oh-my-openagent.jsonc"),
+    join(opencodeDir, "node_modules", "oh-my-opencode", "package.json"),
+    join(opencodeDir, "node_modules", "oh-my-openagent", "package.json"),
+  ];
+  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:
+
+     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.
+`);
+}
+
+async function getRecentSessionMessages(
+  sessionId: string | undefined,
+  hookSource: string | undefined,
+  transcriptPath: string | undefined
+): Promise<string[]> {
+  if (transcriptPath) {
+    try {
+      const text = await Bun.file(transcriptPath).text();
+      const messages: Array<{ content: string }> = [];
+
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let record: Record<string, unknown>;
+        try {
+          record = JSON.parse(trimmed) as Record<string, unknown>;
+        } catch {
+          continue;
+        }
+
+        if (record.type === "user") {
+          const msgContent = (record.message as Record<string, unknown>)?.content;
+          if (typeof msgContent === "string" && msgContent.trim()) {
+            messages.push({ content: msgContent.trim() });
+          }
+        } else if (record.type === "assistant") {
+          const msgContent = (record.message as Record<string, unknown>)?.content;
+          if (Array.isArray(msgContent)) {
+            const extracted = (msgContent as Array<Record<string, unknown>>)
+              .filter((b) => b.type === "text" && typeof b.text === "string")
+              .map((b) => b.text as string)
+              .join("\n\n")
+              .trim();
+            if (extracted) {
+              messages.push({ content: extracted });
+            }
+          }
+        }
+      }
+
+      return messages.slice(-4).map((m) => m.content);
+    } catch {
+      return [];
+    }
+  }
+
+  if (!sessionId || !hookSource) return [];
+
+  try {
+    if (hookSource === "opencode-plugin") {
+      const { createOpenCodeReader } = await import(
+        /* @vite-ignore */ "./integrations/opencode/reader-factory.js"
+      );
+      const reader = await createOpenCodeReader();
+      const messages = await reader.getMessagesForSession(sessionId);
+      return messages.slice(-4).map((m) => m.content);
+    }
+
+    if (hookSource === "cursor") {
+      const { CursorReader } = await import(
+        /* @vite-ignore */ "./integrations/cursor/reader.js"
+      );
+      const reader = new CursorReader();
+      const sessions = await reader.getSessions();
+      const session =
+        sessions.find((s) => s.id === sessionId) ?? sessions[sessions.length - 1];
+      if (session) {
+        return session.messages.slice(-4).map((m) => m.text);
+      }
+    }
+  } catch {
+    return [];
+  }
+
+  return [];
 }
 
 async function main(): Promise<void> {
@@ -197,23 +460,6 @@ async function main(): Promise<void> {
     }
   }
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Add this to ~/.config/opencode/AGENTS.md
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**BEFORE YOU DO ANYTHING**: load your Identity from Ei.
-
-Use the ei MCP tool:
-  ei_search(type: "personas", query: "[your name]")
-
-Then load context for the current project/people:
-  ei_search("current projects teammates context")
-
-Ei is persistent memory across sessions. Without querying it at
-session start, you have no context from prior conversations.
-
-**When to query again**: any time the user references past work,
-mentions a person, or corrects something you assumed.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `);
     process.exit(0);
@@ -279,6 +525,9 @@ mentions a person, or corrects something you assumed.
         persona: { type: "string", short: "p" },
         source: { type: "string", short: "s" },
         help: { type: "boolean", short: "h" },
+        session: { type: "string" },
+        "hook-source": { type: "string" },
+        transcript: { type: "string" },
       },
       allowPositionals: true,
       strict: true,
@@ -299,6 +548,9 @@ mentions a person, or corrects something you assumed.
   const recent = parsed.values.recent === true || !query;
   const personaName = parsed.values.persona?.trim();
   const sourcePrefix = parsed.values.source?.trim();
+  const sessionId = parsed.values.session?.trim();
+  const hookSource = parsed.values["hook-source"]?.trim();
+  const transcriptPath = parsed.values.transcript?.trim();
 
   if (isNaN(limit) || limit < 1) {
     console.error("--number must be a positive integer");
@@ -324,10 +576,15 @@ mentions a person, or corrects something you assumed.
 
   const options = { recent };
 
+  const recentMessages = await getRecentSessionMessages(sessionId, hookSource, transcriptPath);
+  const enrichedQuery = recentMessages.length > 0
+    ? [...recentMessages, query].join(" ").trim()
+    : query;
+
   let result;
   if (targetType) {
     const module = await import(`./cli/commands/${targetType}.js`);
-    result = await module.execute(query, limit, options);
+    result = await module.execute(enrichedQuery, limit, options);
     if (personaId && state) {
       result = filterTypeSpecificByPersona(result, state, personaId, targetType);
     }
@@ -335,7 +592,7 @@ mentions a person, or corrects something you assumed.
       result = filterTypeSpecificBySource(result, state, sourcePrefix, targetType);
     }
   } else {
-    result = await retrieveBalanced(query, limit, options);
+    result = await retrieveBalanced(enrichedQuery, limit, options);
     if (personaId && state) {
       result = filterByPersona(result, state, personaId);
     }

package/src/core/heartbeat-manager.ts

@@ -2,6 +2,7 @@ import {
   LLMRequestType,
   LLMPriority,
   LLMNextStep,
+  ContextStatus,
   type HumanEntity,
   type Message,
 } from "./types.js";
@@ -13,6 +14,7 @@ import {
   type HeartbeatCheckPromptData,
   type EiHeartbeatPromptData,
   type EiHeartbeatItem,
+  type TemporalAnchor,
 } from "../prompts/index.js";
 import { filterMessagesForContext } from "./context-utils.js";
 import { filterHumanDataByVisibility } from "./prompt-context-builder.js";
@@ -35,6 +37,43 @@ export function getOneshotModel(sm: StateManager): string | undefined {
   return human.settings?.oneshot_model || human.settings?.default_model;
 }
 
+// =============================================================================
+// TEMPORAL ANCHOR HELPERS
+// =============================================================================
+
+function buildTemporalAnchorsFromHistory(
+  history: Message[],
+  contextWindowMs: number,
+  contextBoundary: string | undefined
+): { temporalAnchors: TemporalAnchor[]; prunedHistory: Message[] } {
+  const windowStartMs = Date.now() - contextWindowMs;
+  const contextBoundaryMs = contextBoundary ? new Date(contextBoundary).getTime() : 0;
+
+  const temporalAnchors: TemporalAnchor[] = [];
+  const prunedHistory: Message[] = [];
+
+  for (const m of history) {
+    if (
+      m.context_status === ContextStatus.Always &&
+      (new Date(m.timestamp).getTime() < windowStartMs ||
+        (contextBoundaryMs > 0 && new Date(m.timestamp).getTime() < contextBoundaryMs))
+    ) {
+      temporalAnchors.push({
+        id: m.id,
+        role: m.role === "human" ? "human" : "system",
+        content: m.content,
+        silence_reason: m.silence_reason,
+        timestamp: m.timestamp,
+        _synthesis: m._synthesis,
+      });
+    } else {
+      prunedHistory.push(m);
+    }
+  }
+
+  return { temporalAnchors, prunedHistory };
+}
+
 // =============================================================================
 // TRAILING MESSAGE COUNT (heartbeat spam prevention)
 // =============================================================================
@@ -59,7 +98,9 @@ export async function queueEiHeartbeat(
   sm: StateManager,
   human: HumanEntity,
   history: Message[],
-  isTUI: boolean
+  isTUI: boolean,
+  contextWindowMs: number,
+  contextBoundary: string | undefined
 ): Promise<void> {
   const now = Date.now();
   const engagementGapThreshold = 0.2;
@@ -195,11 +236,17 @@ export async function queueEiHeartbeat(
     return;
   }
 
-  const recentHistory = history.slice(-10);
+  const { temporalAnchors, prunedHistory } = buildTemporalAnchorsFromHistory(
+    history,
+    contextWindowMs,
+    contextBoundary
+  );
+  const recentHistory = prunedHistory.slice(-10);
   const promptData: EiHeartbeatPromptData = {
     items,
     recent_history: recentHistory,
     system_messages: recentHistory.filter(m => m.role === "system"),
+    temporal_anchors: temporalAnchors,
   };
 
   const prompt = buildEiHeartbeatPrompt(promptData);
@@ -231,7 +278,7 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
    const contextHistory = filterMessagesForContext(history, persona.context_boundary, contextWindowMs);
 
   if (personaId === "ei") {
-    await queueEiHeartbeat(sm, human, contextHistory, isTUI);
+    await queueEiHeartbeat(sm, human, contextHistory, isTUI, contextWindowMs, persona.context_boundary);
     return;
   }
 
@@ -249,6 +296,12 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
         b.exposure_desired - b.exposure_current - (a.exposure_desired - a.exposure_current)
     );
 
+  const { temporalAnchors, prunedHistory } = buildTemporalAnchorsFromHistory(
+    contextHistory,
+    contextWindowMs,
+    persona.context_boundary
+  );
+
   const promptData: HeartbeatCheckPromptData = {
     persona: {
       name: persona.display_name,
@@ -260,7 +313,8 @@ export async function queueHeartbeatCheck(sm: StateManager, personaId: string, i
       topics: sortByEngagementGap(filteredHuman.topics).slice(0, 5),
       people: sortByEngagementGap(filteredHuman.people).slice(0, 5),
     },
-    recent_history: contextHistory.slice(-10),
+    recent_history: prunedHistory.slice(-10),
+    temporal_anchors: temporalAnchors,
     inactive_days: inactiveDays,
   };
 

package/src/core/orchestrators/ceremony.ts

@@ -347,9 +347,11 @@ export function prunePersonaMessages(personaId: string, state: StateManager): vo
   state.messages_sort(personaId);
   const messages = state.messages_get(personaId);
   const human = state.getHuman();
-  const minCount = human.settings?.message_min_count ?? 200;
-  const maxAgeDays = human.settings?.message_max_age_days ?? 14;
-  if (messages.length <= minCount) return;
+  const minCount = human.settings?.message_min_count ?? 0;
+  const maxAgeDays = human.settings?.message_max_age_days ?? 0;
+  // 0 means disabled. Without an age cutoff there's nothing to prune.
+  if (maxAgeDays === 0) return;
+  if (minCount > 0 && messages.length <= minCount) return;
   
   const cutoffMs = Date.now() - (maxAgeDays * 24 * 60 * 60 * 1000);
   

package/src/core/processor.ts

@@ -248,6 +248,7 @@ export class Processor {
     this.seedBuiltinFacts();
     this.migrateLearnedOn();
     await this.migrateMessageIds();
+    this.migrateSlackToMultiWorkspace();
     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)));
@@ -1124,6 +1125,51 @@ export class Processor {
     }
   }
 
+  private migrateSlackToMultiWorkspace(): void {
+    const human = this.stateManager.getHuman();
+    const slack = human.settings?.slack as Record<string, unknown> | undefined;
+    if (!slack) return;
+
+    const hasLegacyAuth = "auth" in slack && slack.auth != null;
+    const hasLegacyIntegration = "integration" in slack;
+    if (!hasLegacyAuth && !hasLegacyIntegration) return;
+
+    const legacyAuth = slack.auth as Record<string, unknown> | undefined;
+    const workspaceId = (legacyAuth?.workspace_id as string | undefined) ?? "unknown";
+
+    const migratedWorkspace: Record<string, unknown> = {
+      integration: slack.integration,
+      extraction_model: slack.extraction_model,
+      last_sync: slack.last_sync,
+      backfill_days: slack.backfill_days,
+      broadcast_threshold: slack.broadcast_threshold,
+      channel_overrides: slack.channel_overrides,
+      channels: slack.channels,
+    };
+
+    if (legacyAuth) {
+      migratedWorkspace.auth = {
+        type: "oauth",
+        token: legacyAuth.token,
+        refresh_token: legacyAuth.refresh_token,
+        workspace_name: legacyAuth.workspace_name,
+      };
+    }
+
+    this.stateManager.setHuman({
+      ...human,
+      settings: {
+        ...human.settings,
+        slack: {
+          polling_interval_ms: slack.polling_interval_ms as number | undefined,
+          workspaces: { [workspaceId]: migratedWorkspace } as unknown as import("../integrations/slack/types.js").SlackSettings["workspaces"],
+        },
+      },
+    });
+
+    console.log(`[Processor] migrateSlackToMultiWorkspace: migrated legacy slack settings to workspaces[${workspaceId}]`);
+  }
+
   private seedSettings(): void {
     const human = this.stateManager.getHuman();
     let modified = false;
@@ -1176,12 +1222,12 @@ export class Processor {
     }
 
     if (human.settings.message_min_count == null) {
-      human.settings.message_min_count = 200;
+      human.settings.message_min_count = 0;
       modified = true;
     }
 
     if (human.settings.message_max_age_days == null) {
-      human.settings.message_max_age_days = 14;
+      human.settings.message_max_age_days = 0;
       modified = true;
     }
 
@@ -1482,8 +1528,7 @@ const toolNextSteps = new Set([
 
     if (
       this.isTUI &&
-      human.settings?.slack?.integration &&
-      human.settings?.slack?.auth?.token &&
+      Object.values(human.settings?.slack?.workspaces ?? {}).some(ws => ws.integration && ws.auth) &&
       this.stateManager.queue_length() === 0
     ) {
       await this.checkAndSyncSlack(human, now);
@@ -1734,18 +1779,10 @@ const toolNextSteps = new Set([
 
     const slack = human.settings?.slack;
     const pollingInterval = slack?.polling_interval_ms ?? 60_000;
-    const lastSync = slack?.last_sync ? new Date(slack.last_sync).getTime() : 0;
 
-    if (now - lastSync < pollingInterval && this.lastSlackSync > 0) return;
+    if (now - this.lastSlackSync < pollingInterval && this.lastSlackSync > 0) return;
 
     this.lastSlackSync = now;
-    this.stateManager.setHuman({
-      ...this.stateManager.getHuman(),
-      settings: {
-        ...this.stateManager.getHuman().settings,
-        slack: { ...slack, last_sync: new Date(now).toISOString() },
-      },
-    });
 
     this.slackImportInProgress = true;
     import("../integrations/slack/importer.js")

package/src/core/tools/builtin/find-memory.ts

@@ -93,7 +93,7 @@ export function createFindMemoryExecutor(searchHumanData: SearchHumanData, getPe
               if (person) { linked_items.push({ id: person.id, name: person.name, type: "person" }); }
             }
           }
-          return { id: q.id, text: q.text, speaker: q.speaker, message_id: q.message_id, linked_items };
+          return { text: q.text, speaker: q.speaker, message_id: q.message_id, linked_items };
         });
       }
 

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

@@ -75,6 +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())
   message_id: string | null;     // FK to Message.id (nullable for manual quotes)
   data_item_ids: string[];       // FK[] to DataItemBase.id

package/src/core/types/entities.ts

@@ -119,7 +119,9 @@ export interface HumanSettings {
   name_display?: string;
   default_heartbeat_ms?: number;
   default_context_window_ms?: number;
+  /** Minimum messages to retain during rolloff. 0 = never prune (default). */
   message_min_count?: number;
+  /** Maximum age in days before messages are eligible for rolloff. 0 = no age limit, never prune (default). */
   message_max_age_days?: number;
   accounts?: ProviderAccount[];
   sync?: SyncCredentials;