pi-session-memory 0.1.3 → 0.2.0

package/src/db.ts

@@ -2,6 +2,7 @@ import { DatabaseSync } from "node:sqlite";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { mkdirSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
 
 const DB_PATH = process.env.MEMORY_DB_PATH ?? join(homedir(), ".pi", "agent", "memory.db");
 
@@ -30,10 +31,37 @@ CREATE TABLE IF NOT EXISTS turns (
 
 CREATE INDEX IF NOT EXISTS idx_turns_session ON turns(session_id, turn_index);
 CREATE INDEX IF NOT EXISTS idx_turns_ts      ON turns(ts DESC);
+
+CREATE TABLE IF NOT EXISTS memories (
+  memory_id         TEXT PRIMARY KEY,
+  kind              TEXT NOT NULL CHECK(kind IN ('preference', 'decision', 'fact', 'project_state', 'task', 'lesson')),
+  content           TEXT NOT NULL,
+  project_key       TEXT NOT NULL,
+  source_turn_id    TEXT,
+  source_session_id TEXT,
+  source_content_hash TEXT,
+  source_turn_index INTEGER,
+  created_at        INTEGER NOT NULL,
+  last_confirmed_at INTEGER NOT NULL,
+  importance        REAL NOT NULL,
+  superseded_by     TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project_key);
+CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by, last_confirmed_at DESC);
+
+CREATE TABLE IF NOT EXISTS source_files (
+  jsonl_path TEXT PRIMARY KEY,
+  source     TEXT NOT NULL,
+  size       INTEGER NOT NULL,
+  mtime_ms   REAL NOT NULL,
+  sha256     TEXT NOT NULL
+);
 `;
 
 let _db: DatabaseSync | undefined;
 
+/** Open the singleton SQLite database and ensure its schema is ready for use. */
 export function getDb(): DatabaseSync {
   if (_db) return _db;
   mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
@@ -45,6 +73,7 @@ export function getDb(): DatabaseSync {
   return _db;
 }
 
+/** Apply additive schema migrations required by newer memory formats. */
 function _migrate(db: DatabaseSync): void {
   const sessionColumns = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
   if (!sessionColumns.some((column) => column.name === "source")) {
@@ -57,6 +86,17 @@ function _migrate(db: DatabaseSync): void {
     db.exec("DELETE FROM turns WHERE user_message_id IS NULL");
     db.exec("DELETE FROM sessions WHERE session_id NOT IN (SELECT DISTINCT session_id FROM turns)");
   }
+
+  const memoryColumns = db.prepare("PRAGMA table_info(memories)").all() as Array<{ name: string }>;
+  if (!memoryColumns.some((column) => column.name === "source_session_id")) {
+    db.exec("ALTER TABLE memories ADD COLUMN source_session_id TEXT");
+  }
+  if (!memoryColumns.some((column) => column.name === "source_content_hash")) {
+    db.exec("ALTER TABLE memories ADD COLUMN source_content_hash TEXT");
+  }
+  if (!memoryColumns.some((column) => column.name === "source_turn_index")) {
+    db.exec("ALTER TABLE memories ADD COLUMN source_turn_index INTEGER");
+  }
 }
 
 export interface SessionRow {
@@ -79,6 +119,171 @@ export interface TurnRow {
   user_message_id: string;
 }
 
+export interface StoredSession {
+  session: SessionRow;
+  turns: TurnRow[];
+}
+
+export type MemoryKind = "preference" | "decision" | "fact" | "project_state" | "task" | "lesson";
+
+export interface MemoryRow {
+  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;
+  created_at: number;
+  last_confirmed_at: number;
+  importance: number;
+  superseded_by: string | null;
+}
+
+export interface SourceFileRow {
+  jsonl_path: string;
+  source: "pi" | "claude" | "codex";
+  size: number;
+  mtime_ms: number;
+  sha256: string;
+}
+
+/** Create an explicit durable memory that remains independent from transcript retention. */
+export function createMemory(input: Omit<MemoryRow, "memory_id" | "source_session_id" | "source_content_hash" | "source_turn_index" | "created_at" | "last_confirmed_at" | "superseded_by"> & {
+  memory_id?: string;
+  source_session_id?: string | null;
+  source_content_hash?: string | null;
+  source_turn_index?: number | null;
+  created_at?: number;
+  last_confirmed_at?: number;
+}): MemoryRow {
+  const memory: MemoryRow = {
+    memory_id: input.memory_id ?? randomUUID(),
+    kind: input.kind,
+    content: input.content,
+    project_key: input.project_key,
+    source_turn_id: input.source_turn_id,
+    source_session_id: input.source_session_id ?? null,
+    source_content_hash: input.source_content_hash ?? null,
+    source_turn_index: input.source_turn_index ?? null,
+    created_at: input.created_at ?? Date.now(),
+    last_confirmed_at: input.last_confirmed_at ?? input.created_at ?? Date.now(),
+    importance: input.importance,
+    superseded_by: null,
+  };
+  getDb().prepare(`
+    INSERT INTO memories
+      (memory_id, kind, content, project_key, source_turn_id, source_session_id, source_content_hash, source_turn_index, created_at, last_confirmed_at, importance, superseded_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    memory.memory_id, memory.kind, memory.content, memory.project_key, memory.source_turn_id, memory.source_session_id, memory.source_content_hash, memory.source_turn_index,
+    memory.created_at, memory.last_confirmed_at, memory.importance, memory.superseded_by,
+  );
+  return memory;
+}
+
+/** Promote a historical turn into a durable fact with a permanent provenance reference. */
+export function pinTurnAsMemory(turnId: string): MemoryRow {
+  const turn = getDb().prepare(`
+    SELECT turns.turn_id, turns.session_id, turns.turn_index, turns.user_text, turns.reply_text, sessions.cwd
+    FROM turns JOIN sessions ON sessions.session_id = turns.session_id
+    WHERE turns.turn_id = ?
+  `).get(turnId) as { turn_id: string; session_id: string; turn_index: number; user_text: string; reply_text: string; cwd: string } | undefined;
+  if (!turn) throw new Error(`Memory turn not found: ${turnId}`);
+  const content = turn.reply_text ? `User: ${turn.user_text}\nAssistant: ${turn.reply_text}` : turn.user_text;
+  return createMemory({
+    kind: "fact",
+    content,
+    project_key: turn.cwd,
+    source_turn_id: turn.turn_id,
+    source_session_id: turn.session_id,
+    source_content_hash: _turnContentHash(turn.user_text, turn.reply_text),
+    source_turn_index: turn.turn_index,
+    importance: 1,
+  });
+}
+
+/** Hash the exact source evidence copied into a pinned durable memory. */
+function _turnContentHash(userText: string, replyText: string): string {
+  return createHash("sha256").update(JSON.stringify([userText, replyText])).digest("hex");
+}
+
+/** List durable memories, optionally narrowed to one validated memory kind. */
+export function listMemories(kind?: MemoryKind): MemoryRow[] {
+  const statement = kind
+    ? getDb().prepare(`SELECT * FROM memories WHERE kind = ? ORDER BY last_confirmed_at DESC, memory_id`)
+    : getDb().prepare(`SELECT * FROM memories ORDER BY last_confirmed_at DESC, memory_id`);
+  return (kind ? statement.all(kind) : statement.all()) as MemoryRow[];
+}
+
+/** Mark an active memory as recently reviewed without changing its content or provenance. */
+export function confirmMemory(memoryId: string): MemoryRow {
+  const memory = getDb().prepare("SELECT * FROM memories WHERE memory_id = ? AND superseded_by IS NULL").get(memoryId) as MemoryRow | undefined;
+  if (!memory) throw new Error(`Active durable memory not found: ${memoryId}`);
+  const last_confirmed_at = Date.now();
+  getDb().prepare("UPDATE memories SET last_confirmed_at = ? WHERE memory_id = ?").run(last_confirmed_at, memoryId);
+  return { ...memory, last_confirmed_at };
+}
+
+/** Explicitly replace one active memory with another while retaining the old record as history. */
+export function supersedeMemory(oldMemoryId: string, newMemoryId: string): void {
+  if (oldMemoryId === newMemoryId) throw new Error("A memory cannot supersede itself");
+  const db = getDb();
+  const oldMemory = db.prepare("SELECT memory_id, superseded_by FROM memories WHERE memory_id = ?").get(oldMemoryId) as { memory_id: string; superseded_by: string | null } | undefined;
+  const newMemory = db.prepare("SELECT memory_id FROM memories WHERE memory_id = ?").get(newMemoryId) as { memory_id: string } | undefined;
+  if (!oldMemory) throw new Error(`Durable memory not found: ${oldMemoryId}`);
+  if (!newMemory) throw new Error(`Durable memory not found: ${newMemoryId}`);
+  if (oldMemory.superseded_by) throw new Error(`Durable memory is already superseded: ${oldMemoryId}`);
+  db.prepare("UPDATE memories SET superseded_by = ? WHERE memory_id = ?").run(newMemoryId, oldMemoryId);
+}
+
+/** Return the complete oldest-to-newest replacement chain containing a durable memory. */
+export function getMemoryHistory(memoryId: string): MemoryRow[] {
+  const db = getDb();
+  let current = db.prepare("SELECT * FROM memories WHERE memory_id = ?").get(memoryId) as MemoryRow | undefined;
+  if (!current) throw new Error(`Durable memory not found: ${memoryId}`);
+  while (true) {
+    const predecessor = db.prepare("SELECT * FROM memories WHERE superseded_by = ?").get(current.memory_id) as MemoryRow | undefined;
+    if (!predecessor) break;
+    current = predecessor;
+  }
+  const history = [current];
+  while (current.superseded_by) {
+    current = db.prepare("SELECT * FROM memories WHERE memory_id = ?").get(current.superseded_by) as MemoryRow;
+    history.push(current);
+  }
+  return history;
+}
+
+/** Permanently delete one durable memory without altering its source transcript turn. */
+export function deleteMemory(memoryId: string): boolean {
+  return getDb().prepare("DELETE FROM memories WHERE memory_id = ?").run(memoryId).changes === 1;
+}
+
+/** Look up the persisted fingerprint for a source JSONL file. */
+export function getSourceFile(jsonlPath: string): SourceFileRow | undefined {
+  return getDb().prepare(`
+    SELECT jsonl_path, source, size, mtime_ms, sha256
+    FROM source_files
+    WHERE jsonl_path = ?
+  `).get(jsonlPath) as SourceFileRow | undefined;
+}
+
+/** Store the latest metadata and content hash for an imported source file. */
+export function upsertSourceFile(row: SourceFileRow): void {
+  getDb().prepare(`
+    INSERT INTO source_files (jsonl_path, source, size, mtime_ms, sha256)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(jsonl_path) DO UPDATE SET
+      source = excluded.source,
+      size = excluded.size,
+      mtime_ms = excluded.mtime_ms,
+      sha256 = excluded.sha256
+  `).run(row.jsonl_path, row.source, row.size, row.mtime_ms, row.sha256);
+}
+
+/** Insert session metadata when a source session is first encountered. */
 export function upsertSession(row: SessionRow): void {
   getDb().prepare(`
     INSERT OR IGNORE INTO sessions (session_id, source, cwd, started_at, model_id, jsonl_path)
@@ -86,14 +291,95 @@ export function upsertSession(row: SessionRow): void {
   `).run(row.session_id, row.source, row.cwd, row.started_at, row.model_id, row.jsonl_path);
 }
 
