pi-session-memory 0.1.4 → 0.2.1

package/README.md

@@ -9,22 +9,44 @@ A local-first Pi extension that saves completed conversations to SQLite and give
 
 - Persists completed Pi conversations in `~/.pi/agent/memory.db`.
 - Automatically imports only new or changed Pi, Claude Code, and Codex session files when Pi starts.
-- Supports a forced full rescan with `/memory-backfill`.
+- Supports a forced full SQLite history rescan with `/memory-backfill`.
+- Converts current-project Codex sessions into separate native Pi sessions with `/project-session-migration`, ready to select through `/resume`.
 - Exposes `recall_memory`, allowing Pi to retrieve relevant prior discussions when users explicitly refer to earlier work.
 - Uses stable native user-message IDs and `INSERT OR IGNORE`, making live persistence and backfill idempotent.
 - Searches literal substrings with escaped SQLite `LIKE` patterns, including technical terms containing `%`, `_`, or `\\`.
+- Ranks results by literal relevance and recency, boosts an explicitly scoped project, and limits results to two turns per session for diversity.
+- Supports explicit durable memories, which remain after their source transcript turns are deleted.
+- Suppresses a raw turn from recall when an active durable memory contains the same unchanged pinned source evidence; other turns in that session remain eligible.
+- Flags a recalled durable memory when a newer matching turn exists in its source session, so users can explicitly confirm or supersede it without silent updates.
+- Includes status, direct search, and permanent deletion commands so users can inspect and control local memory.
 - Uses only Node.js built-ins and SQLite (`node:sqlite`); no external runtime dependencies.
 
 ## Installation
 
 ```bash
-pi install npm:pi-session-memory@0.1.4
+pi install npm:pi-session-memory
 ```
 
-To try the package without installing it permanently:
+This unpinned source can receive package-update checks at Pi startup. After a new release, update it explicitly with:
 
 ```bash
-pi -e npm:pi-session-memory@0.1.4
+pi update npm:pi-session-memory
+# or update every unpinned Pi extension
+pi update --extensions
+```
+
+Restart Pi after the update to load the new extension code.
+
+To try the latest package without installing it permanently:
+
+```bash
+pi -e npm:pi-session-memory
+```
+
+To intentionally pin a known version (which `pi update --extensions` skips), add its version explicitly:
+
+```bash
+pi install npm:pi-session-memory@0.2.1
 ```
 
 ## Usage
@@ -50,6 +72,32 @@ The command imports eligible user/assistant exchanges from:
 | Claude Code | `~/.claude/projects/**/*.jsonl` |
 | Codex | `~/.codex/sessions/**/*.jsonl` |
 
+### Continue a Codex session natively in Pi
+
+Use this command only when you want to continue prior **Codex** work as a real Pi session rather than search it as memory:
+
+```text
+/project-session-migration
+```
+
+It selects Codex JSONL files whose recorded `cwd` exactly equals the current project, then creates one independent Pi v3 session JSONL for each under Pi's normal session directory. Each migrated entry is named `Migrated from Codex: <session-id>`.
+
+After the command completes, run:
+
+```text
+/resume
+```
+
+and select the migrated session to continue it in Pi. Existing migrated outputs are skipped on subsequent runs.
+
+The converter preserves user and assistant text messages only. It deliberately does not convert Codex system/developer prompts, reasoning, tool calls, or tool results into Pi messages. Migration is separate from SQLite backfill and `recall_memory`; normal cross-client recall does not require migration.
+
+#### Context compaction and retention
+
+Compaction reduces what a running client sends to its model; it is not necessarily deletion of the local JSONL history. In locally observed Claude Code and Codex files, compaction is appended as a separate event (`system/compact_boundary` for Claude Code and `compacted` for Codex), while earlier user/assistant message records remain in the file and remain importable. This is observed behavior rather than a retention guarantee from those clients.
+
+The extension indexes normalized user/assistant text and selected tool names, not every JSONL event. It intentionally excludes reasoning, full tool inputs/outputs, system/developer context, workspace state, Pi custom records, Claude compaction metadata, and Codex handoff summaries. See [`quick-notes/jsonl-schema.md`](quick-notes/jsonl-schema.md) for source-specific formats and the exact importer boundary.
+
 ### Recall prior work
 
 The extension instructs Pi to call `recall_memory` when a user explicitly asks about a previous discussion, for example:
