pi-session-memory 0.1.4 → 0.2.1

package/src/retriever.ts

@@ -1,70 +1,235 @@
-import { getDb } from "./db.ts";
+import { createHash } from "node:crypto";
+import { getDb, type MemoryKind } from "./db.ts";
 
-export interface RecallResult {
+export type MemorySource = "pi" | "claude" | "codex";
+
+export interface RecallOptions {
+  query: string;
+  entities?: string[];
+  sources?: MemorySource[];
+  cwd?: string;
+  after?: number;
+  before?: number;
+}
+
+export interface RecallTurnResult {
+  type: "turn";
   turn_id: string;
-  source: "pi" | "claude" | "codex";
+  session_id: string;
+  turn_index: number;
+  source: MemorySource;
+  cwd: string;
   ts: number;
   user_text: string;
   reply_text: string;
   hits: number;
+  score: number;
 }
 
-export function recallTurns(entities: string[], topK = 5): RecallResult[] {
-  if (entities.length === 0) return [];
+export interface RecallDurableMemoryResult {
+  type: "memory";
+  memory_id: string;
+  kind: MemoryKind;
+  content: string;
+  project_key: string;
+  source_turn_id: string | null;
+  source_session_id: string | null;
+  source_content_hash: string | null;
+  source_turn_index: number | null;
+  freshness_candidate: boolean;
+  created_at: number;
+  last_confirmed_at: number;
+  importance: number;
+  hits: number;
+  score: number;
+}
 
-  const scoreExpression = entities.map(() => `(
-    CASE WHEN LOWER(turns.user_text) LIKE ? ESCAPE '\\' THEN 2 ELSE 0 END +
-    CASE WHEN LOWER(turns.reply_text) LIKE ? ESCAPE '\\' THEN 1 ELSE 0 END
-  )`).join(" + ");
-  const scoreParameters = entities.flatMap((entity) => {
-    const pattern = _likePattern(entity);
-    return [pattern, pattern];
-  });
+export type RecallResult = RecallDurableMemoryResult | RecallTurnResult;
 
-  const whereExpression = entities.map(() => `(
-    LOWER(turns.user_text) LIKE ? ESCAPE '\\' OR
-    LOWER(turns.reply_text) LIKE ? ESCAPE '\\'
-  )`).join(" OR ");
-  const whereParameters = entities.flatMap((entity) => {
-    const pattern = _likePattern(entity);
-    return [pattern, pattern];
-  });
+export const RECALL_PAGE_SIZE = 5;
 
-  return getDb().prepare(`
-    SELECT
-      turns.turn_id,
-      sessions.source,
-      turns.ts,
-      turns.user_text,
-      turns.reply_text,
-      (${scoreExpression}) AS hits
-    FROM turns
-    JOIN sessions ON sessions.session_id = turns.session_id
-    WHERE ${whereExpression}
-    ORDER BY hits DESC, turns.ts DESC
-    LIMIT ?
-  `).all(...scoreParameters, ...whereParameters, topK) as RecallResult[];
+export interface RecallPage {
+  results: RecallResult[];
+  offset: number;
+  totalResults: number;
+  nextOffset: number | null;
+}
+
+// Recency is a bounded tie-breaker, not a replacement for literal relevance.
+const RECENCY_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+
+/** Retained for compatibility with the v0.1 public retrieval helper. */
+export function recallTurns(entities: string[]): RecallTurnResult[] {
+  return _recallTurns({ query: entities.join(" "), entities });
 }
 
-export function formatRecallResults(results: RecallResult[]): string {
-  if (results.length === 0) return "No relevant past conversations found.";
+/** Retrieve active durable memories, then raw turns not already represented by unchanged source evidence. */
+export function recallMemories(options: RecallOptions): RecallResult[] {
+  const durableMemories = _recallDurableMemories(options);
+  const recalledTurns = _recallTurns(options);
+  const freshnessCandidates = new Set(
+    durableMemories
+      .filter((memory) => memory.source_session_id && memory.source_turn_index !== null)
+      .filter((memory) => recalledTurns.some((turn) => turn.session_id === memory.source_session_id && turn.turn_index > memory.source_turn_index!))
+      .map((memory) => memory.memory_id),
+  );
+  const memories = durableMemories.map((memory) => ({ ...memory, freshness_candidate: freshnessCandidates.has(memory.memory_id) }));
+  const coveredSourceHashes = new Map(
+    memories
+      .filter((memory) => memory.source_turn_id && memory.source_content_hash)
+      .map((memory) => [memory.source_turn_id!, memory.source_content_hash!]),
+  );
+  const rawTurns = recalledTurns.filter((turn) => coveredSourceHashes.get(turn.turn_id) !== _turnContentHash(turn));
+  return [...memories, ...rawTurns];
+}
+
+/** Select one fixed-size recall page without limiting the complete local retrieval result. */
+export function paginateRecallResults(results: RecallResult[], offset = 0): RecallPage {
+  if (!Number.isInteger(offset) || offset < 0) throw new Error("Recall offset must be a non-negative integer");
+  const pageResults = results.slice(offset, offset + RECALL_PAGE_SIZE);
+  const nextOffset = offset + pageResults.length < results.length ? offset + pageResults.length : null;
+  return { results: pageResults, offset, totalResults: results.length, nextOffset };
+}
 
-  const lines = ["## Relevant past conversations\n"];
+/** Render the exact query inputs and recall results as concise Markdown for a command notification or tool response. */
+export function formatRecallResults(results: RecallResult[], options?: Pick<RecallOptions, "query" | "entities" | "sources" | "cwd" | "after" | "before">, page?: Omit<RecallPage, "results">): string {
+  const lines = options ? [_formatRecallQuery(options), ""] : [];
+  if (results.length === 0) return [...lines, page && page.totalResults > 0 ? `No results at offset ${page.offset}; the matching result set contains ${page.totalResults} result(s).` : "No relevant past conversations found."].join("\n");
+
+  if (page) lines.push(`**Results:** ${page.offset + 1}–${page.offset + results.length} of ${page.totalResults} (five results per page)\n`);
+  lines.push("## Relevant past memories\n");
   for (const result of results) {
-    const date = new Date(result.ts).toLocaleString();
-    lines.push(`### [${result.source} · ${date}]`);
-    lines.push(`**You:** ${result.user_text}`);
-    if (result.reply_text) {
-      const preview = result.reply_text.length > 500
-        ? `${result.reply_text.slice(0, 500)}…`
-        : result.reply_text;
-      lines.push(`**Assistant:** ${preview}`);
+    if (result.type === "memory") {
+      lines.push(`### [durable ${result.kind} · ${new Date(result.last_confirmed_at).toLocaleString()}]`);
+      lines.push(result.content);
+      lines.push(`**Memory ID:** ${result.memory_id}`);
+      if (result.source_turn_id) lines.push(`**Source turn:** ${result.source_turn_id}`);
+      if (result.source_session_id) lines.push(`**Source session:** ${result.source_session_id}`);
+      if (result.freshness_candidate) lines.push("**Freshness:** newer matching turn exists in the source session; confirm or supersede this memory.");
+    } else {
+      const date = new Date(result.ts).toLocaleString();
+      lines.push(`### [${result.source} · ${date}]`);
+      lines.push(`**Session:** ${result.session_id} · **Turn:** ${result.turn_index}`);
+      lines.push(`**Excerpt:** ${_excerpt(result.user_text || result.reply_text)}`);
+      lines.push("Use `fetch_session` with this session ID when the surrounding conversation is needed.");
     }
     lines.push("");
   }
+  if (page?.nextOffset !== null && page?.nextOffset !== undefined) {
+    lines.push(`More matching results exist. To retrieve the next five, call \`recall_memory\` again with every same search/filter parameter and \`offset: ${page.nextOffset}\`.`);
+  }
   return lines.join("\n");
 }
 
-function _likePattern(entity: string): string {
-  return `%${entity.toLowerCase().replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_")}%`;
+/** Make each tool invocation auditable by showing its exact literal terms and scopes. */
+function _formatRecallQuery(options: Pick<RecallOptions, "query" | "entities" | "sources" | "cwd" | "after" | "before">): string {
+  const filters = [
+    options.entities?.length ? `entities: ${options.entities.map((entity) => `\`${entity}\``).join(", ")}` : null,
+    options.sources?.length ? `sources: ${options.sources.join(", ")}` : null,
+    options.cwd ? `cwd: \`${options.cwd}\`` : null,
+    options.after !== undefined ? `after: ${new Date(options.after).toISOString()}` : null,
+    options.before !== undefined ? `before: ${new Date(options.before).toISOString()}` : null,
+  ].filter(Boolean);
+  return `**Search query:** \`${options.query}\`${filters.length ? `  \\n**Filters:** ${filters.join(" · ")}` : ""}`;
+}
+
+/** Keep discovery results small; full persisted turn text belongs to fetch_session. */
+function _excerpt(text: string, maxLength = 240): string {
+  const normalized = text.replaceAll(/\s+/g, " ").trim();
+  return normalized.length > maxLength ? `${normalized.slice(0, maxLength)}…` : normalized;
+}
+
+/** Search active durable memories with the same escaped literal matching used for transcript recall. */
+function _recallDurableMemories(options: RecallOptions): RecallDurableMemoryResult[] {
+  const terms = _terms(options);
+  if (terms.length === 0) return [];
+  const scoreExpression = terms.map(() => "CASE WHEN LOWER(content) LIKE ? ESCAPE '\\' THEN 1 ELSE 0 END").join(" + ");
+  const parameters = terms.map(_likePattern);
+  const filters = terms.map(() => "LOWER(content) LIKE ? ESCAPE '\\'");
+  const filterParameters: Array<string | number> = terms.map(_likePattern);
+  filters.push("superseded_by IS NULL");
+  if (options.cwd) {
+    filters.push("project_key = ?");
+    filterParameters.push(options.cwd);
+  }
+  if (options.after !== undefined) {
+    filters.push("last_confirmed_at >= ?");
+    filterParameters.push(options.after);
+  }
+  if (options.before !== undefined) {
+    filters.push("last_confirmed_at <= ?");
+    filterParameters.push(options.before);
+  }
+  return getDb().prepare(`
+    SELECT memory_id, kind, content, project_key, source_turn_id, source_session_id, source_content_hash, source_turn_index, created_at, last_confirmed_at, importance,
+      (${scoreExpression}) AS hits
+    FROM memories
+    WHERE ${filters.join(" AND ")}
+    ORDER BY hits DESC, importance DESC, last_confirmed_at DESC
+  `).all(...parameters, ...filterParameters)
+    .map((memory) => ({ ...memory, type: "memory" as const, freshness_candidate: false, score: memory.hits + memory.importance })) as RecallDurableMemoryResult[];
+}
+
+/** Retrieve and rank locally stored turns using literal query terms and optional scopes. */
+function _recallTurns(options: RecallOptions): RecallTurnResult[] {
+  const terms = _terms(options);
+  if (terms.length === 0) return [];
+  const scoreExpression = terms.map(() => `(CASE WHEN LOWER(turns.user_text) LIKE ? ESCAPE '\\' THEN 2 ELSE 0 END + CASE WHEN LOWER(turns.reply_text) LIKE ? ESCAPE '\\' THEN 1 ELSE 0 END)`).join(" + ");
+  const scoreParameters = terms.flatMap((term) => _likeParameters(term));
+  const whereExpressions = terms.map(() => "(LOWER(turns.user_text) LIKE ? ESCAPE '\\' OR LOWER(turns.reply_text) LIKE ? ESCAPE '\\')");
+  const whereParameters = terms.flatMap((term) => _likeParameters(term));
+  const filters = [...whereExpressions];
+  const filterParameters: Array<string | number> = [...whereParameters];
+  if (options.sources?.length) {
+    filters.push(`sessions.source IN (${options.sources.map(() => "?").join(", ")})`);
+    filterParameters.push(...options.sources);
+  }
+  if (options.cwd) {
+    filters.push("sessions.cwd = ?");
+    filterParameters.push(options.cwd);
+  }
+  if (options.after !== undefined) {
+    filters.push("turns.ts >= ?");
+    filterParameters.push(options.after);
+  }
+  if (options.before !== undefined) {
+    filters.push("turns.ts <= ?");
+    filterParameters.push(options.before);
+  }
+  const candidates = getDb().prepare(`
+    SELECT turns.turn_id, turns.session_id, turns.turn_index, sessions.source, sessions.cwd, turns.ts, turns.user_text, turns.reply_text,
+      (${scoreExpression}) AS hits
+    FROM turns JOIN sessions ON sessions.session_id = turns.session_id
+    WHERE ${filters.join(" AND ")}
+    ORDER BY hits DESC, turns.ts DESC
+  `).all(...scoreParameters, ...filterParameters) as Array<Omit<RecallTurnResult, "type" | "score">>;
+  const newestTs = candidates.reduce((newest, result) => Math.max(newest, result.ts), 0);
+  const results = candidates.map((result) => ({ ...result, type: "turn" as const, score: result.hits + _recencyScore(result.ts, newestTs) + (options.cwd === result.cwd ? 0.8 : 0) })).sort((left, right) => right.score - left.score || right.ts - left.ts);
+  return results;
+}
+
+/** Hash the current raw turn evidence using the same representation captured during pinning. */
+function _turnContentHash(turn: RecallTurnResult): string {
+  return createHash("sha256").update(JSON.stringify([turn.user_text, turn.reply_text])).digest("hex");
+}
+
+/** Build a de-duplicated set of non-empty literal search terms from the request. */
+function _terms(options: RecallOptions): string[] {
+  return [...new Set([options.query, ...(options.entities ?? [])].map((term) => term.trim()).filter(Boolean))];
+}
+
+/** Produce matching user and assistant SQL LIKE parameters for one term. */
+function _likeParameters(term: string): [string, string] {
+  const pattern = _likePattern(term);
+  return [pattern, pattern];
+}
+
+/** Convert one literal search term into an escaped, case-normalized SQL LIKE pattern. */
+function _likePattern(term: string): string {
+  return `%${term.toLowerCase().replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_")}%`;
+}
+
+/** Return a bounded recency bonus relative to the newest candidate timestamp. */
+function _recencyScore(ts: number, newestTs: number): number {
+  return Math.max(0, 0.5 * (1 - (newestTs - ts) / RECENCY_WINDOW_MS));
 }

package/src/session-migration.ts

@@ -0,0 +1,188 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+interface CodexMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  timestamp: number;
+}
+
+interface CodexSession {
+  id: string;
+  cwd: string;
+  timestamp: number;
+  messages: CodexMessage[];
+}
+
+export interface ProjectSessionMigrationStats {
+  scannedFiles: number;
+  migratedSessions: number;
+  skippedSessions: number;
+  migratedMessages: number;
+  issues: Array<{ path: string; error: string }>;
+}
+
+/** Convert every Codex session recorded for cwd into an independently resumable Pi session file. */
+export function migrateCodexProjectSessions(cwd: string): ProjectSessionMigrationStats {
+  const stats: ProjectSessionMigrationStats = {
+    scannedFiles: 0,
+    migratedSessions: 0,
+    skippedSessions: 0,
+    migratedMessages: 0,
+    issues: [],
+  };
+  for (const path of _jsonlFiles(join(homedir(), ".codex", "sessions"))) {
+    stats.scannedFiles++;
+    try {
+      const session = _parseCodexSession(path);
+      if (!session || session.cwd !== cwd) continue;
+      const outputPath = _targetPath(session);
+      if (existsSync(outputPath)) {
+        stats.skippedSessions++;
+        continue;
+      }
+      _writePiSession(session, outputPath);
+      stats.migratedSessions++;
+      stats.migratedMessages += session.messages.length;
+    } catch (error) {
+      stats.issues.push({ path, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return stats;
+}
+
+/** Convert one supported Codex JSONL file into its session metadata and textual messages. */
+function _parseCodexSession(path: string): CodexSession | undefined {
+  const entries = readFileSync(path, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line) as Record<string, unknown>);
+  const metadata = entries.find((entry) => entry.type === "session_meta")?.payload as Record<string, unknown> | undefined;
+  if (!metadata) return undefined;
+  const id = _string(metadata.session_id) ?? _string(metadata.id);
+  const cwd = _string(metadata.cwd);
+  const timestamp = _timestamp(_string(metadata.timestamp));
+  if (!id || !cwd || timestamp === undefined) throw new Error("Codex session_meta requires session_id/id, cwd, and timestamp");
+
+  const messages: CodexMessage[] = [];
+  for (const [index, entry] of entries.entries()) {
+    if (entry.type !== "response_item") continue;
+    const payload = entry.payload as Record<string, unknown> | undefined;
+    if (payload?.type !== "message") continue;
+    const role = _string(payload.role);
+    if (role !== "user" && role !== "assistant") continue;
+    const text = _text(payload.content);
+    if (!text) continue;
+    const messageId = _string(payload.id)
+      ?? _string(entry.id)
+      ?? _string((payload.internal_chat_message_metadata_passthrough as Record<string, unknown> | undefined)?.turn_id);
+    if (!messageId) throw new Error(`Codex textual message at entry ${index} has no stable native ID`);
+    messages.push({
+      id: messageId,
+      role,
+      text,
+      timestamp: _timestamp(_string(entry.timestamp)) ?? timestamp,
+    });
+  }
+  return { id, cwd, timestamp, messages };
+}
+
+/** Write a valid Pi v3 session with a linear message branch and an explicit migration name. */
+function _writePiSession(session: CodexSession, path: string): void {
+  mkdirSync(join(homedir(), ".pi", "agent", "sessions", _encodedCwd(session.cwd)), { recursive: true });
+  const lines: string[] = [JSON.stringify({
+    type: "session",
+    version: 3,
+    id: randomUUID(),
+    timestamp: new Date(session.timestamp).toISOString(),
+    cwd: session.cwd,
+  })];
+  let parentId: string | null = null;
+  const nameId = _entryId(session.id, "name");
+  lines.push(JSON.stringify({
+    type: "session_info",
+    id: nameId,
+    parentId,
+    timestamp: new Date(session.timestamp).toISOString(),
+    name: `Migrated from Codex: ${session.id}`,
+  }));
+  parentId = nameId;
+  for (const message of session.messages) {
+    const id = _entryId(session.id, message.id);
+    const timestamp = new Date(message.timestamp).toISOString();
+    lines.push(JSON.stringify({
+      type: "message",
+      id,
+      parentId,
+      timestamp,
+      message: message.role === "user"
+        ? { role: "user", content: [{ type: "text", text: message.text }], timestamp: message.timestamp }
+        : {
+          role: "assistant",
+          content: [{ type: "text", text: message.text }],
+          api: "codex-migration",
+          provider: "codex",
+          model: "unknown",
+          usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+          stopReason: "stop",
+          timestamp: message.timestamp,
+        },
+    }));
+    parentId = id;
+  }
+  const temporaryPath = `${path}.tmp-${randomUUID()}`;
+  try {
+    writeFileSync(temporaryPath, `${lines.join("\n")}\n`, { flag: "wx" });
+    renameSync(temporaryPath, path);
+  } finally {
+    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
+  }
+}
+
+/** Return the deterministic Pi session-file location for one Codex session. */
+function _targetPath(session: CodexSession): string {
+  return join(homedir(), ".pi", "agent", "sessions", _encodedCwd(session.cwd), `${new Date(session.timestamp).toISOString().replace(/[.:]/g, "-")}_codex-${session.id}.jsonl`);
+}
+
+/** Encode cwd exactly as Pi's default session directory convention. */
+function _encodedCwd(cwd: string): string {
+  return `--${cwd.split("/").filter(Boolean).join("-")}--`;
+}
+
+/** Create stable, Pi-safe entry IDs without fabricating source message identity. */
+function _entryId(sessionId: string, sourceId: string): string {
+  return createHash("sha256").update(`${sessionId}:${sourceId}`).digest("hex").slice(0, 16);
+}
+
+/** Extract non-empty string values only. */
+function _string(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+/** Parse an ISO timestamp only when it is valid. */
+function _timestamp(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp) ? undefined : timestamp;
+}
+
+/** Join supported Codex text content blocks. */
+function _text(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block): block is { type: string; text: string } => Boolean(block) && typeof block === "object" && typeof (block as { type?: unknown }).type === "string" && typeof (block as { text?: unknown }).text === "string")
+    .filter((block) => block.type === "input_text" || block.type === "output_text" || block.type === "text")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+}
+
+/** Recursively enumerate source JSONL files. */
+function _jsonlFiles(root: string): string[] {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return _jsonlFiles(path);
+    return entry.isFile() && path.endsWith(".jsonl") ? [path] : [];
+  });
+}

package/src/writer.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import { upsertSession, insertTurn } from "./db.ts";
 
+/** Persist the latest Pi user request and all following assistant output as one turn. */
 export function writeTurn(ctx: ExtensionContext): void {
   const sessionManager = ctx.sessionManager;
   const sessionId = `pi:${sessionManager.getSessionId()}`;
@@ -50,6 +51,7 @@ export function writeTurn(ctx: ExtensionContext): void {
   });
 }
 