+/** Read one persisted session and an optional inclusive range of its ordered conversation turns. */
+export function getSession(sessionId: string, fromTurnIndex?: number, toTurnIndex?: number): StoredSession {
+  const session = getDb().prepare("SELECT * FROM sessions WHERE session_id = ?").get(sessionId) as SessionRow | undefined;
+  if (!session) throw new Error(`Memory session not found: ${sessionId}`);
+  const filters = ["session_id = ?"];
+  const parameters: Array<string | number> = [sessionId];
+  if (fromTurnIndex !== undefined) {
+    filters.push("turn_index >= ?");
+    parameters.push(fromTurnIndex);
+  }
+  if (toTurnIndex !== undefined) {
+    filters.push("turn_index <= ?");
+    parameters.push(toTurnIndex);
+  }
+  const turns = getDb().prepare(`
+    SELECT turn_id, session_id, turn_index, ts, user_text, reply_text, tool_names, user_message_id
+    FROM turns
+    WHERE ${filters.join(" AND ")}
+    ORDER BY turn_index
+  `).all(...parameters) as TurnRow[];
+  return { session, turns };
+}
+
+export interface MemoryStats {
+  sessions: number;
+  turns: number;
+  oldestTs: number | null;
+  newestTs: number | null;
+  sources: Array<{ source: "pi" | "claude" | "codex"; sessions: number; turns: number }>;
+}
+
+/** Summarize locally stored sessions and turns for memory management UI. */
+export function getMemoryStats(): MemoryStats {
+  const summary = getDb().prepare(`
+    SELECT count(*) AS turns, min(ts) AS oldestTs, max(ts) AS newestTs
+    FROM turns
+  `).get() as { turns: number; oldestTs: number | null; newestTs: number | null };
+  const sessionCount = getDb().prepare("SELECT count(*) AS count FROM sessions").get() as { count: number };
+  const sources = getDb().prepare(`
+    SELECT sessions.source, count(DISTINCT sessions.session_id) AS sessions, count(turns.turn_id) AS turns
+    FROM sessions
+    LEFT JOIN turns ON turns.session_id = sessions.session_id
+    GROUP BY sessions.source
+    ORDER BY sessions.source
+  `).all() as MemoryStats["sources"];
+  return { sessions: sessionCount.count, turns: summary.turns, oldestTs: summary.oldestTs, newestTs: summary.newestTs, sources };
+}
+
+/** Permanently remove one turn and clean up its session if it becomes empty. */
+export function deleteTurn(turnId: string): boolean {
+  const db = getDb();
+  const turn = db.prepare("SELECT session_id FROM turns WHERE turn_id = ?").get(turnId) as { session_id: string } | undefined;
+  if (!turn) return false;
+  // Delete the turn and its now-empty session atomically; a failed cleanup must not leave partial state.
+  db.exec("BEGIN");
+  try {
+    db.prepare("DELETE FROM turns WHERE turn_id = ?").run(turnId);
+    // Session metadata exists only to support its turns, so remove it after the final turn is forgotten.
+    db.prepare(`
+      DELETE FROM sessions
+      WHERE session_id = ?
+        AND NOT EXISTS (SELECT 1 FROM turns WHERE turns.session_id = sessions.session_id)
+    `).run(turn.session_id);
+    db.exec("COMMIT");
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+  return true;
+}
+
+/** Idempotently insert a normalized conversation turn and report whether it was new. */
 export function insertTurn(row: TurnRow): boolean {
+  const values: Array<string | number | bigint | Uint8Array | null> = [
+    row.turn_id, row.session_id, row.turn_index, row.ts,
+    row.user_text, row.reply_text, row.tool_names, row.user_message_id,
+  ];
+  values.forEach((value, index) => _assertSqliteValue(value, index + 1));
+
   const result = getDb().prepare(`
     INSERT OR IGNORE INTO turns
       (turn_id, session_id, turn_index, ts, user_text, reply_text, tool_names, user_message_id)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(
-    row.turn_id, row.session_id, row.turn_index, row.ts,
-    row.user_text, row.reply_text, row.tool_names, row.user_message_id,
-  );
+  `).run(...values);
   return result.changes === 1;
 }
+
+/** Reject unsupported SQLite values before binding them to an INSERT statement. */
+function _assertSqliteValue(value: unknown, parameter: number): asserts value is string | number | bigint | Uint8Array | null {
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "bigint" || value instanceof Uint8Array) return;
+  throw new TypeError(`SQLite parameter ${parameter} must be string, number, bigint, Uint8Array, or null; received ${typeof value}`);
+}