@@ -58,21 +106,50 @@ The extension instructs Pi to call `recall_memory` when a user explicitly asks a
 What did we decide about LangGraph last time?
 ```
 
+`recall_memory` is the discovery step: it searches and ranks the complete active durable-memory and raw-turn match set using the original request plus important entities. It supports optional exact project-directory, source, and time-window filters. Each tool response deliberately renders five results and reports `totalResults` and `nextOffset`; when more candidates are needed, Pi repeats the exact same query and filters with that explicit offset. This pages model context without silently limiting the local search. Raw transcript candidates contain a short excerpt plus a session ID and turn index, rather than the entire turn context. When surrounding conversation is needed to answer accurately, Pi calls `fetch_session` with that session ID and the smallest useful turn-index range. When an initial literal search is empty, Pi may make up to two additional local searches using reasoned alternatives—such as abbreviations, expansions, aliases, translations, or likely task wording—while retaining the original filters.
+
+When recall returns a durable memory, Pi is instructed to naturally communicate a relevant remembered conclusion and provenance when useful. If newer matching evidence makes that memory a freshness candidate, Pi explains the discrepancy and asks whether you want to keep, confirm, or replace it. It never claims a memory was updated or superseded without your explicit choice.
+
+### Inspect and control memory
+
+Recall and freshness explanations are automatic model behavior. The commands below remain deliberate user-control actions for inspecting or changing stored memory; they are not required for normal recalled answers.
+
 ```text
-回顾一下我们开发历史中关于 Joule 的内容
+/remember Keep SQLite writes local only
+/memory-pin pi:<session-id>:<user-message-id>
+/memory-list [decision]
+/memory-confirm <memory-id>
+/memory-supersede <old-memory-id> <new-memory-id>
+/memory-history <memory-id>
+/memory-forget <memory-id>
+/memory-delete-turn pi:<session-id>:<user-message-id>
+/memory-status
+/memory-search SQLite migration
 ```
 
-The tool searches prior user prompts and assistant responses, ranks matches by entity hits, and returns the five most relevant turns.
+`fetch_session` is an agent tool, not a user command: Pi invokes it selectively after `recall_memory` when it needs additional context from a specific discovered session.
+
+- `/remember <text>` saves an explicit durable `fact` scoped to the current project.
+- `/memory-pin <turn-id>` promotes a historical turn to a durable fact and records its source session, source turn ID, and a hash of the pinned evidence.
+- `/memory-list [kind]` displays durable memories, optionally limited to `preference`, `decision`, `fact`, `project_state`, `task`, or `lesson`.
+- Recall marks a durable memory as a freshness candidate when a newer query-matching turn appears in its source session; this is a review signal, not an automatic update.
+- `/memory-confirm <memory-id>` records that an active memory remains current by updating `last_confirmed_at`.
+- `/memory-supersede <old-memory-id> <new-memory-id>` explicitly replaces an active memory while retaining the old record for history; superseded memories are excluded from normal recall.
+- `/memory-history <memory-id>` displays the complete oldest-to-newest supersession chain.
+- `/memory-forget <memory-id>` permanently deletes a durable memory without deleting its source transcript.
+- `/memory-delete-turn <turn-id>` permanently deletes one raw turn; its session is also removed if it has no turns left.
+- `/memory-status` reports turn and session totals, per-source distribution, and newest memory time.
+- `/memory-search <query>` previews the same local literal retrieval used by the agent.
 
 ## How it works
 
 ```text