+/** Join text blocks from a Pi message while ignoring non-text content. */
 function _extractText(message: { content: string | Array<{ type: string; text?: string }> }): string {
   if (typeof message.content === "string") return message.content.trim();
   return message.content
@@ -59,6 +61,7 @@ function _extractText(message: { content: string | Array<{ type: string; text?:
     .trim();
 }
 
+/** Calculate the zero-based user-turn position within the current session branch. */
 function _userTurnIndex(branch: ReturnType<ExtensionContext["sessionManager"]["getBranch"]>, userIndex: number): number {
   return branch.slice(0, userIndex + 1)
     .filter((entry) => entry.type === "message" && entry.message.role === "user")

package/spec.md

@@ -1,172 +0,0 @@
-# pi-session-memory — Spec
-
-## Goal
-
-A pi extension that persists every conversation turn to SQLite and exposes a
-`recall_memory` tool so the LLM can retrieve relevant past turns when the user
-references previous discussions.
-
-## Architecture
-
-```
-pi turn_end event ──────────────────────────┐
-                                             ▼
-                                 Writer (src/writer.ts)
-                                 - writes current pi turns
-                                             │
-session_start ───────────┐                 │
-                          ▼                 ▼
-                 Incremental source sync → SQLite ~/.pi/agent/memory.db
-                 - per-file size + mtime quick check
-                 - SHA-256 only for changed candidates
-                 - Pi / Claude / Codex JSONL adapters
-
-/memory-backfill forces a full rescan.
-                                             │
-                                             ▼
-                                 recall_memory tool
-                                 - LLM supplies entities[]
-                                 - LIKE substring match + hit-score ranking
-                                 - returns top-5 turns
-```
-
-## Tables
-
-### sessions
-| column     | type    | note                          |
-|------------|---------|-------------------------------|
-| session_id | TEXT PK | native source session ID (UUID) |
-| source     | TEXT    | `pi`, `claude`, or `codex`     |
-| cwd        | TEXT    | working directory             |
-| started_at | INTEGER | unix ms                       |
-| model_id   | TEXT    | first model_change value      |
-| jsonl_path | TEXT    | absolute path to source file  |
-
-### turns
-| column      | type    | note                                      |
-|-------------|---------|-------------------------------------------|
-| turn_id     | TEXT PK | `{session_id}:{user_message_id}` — stable across live write and backfill |
-| session_id  | TEXT FK |                                           |
-| turn_index  | INTEGER | display order within session; never used as identity |
-| ts          | INTEGER | user message timestamp (unix ms)          |
-| user_text   | TEXT    | user message content                      |
-| reply_text  | TEXT    | assistant final text (all text blocks)    |
-| tool_names  | TEXT    | JSON array e.g. `["bash","read"]`         |
-
-There is intentionally no full-text virtual table. Retrieval uses escaped
-SQLite `LIKE` against the complete `user_text` and `reply_text`, because literal
-substring coverage and retrieval quality are prioritized over index performance.
-
-## Write Path
-
-Trigger: `agent_settled` event, after the agent run and any automatic
-continuations have completed.
-
-Steps:
-1. Locate the latest user `SessionEntry` in `ctx.sessionManager.getBranch()` and
-   use its stable entry ID as `user_message_id`; do not use pi's transient `turnIndex`.
-2. Extract `user_text` from that user entry's text content blocks.
-3. Walk branch entries after that user entry to collect assistant text blocks →
-   `reply_text`, and toolCall names → `tool_names`.
-4. Upsert source=`pi` session row (INSERT OR IGNORE).
-5. Insert turn by stable ID (INSERT OR IGNORE — live writing and backfill target
-   the same row).
-
-## Retrieval Path (recall_memory tool)
-
-### source_files
-| column | type | note |
-|---|---|---|
-| jsonl_path | TEXT PK | absolute source file path |
-| source | TEXT | `pi`, `claude`, or `codex` |
-| size | INTEGER | file size at last sync |
-| mtime_ms | REAL | modification time at last sync |
-| sha256 | TEXT | content hash for changed candidates |
-
-### Tool Invocation Policy
-
-- **Direct recall:** Call `recall_memory` immediately when the user explicitly
-  asks to review, remember, summarize, continue, or compare a prior discussion
-  about a topic.
-- **Knowledge-gap recall:** When the user asks about a topic you cannot answer
-  confidently from the current conversation and your general knowledge, but it
-  may have been discussed in the user's past sessions, ask the user whether they
-  want you to search their conversation history. Call `recall_memory` only after
-  the user agrees.
-- Do not search history merely because a question is difficult when the user has
-  not indicated that their own prior work or discussions are relevant.
-
-Input: `{ entities: string[] }` — 2-5 key terms extracted by LLM from user query.
-
-Steps:
-1. Build per-entity LIKE hit score:
-   - `user_text` match = 2 points
-   - `reply_text` match = 1 point
-2. `SELECT ... WHERE (LOWER(user_text) LIKE ? OR LOWER(reply_text) LIKE ?) OR ...`
-3. Escape `%`, `_`, and `\\` in every entity, then use `LIKE ? ESCAPE '\\'` so
-   technical names containing LIKE wildcards remain literal substring matches.
-4. `ORDER BY hits DESC, ts DESC LIMIT 5`
-
-No FTS5 or write-time preprocessing. LIKE is a literal substring match after
-escaping, so it does not lose substring matches through tokenization.
-
-## Backfill
-
-At `session_start`, `syncChangedHistory()` recursively enumerates the three
-source roots. It records one row per source JSONL file in `source_files`:
-`jsonl_path`, source, size, `mtime_ms`, and SHA-256. Unchanged size/mtime files
-are skipped without reading; changed candidates are SHA-256 checked, and only
-new content is parsed and imported.
-
-`/memory-backfill` forces a full reparse of all historical records. All writes
-use `INSERT OR IGNORE`, so both automatic sync and forced backfill are safe and
-idempotent to run repeatedly.
-
-| source | scan root | accepted user/assistant records | excluded records |
-|---|---|---|---|
-| pi | `~/.pi/agent/sessions/**/*.jsonl` | `message.role=user|assistant` | thinking, tool results, non-text content |
-| claude | `~/.claude/projects/**/*.jsonl` | `type=user|assistant`, `message.role=user|assistant` | `isMeta`, sidechains, slash commands, local-command tags, continuation summaries, system/snapshot/attachments |
-| codex | `~/.codex/sessions/**/*.jsonl` | `type=response_item`, `payload.type=message`, `role=user|assistant` | developer/system context, AGENTS.md and environment-context injection, IDE/image context, reasoning and tool events |
-
-Each adapter outputs the common `ImportedSession` / `ImportedTurn` model.
-Turns pair one accepted user message with all following accepted assistant text
-until the next accepted user message. Each source adapter preserves the native
-user-message ID (`pi entry.id`, Claude `uuid`, Codex `payload.id`) so rerunning
-backfill never creates a duplicate of an already live-written pi turn.
-
-## Acceptance Criteria
-
-- A pi session with multiple user turns produces one distinct `turns` row per
-  user message; no row is dropped because `turnIndex` restarts.
-- Running backfill after live pi writing does not duplicate those pi turns.
-- Claude and Codex injected context records listed above are absent from
-  `turns.user_text`.
-- Entity text containing `%`, `_`, or `\\` only matches its literal occurrence.
-- Automated tests cover stable turn identity, LIKE escaping/ranking, and
-  cross-source backfill parsing.
-
-## File Structure
-
-```
-pi-session-memory/
-├── spec.md
-├── package.json
-├── tsconfig.json
-├── extensions/
-│   └── index.ts       ← extension entry: tool + /memory-backfill
-├── tests/
-│   └── core.test.ts   ← persistence identity and literal-LIKE tests
-└── src/
-    ├── db.ts          ← DatabaseSync schema + upsert helpers
-    ├── writer.ts      ← live pi turn_end writer
-    ├── retriever.ts   ← LIKE query + hit-score ranking
-    └── backfill.ts    ← Pi / Claude / Codex adapters and import runner
-```
-
-## Constraints
-
-- Zero external dependencies (use `node:sqlite`, `node:fs`, `node:path`, `node:os`)
-- Idempotent writes (INSERT OR IGNORE on turn_id)
-- Cross-platform paths: storage is `join(homedir(), ".pi", "agent", "memory.db")`; source roots are derived with `join(homedir(), ...)`, never hard-coded POSIX paths.
-- Requires a Pi-supported Node.js runtime that exposes `node:sqlite` (`DatabaseSync`).
-- No fallback / silent failure — let errors surface