pi-session-memory 0.4.0 → 0.6.0

package/src/db.ts

@@ -2,66 +2,29 @@ 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");
 
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS sessions (
-  session_id  TEXT PRIMARY KEY,
-  source      TEXT NOT NULL DEFAULT 'pi',
-  cwd         TEXT NOT NULL,
-  started_at  INTEGER NOT NULL,
-  model_id    TEXT,
-  jsonl_path  TEXT NOT NULL
+  session_id TEXT PRIMARY KEY, source TEXT NOT NULL DEFAULT 'pi', cwd TEXT NOT NULL,
+  started_at INTEGER NOT NULL, model_id TEXT, jsonl_path TEXT NOT NULL
 );
-
 CREATE INDEX IF NOT EXISTS idx_sessions_time ON sessions(started_at DESC);
-
 CREATE TABLE IF NOT EXISTS turns (
-  turn_id     TEXT PRIMARY KEY,
-  session_id  TEXT NOT NULL REFERENCES sessions(session_id),
-  turn_index  INTEGER NOT NULL,
-  ts          INTEGER NOT NULL,
-  user_text   TEXT NOT NULL,
-  reply_text  TEXT NOT NULL,
-  tool_names  TEXT,
-  user_message_id TEXT
+  turn_id TEXT PRIMARY KEY, session_id TEXT NOT NULL REFERENCES sessions(session_id),
+  turn_index INTEGER NOT NULL, ts INTEGER NOT NULL, user_text TEXT NOT NULL, reply_text TEXT NOT NULL,
+  tool_names TEXT, user_message_id TEXT
 );
-
 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 INDEX IF NOT EXISTS idx_turns_ts ON turns(ts 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
-);
-`;
+  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. */
+/** Open the singleton local transcript index and upgrade its raw-history schema. */
 export function getDb(): DatabaseSync {
   if (_db) return _db;
   mkdirSync(join(homedir(), ".pi", "agent"), { recursive: true });
@@ -70,316 +33,50 @@ export function getDb(): DatabaseSync {
   _db.exec("PRAGMA synchronous = NORMAL");
   _db.exec(SCHEMA);
   _migrate(_db);
+  _db.exec(SCHEMA);
   return _db;
 }
 
-/** Apply additive schema migrations required by newer memory formats. */
+/** Keep only raw session history when opening databases created by earlier package versions. */
 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")) {
-    db.exec("ALTER TABLE sessions ADD COLUMN source TEXT NOT NULL DEFAULT 'pi'");
-  }
-
+  if (!sessionColumns.some((column) => column.name === "source")) db.exec("ALTER TABLE sessions ADD COLUMN source TEXT NOT NULL DEFAULT 'pi'");
   const turnColumns = db.prepare("PRAGMA table_info(turns)").all() as Array<{ name: string }>;
   if (!turnColumns.some((column) => column.name === "user_message_id")) {
     db.exec("ALTER TABLE turns ADD COLUMN user_message_id TEXT");
     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");
-  }
+  db.exec("DROP TABLE IF EXISTS memory_sources");
+  db.exec("DROP TABLE IF EXISTS cache_migration_audit");
+  db.exec("DROP TABLE IF EXISTS memories");
 }
 
-export interface SessionRow {
-  session_id: string;
-  source:     "pi" | "claude" | "codex";
-  cwd:        string;
-  started_at: number;
-  model_id:   string | null;
-  jsonl_path: string;
-}
-
-export interface TurnRow {
-  turn_id:    string;
-  session_id: string;
-  turn_index: number;
-  ts:         number;
-  user_text:  string;
-  reply_text: string;
-  tool_names: string | null;
-  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");
-}
+export interface SessionRow { session_id: string; source: "pi" | "claude" | "codex"; cwd: string; started_at: number; model_id: string | null; jsonl_path: string; }
+export interface TurnRow { turn_id: string; session_id: string; turn_index: number; ts: number; user_text: string; reply_text: string; tool_names: string | null; user_message_id: string; }
+export interface StoredSession { session: SessionRow; turns: TurnRow[]; }
+export interface SourceFileRow { jsonl_path: string; source: "pi" | "claude" | "codex"; size: number; mtime_ms: number; sha256: string; }
+export interface HistoryStats { sessions: number; turns: number; oldestTs: number | null; newestTs: number | null; sources: Array<{ source: "pi" | "claude" | "codex"; sessions: number; turns: number }>; }
 
-/** 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)
-    VALUES (?, ?, ?, ?, ?, ?)
-  `).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 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; }
+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); }
+export function upsertSession(row: SessionRow): void { getDb().prepare("INSERT OR IGNORE INTO sessions (session_id, source, cwd, started_at, model_id, jsonl_path) VALUES (?, ?, ?, ?, ?, ?)").run(row.session_id, row.source, row.cwd, row.started_at, row.model_id, row.jsonl_path); }
 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[];