package/src/helper.ts

@@ -0,0 +1,44 @@
+/** Static user-facing overview displayed by the pi-session-memory helper command. */
+export const SESSION_MEMORY_HELP = `# pi-session-memory
+
+你可以直接像正常聊天一样请求使用历史记忆。
+You can request history and memory features in natural language.
+
+**跨客户端回忆与记忆 / Cross-client recall and memory**
+
+无论对话来自 Pi、Claude Code 还是 Codex，你都可以直接请求回忆历史或保存、管理长期记忆。
+Regardless of whether a conversation came from Pi, Claude Code, or Codex, you can directly recall history and save or manage durable memories.
+
+- **在 Pi 中无缝接续 Codex 项目会话 / Seamlessly continue Codex project sessions in Pi**
+  - 只有当你明确希望在 Pi 中接续某个项目的 Codex 历史工作流时，才建议迁移项目会话。
+  - Migrate sessions only when you explicitly want to continue a project's Codex workflow seamlessly in Pi.
+  - “请把当前项目以前的 Codex 会话迁移成 Pi session。”
+  - “Convert this project's previous Codex sessions into Pi sessions.”
+  - 每个 Codex session 会成为一个独立的 Pi session；完成后用 \`/resume\` 选择要继续的会话。
+  - Each Codex session becomes an independent Pi session; use \`/resume\` to select the one you want to continue.
+  - 只迁移记录的工作目录与当前项目一致的 Codex 会话。
+  - Only Codex sessions whose recorded working directory matches the current project are migrated.
+
+- **回忆以前的讨论 / Recall past discussions**
+  - “我们之前讨论过 xxx 的什么方案？”、“找一下我以前关于 xxx 的结论。”
+  - “What did we decide about xxx?” or “Find our earlier conclusion about the xxx.”
+  - 我会检索本地历史；必要时会读取匹配会话的相关上下文。
+  - I search local history and, when needed, retrieve relevant context from a matching session.
+
+- **保存长期结论 / Save a durable conclusion**
+  - “记住：发布前必须运行集成测试。”或“把刚才的架构决定固定下来。”
+  - “Remember that integration tests must run before release.” or “Save the architecture decision we just made.”
+
+- **管理保存的记忆 / Manage saved memories**
+  - “列出我保存的记忆”、“确认这条记忆仍然有效”、“用新结论替换旧记忆”，或“忘记那条部署约定。”
+  - “List my saved memories,” “confirm this memory is still current,” “replace the old memory with this conclusion,” or “forget that deployment convention.”
+
+- **查看当前存储情况 / Check local storage**
+  - “现在已经导入了多少历史记录？”
+  - “How much conversation history has been imported?”
+
+历史和记忆均保存在本机 SQLite 中。历史导入会按来源和文件隔离错误：一个不兼容的 Pi、Claude Code 或 Codex 会话不会阻止其他会话被导入。
+History and memories stay in local SQLite storage. Import errors are isolated by source and file, so one incompatible Pi, Claude Code, or Codex session does not block other sessions.
+
+随时运行 \`/pi-session-memory-helper\` 再次查看这些使用方式。
+Run \`/pi-session-memory-helper\` at any time to view this guide again.`;