-Pi startup ──► incremental source sync ──► SQLite memory.db ◄── completed Pi agent run
-                                                  ▲
-                                                  │
-                                           recall_memory
-                                                  │
-                                      Pi / Claude / Codex
+Pi / Claude Code / Codex history ──► incremental source sync ──► SQLite memory.db
+                                                                  ▲
+                                                                  │
+                                                           recall_memory
+
+Current-project Codex JSONL ──► /project-session-migration ──► native Pi session JSONL ──► /resume
 ```
 
 After a Pi agent run settles, the extension captures the latest user message and the subsequent assistant replies/tool names from the active session branch. Historical imports normalize each supported source into the same session/turn schema.
@@ -87,6 +164,18 @@ The database stays on the local machine at:
 
 Conversation data is stored and queried locally. This package does not add a remote storage service or transmit conversation history on its own. Review the source and your model provider's configuration before using it with sensitive conversations.
 
+## Release notes
+
+| Version | Highlights |
+| --- | --- |
+| `0.2.1` | Pages `recall_memory` results in explicit five-result `offset` windows while still evaluating the complete local match set; npm publishing now uses a runtime-file allowlist. |
+| `0.2.0` | Added cross-client SQLite recall and durable-memory controls, plus native current-project Codex-to-Pi session migration for `/resume`. |
+| `0.1.4` | Automatically syncs new or changed Pi, Claude Code, and Codex history when Pi starts; `/memory-backfill` forces a full rescan. |
+| `0.1.3` | Improved package documentation and installation guidance. |
+| `0.1.2` | Added the MIT license. |
+| `0.1.1` | Added repository and package metadata for public distribution. |
+| `0.1.0` | Initial release: local SQLite memory, Pi live persistence, historical import, and `recall_memory` retrieval. |
+
 ## Development
 
 ```bash

package/extensions/index.ts

@@ -1,22 +1,32 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { writeTurn } from "../src/writer.ts";
-import { recallTurns, formatRecallResults } from "../src/retriever.ts";
-import { backfillAll, syncChangedHistory } from "../src/backfill.ts";
+import { confirmMemory, createMemory, deleteMemory, deleteTurn, getMemoryHistory, getMemoryStats, getSession, listMemories, pinTurnAsMemory, supersedeMemory, type MemoryKind } from "../src/db.ts";
+import { recallMemories, formatRecallResults, paginateRecallResults } from "../src/retriever.ts";
+import { backfillAll, syncChangedHistory, type BackfillStats } from "../src/backfill.ts";
+import { migrateCodexProjectSessions, type ProjectSessionMigrationStats } from "../src/session-migration.ts";
+import { SESSION_MEMORY_HELP } from "../src/helper.ts";
 