+  if (!session) throw new Error(`History 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 };
+export function getHistoryStats(): HistoryStats {
+  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"];
+  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 HistoryStats["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(...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}`);
+  return 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).changes === 1;
 }

package/src/fetch-session.ts

@@ -0,0 +1,8 @@
+import { getSession, type StoredSession } from "./db.ts";
+
+export interface FetchedSessionResult { stored: StoredSession; }
+
+/** Fetch original persisted transcript evidence without changing the local transcript index. */
+export function fetchSession(sessionId: string, fromTurnIndex?: number, toTurnIndex?: number): FetchedSessionResult {
+  return { stored: getSession(sessionId, fromTurnIndex, toTurnIndex) };
+}

package/src/helper.ts

@@ -1,44 +1,24 @@
 /** 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 中无缝接续 Claude Code 或 Codex 项目会话 / Seamlessly continue Claude Code or Codex project sessions in Pi**
-  - 只有当你明确希望在 Pi 中接续某个项目的 Claude Code 或 Codex 历史工作流时，才建议迁移项目会话。
-  - Migrate sessions only when you explicitly want to continue a project's Claude Code or Codex workflow seamlessly in Pi.
-  - “请把当前项目以前的 Claude Code 会话迁移成 Pi session。”或“请把当前项目以前的 Codex 会话迁移成 Pi session。”
-  - “Convert this project's previous Claude Code sessions into Pi sessions.” or “Convert this project's previous Codex sessions into Pi sessions.”
-  - 每个迁移的 session 会成为一个独立的 Pi session；完成后用 \`/resume\` 选择要继续的会话。
-  - Each migrated session becomes an independent Pi session; use \`/resume\` to select the one you want to continue.
-  - 只迁移记录的工作目录与当前项目一致的会话。
-  - Only 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.`;
+本插件将 Pi、Claude Code 和 Codex 的本地历史索引到 SQLite，供按需跨会话检索。
+This extension indexes local Pi, Claude Code, and Codex history for on-demand cross-session retrieval.
+
+- **检索以前的讨论 / Recall past discussions**
+  - 直接询问“我们之前讨论过 xxx 的什么方案？”或 “What did we decide about xxx?”
+  - Pi 只在需要时搜索本地历史；匹配摘要不足时才读取最小必要会话范围。
+  - 历史不会自动注入模型上下文，也不会保存 Agent 生成的记忆摘要。
+
+- **迁移项目会话 / Migrate project sessions**
+  - 只有希望通过 \`/resume\` 在 Pi 原生继续 Claude Code 或 Codex 项目会话时，才运行迁移。
+  - 使用 \`/project-claude-session-migration\` 或 \`/project-session-migration\`。
+  - 每个迁移源会话生成一个独立 Pi session。
+
+- **本地存储 / Local storage**
+  - \`/memory-search <query>\` 搜索原始本地 transcript。
+  - \`/memory-backfill\` 明确要求时全量重扫历史。
+  - \`/memory-status\` 显示已索引的 session 和 turn 总数。
+  - 持久规则、偏好和项目指令应写在 \`AGENTS.md\`。
+
+历史仅保存在本机 SQLite。导入错误按来源文件隔离，不会阻止其他 Pi、Claude Code 或 Codex 会话被索引。
+History stays in local SQLite; an import error in one source file does not block other sessions.`;