pi-session-memory 0.1.4 → 0.2.1

package/src/backfill.ts

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -25,6 +25,12 @@ interface ImportedSession {
   messages: ImportedMessage[];
 }
 
+export interface BackfillIssue {
+  source: Source;
+  jsonlPath: string | null;
+  error: string;
+}
+
 export interface BackfillStats {
   pi: number;
   claude: number;
@@ -32,8 +38,16 @@ export interface BackfillStats {
   turns: number;
   scannedFiles: number;
   skippedFiles: number;
+  issues: BackfillIssue[];
 }
 
+/** Versions whose Claude Code and Codex JSONL schemas this importer was verified against. */
+export const HISTORY_SCHEMA_REFERENCE_VERSIONS = {
+  pi: "0.85.1",
+  claude: "2.1.234",
+  codex: "0.154.0",
+} as const;
+
 const SOURCES: Array<{ source: Source; root: string; parse: (path: string) => ImportedSession | undefined }> = [
   { source: "pi", root: join(homedir(), ".pi", "agent", "sessions"), parse: _parsePi },
   { source: "claude", root: join(homedir(), ".claude", "projects"), parse: _parseClaude },
@@ -50,35 +64,61 @@ export function syncChangedHistory(): BackfillStats {
   return _syncHistory(false);
 }
 
+/** Synchronize all configured JSONL sources. */
 function _syncHistory(force: boolean): BackfillStats {
-  const stats: BackfillStats = { pi: 0, claude: 0, codex: 0, turns: 0, scannedFiles: 0, skippedFiles: 0 };
+  const stats: BackfillStats = { pi: 0, claude: 0, codex: 0, turns: 0, scannedFiles: 0, skippedFiles: 0, issues: [] };
   for (const definition of SOURCES) {
-    for (const jsonlPath of _jsonlFiles(definition.root)) {
-      const metadata = statSync(jsonlPath);
-      const known = getSourceFile(jsonlPath);
-      if (!force && known?.size === metadata.size && known.mtime_ms === metadata.mtimeMs) {
-        stats.skippedFiles++;
-        continue;
-      }
-
-      const sha256 = _sha256(jsonlPath);
-      if (!force && known?.sha256 === sha256) {
-        upsertSourceFile({ jsonl_path: jsonlPath, source: definition.source, size: metadata.size, mtime_ms: metadata.mtimeMs, sha256 });
-        stats.skippedFiles++;
-        continue;
-      }
-
-      const session = definition.parse(jsonlPath);
+    if (!existsSync(definition.root)) continue;
+    try {
+      for (const jsonlPath of _jsonlFiles(definition.root)) _syncSourceFile(definition, jsonlPath, force, stats);
+    } catch (error) {
+      stats.issues.push(_backfillIssue(definition.source, null, error));
+    }
+  }
+  return stats;
+}
+
+/** Synchronize one source file without allowing its failure to block other files or sources. */
+function _syncSourceFile(definition: typeof SOURCES[number], jsonlPath: string, force: boolean, stats: BackfillStats): void {
+  try {
+    const metadata = statSync(jsonlPath);
+    const known = getSourceFile(jsonlPath);
+    if (!force && known?.size === metadata.size && known.mtime_ms === metadata.mtimeMs) {
+      stats.skippedFiles++;
+      return;
+    }
+
+    const sha256 = _sha256(jsonlPath);
+    if (!force && known?.sha256 === sha256) {
       upsertSourceFile({ jsonl_path: jsonlPath, source: definition.source, size: metadata.size, mtime_ms: metadata.mtimeMs, sha256 });
-      stats.scannedFiles++;
-      if (!session) continue;
+      stats.skippedFiles++;
+      return;
+    }
+
+    const session = definition.parse(jsonlPath);
+    if (session) {
       stats[definition.source]++;
       stats.turns += _persist(session);
+      upsertSourceFile({ jsonl_path: jsonlPath, source: definition.source, size: metadata.size, mtime_ms: metadata.mtimeMs, sha256 });
     }
+    stats.scannedFiles++;
+  } catch (error) {
+    stats.issues.push(_backfillIssue(definition.source, jsonlPath, error));
   }
-  return stats;
 }
 
+/** Format an isolated source failure with the reference version for schema comparison. */
+function _backfillIssue(source: Source, jsonlPath: string | null, error: unknown): BackfillIssue {
+  const location = jsonlPath ? ` (${jsonlPath})` : "";
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    source,
+    jsonlPath,
+    error: `${source} history import failed${location}: ${message}. Compare the local ${source} version with the supported reference ${HISTORY_SCHEMA_REFERENCE_VERSIONS[source]}; this may be a JSONL schema compatibility issue.`,
+  };
+}
+
+/** Convert one normalized source session into paired, idempotently stored memory turns. */
 function _persist(session: ImportedSession): number {
   const sessionId = `${session.source}:${session.nativeSessionId}`;
   upsertSession({
@@ -96,6 +136,7 @@ function _persist(session: ImportedSession): number {
   const toolNames: string[] = [];
   let persisted = 0;
 
+  /** Persist the current user-plus-assistant accumulation when a turn boundary is reached. */
   const flush = () => {
     if (!user || !replyText.trim()) return;
     const inserted = insertTurn({
@@ -127,6 +168,7 @@ function _persist(session: ImportedSession): number {
   return persisted;
 }
 
+/** Parse a Pi JSONL session into the source-neutral import representation. */
 function _parsePi(jsonlPath: string): ImportedSession | undefined {
   const entries = _readJsonl(jsonlPath);
   const header = entries.find((entry) => entry.type === "session");
@@ -143,7 +185,13 @@ function _parsePi(jsonlPath: string): ImportedSession | undefined {
     const toolNames = message.role === "assistant"
       ? message.content.filter((block: any) => block.type === "toolCall").map((block: any) => block.name)
       : [];
-    messages.push({ id: entry.id, role: message.role, text, ts: message.timestamp, toolNames });
+    messages.push({
+      id: _messageId("Pi entry.id", entry.id),
+      role: message.role,
+      text,
+      ts: message.timestamp,
+      toolNames,
+    });
   }
 
   return {
@@ -157,6 +205,7 @@ function _parsePi(jsonlPath: string): ImportedSession | undefined {
   };
 }
 
+/** Parse non-meta Claude Code conversation records into normalized messages. */
 function _parseClaude(jsonlPath: string): ImportedSession | undefined {
   const entries = _readJsonl(jsonlPath);
   const firstConversation = entries.find((entry) =>
@@ -174,7 +223,14 @@ function _parseClaude(jsonlPath: string): ImportedSession | undefined {
     const toolNames = role === "assistant"
       ? entry.message.content.filter((block: any) => block.type === "tool_use").map((block: any) => block.name)
       : [];
-    messages.push({ id: entry.uuid, role, text, ts: Date.parse(entry.timestamp), toolNames });
+    // Workaround: Claude Code JSONL schema differs by version; message IDs may be in uuid or id.
+    messages.push({
+      id: _messageId("Claude entry.uuid or entry.id", entry.uuid, entry.id),
+      role,
+      text,
+      ts: Date.parse(entry.timestamp),
+      toolNames,
+    });
   }
 
   return {
@@ -188,6 +244,7 @@ function _parseClaude(jsonlPath: string): ImportedSession | undefined {
   };
 }
 
+/** Parse Codex session metadata and response-message envelopes into normalized messages. */
 function _parseCodex(jsonlPath: string): ImportedSession | undefined {
   const entries = _readJsonl(jsonlPath);
   const meta = entries.find((entry) => entry.type === "session_meta")?.payload;
@@ -200,8 +257,14 @@ function _parseCodex(jsonlPath: string): ImportedSession | undefined {
     if (payload?.type !== "message" || (payload.role !== "user" && payload.role !== "assistant")) continue;
     const text = _codexText(payload);
     if (!text || (payload.role === "user" && _isCodexInjectedContext(text))) continue;
+    // Workaround: Codex JSONL schema differs by version; legacy sessions store the ID as metadata.turn_id.
     messages.push({
-      id: payload.id,
+      id: _messageId(
+        "Codex payload.id, entry.id, or metadata.turn_id",
+        payload.id,
+        entry.id,
+        payload.internal_chat_message_metadata_passthrough?.turn_id,
+      ),
       role: payload.role,
       text,
       ts: Date.parse(entry.timestamp),
@@ -220,6 +283,14 @@ function _parseCodex(jsonlPath: string): ImportedSession | undefined {
   };
 }
 
+/** Read a source message ID from a known schema field without inventing one for malformed records. */
+function _messageId(field: string, ...values: unknown[]): string {
+  const id = values.find((value): value is string => typeof value === "string" && value.length > 0);
+  if (!id) throw new Error(`Invalid ${field}: expected a non-empty string`);
+  return id;
+}
+
+/** Extract Pi text content while excluding thinking and non-text blocks. */
 function _piText(message: any): string {
   if (typeof message.content === "string") return message.content.trim();
   return message.content
@@ -229,6 +300,7 @@ function _piText(message: any): string {
     .trim();
 }
 
+/** Extract Claude Code text content from either legacy strings or content blocks. */
 function _claudeText(message: any): string {
   if (typeof message.content === "string") return message.content.trim();
   if (!Array.isArray(message.content)) return "";
@@ -239,6 +311,7 @@ function _claudeText(message: any): string {
     .trim();
 }
 
+/** Extract user input and assistant output text from a Codex message payload. */
 function _codexText(message: any): string {
   return message.content
     .filter((block: any) => block.type === "input_text" || block.type === "output_text")
@@ -247,6 +320,7 @@ function _codexText(message: any): string {
     .trim();
 }
 
+/** Identify Claude Code client-injected text that must not become user memory. */
 function _isClaudeInjectedContext(text: string): boolean {
   return text.startsWith("<command-name>")
     || text.startsWith("<command-message>")
@@ -255,6 +329,7 @@ function _isClaudeInjectedContext(text: string): boolean {
     || text.startsWith("This session is being continued from a previous conversation");
 }
 
+/** Identify Codex environment or IDE context that must not become user memory. */
 function _isCodexInjectedContext(text: string): boolean {
   return text.startsWith("# AGENTS.md instructions")
     || text.startsWith("<environment_context>")
@@ -262,10 +337,12 @@ function _isCodexInjectedContext(text: string): boolean {
     || text.startsWith("<image name=");
 }
 
+/** Hash a source JSONL file so unchanged content can skip reparsing. */
 function _sha256(jsonlPath: string): string {
   return createHash("sha256").update(readFileSync(jsonlPath)).digest("hex");
 }
 
+/** Read every non-empty JSONL line into its ordered JSON record. */
 function _readJsonl(jsonlPath: string): any[] {
   return readFileSync(jsonlPath, "utf8")
     .split("\n")
@@ -273,6 +350,7 @@ function _readJsonl(jsonlPath: string): any[] {
     .map((line) => JSON.parse(line));
 }
 
+/** Recursively discover JSONL session files under a source root. */
 function _jsonlFiles(root: string): string[] {
   const files: string[] = [];
   for (const entry of readdirSync(root, { withFileTypes: true })) {

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");
 
@@ -31,6 +32,24 @@ 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,
@@ -42,6 +61,7 @@ CREATE TABLE IF NOT EXISTS source_files (
 
 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 });
@@ -53,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")) {
@@ -65,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 {
@@ -87,6 +119,28 @@ 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";
@@ -95,6 +149,119 @@ export interface SourceFileRow {
   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
@@ -103,6 +270,7 @@ export function getSourceFile(jsonlPath: string): SourceFileRow | undefined {
   `).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)
@@ -115,6 +283,7 @@ export function upsertSourceFile(row: SourceFileRow): void {
   `).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)
@@ -122,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.`;