pi-hermes-memory 0.7.17 → 0.7.19

package/README.md

@@ -283,7 +283,7 @@ Search behavior notes:
 - Exact phrases can be requested with quotes, for example `"memory search"`.
 - Advanced FTS queries with operators like `OR` still work when you need them.
 
-Session history is indexed automatically on session shutdown. To bulk-import existing sessions:
+Session history is indexed automatically during the active session and on session shutdown. Startup also runs a bounded incremental backfill for missed sessions: it compares stored file metadata and only parses files without matching metadata, capped per startup. To bulk-import existing sessions manually:
 
 ```
 /memory-index-sessions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.7.17",
+  "version": "0.7.19",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. Token-aware policy-only memory by default, SQLite FTS5 search, auto-consolidation, procedural skills. 368 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/handlers/pi-child-process.ts

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { MemoryConfig, ThinkingLevel } from "../types.js";
 
@@ -15,9 +18,32 @@ interface ExecChildPromptOptions {
   retryWithoutOverrides?: boolean;
 }
 
+export interface ChildPiInvocation {
+  command: string;
+  args: string[];
+}
+
+interface ResolveChildPiInvocationOptions {
+  platform?: NodeJS.Platform;
+  execPath?: string;
+  argv?: string[];
+  piCliPath?: string | null;
+}
+
 const OVERRIDE_FAILURE_SUBJECT = /\b(model|provider|thinking)\b/i;
 const OVERRIDE_FAILURE_REASON = /\b(not found|unknown|invalid|unsupported|unavailable|unrecognized|no match|no matches|cannot resolve|failed to resolve)\b/i;
 
+// Resolve the path to pi-hermes-memory's own extension entry point.
+// Used to pass -e <path> to child subprocesses so they only load this
+// extension instead of all plugins from settings.json.
+const OWN_EXTENSION_PATH: string = (() => {
+  try {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "../index.ts");
+  } catch {
+    return "";
+  }
+})();
+
 function normalizedModelOverride(config: ChildLlmConfig): string | undefined {
   const trimmed = config.llmModelOverride?.trim();
   return trimmed ? trimmed : undefined;
@@ -31,6 +57,7 @@ export function hasChildLlmOverrides(config: ChildLlmConfig): boolean {
   return normalizedModelOverride(config) !== undefined || effectiveThinkingOverride(config) !== undefined;
 }
 
+/** @deprecated No longer called after PR #78 — kept for API backward compat. */
 export function inheritedExtensionArgs(argv: string[] = process.argv.slice(2)): string[] {
   const args: string[] = [];
 
@@ -53,22 +80,86 @@ export function inheritedExtensionArgs(argv: string[] = process.argv.slice(2)):
   return args;
 }
 
-export function buildChildPiPromptArgs(prompt: string, config: ChildLlmConfig, argv: string[] = process.argv.slice(2)): string[] {
+function appendOwnExtensionArgs(args: string[]): void {
+  // Skip all packages from settings.json (--no-extensions) — the subprocess
+  // only needs pi-hermes-memory to access the memory tool. Loading every
+  // plugin (context-mode, pi-lens, pi-web-access, pi-review, …) wastes
+  // prompt tokens and startup CPU for simple one-shot memory tasks.
+  if (OWN_EXTENSION_PATH) {
+    args.push("--no-extensions", "-e", OWN_EXTENSION_PATH);
+  }
+}
+
+export function buildChildPiPromptArgs(prompt: string, config: ChildLlmConfig, _argv?: string[]): string[] {
   const args = ["-p", "--no-session"];
   const model = normalizedModelOverride(config);
   const thinking = effectiveThinkingOverride(config);
-  const inheritedExtensions = inheritedExtensionArgs(argv);
 
   if (model) args.push("--model", model);
   if (thinking) args.push("--thinking", thinking);
-  args.push(...inheritedExtensions);
+  appendOwnExtensionArgs(args);
   args.push(prompt);
 
   return args;
 }
 
 function basePromptArgs(prompt: string): string[] {
-  return ["-p", "--no-session", prompt];
+  // Always use --no-extensions + own path so the retry also avoids loading
+  // all settings.json packages — matching the primary code path.
+  const args = ["-p", "--no-session"];
+  appendOwnExtensionArgs(args);
+  args.push(prompt);
+  return args;
+}
+
+function isCliJsPath(value: string | undefined): value is string {
+  if (!value) return false;
+  return value.replace(/\\/g, "/").toLowerCase().endsWith("/cli.js");
+}
+
+function resolvedInstalledPiCliPath(): string | undefined {
+  try {
+    const packageEntry = import.meta.resolve("@earendil-works/pi-coding-agent");
+    const entryPath = fileURLToPath(packageEntry);
+    const cliPath = join(dirname(entryPath), "cli.js");
+    return existsSync(cliPath) ? cliPath : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvedPiCliPath(options: ResolveChildPiInvocationOptions): string | undefined {
+  if (options.piCliPath !== undefined) {
+    return options.piCliPath ?? undefined;
+  }
+
+  const argv = options.argv ?? process.argv;
+  const currentCli = argv[1];
+  if (isCliJsPath(currentCli) && existsSync(currentCli)) {
+    return currentCli;
+  }
+
+  return resolvedInstalledPiCliPath();
+}
+
+export function resolveChildPiInvocation(
+  args: string[],
+  options: ResolveChildPiInvocationOptions = {},
+): ChildPiInvocation {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "win32") {
+    return { command: "pi", args };
+  }
+
+  const piCliPath = resolvedPiCliPath(options);
+  if (!piCliPath) {
+    return { command: "pi", args };
+  }
+
+  return {
+    command: options.execPath ?? process.execPath,
+    args: [piCliPath, ...args],
+  };
 }
 
 function shouldRetryWithoutOverridesFromText(text: string | undefined): boolean {
@@ -96,7 +187,8 @@ export async function execChildPrompt(
   };
 
   try {
-    const result = await pi.exec("pi", buildChildPiPromptArgs(prompt, config), execOptions) as PiExecResult;
+    const invocation = resolveChildPiInvocation(buildChildPiPromptArgs(prompt, config));
+    const result = await pi.exec(invocation.command, invocation.args, execOptions) as PiExecResult;
     if (
       result.code === 0 ||
       !options.retryWithoutOverrides ||
@@ -115,5 +207,6 @@ export async function execChildPrompt(
     }
   }
 
-  return pi.exec("pi", basePromptArgs(prompt), execOptions) as Promise<PiExecResult>;
+  const retryInvocation = resolveChildPiInvocation(basePromptArgs(prompt));
+  return pi.exec(retryInvocation.command, retryInvocation.args, execOptions) as Promise<PiExecResult>;
 }

package/src/handlers/session-backfill.ts

@@ -0,0 +1,139 @@
+import type { DatabaseManager } from '../store/db.js';
+import {
+  indexChangedSessions,
+  needsBackfill,
+  touchBackfillTimestamp,
+  type BulkIndexResult,
+} from '../store/session-indexer.js';
+
+export const SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS = 5000;
+export const SESSION_BACKFILL_MAX_FILES = 50;
+
+type NotifyLevel = 'info' | 'warning' | 'error';
+type NotifyFn = (message: string, level: NotifyLevel) => void;
+
+type SetTimeoutFn = (callback: () => void, ms: number) => unknown;
+
+export interface SessionBackfillState {
+  inProgress: boolean;
+  promise: Promise<void> | null;
+}
+
+export const sessionBackfillState: SessionBackfillState = {
+  inProgress: false,
+  promise: null,
+};
+
+export interface ScheduleSessionBackfillOptions {
+  notify?: NotifyFn;
+  state?: SessionBackfillState;
+  setTimeoutFn?: SetTimeoutFn;
+  needsBackfillFn?: typeof needsBackfill;
+  indexSessionsFn?: typeof indexChangedSessions;
+  maxFilesToIndex?: number;
+  touchBackfillTimestampFn?: typeof touchBackfillTimestamp;
+}
+
+function formatBackfillResult(result: BulkIndexResult): string {
+  const errorSuffix = result.errors.length > 0 ? ` (${result.errors.length} file error${result.errors.length === 1 ? '' : 's'})` : '';
+  const limitSuffix = result.reachedLimit ? ' (startup limit reached)' : '';
+  return `🧠 Session backfill complete: ${result.sessionsIndexed} indexed, ${result.sessionsSkipped} skipped, ${result.messagesIndexed} messages${errorSuffix}${limitSuffix}.`;
+}
+
+function notifyBestEffort(notify: NotifyFn | undefined, message: string, level: NotifyLevel): void {
+  try {
+    notify?.(message, level);
+  } catch {
+    // Notification failures must never affect backfill.
+  }
+}
+
+/**
+ * Schedule a best-effort, bounded incremental backfill of unindexed Pi sessions.
+ *
+ * The JSONL parsing work is deferred with setTimeout(0) so session_start can
+ * resolve first. The scheduled pass only parses files without matching stored
+ * metadata and caps the number of files parsed per startup.
+ *
+ * @returns true when a backfill task was scheduled; false when it was skipped.
+ */
+export function scheduleSessionBackfill(
+  dbManager: DatabaseManager,
+  sessionsDir: string,
+  options: ScheduleSessionBackfillOptions = {},
+): boolean {
+  const state = options.state ?? sessionBackfillState;
+  const setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+  const needsBackfillFn = options.needsBackfillFn ?? needsBackfill;
+  const indexSessionsFn = options.indexSessionsFn ?? indexChangedSessions;
+  const maxFilesToIndex = options.maxFilesToIndex ?? SESSION_BACKFILL_MAX_FILES;
+  const touchBackfillTimestampFn = options.touchBackfillTimestampFn ?? touchBackfillTimestamp;
+
+  if (state.inProgress) {
+    return false;
+  }
+
+  try {
+    if (!needsBackfillFn(dbManager, sessionsDir)) {
+      return false;
+    }
+  } catch (err) {
+    notifyBestEffort(
+      options.notify,
+      `⚠️ Session backfill check failed: ${err instanceof Error ? err.message : String(err)}`,
+      'warning',
+    );
+    return false;
+  }
+
+  state.inProgress = true;
+  state.promise = new Promise<void>((resolve) => {
+    setTimeoutFn(() => {
+      try {
+        const result = indexSessionsFn(dbManager, sessionsDir, { maxFilesToIndex });
+        if (!result.reachedLimit) touchBackfillTimestampFn(dbManager);
+        notifyBestEffort(options.notify, formatBackfillResult(result), result.errors.length > 0 || result.reachedLimit ? 'warning' : 'info');
+      } catch (err) {
+        notifyBestEffort(
+          options.notify,
+          `⚠️ Session backfill failed: ${err instanceof Error ? err.message : String(err)}`,
+          'warning',
+        );
+      } finally {
+        state.inProgress = false;
+        state.promise = null;
+        resolve();
+      }
+    }, 0);
+  });
+
+  return true;
+}
+
+/**
+ * Wait briefly for an in-progress backfill before shutdown closes SQLite.
+ *
+ * @returns true if no backfill was running or it completed before the timeout;
+ * false if the timeout elapsed first.
+ */
+export async function waitForSessionBackfill(
+  timeoutMs = SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS,
+  state: SessionBackfillState = sessionBackfillState,
+): Promise<boolean> {
+  const promise = state.promise;
+  if (!state.inProgress || !promise) {
+    return true;
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise.then(() => true),
+      new Promise<boolean>((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}

package/src/handlers/session-live-index.ts

@@ -0,0 +1,89 @@
+import type { DatabaseManager } from '../store/db.js';
+import { indexLiveSession } from '../store/session-indexer.js';
+
+export const SESSION_LIVE_INDEX_DELAY_MS = 50;
+export const SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS = 5000;
+
+type SetTimeoutFn = (callback: () => void, ms: number) => unknown;
+
+type SessionManagerSnapshot = Parameters<typeof indexLiveSession>[1];
+
+export interface SessionLiveIndexState {
+  inProgress: boolean;
+  promise: Promise<void> | null;
+}
+
+export const sessionLiveIndexState: SessionLiveIndexState = {
+  inProgress: false,
+  promise: null,
+};
+
+export interface ScheduleLiveSessionIndexOptions {
+  state?: SessionLiveIndexState;
+  setTimeoutFn?: SetTimeoutFn;
+  indexLiveSessionFn?: typeof indexLiveSession;
+  delayMs?: number;
+  onError?: (error: unknown) => void;
+}
+
+/**
+ * Schedule non-blocking indexing of the current live session.
+ *
+ * Pi emits message_end before it appends the finalized message to the JSONL
+ * session file/session manager. Deferring briefly lets Pi persist the entry
+ * first, then we index any message ids not already present in SQLite. Multiple
+ * message_end events in the same window coalesce into one all-missing sync.
+ */
+export function scheduleLiveSessionIndex(
+  dbManager: DatabaseManager,
+  sessionManager: SessionManagerSnapshot,
+  options: ScheduleLiveSessionIndexOptions = {},
+): boolean {
+  const state = options.state ?? sessionLiveIndexState;
+  if (state.inProgress) {
+    return false;
+  }
+
+  const setTimeoutFn = options.setTimeoutFn ?? setTimeout;
+  const indexLiveSessionFn = options.indexLiveSessionFn ?? indexLiveSession;
+  const delayMs = options.delayMs ?? SESSION_LIVE_INDEX_DELAY_MS;
+
+  state.inProgress = true;
+  state.promise = new Promise<void>((resolve) => {
+    setTimeoutFn(() => {
+      try {
+        indexLiveSessionFn(dbManager, sessionManager);
+      } catch (err) {
+        try { options.onError?.(err); } catch { /* best effort */ }
+      } finally {
+        state.inProgress = false;
+        state.promise = null;
+        resolve();
+      }
+    }, delayMs);
+  });
+
+  return true;
+}
+
+export async function waitForLiveSessionIndex(
+  timeoutMs = SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS,
+  state: SessionLiveIndexState = sessionLiveIndexState,
+): Promise<boolean> {
+  const promise = state.promise;
+  if (!state.inProgress || !promise) {
+    return true;
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise.then(() => true),
+      new Promise<boolean>((resolve) => {
+        timeout = setTimeout(() => resolve(false), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}

package/src/index.ts

@@ -27,7 +27,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { MemoryStore } from "./store/memory-store.js";
 import { SkillStore } from "./store/skill-store.js";
 import { DatabaseManager } from "./store/db.js";
-import { indexSession } from "./store/session-indexer.js";
+import { indexSession, upsertSessionFileMetadata } from "./store/session-indexer.js";
+import { scheduleSessionBackfill, waitForSessionBackfill, SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS } from "./handlers/session-backfill.js";
+import { scheduleLiveSessionIndex, waitForLiveSessionIndex, SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS } from "./handlers/session-live-index.js";
 import { parseSessionFile } from "./store/session-parser.js";
 import { registerMemoryTool } from "./tools/memory-tool.js";
 import { registerSkillTool } from "./tools/skill-tool.js";
@@ -107,6 +109,7 @@ export default function (pi: ExtensionAPI) {
     migrationSentinelPath: path.join(globalDir, ".skills-migrated-to-extension-storage"),
   });
   const dbManager = new DatabaseManager(globalDir);
+  const sessionsDir = path.join(agentRoot, "sessions");
 
   const refreshSkillProjectContext = (cwd?: string) => {
     const resource = resolveProjectSkillDiscovery(skillStore, config.projectsMemoryDir, cwd);
@@ -150,6 +153,19 @@ export default function (pi: ExtensionAPI) {
     await skillStore.ensureDiscoveredRoots();
     await store.loadFromDisk();
     if (projectStore) await projectStore.loadFromDisk();
+
+    scheduleSessionBackfill(dbManager, sessionsDir, {
+      notify: (message, level) => {
+        const ui = (ctx as { ui?: { notify?: (message: string, level?: string) => void } }).ui;
+        if (ui?.notify) {
+          ui.notify(message, level);
+        } else if (level === "error" || level === "warning") {
+          console.warn(message);
+        } else {
+          console.info(message);
+        }
+      },
+    });
   });
 
   registerProjectSkillDiscoveryHandler(pi, skillStore, config.projectsMemoryDir);
@@ -201,12 +217,19 @@ export default function (pi: ExtensionAPI) {
   registerSyncMarkdownMemoriesCommand(pi, dbManager, globalDir, config.projectsMemoryDir, agentRoot);
   registerPreviewContextCommand(pi, store, projectStore, projectName, config);
 
-  // ── 10. SQLite session search + extended memory ──
+  // ── 10. Live session indexing ──
+  pi.on("message_end", async (_event, ctx) => {
+    scheduleLiveSessionIndex(dbManager, ctx.sessionManager, {
+      onError: (err) => console.warn(`⚠️ Live session indexing failed: ${err instanceof Error ? err.message : String(err)}`),
+    });
+  });
+
+  // ── 11. SQLite session search + extended memory ──
   registerSessionSearchTool(pi, dbManager, config.sessionSearch ?? { variant: "legacy" });
   registerMemorySearchTool(pi, dbManager);
   registerIndexSessionsCommand(pi);
 
-  // ── 11. Auto-index session on shutdown ──
+  // ── 12. Auto-index session on shutdown ──
   // Registered last, so this runs after the session-flush shutdown handler and
   // is the final DB activity. Closing here truncates the WAL via
   // PRAGMA wal_checkpoint(TRUNCATE); without it the WAL only grows to its
@@ -224,11 +247,24 @@ export default function (pi: ExtensionAPI) {
         const sessionData = parseSessionFile(sessionFile);
         if (sessionData) {
           indexSession(dbManager, sessionData);
+          // Keep session_files metadata in sync with the final on-disk state.
+          // Pi appends the closing session entry on shutdown after the last
+          // message_end, so without this upsert the stored size/mtime would be
+          // stale and the next startup would re-parse this file unnecessarily.
+          upsertSessionFileMetadata(dbManager, sessionFile, sessionData.id);
         }
       }
     } catch {
       // Silent fail — don't block shutdown
     } finally {
+      try {
+        await Promise.all([
+          waitForSessionBackfill(SESSION_BACKFILL_SHUTDOWN_TIMEOUT_MS),
+          waitForLiveSessionIndex(SESSION_LIVE_INDEX_SHUTDOWN_TIMEOUT_MS),
+        ]);
+      } catch {
+        // Best effort only — shutdown should not be held up by indexing errors.
+      }
       try { dbManager.close(); } catch { /* best effort — never block shutdown */ }
     }
   });

package/src/store/fts-query.ts

@@ -2,6 +2,10 @@ const FTS5_OPERATOR_PATTERN = /\b(OR|AND|NOT|NEAR)\b/;
 const FTS5_TOKEN_PATTERN = /"([^"]*)"|(\S+)/g;
 const NATURAL_LANGUAGE_CONNECTORS = new Set(['and', 'or', 'not', 'near']);
 
+export function hasExplicitFts5Operator(query: string): boolean {
+  return FTS5_OPERATOR_PATTERN.test(query.trim());
+}
+
 function collectNaturalLanguageTerms(query: string): string[] {
   const terms: string[] = [];
 
@@ -29,7 +33,7 @@ export function normalizeFts5Query(query: string): string {
   const trimmed = query.trim();
   if (trimmed.length === 0) return '';
 
-  if (FTS5_OPERATOR_PATTERN.test(trimmed)) {
+  if (hasExplicitFts5Operator(trimmed)) {
     return trimmed;
   }
 
@@ -45,7 +49,7 @@ export function normalizeFts5Query(query: string): string {
  */
 export function buildFallbackFts5Query(query: string): string | null {
   const trimmed = query.trim();
-  if (trimmed.length === 0 || FTS5_OPERATOR_PATTERN.test(trimmed)) {
+  if (trimmed.length === 0 || hasExplicitFts5Operator(trimmed)) {
     return null;
   }
 

package/src/store/schema.ts

@@ -3,6 +3,7 @@
  *
  * Tables:
  * - sessions — Pi session metadata
+ * - session_files — indexed JSONL metadata for incremental backfill
  * - messages — all conversation messages
  * - message_fts — FTS5 index for full-text search across messages
  * - memories — extended memory entries (unlimited, searchable)
@@ -10,6 +11,12 @@
  */
 
 export const SCHEMA_SQL = `