package/src/retriever.ts

@@ -1,70 +1,230 @@
-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[];
+  topK?: number;
+  sources?: MemorySource[];
+  cwd?: string;
+  after?: number;
+  before?: number;
+  diversify?: boolean;
+}
+
+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 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;
 }
 
-export function recallTurns(entities: string[], topK = 5): RecallResult[] {
-  if (entities.length === 0) return [];
+export type RecallResult = RecallDurableMemoryResult | RecallTurnResult;
 
-  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];
-  });
+// Avoid allowing one long conversation to fill every raw-transcript recall slot.
+const MAX_TURNS_PER_SESSION = 2;
+// Recency is a bounded tie-breaker, not a replacement for literal relevance.
+const RECENCY_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
 
-  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];
-  });
+/** Retained for compatibility with the v0.1 public retrieval helper. */
+export function recallTurns(entities: string[], topK = 5): RecallTurnResult[] {
+  return _recallTurns({ query: entities.join(" "), entities, topK, diversify: false });
+}
 
-  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[];
+/** 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].slice(0, options.topK ?? 5);
 }
 
-export function formatRecallResults(results: RecallResult[]): string {
-  if (results.length === 0) return "No relevant past conversations found.";
+/** 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">): string {
+  const lines = options ? [_formatRecallQuery(options), ""] : [];
+  if (results.length === 0) return [...lines, "No relevant past conversations found."].join("\n");
 
-  const lines = ["## Relevant past conversations\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("");
   }
   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
+    LIMIT ?
+  `).all(...parameters, ...filterParameters, Math.max(options.topK ?? 5, 1))
+    .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 LIMIT ?
+  `).all(...scoreParameters, ...filterParameters, Math.max(options.topK ?? 5, 1) * 10) 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 options.diversify === false ? results.slice(0, options.topK ?? 5) : _diversify(results, options.topK ?? 5);
+}
+
+/** 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));
+}
+
+/** Limit ranked output to prevent any one session from dominating the recall window. */
+function _diversify(results: RecallTurnResult[], topK: number): RecallTurnResult[] {
+  const counts = new Map<string, number>();
+  return results.filter((result) => {
+    const count = counts.get(result.session_id) ?? 0;
+    if (count >= MAX_TURNS_PER_SESSION) return false;
+    counts.set(result.session_id, count + 1);
+    return true;
+  }).slice(0, topK);
 }