+/** Register lifecycle persistence, memory-management commands, and the recall tool with Pi. */
 export default function (pi: ExtensionAPI) {
 
-  pi.on("session_start", async (_event, ctx) => {
+  /** Synchronize changed external session history whenever a Pi session starts. */
+  pi.on("session_start", async (event, ctx) => {
     const stats = syncChangedHistory();
-    if (stats.scannedFiles > 0) {
+    if (event.reason === "startup" || stats.scannedFiles > 0) {
+      const summary = stats.scannedFiles > 0
+        ? `synced ${stats.turns} turns from ${stats.scannedFiles} changed session files`
+        : "ready";
       ctx.ui.notify(
-        `[session-memory] synced ${stats.turns} turns from ${stats.scannedFiles} changed session files`,
+        `[session-memory] ${summary}. Run /pi-session-memory-helper for an overview of cross-client memory features.`,
         "info",
       );
     }
+    for (const issue of stats.issues) ctx.ui.notify(`[session-memory] ${issue.error}`, "error");
   });
 
   // ── Write: persist each completed agent run to SQLite ────────────────────
+  /** Persist the just-completed live Pi turn after the agent has settled. */
   pi.on("agent_settled", async (_event, ctx) => {
     try {
       writeTurn(ctx);
@@ -25,14 +35,160 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  pi.registerCommand("pi-session-memory-helper", {
+    description: "Show pi-session-memory features and commands",
+    /** Display the static pi-session-memory feature overview without invoking the model. */
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(SESSION_MEMORY_HELP, "info");
+    },
+  });
+
+  pi.registerCommand("memory-status", {
+    description: "Show local memory storage and source statistics",
+    /** Report aggregate local-memory storage statistics. */
+    handler: async (_args, ctx) => {
+      const stats = getMemoryStats();
+      const sources = stats.sources.length
+        ? stats.sources.map((source) => `${source.source}: ${source.turns} turns / ${source.sessions} sessions`).join(", ")
+        : "no imported sources";
+      const newest = stats.newestTs ? new Date(stats.newestTs).toLocaleString() : "n/a";
+      ctx.ui.notify(`[session-memory] ${stats.turns} turns across ${stats.sessions} sessions; ${sources}; newest: ${newest}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-search", {
+    description: "Search local memory with a literal query and show its first five results",
+    /** Search stored memory from a literal command query without rendering the entire match set. */
+    handler: async (args, ctx) => {
+      const query = args.trim();
+      if (!query) throw new Error("Usage: /memory-search <query>");
+      const page = paginateRecallResults(recallMemories({ query }));
+      ctx.ui.notify(formatRecallResults(page.results, { query }, page), "info");
+    },
+  });
+
+  pi.registerCommand("remember", {
+    description: "Create an explicit durable fact memory in the current project",
+    /** Store user-authored reusable knowledge independently from transcript retention. */
+    handler: async (args, ctx) => {
+      const content = args.trim();
+      if (!content) throw new Error("Usage: /remember <text>");
+      const memory = createMemory({ kind: "fact", content, project_key: ctx.sessionManager.getCwd(), source_turn_id: null, importance: 1 });
+      ctx.ui.notify(`[session-memory] remembered ${memory.memory_id}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-pin", {
+    description: "Promote a historical turn into a durable fact memory",
+    /** Preserve a selected transcript turn as an independent durable memory with provenance. */
+    handler: async (args, ctx) => {
+      const turnId = args.trim();
+      if (!turnId) throw new Error("Usage: /memory-pin <turn-id>");
+      const memory = pinTurnAsMemory(turnId);
+      ctx.ui.notify(`[session-memory] pinned ${turnId} as ${memory.memory_id}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-list", {
+    description: "List durable memories, optionally filtered by kind",
+    /** Present durable memories and their provenance for direct management. */
+    handler: async (args, ctx) => {
+      const kind = args.trim() as MemoryKind | "";
+      if (kind && !["preference", "decision", "fact", "project_state", "task", "lesson"].includes(kind)) {
+        throw new Error("Usage: /memory-list [preference|decision|fact|project_state|task|lesson]");
+      }
+      const memories = listMemories(kind || undefined);
+      const text = memories.length
+        ? memories.map((memory) => `[${memory.kind}] ${memory.memory_id}: ${memory.content}${memory.source_turn_id ? ` (source: ${memory.source_turn_id})` : ""}`).join("\n")
+        : "No durable memories found.";
+      ctx.ui.notify(text, "info");
+    },
+  });
+
+  pi.registerCommand("memory-confirm", {
+    description: "Confirm an active durable memory remains current",
+    /** Explicitly acknowledge current evidence without rewriting the memory or its provenance. */
+    handler: async (args, ctx) => {
+      const memoryId = args.trim();
+      if (!memoryId) throw new Error("Usage: /memory-confirm <memory-id>");
+      const memory = confirmMemory(memoryId);
+      ctx.ui.notify(`[session-memory] confirmed ${memory.memory_id}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-supersede", {
+    description: "Replace one durable memory with another while retaining history",
+    /** Make supersession explicit so obsolete decisions remain inspectable instead of being silently overwritten. */
+    handler: async (args, ctx) => {
+      const [oldMemoryId, newMemoryId, ...extra] = args.trim().split(/\s+/);
+      if (!oldMemoryId || !newMemoryId || extra.length) throw new Error("Usage: /memory-supersede <old-memory-id> <new-memory-id>");
+      supersedeMemory(oldMemoryId, newMemoryId);
+      ctx.ui.notify(`[session-memory] superseded ${oldMemoryId} with ${newMemoryId}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-history", {
+    description: "Show the replacement chain containing a durable memory",
+    /** Render the full predecessor-to-successor chain for an active or superseded memory. */
+    handler: async (args, ctx) => {
+      const memoryId = args.trim();
+      if (!memoryId) throw new Error("Usage: /memory-history <memory-id>");
+      const history = getMemoryHistory(memoryId);
+      ctx.ui.notify(history.map((memory) => `[${memory.superseded_by ? "superseded" : "active"}] ${memory.memory_id}: ${memory.content}`).join("\n"), "info");
+    },
+  });
+
+  pi.registerCommand("memory-forget", {
+    description: "Permanently delete a durable memory by memory ID",
+    /** Delete only the selected durable memory; its provenance turn is retained. */
+    handler: async (args, ctx) => {
+      const memoryId = args.trim();
+      if (!memoryId) throw new Error("Usage: /memory-forget <memory-id>");
+      if (!deleteMemory(memoryId)) throw new Error(`Durable memory not found: ${memoryId}`);
+      ctx.ui.notify(`[session-memory] forgot ${memoryId}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-delete-turn", {
+    description: "Permanently delete a raw transcript turn by turn ID",
+    /** Keep raw transcript deletion explicit and separate from durable-memory deletion. */
+    handler: async (args, ctx) => {
+      const turnId = args.trim();
+      if (!turnId) throw new Error("Usage: /memory-delete-turn <turn-id>");
+      if (!deleteTurn(turnId)) throw new Error(`Memory turn not found: ${turnId}`);
+      ctx.ui.notify(`[session-memory] deleted transcript turn ${turnId}`, "info");
+    },
+  });
+
   pi.registerCommand("memory-backfill", {
     description: "Import historical Pi, Claude Code, and Codex sessions into memory.db",
+    /** Force a full historical import regardless of saved source-file fingerprints. */
     handler: async (_args, ctx) => {
-      const stats = backfillAll();
-      ctx.ui.notify(
-        `[session-memory] imported ${stats.turns} turns from ${stats.scannedFiles} files: ${stats.pi} Pi, ${stats.claude} Claude, ${stats.codex} Codex sessions`,
-        "info",
-      );
+      _notifyBackfill(ctx, backfillAll(), "imported");
+    },
+  });
+
+  pi.registerCommand("project-session-migration", {
+    description: "Convert this project's Codex sessions into separate Pi sessions that can be resumed",
+    /** Create independently resumable Pi session JSONL files from current-project Codex sessions. */
+    handler: async (_args, ctx) => {
+      _notifySessionMigration(ctx, migrateCodexProjectSessions(ctx.sessionManager.getCwd()));
+    },
+  });
+
+  pi.registerTool({
+    name: "migrate_codex_project_sessions",
+    label: "Migrate Codex Project Sessions",
+    description: "Convert each Codex session for the current project into a separate native Pi session that the user can select with /resume. Call only when the user explicitly wants to continue prior Codex work as a resumable Pi session. This does not index history for recall_memory and must not be used for ordinary cross-client recall or durable-memory requests.",
+    promptSnippet: "Convert this project's Codex sessions into separately resumable Pi sessions only when the user explicitly requests native Pi continuation.",
+    parameters: Type.Object({}),
+    /** Give the agent the same native Codex-to-Pi migration available through /project-session-migration. */
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const stats = migrateCodexProjectSessions(ctx.sessionManager.getCwd());
+      return {
+        content: [{ type: "text" as const, text: _sessionMigrationSummary(stats) }],
+        details: stats,
+      };
     },
   });
 
@@ -40,7 +196,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool({
     name: "recall_memory",
     label: "Recall Memory",
-    description: `Search this user's past conversation history across Pi, Claude Code, and Codex.
+    description: `Search this user's past conversation history across Pi, Claude Code, and Codex. Use query for the user's full request and entities for its important identifiers. Filters only narrow the local search.
 
 Invocation policy:
 1. Call this tool immediately when the user explicitly asks to review, remember, summarize, continue, or compare a previous discussion about a topic. Examples:
@@ -50,27 +206,106 @@ Invocation policy:
    - "之前那个方案怎么说的" / "what was that plan we had?"
 2. When you cannot confidently answer from the current conversation and your general knowledge, but the user may have discussed the topic in prior sessions, first ask whether they want you to search their conversation history. Call this tool only after they agree.
 3. Do not search history merely because a question is difficult when the user's prior discussions are not relevant.
+4. If a recall returns no results, use your judgment to make up to two additional recall calls before concluding the history has no answer. Each retry must use a distinct, concise literal query and/or entities chosen from semantic alternatives: abbreviations or expansions, aliases, translations, product or project names, and likely wording of the underlying task or decision. For example, after no result for "SAP BTP", try alternatives such as "BTP", "Business Technology Platform", and the specific platform/topic implied by the user's question.
+5. Preserve every source, project, and time filter from the original request on retries. Do not repeat an equivalent query, search indefinitely, claim a result that was not returned, or say history was searched exhaustively after fewer than three total attempts.
+
+Memory-aware response policy:
+1. Treat returned durable memories as reusable evidence, not as invisible context. In your natural-language answer, briefly state the relevant remembered conclusion and identify its source turn/session when that provenance matters to the answer.
+2. If a durable memory is marked **Freshness**, explain that newer matching evidence exists. Compare the old memory and the newer raw evidence; do not claim that the memory was updated, confirmed, or superseded unless the user explicitly chose that action.
+3. After explaining a meaningful freshness conflict or decision change, offer the user clear control: keep the current memory, confirm that it remains current, or create/pin a replacement and supersede the old memory. Ask which outcome they want before any persistent memory-management action.
+4. When an existing durable memory resolves the question and has no freshness signal, use it directly and avoid repeating its identical source turn. Do not mention memory mechanics unless provenance or freshness is useful to the user.
+5. Slash commands are user-controlled management actions. Do not instruct the user to execute a command merely to answer their question; mention the relevant command only when they want to inspect, confirm, replace, or delete a memory.
+
+Session-expansion policy:
+1. \`recall_memory\` is a discovery tool. Raw-turn results are intentionally short excerpts with session ID and turn index.
+2. Call \`fetch_session\` only when a candidate's surrounding conversation is necessary to answer accurately, verify a conclusion, resolve a conflict, or inspect context around a matched turn. Use its turn bounds to request the smallest useful range.
+3. Do not fetch a session when a durable memory or returned excerpt already answers the question. Do not fetch unrelated sessions merely because they were listed.
+
+Pagination policy:
+1. Each invocation returns five results. Local retrieval still evaluates every match before selecting that page.
+2. When the result reports a \`nextOffset\`, call \`recall_memory\` again with the exact same query and filters plus that offset only when more candidates are needed. Do not request pages merely to exhaust the result set.
 
-Extract 2–5 specific entities from the user's topic: project names, tool names, technologies, domain terms, or identifiers.`, 
+Extract 2–5 specific entities from the user's topic: project names, tool names, technologies, domain terms, or identifiers.`,
+    promptSnippet: "Search cross-client Pi, Claude Code, and Codex history when the user asks about prior discussions or work.",
 
     parameters: Type.Object({
-      entities: Type.Array(
+      query: Type.String({ minLength: 1, description: "The user's full memory request or its most specific literal phrase." }),
+      entities: Type.Optional(Type.Array(
         Type.String({ minLength: 1 }),
         {
-          description: 'Key technical terms from the query. E.g. ["payroll", "LangGraph", "A2A"]',
+          description: 'Important identifiers from the request. E.g. ["payroll", "LangGraph", "A2A"]',
           minItems: 1,
           maxItems: 8,
         },
-      ),
+      )),
+      sources: Type.Optional(Type.Array(Type.Union([
+        Type.Literal("pi"), Type.Literal("claude"), Type.Literal("codex"),
+      ]))),
+      cwd: Type.Optional(Type.String({ minLength: 1, description: "Exact project working directory to restrict results." })),
+      after: Type.Optional(Type.Number({ description: "Inclusive Unix timestamp in milliseconds." })),
+      before: Type.Optional(Type.Number({ description: "Inclusive Unix timestamp in milliseconds." })),
+      offset: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based result offset. Each call returns five results; use the returned nextOffset with identical search and filter inputs only when more candidates are needed." })),
     }),
 
-    async execute(_toolCallId, { entities }) {
-      const results = recallTurns(entities, 5);
-      const text = formatRecallResults(results);
+    /** Resolve an agent memory request into one explicit page of a fully evaluated local result set. */
+    async execute(_toolCallId, { query, entities, sources, cwd, after, before, offset }) {
+      const results = recallMemories({ query, entities, sources, cwd, after, before });
+      const page = paginateRecallResults(results, offset);
+      const text = formatRecallResults(page.results, { query, entities, sources, cwd, after, before }, page);
       return {
         content: [{ type: "text" as const, text }],
-        details: { entities, resultCount: results.length },
+        details: { query, entities, sources, cwd, after, before, offset: page.offset, pageSize: page.results.length, totalResults: page.totalResults, nextOffset: page.nextOffset },
       };
     },
   });
+
+  pi.registerTool({
+    name: "fetch_session",
+    label: "Fetch Session",
+    description: "Fetch ordered persisted conversation turns for one session returned by recall_memory. Use only when the candidate excerpt or durable memory is insufficient and surrounding context is necessary. Request the smallest useful inclusive turn-index range.",
+    promptSnippet: "Expand only a recall_memory result when its excerpt is insufficient; request the smallest useful turn range.",
+    parameters: Type.Object({
+      session_id: Type.String({ minLength: 1, description: "Exact session ID returned by recall_memory." }),
+      from_turn_index: Type.Optional(Type.Number({ minimum: 0, description: "Optional inclusive first turn index." })),
+      to_turn_index: Type.Optional(Type.Number({ minimum: 0, description: "Optional inclusive last turn index." })),
+    }),
+    /** Expand a specifically selected persisted session without coupling search ranking to context payload size. */
+    async execute(_toolCallId, { session_id, from_turn_index, to_turn_index }) {
+      const stored = getSession(session_id, from_turn_index, to_turn_index);
+      const header = `## Session ${stored.session.session_id}\n**Source:** ${stored.session.source} · **Project:** \`${stored.session.cwd}\`\n**Turns:** ${stored.turns.length}`;
+      const turns = stored.turns.length
+        ? stored.turns.map((turn) => [
+          `### Turn ${turn.turn_index} · ${new Date(turn.ts).toLocaleString()}`,
+          `**You:** ${turn.user_text}`,
+          turn.reply_text ? `**Assistant:** ${turn.reply_text}` : "",
+        ].filter(Boolean).join("\n")).join("\n\n")
+        : "No persisted turns in the requested range.";
+      return {
+        content: [{ type: "text" as const, text: `${header}\n\n${turns}` }],
+        details: { session_id, from_turn_index, to_turn_index, turnCount: stored.turns.length },
+      };
+    },
+  });
+}
+
+/** Present one backfill result consistently for user commands and agent tool calls. */
+function _backfillSummary(stats: BackfillStats, action: string): string {
+  return `[session-memory] ${action} ${stats.turns} turns from ${stats.scannedFiles} files: ${stats.pi} Pi, ${stats.claude} Claude, ${stats.codex} Codex sessions`;
+}
+
+/** Notify command users of one backfill summary and every isolated import issue. */
+function _notifyBackfill(ctx: ExtensionContext, stats: BackfillStats, action: string): void {
+  ctx.ui.notify(_backfillSummary(stats, action), "info");
+  for (const issue of stats.issues) ctx.ui.notify(`[session-memory] ${issue.error}`, "error");
+}
+
+/** Report native Codex-to-Pi session migration results and isolated conversion failures. */
+function _notifySessionMigration(ctx: ExtensionContext, stats: ProjectSessionMigrationStats): void {
+  ctx.ui.notify(_sessionMigrationSummary(stats), "info");
+  for (const issue of stats.issues) ctx.ui.notify(`[session-memory] Codex migration failed (${issue.path}): ${issue.error}`, "error");
+}
+
+/** Format a concise native-session migration result for commands and tools. */
+function _sessionMigrationSummary(stats: ProjectSessionMigrationStats): string {
+  return `[session-memory] migrated ${stats.migratedSessions} Codex sessions (${stats.migratedMessages} messages); skipped ${stats.skippedSessions} already migrated sessions from ${stats.scannedFiles} scanned files. Use /resume to select a migrated Pi session.`;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-session-memory",
-  "version": "0.1.4",
-  "description": "Persistent, local-first cross-session memory for Pi, with SQLite-backed recall across Pi, Claude Code, and Codex conversations",
+  "version": "0.2.1",
+  "description": "Persistent, local-first cross-session memory for Pi, with SQLite-backed paginated recall across Pi, Claude Code, and Codex conversations",
   "keywords": [
     "pi-package"
   ],
@@ -15,6 +15,10 @@
     "url": "https://github.com/shengxiao20/pi-session-memory/issues"
   },
   "type": "module",
+  "files": [
+    "extensions/",
+    "src/"
+  ],
   "scripts": {
     "test": "tsx tests/core.test.ts"
   },