+  -- Extension key/value metadata
+  CREATE TABLE IF NOT EXISTS extension_metadata (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
   -- Session metadata
   CREATE TABLE IF NOT EXISTS sessions (
     id TEXT PRIMARY KEY,
@@ -20,6 +27,15 @@ export const SCHEMA_SQL = `
     message_count INTEGER DEFAULT 0
   );
 
+  -- Indexed session file metadata for cheap incremental backfill
+  CREATE TABLE IF NOT EXISTS session_files (
+    path TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    size INTEGER NOT NULL,
+    mtime_ms INTEGER NOT NULL,
+    indexed_at TEXT NOT NULL
+  );
+
   -- All messages from all sessions
   CREATE TABLE IF NOT EXISTS messages (
     id TEXT PRIMARY KEY,
@@ -96,4 +112,5 @@ export const SCHEMA_SQL = `
   CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
   CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
   CREATE INDEX IF NOT EXISTS idx_sessions_started_at ON sessions(started_at);
+  CREATE INDEX IF NOT EXISTS idx_session_files_session_id ON session_files(session_id);
 `;

package/src/store/session-indexer.ts

@@ -1,13 +1,17 @@
+import fs from 'node:fs';
 import { DatabaseManager } from './db.js';
 import { parseSessionFile, getSessionFiles, type ParsedSession } from './session-parser.js';
 
+export const LAST_SESSION_BACKFILL_KEY = 'last_session_backfill';
+export const SESSION_BACKFILL_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
 /**
  * Index result for a single session.
  */
 export interface IndexResult {
   sessionId: string;
   messagesIndexed: number;
-  skipped: boolean; // true if already indexed
+  skipped: boolean; // true if the session already existed and no new messages were indexed
 }
 
 /**
@@ -19,6 +23,18 @@ export interface BulkIndexResult {
   sessionsSkipped: number;
   messagesIndexed: number;
   errors: string[];
+  reachedLimit?: boolean;
+}
+
+interface SessionFileMetadata {
+  path: string;
+  size: number;
+  mtimeMs: number;
+}
+
+export interface IncrementalIndexOptions {
+  projectDir?: string;
+  maxFilesToIndex?: number;
 }
 
 /**
@@ -29,33 +45,39 @@ export interface BulkIndexResult {
 export function indexSession(dbManager: DatabaseManager, session: ParsedSession): IndexResult {
   const db = dbManager.getDb();
 
-  // Check if already indexed
-  const existing = db.prepare('SELECT id FROM sessions WHERE id = ?').get(session.id) as { id: string } | undefined;
-  if (existing) {
-    return { sessionId: session.id, messagesIndexed: 0, skipped: true };
-  }
+  const existingSession = db.prepare('SELECT id FROM sessions WHERE id = ?').get(session.id) as { id: string } | undefined;
+  const before = db.prepare('SELECT COUNT(*) as count FROM messages WHERE session_id = ?').get(session.id) as { count: number };
 
-  // Insert session
-  db.prepare(`
-    INSERT INTO sessions (id, project, cwd, started_at, ended_at, message_count)
+  const insertSession = db.prepare(`
+    INSERT OR IGNORE INTO sessions (id, project, cwd, started_at, ended_at, message_count)
     VALUES (?, ?, ?, ?, ?, ?)
-  `).run(
-    session.id,
-    session.project,
-    session.cwd,
-    session.startedAt,
-    session.endedAt,
-    session.messages.length
-  );
-
-  // Insert messages in a transaction for performance
+  `);
+
   const insertMsg = db.prepare(`
-    INSERT INTO messages (id, session_id, role, content, timestamp, tool_calls)
+    INSERT OR IGNORE INTO messages (id, session_id, role, content, timestamp, tool_calls)
     VALUES (?, ?, ?, ?, ?, ?)
   `);
 
-  const writeMessages = (messages: ParsedSession['messages']) => {
-    for (const msg of messages) {
+  const updateSession = db.prepare(`
+    UPDATE sessions
+    SET project = ?,
+        cwd = ?,
+        ended_at = COALESCE(?, ended_at),
+        message_count = (SELECT COUNT(*) FROM messages WHERE session_id = ?)
+    WHERE id = ?
+  `);
+
+  const writeSession = () => {
+    insertSession.run(
+      session.id,
+      session.project,
+      session.cwd,
+      session.startedAt,
+      session.endedAt,
+      session.messages.length
+    );
+
+    for (const msg of session.messages) {
       insertMsg.run(
         msg.id,
         session.id,
@@ -65,16 +87,202 @@ export function indexSession(dbManager: DatabaseManager, session: ParsedSession)
         msg.toolCalls ? JSON.stringify(msg.toolCalls) : null
       );
     }
+
+    updateSession.run(session.project, session.cwd, session.endedAt, session.id, session.id);
   };
 
   if (db.transaction) {
-    const insertMany = db.transaction(writeMessages);
-    insertMany(session.messages);
+    const tx = db.transaction(writeSession);
+    tx();
   } else {
-    writeMessages(session.messages);
+    writeSession();
+  }
+
+  const after = db.prepare('SELECT COUNT(*) as count FROM messages WHERE session_id = ?').get(session.id) as { count: number };
+  const messagesIndexed = after.count - before.count;
+
+  return { sessionId: session.id, messagesIndexed, skipped: Boolean(existingSession) && messagesIndexed === 0 };
+}
+
+type SessionManagerSnapshot = {
+  getHeader: () => { id: string; timestamp: string; cwd: string } | null;
+  getEntries: () => unknown[];
+  getSessionFile?: () => string | undefined;
+};
+
+type SessionMessageEntryLike = {
+  type?: unknown;
+  id?: unknown;
+  timestamp?: unknown;
+  message?: {
+    role?: unknown;
+    content?: unknown;
+  };
+};
+
+function extractTextContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as Record<string, unknown>;
+
+    switch (b.type) {
+      case 'text':
+        if (typeof b.text === 'string') parts.push(b.text);
+        break;
+      case 'tool_result':
+        if (typeof b.content === 'string') {
+          parts.push(b.content);
+        } else if (Array.isArray(b.content)) {
+          for (const item of b.content) {
+            if (item && typeof item === 'object' && (item as Record<string, unknown>).type === 'text') {
+              const text = (item as Record<string, unknown>).text;
+              if (typeof text === 'string') parts.push(text);
+            }
+          }
+        }
+        break;
+    }
+  }
+
+  return parts.join('\n').trim();
+}
+
+function extractToolCalls(content: unknown): string[] | undefined {
+  if (!Array.isArray(content)) return undefined;
+
+  const toolNames: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as Record<string, unknown>;
+    if ((b.type === 'toolCall' || b.type === 'tool_use') && typeof b.name === 'string') {
+      toolNames.push(b.name);
+    }
+  }
+  return toolNames.length > 0 ? toolNames : undefined;
+}
+
+function parseMessageEntry(entry: unknown): ParsedSession['messages'][number] | null {
+  if (!entry || typeof entry !== 'object') return null;
+  const e = entry as SessionMessageEntryLike;
+  if (e.type !== 'message' || typeof e.id !== 'string' || typeof e.timestamp !== 'string' || !e.message) return null;
+
+  const role = e.message.role;
+  if (role !== 'user' && role !== 'assistant' && role !== 'system') return null;
+
+  const content = extractTextContent(e.message.content);
+  if (!content) return null;
+
+  return {
+    id: e.id,
+    role,
+    content,
+    timestamp: e.timestamp,
+    toolCalls: role === 'assistant' ? extractToolCalls(e.message.content) : undefined,
+  };
+}
+
+export function parseSessionManagerSnapshot(sessionManager: SessionManagerSnapshot): ParsedSession | null {
+  const header = sessionManager.getHeader();
+  if (!header?.id || !header.cwd || !header.timestamp) return null;
+
+  const messages = sessionManager.getEntries()
+    .map(parseMessageEntry)
+    .filter((msg): msg is ParsedSession['messages'][number] => msg !== null);
+
+  return {
+    id: header.id,
+    project: header.cwd.split('/').pop() ?? header.cwd,
+    cwd: header.cwd,
+    startedAt: header.timestamp,
+    endedAt: null,
+    messages,
+  };
+}
+
+export function indexCurrentSession(dbManager: DatabaseManager, sessionManager: SessionManagerSnapshot): IndexResult | null {
+  const session = parseSessionManagerSnapshot(sessionManager);
+  if (!session) return null;
+  return indexSession(dbManager, session);
+}
+
+export function indexLiveSession(dbManager: DatabaseManager, sessionManager: SessionManagerSnapshot): IndexResult | null {
+  const sessionFile = sessionManager.getSessionFile?.();
+  if (sessionFile && fs.existsSync(sessionFile)) {
+    const session = parseSessionFile(sessionFile);
+    if (session) {
+      const result = indexSession(dbManager, session);
+      upsertSessionFileMetadata(dbManager, sessionFile, session.id);
+      return result;
+    }
+  }
+
+  return indexCurrentSession(dbManager, sessionManager);
+}
+
+function getSessionFileMetadata(filePath: string): SessionFileMetadata {
+  const stat = fs.statSync(filePath);
+  return { path: filePath, size: stat.size, mtimeMs: Math.trunc(stat.mtimeMs) };
+}
+
+function getStoredSessionFileMetadata(dbManager: DatabaseManager, filePath: string): { size: number; mtime_ms: number } | undefined {
+  return dbManager.getDb().prepare('SELECT size, mtime_ms FROM session_files WHERE path = ?').get(filePath) as { size: number; mtime_ms: number } | undefined;
+}
+
+function storedSessionFileMatches(dbManager: DatabaseManager, metadata: SessionFileMetadata): boolean {
+  const row = getStoredSessionFileMetadata(dbManager, metadata.path);
+  return Boolean(row && row.size === metadata.size && row.mtime_ms === metadata.mtimeMs);
+}
+
+export function upsertSessionFileMetadata(
+  dbManager: DatabaseManager,
+  filePath: string,
+  sessionId: string,
+  metadata = getSessionFileMetadata(filePath),
+  indexedAt = new Date(),
+): void {
+  const db = dbManager.getDb();
+  db.prepare(`
+    INSERT INTO session_files (path, session_id, size, mtime_ms, indexed_at)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(path) DO UPDATE SET
+      session_id = excluded.session_id,
+      size = excluded.size,
+      mtime_ms = excluded.mtime_ms,
+      indexed_at = excluded.indexed_at
+  `).run(metadata.path, sessionId, metadata.size, metadata.mtimeMs, indexedAt.toISOString());
+}
+
+function emptyBulkIndexResult(): BulkIndexResult {
+  return {
+    sessionsProcessed: 0,
+    sessionsIndexed: 0,
+    sessionsSkipped: 0,
+    messagesIndexed: 0,
+    errors: [],
+  };
+}
+
+function indexSessionFile(dbManager: DatabaseManager, file: string, result: BulkIndexResult): void {
+  result.sessionsProcessed++;
+
+  const session = parseSessionFile(file);
+  if (!session) {
+    result.errors.push(`Failed to parse: ${file}`);
+    return;
   }
 
-  return { sessionId: session.id, messagesIndexed: session.messages.length, skipped: false };
+  const indexResult = indexSession(dbManager, session);
+  upsertSessionFileMetadata(dbManager, file, session.id);
+  if (indexResult.skipped) {
+    result.sessionsSkipped++;
+  } else {
+    result.sessionsIndexed++;
+    result.messagesIndexed += indexResult.messagesIndexed;
+  }
 }
 
 /**
@@ -91,39 +299,132 @@ export function indexAllSessions(
   projectDir?: string
 ): BulkIndexResult {
   const files = getSessionFiles(sessionsDir, projectDir);
-  const result: BulkIndexResult = {
-    sessionsProcessed: 0,
-    sessionsIndexed: 0,
-    sessionsSkipped: 0,
-    messagesIndexed: 0,
-    errors: [],
-  };
+  const result = emptyBulkIndexResult();
 
   for (const file of files) {
-    result.sessionsProcessed++;
-
     try {
-      const session = parseSessionFile(file);
-      if (!session) {
-        result.errors.push(`Failed to parse: ${file}`);
-        continue;
-      }
+      indexSessionFile(dbManager, file, result);
+    } catch (err) {
+      result.errors.push(`Error indexing ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return result;
+}
 
-      const indexResult = indexSession(dbManager, session);
-      if (indexResult.skipped) {
+/**
+ * Incrementally index session JSONL files without matching stored metadata.
+ *
+ * This is intentionally cheaper than indexAllSessions() for startup backfill:
+ * files with matching stored size/mtime metadata are skipped, and all other
+ * files are parsed under the startup cap.
+ */
+export function indexChangedSessions(
+  dbManager: DatabaseManager,
+  sessionsDir: string,
+  options: IncrementalIndexOptions = {},
+): BulkIndexResult {
+  const files = getSessionFiles(sessionsDir, options.projectDir);
+  const maxFilesToIndex = options.maxFilesToIndex ?? 50;
+  const result = emptyBulkIndexResult();
+
+  // Gather the changed set first, then sort newest-first before applying the
+  // cap. Crash recovery is the primary value of startup backfill (the live
+  // message_end path missed the session's final state), and crashed sessions
+  // are the most recently modified files. Sorting newest-first ensures they
+  // are indexed on the very next startup instead of waiting behind old
+  // historical files that fill the per-startup cap in filesystem order.
+  const changed: SessionFileMetadata[] = [];
+  for (const file of files) {
+    try {
+      const metadata = getSessionFileMetadata(file);
+      if (storedSessionFileMatches(dbManager, metadata)) {
         result.sessionsSkipped++;
-      } else {
-        result.sessionsIndexed++;
-        result.messagesIndexed += indexResult.messagesIndexed;
+        continue;
       }
+      changed.push(metadata);
     } catch (err) {
       result.errors.push(`Error indexing ${file}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
+  changed.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const metadata of changed) {
+    if (result.sessionsProcessed >= maxFilesToIndex) {
+      result.reachedLimit = true;
+      break;
+    }
+    try {
+      indexSessionFile(dbManager, metadata.path, result);
+    } catch (err) {
+      result.errors.push(`Error indexing ${metadata.path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   return result;
 }
 
+/**
+ * Cheaply count session JSONL files in the same scope indexAllSessions scans.
+ */
+export function countSessionFiles(sessionsDir: string): number {
+  return getSessionFiles(sessionsDir).length;
+}
+
+function getLastBackfillTimestamp(dbManager: DatabaseManager): string | null {
+  const db = dbManager.getDb();
+  const row = db.prepare('SELECT value FROM extension_metadata WHERE key = ?').get(LAST_SESSION_BACKFILL_KEY) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+function isRecentBackfillTimestamp(value: string | null, nowMs: number): boolean {
+  if (!value) return false;
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed)) return false;
+  return nowMs - parsed < SESSION_BACKFILL_INTERVAL_MS;
+}
+
+/**
+ * Determine whether a background session backfill should run.
+ *
+ * The check stays cheap: it compares file counts and stored file size/mtime
+ * metadata. Full JSONL parsing is left to the scheduled incremental backfill.
+ */
+export function needsBackfill(dbManager: DatabaseManager, sessionsDir: string, now = new Date()): boolean {
+  const db = dbManager.getDb();
+  const files = getSessionFiles(sessionsDir);
+  const indexed = db.prepare('SELECT COUNT(*) as count FROM sessions').get() as { count: number };
+
+  if (files.length > indexed.count) {
+    return true;
+  }
+
+  for (const file of files) {
+    try {
+      const metadata = getSessionFileMetadata(file);
+      if (storedSessionFileMatches(dbManager, metadata)) continue;
+      return true;
+    } catch {
+      return true;
+    }
+  }
+
+  return !isRecentBackfillTimestamp(getLastBackfillTimestamp(dbManager), now.getTime());
+}
+
+/**
+ * Record a successful session backfill completion timestamp.
+ */
+export function touchBackfillTimestamp(dbManager: DatabaseManager, timestamp = new Date()): void {
+  const db = dbManager.getDb();
+  db.prepare(`
+    INSERT INTO extension_metadata (key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(LAST_SESSION_BACKFILL_KEY, timestamp.toISOString());
+}
+
 /**
  * Get statistics about indexed sessions.
  */

package/src/store/session-parser.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 
 /**
  * Parsed session data from a JSONL file.
@@ -90,7 +91,7 @@ function extractToolCalls(content: unknown): string[] | undefined {
   for (const block of content) {
     if (!block || typeof block !== 'object') continue;
     const b = block as Record<string, unknown>;
-    if (b.type === 'tool_use' && typeof b.name === 'string') {
+    if ((b.type === 'tool_use' || b.type === 'toolCall') && typeof b.name === 'string') {
       toolNames.push(b.name);
     }
   }
@@ -179,23 +180,29 @@ export function parseSessionFile(filePath: string): ParsedSession | null {
  */
 export function getSessionFiles(sessionsDir: string, projectDir?: string): string[] {
   if (projectDir) {
-    const dir = `${sessionsDir}/${projectDir}`;
+    const dir = path.join(sessionsDir, projectDir);
     if (!fs.existsSync(dir)) return [];
     return fs.readdirSync(dir)
       .filter(f => f.endsWith('.jsonl'))
-      .map(f => `${dir}/${f}`);
+      .map(f => path.join(dir, f));
   }
 
   // All projects
   if (!fs.existsSync(sessionsDir)) return [];
   const files: string[] = [];
-  for (const dir of fs.readdirSync(sessionsDir)) {
-    const dirPath = `${sessionsDir}/${dir}`;
-    if (!fs.statSync(dirPath).isDirectory()) continue;
-    for (const f of fs.readdirSync(dirPath)) {
-      if (f.endsWith('.jsonl')) {
-        files.push(`${dirPath}/${f}`);
+  for (const entry of fs.readdirSync(sessionsDir)) {
+    const entryPath = path.join(sessionsDir, entry);
+    const stat = fs.statSync(entryPath);
+    if (stat.isDirectory()) {
+      // Scan .jsonl files inside project subdirectories
+      for (const f of fs.readdirSync(entryPath)) {
+        if (f.endsWith('.jsonl')) {
+          files.push(path.join(entryPath, f));
+        }
       }
+    } else if (stat.isFile() && entry.endsWith('.jsonl')) {
+      // Also pick up root-level .jsonl files
+      files.push(entryPath);
     }
   }
   return files;

package/src/store/session-search.ts

@@ -1,5 +1,5 @@
 import { DatabaseManager } from './db.js';
-import { isFts5QueryError, normalizeFts5Query } from './fts-query.js';
+import { buildFallbackFts5Query, hasExplicitFts5Operator, isFts5QueryError, normalizeFts5Query } from './fts-query.js';
 
 /**
  * Search result from session history.
@@ -27,6 +27,52 @@ export interface SessionSearchOptions {
   since?: string;
 }
 
+type SearchMatch =
+  | { type: 'fts'; query: string }
+  | { type: 'like'; terms: string[] };
+
+const QUERY_TOKEN_PATTERN = /"([^"]*)"|(\S+)/g;
+const NATURAL_LANGUAGE_CONNECTORS = new Set(['and', 'or', 'not', 'near']);
+
+function escapeLikePattern(text: string): string {
+  return text.replace(/[\\%_]/g, '\\$&');
+}
+
+function collectLikeTerms(query: string): string[] {
+  const terms: string[] = [];
+
+  for (const match of query.matchAll(QUERY_TOKEN_PATTERN)) {
+    const phrase = match[1];
+    const term = match[2];
+    if (phrase === undefined && term && NATURAL_LANGUAGE_CONNECTORS.has(term.toLowerCase())) {
+      continue;
+    }
+
+    const rawValue = phrase ?? term ?? '';
+    if (rawValue.length > 0) terms.push(rawValue);
+  }
+
+  return terms;
+}
+
+function mapRows(rows: Array<{
+  session_id: string;
+  project: string;
+  role: string;
+  content: string;
+  timestamp: string;
+  snippet: string;
+}>): SessionSearchResult[] {
+  return rows.map(row => ({
+    sessionId: row.session_id,
+    project: row.project,
+    role: row.role,
+    content: row.content,
+    timestamp: row.timestamp,
+    snippet: row.snippet,
+  }));
+}
+
 /**
  * Search across indexed session messages using FTS5.
  *
@@ -47,79 +93,104 @@ export function searchSessions(
   const db = dbManager.getDb();
   const { limit = 10, project, role, since } = options;
 
-  // Build the query dynamically based on filters
-  const conditions: string[] = [];
-  const params: unknown[] = [];
+  const executeSearch = (match: SearchMatch): SessionSearchResult[] => {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (match.type === 'fts') {
+      // FTS5 match condition — use subquery for reliable rowid matching
+      conditions.push('m.rowid IN (SELECT rowid FROM message_fts WHERE message_fts MATCH ?)');
+      params.push(match.query);
+    } else {
+      if (match.terms.length === 0) {
+        return [];
+      }
+      const likeConditions = match.terms.map(() => `m.content LIKE ? ESCAPE '\\'`);
+      conditions.push(`(${likeConditions.join(' OR ')})`);
+      for (const term of match.terms) {
+        params.push(`%${escapeLikePattern(term)}%`);
+      }
+    }
+
+    // Project filter
+    if (project) {
+      conditions.push('s.project = ?');
+      params.push(project);
+    }
+
+    // Role filter
+    if (role) {
+      conditions.push('m.role = ?');
+      params.push(role);
+    }
+
+    // Date filter
+    if (since) {
+      conditions.push('m.timestamp >= ?');
+      params.push(since);
+    }
+
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+    const sql = `
+      SELECT
+        m.session_id,
+        s.project,
+        m.role,
+        m.content,
+        m.timestamp,
+        m.content as snippet
+      FROM messages m
+      JOIN sessions s ON s.id = m.session_id
+      ${whereClause}
+      ORDER BY m.timestamp DESC
+      LIMIT ?
+    `;
+
+    try {
+      const rows = db.prepare(sql).all(...params, limit) as Array<{
+        session_id: string;
+        project: string;
+        role: string;
+        content: string;
+        timestamp: string;
+        snippet: string;
+      }>;
+
+      return mapRows(rows);
+    } catch (err) {
+      if (match.type === 'fts' && isFts5QueryError(err)) {
+        return [];
+      }
+      throw err;
+    }
+  };
 
-  // FTS5 match condition — use subquery for reliable rowid matching
   const normalizedQuery = normalizeFts5Query(query);
   if (normalizedQuery.length === 0) {
     return [];
   }
-  conditions.push('m.rowid IN (SELECT rowid FROM message_fts WHERE message_fts MATCH ?)');
-  params.push(normalizedQuery);
-
-  // Project filter
-  if (project) {
-    conditions.push('s.project = ?');
-    params.push(project);
-  }
 
-  // Role filter
-  if (role) {
-    conditions.push('m.role = ?');
-    params.push(role);
+  const exactResults = executeSearch({ type: 'fts', query: normalizedQuery });
+  if (exactResults.length > 0) {
+    return exactResults;
   }
 
-  // Date filter
-  if (since) {
-    conditions.push('m.timestamp >= ?');
-    params.push(since);
+  const explicitOperatorQuery = hasExplicitFts5Operator(query);
+  if (explicitOperatorQuery) {
+    return exactResults;
   }
 
-  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
-
-  const sql = `
-    SELECT
-      m.session_id,
-      s.project,
-      m.role,
-      m.content,
-      m.timestamp,
-      m.content as snippet
-    FROM messages m
-    JOIN sessions s ON s.id = m.session_id
-    ${whereClause}
-    ORDER BY m.timestamp DESC
-    LIMIT ?
-  `;
-  params.push(limit);
-
-  try {
-    const rows = db.prepare(sql).all(...params) as Array<{
-      session_id: string;
-      project: string;
-      role: string;
-      content: string;
-      timestamp: string;
-      snippet: string;
-    }>;
-
-    // Map snake_case column names to camelCase
-    return rows.map(row => ({
-      sessionId: row.session_id,
-      project: row.project,
-      role: row.role,
-      content: row.content,
-      timestamp: row.timestamp,
-      snippet: row.snippet,
-    }));
-  } catch (err) {
-    if (isFts5QueryError(err)) {
-      return [];
+  const fallbackQuery = buildFallbackFts5Query(query);
+  if (fallbackQuery && fallbackQuery !== normalizedQuery) {
+    const fallbackResults = executeSearch({ type: 'fts', query: fallbackQuery });
+    if (fallbackResults.length > 0) {
+      return fallbackResults;
     }
-    throw err;
   }
+
+  const likeTerms = collectLikeTerms(query);
+  return executeSearch({ type: 'like', terms: likeTerms });
 }
 
 /**