pi-session-memory 0.3.1 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ 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 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`.
+- Converts current-project Codex or Claude Code sessions into separate native Pi sessions, 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 `\\`.
@@ -46,7 +46,7 @@ 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.3.1
+pi install npm:pi-session-memory@0.4.0
 ```
 
 ## Usage
@@ -72,15 +72,16 @@ The command imports eligible user/assistant exchanges from:
 | Claude Code | `~/.claude/projects/**/*.jsonl` |
 | Codex | `~/.codex/sessions/**/*.jsonl` |
 
-### Continue a Codex session natively in Pi
+### Continue a Claude Code or 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:
+Use a migration command only when you want to continue prior work as a real Pi session rather than search it as memory:
 
 ```text
-/project-session-migration
+/project-claude-session-migration  # Claude Code → Pi
+/project-session-migration         # Codex → Pi
 ```
 
-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>`.
+Each command selects only source JSONL files whose recorded `cwd` exactly equals the current project, then creates one independent Pi v3 session JSONL under Pi's normal session directory. Entries are named `Migrated from Claude Code: <session-id>` or `Migrated from Codex: <session-id>`.
 
 After the command completes, run:
 
@@ -90,7 +91,7 @@ After the command completes, run:
 
 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.
+The converters preserve user and assistant text messages only. They deliberately do not convert client-injected context, 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
 
@@ -149,7 +150,9 @@ Pi / Claude Code / Codex history ──► incremental source sync ──► SQL
                                                                   │
                                                            recall_memory
 
-Current-project Codex JSONL ──► /project-session-migration ──► native Pi session JSONL ──► /resume
+Current-project Claude Code JSONL ──► /project-claude-session-migration ─┐
+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.
@@ -168,6 +171,7 @@ Conversation data is stored and queried locally. This package does not add a rem
 
 | Version | Highlights |
 | --- | --- |
+| `0.4.0` | Adds native current-project Claude Code-to-Pi session migration through `/project-claude-session-migration` and `migrate_claude_project_sessions`. Claude Code and Codex now share deterministic, source-namespaced, idempotent Pi v3 session output; SQLite data and schema remain compatible, so no database migration is required. |
 | `0.3.1` | Makes `recall_memory` entity-only: 2–8 high-signal literal entities are OR alternatives, results matching more entities rank higher, and output distinguishes search entities from strict scope filters. Existing SQLite data and schema remain compatible; no migration is required. |
 | `0.3.0` | Replaces source-session-only freshness hints with provenance-linked evidence comparison across newer same-session and cross-session turns. This changes recall output and `freshness_candidate` semantics, but keeps SQLite data and explicit user-controlled memory mutation compatible; no migration is required. |
 | `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. |
@@ -189,7 +193,7 @@ Before every significant release, review these compatibility surfaces and record
 5. **Public TypeScript/module API:** exported types/functions and required result fields.
 6. **Extension loadability:** run `npm test`, which imports `extensions/index.ts`; Markdown inline-code backticks inside a template-literal description must be escaped as `\`` so Pi can parse and start the extension.
 
-The `0.3.1` review found no SQLite breaking change: it does not alter tables, migrations, or stored data, so users can upgrade without a database error or migration. It is therefore released as a patch despite changing `recall_memory` search inputs and behavior.
+The `0.4.0` review found no SQLite breaking change: Claude Code native-session migration adds commands, an agent tool, and Pi session-file output only. It does not alter tables, migrations, or stored data, so users can upgrade without a database error or migration. It is therefore released as a minor version because it adds a backward-compatible user capability.
 
 ## Development
 

package/extensions/index.ts

@@ -4,7 +4,7 @@ import { writeTurn } from "../src/writer.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 { migrateClaudeProjectSessions, 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. */
@@ -170,24 +170,48 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.registerCommand("project-session-migration", {
-    description: "Convert this project's Codex sessions into separate Pi sessions that can be resumed",
+    description: "Convert current-project Codex sessions into separate native Pi sessions for /resume",
     /** Create independently resumable Pi session JSONL files from current-project Codex sessions. */
     handler: async (_args, ctx) => {
-      _notifySessionMigration(ctx, migrateCodexProjectSessions(ctx.sessionManager.getCwd()));
+      _notifySessionMigration(ctx, "Codex", migrateCodexProjectSessions(ctx.sessionManager.getCwd()));
+    },
+  });
+
+  pi.registerCommand("project-claude-session-migration", {
+    description: "Convert current-project Claude Code sessions into separate native Pi sessions for /resume",
+    /** Create independently resumable Pi session JSONL files from current-project Claude Code sessions. */
+    handler: async (_args, ctx) => {
+      _notifySessionMigration(ctx, "Claude Code", migrateClaudeProjectSessions(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.",
+    description: "Convert each Codex session for the current project into a separate native Pi session selectable with /resume. Call only when the user explicitly wants native Pi continuation of prior Codex work. This writes resumable sessions; it does not index history for recall_memory or manage durable memories.",
+    promptSnippet: "Use only when the user explicitly requests native Pi continuation of this project's prior Codex sessions.",
     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) }],
+        content: [{ type: "text" as const, text: _sessionMigrationSummary("Codex", stats) }],
+        details: stats,
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "migrate_claude_project_sessions",
+    label: "Migrate Claude Code Project Sessions",
+    description: "Convert each Claude Code session for the current project into a separate native Pi session selectable with /resume. Call only when the user explicitly wants native Pi continuation of prior Claude Code work. This writes resumable sessions; it does not index history for recall_memory or manage durable memories.",
+    promptSnippet: "Use only when the user explicitly requests native Pi continuation of this project's prior Claude Code sessions.",
+    parameters: Type.Object({}),
+    /** Give the agent an explicit Claude Code-to-Pi native-session migration capability. */
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const stats = migrateClaudeProjectSessions(ctx.sessionManager.getCwd());
+      return {
+        content: [{ type: "text" as const, text: _sessionMigrationSummary("Claude Code", stats) }],
         details: stats,
       };
     },
@@ -300,13 +324,13 @@ function _notifyBackfill(ctx: ExtensionContext, stats: BackfillStats, action: st
   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");
+/** Report native source-to-Pi session migration results and isolated conversion failures. */
+function _notifySessionMigration(ctx: ExtensionContext, sourceLabel: string, stats: ProjectSessionMigrationStats): void {
+  ctx.ui.notify(_sessionMigrationSummary(sourceLabel, stats), "info");
+  for (const issue of stats.issues) ctx.ui.notify(`[session-memory] ${sourceLabel} 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.`;
+function _sessionMigrationSummary(sourceLabel: string, stats: ProjectSessionMigrationStats): string {
+  return `[session-memory] migrated ${stats.migratedSessions} ${sourceLabel} 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,6 +1,6 @@
 {
   "name": "pi-session-memory",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Persistent, local-first cross-session memory for Pi, with SQLite-backed paginated recall and freshness-evidence comparison across Pi, Claude Code, and Codex conversations",
   "keywords": [
     "pi-package"

package/src/helper.ts

@@ -9,15 +9,15 @@ You can request history and memory features in natural language.
 无论对话来自 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.
+- **在 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 的结论。”

package/src/session-migration.ts

@@ -3,18 +3,28 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSyn
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-interface CodexMessage {
+type MigrationSource = "claude" | "codex";
+type Role = "user" | "assistant";
+
+interface MigratedMessage {
   id: string;
-  role: "user" | "assistant";
+  role: Role;
   text: string;
   timestamp: number;
 }
 
-interface CodexSession {
+interface SourceSession {
   id: string;
   cwd: string;
   timestamp: number;
-  messages: CodexMessage[];
+  messages: MigratedMessage[];
+}
+
+interface MigrationDefinition {
+  source: MigrationSource;
+  root: string;
+  displayName: string;
+  parse: (path: string) => SourceSession | undefined;
 }
 
 export interface ProjectSessionMigrationStats {
@@ -25,8 +35,33 @@ export interface ProjectSessionMigrationStats {
   issues: Array<{ path: string; error: string }>;
 }
 
-/** Convert every Codex session recorded for cwd into an independently resumable Pi session file. */
+const MIGRATION_SOURCES: Record<MigrationSource, MigrationDefinition> = {
+  claude: {
+    source: "claude",
+    root: join(homedir(), ".claude", "projects"),
+    displayName: "Claude Code",
+    parse: _parseClaudeSession,
+  },
+  codex: {
+    source: "codex",
+    root: join(homedir(), ".codex", "sessions"),
+    displayName: "Codex",
+    parse: _parseCodexSession,
+  },
+};
+
+/** Convert every current-project Claude Code session into an independently resumable Pi session file. */
+export function migrateClaudeProjectSessions(cwd: string): ProjectSessionMigrationStats {
+  return _migrateProjectSessions(MIGRATION_SOURCES.claude, cwd);
+}
+
+/** Convert every current-project Codex session into an independently resumable Pi session file. */
 export function migrateCodexProjectSessions(cwd: string): ProjectSessionMigrationStats {
+  return _migrateProjectSessions(MIGRATION_SOURCES.codex, cwd);
+}
+
+/** Migrate one supported source while isolating malformed files from other source sessions. */
+function _migrateProjectSessions(definition: MigrationDefinition, cwd: string): ProjectSessionMigrationStats {
   const stats: ProjectSessionMigrationStats = {
     scannedFiles: 0,
     migratedSessions: 0,
@@ -34,17 +69,17 @@ export function migrateCodexProjectSessions(cwd: string): ProjectSessionMigratio
     migratedMessages: 0,
     issues: [],
   };
-  for (const path of _jsonlFiles(join(homedir(), ".codex", "sessions"))) {
+  for (const path of _jsonlFiles(definition.root)) {
     stats.scannedFiles++;
     try {
-      const session = _parseCodexSession(path);
+      const session = definition.parse(path);
       if (!session || session.cwd !== cwd) continue;
-      const outputPath = _targetPath(session);
+      const outputPath = _targetPath(definition.source, session);
       if (existsSync(outputPath)) {
         stats.skippedSessions++;
         continue;
       }
-      _writePiSession(session, outputPath);
+      _writePiSession(definition, session, outputPath);
       stats.migratedSessions++;
       stats.migratedMessages += session.messages.length;
     } catch (error) {
@@ -54,9 +89,40 @@ export function migrateCodexProjectSessions(cwd: string): ProjectSessionMigratio
   return stats;
 }
 
-/** Convert one supported Codex JSONL file into its session metadata and textual messages. */
-function _parseCodexSession(path: string): CodexSession | undefined {
-  const entries = readFileSync(path, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line) as Record<string, unknown>);
+/** Convert one Claude Code JSONL file into supported textual user and assistant messages. */
+function _parseClaudeSession(path: string): SourceSession | undefined {
+  const entries = _readJsonl(path);
+  const firstConversation = entries.find((entry) =>
+    (entry.type === "user" || entry.type === "assistant") && !entry.isMeta && !entry.isSidechain,
+  );
+  if (!firstConversation) return undefined;
+  const id = _string(firstConversation.sessionId);
+  const cwd = _string(firstConversation.cwd);
+  const timestamp = _timestamp(_string(firstConversation.timestamp));
+  if (!id || !cwd || timestamp === undefined) throw new Error("Claude Code conversation requires sessionId, cwd, and timestamp");
+
+  const messages: MigratedMessage[] = [];
+  for (const [index, entry] of entries.entries()) {
+    if ((entry.type !== "user" && entry.type !== "assistant") || entry.isMeta || entry.isSidechain) continue;
+    const role = _role(entry.message?.role);
+    if (!role) continue;
+    const text = _claudeText(entry.message?.content);
+    if (!text || (role === "user" && _isClaudeInjectedContext(text))) continue;
+    const messageId = _string(entry.uuid) ?? _string(entry.id);
+    if (!messageId) throw new Error(`Claude Code textual message at entry ${index} has no stable native ID`);
+    messages.push({
+      id: messageId,
+      role,
+      text,
+      timestamp: _timestamp(_string(entry.timestamp)) ?? timestamp,
+    });
+  }
+  return { id, cwd, timestamp, messages };
+}
+
+/** Convert one Codex JSONL file into supported textual user and assistant messages. */
+function _parseCodexSession(path: string): SourceSession | undefined {
+  const entries = _readJsonl(path);
   const metadata = entries.find((entry) => entry.type === "session_meta")?.payload as Record<string, unknown> | undefined;
   if (!metadata) return undefined;
   const id = _string(metadata.session_id) ?? _string(metadata.id);
@@ -64,14 +130,14 @@ function _parseCodexSession(path: string): CodexSession | undefined {
   const timestamp = _timestamp(_string(metadata.timestamp));
   if (!id || !cwd || timestamp === undefined) throw new Error("Codex session_meta requires session_id/id, cwd, and timestamp");
 
-  const messages: CodexMessage[] = [];
+  const messages: MigratedMessage[] = [];
   for (const [index, entry] of entries.entries()) {
     if (entry.type !== "response_item") continue;
     const payload = entry.payload as Record<string, unknown> | undefined;
     if (payload?.type !== "message") continue;
-    const role = _string(payload.role);
-    if (role !== "user" && role !== "assistant") continue;
-    const text = _text(payload.content);
+    const role = _role(payload.role);
+    if (!role) continue;
+    const text = _codexText(payload.content);
     if (!text) continue;
     const messageId = _string(payload.id)
       ?? _string(entry.id)
@@ -87,8 +153,8 @@ function _parseCodexSession(path: string): CodexSession | undefined {
   return { id, cwd, timestamp, messages };
 }
 
-/** Write a valid Pi v3 session with a linear message branch and an explicit migration name. */
-function _writePiSession(session: CodexSession, path: string): void {
+/** Write one valid Pi v3 session with a linear message branch and explicit migration provenance. */
+function _writePiSession(definition: MigrationDefinition, session: SourceSession, path: string): void {
   mkdirSync(join(homedir(), ".pi", "agent", "sessions", _encodedCwd(session.cwd)), { recursive: true });
   const lines: string[] = [JSON.stringify({
     type: "session",
@@ -98,17 +164,17 @@ function _writePiSession(session: CodexSession, path: string): void {
     cwd: session.cwd,
   })];
   let parentId: string | null = null;
-  const nameId = _entryId(session.id, "name");
+  const nameId = _entryId(definition.source, session.id, "name");
   lines.push(JSON.stringify({
     type: "session_info",
     id: nameId,
     parentId,
     timestamp: new Date(session.timestamp).toISOString(),
-    name: `Migrated from Codex: ${session.id}`,
+    name: `Migrated from ${definition.displayName}: ${session.id}`,
   }));
   parentId = nameId;
   for (const message of session.messages) {
-    const id = _entryId(session.id, message.id);
+    const id = _entryId(definition.source, session.id, message.id);
     const timestamp = new Date(message.timestamp).toISOString();
     lines.push(JSON.stringify({
       type: "message",
@@ -120,8 +186,8 @@ function _writePiSession(session: CodexSession, path: string): void {
         : {
           role: "assistant",
           content: [{ type: "text", text: message.text }],
-          api: "codex-migration",
-          provider: "codex",
+          api: `${definition.source}-migration`,
+          provider: definition.source,
           model: "unknown",
           usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
           stopReason: "stop",
@@ -139,9 +205,9 @@ function _writePiSession(session: CodexSession, path: string): void {
   }
 }
 
-/** Return the deterministic Pi session-file location for one Codex session. */
-function _targetPath(session: CodexSession): string {
-  return join(homedir(), ".pi", "agent", "sessions", _encodedCwd(session.cwd), `${new Date(session.timestamp).toISOString().replace(/[.:]/g, "-")}_codex-${session.id}.jsonl`);
+/** Return the deterministic Pi session-file location for one migrated source session. */
+function _targetPath(source: MigrationSource, session: SourceSession): string {
+  return join(homedir(), ".pi", "agent", "sessions", _encodedCwd(session.cwd), `${new Date(session.timestamp).toISOString().replace(/[.:]/g, "-")}_${source}-${session.id}.jsonl`);
 }
 
 /** Encode cwd exactly as Pi's default session directory convention. */
@@ -149,9 +215,14 @@ function _encodedCwd(cwd: string): string {
   return `--${cwd.split("/").filter(Boolean).join("-")}--`;
 }
 
-/** Create stable, Pi-safe entry IDs without fabricating source message identity. */
-function _entryId(sessionId: string, sourceId: string): string {
-  return createHash("sha256").update(`${sessionId}:${sourceId}`).digest("hex").slice(0, 16);
+/** Create stable Pi-safe entry IDs while retaining source-specific identity namespaces. */
+function _entryId(source: MigrationSource, sessionId: string, sourceId: string): string {
+  return createHash("sha256").update(`${source}:${sessionId}:${sourceId}`).digest("hex").slice(0, 16);
+}
+
+/** Accept user and assistant roles only. */
+function _role(value: unknown): Role | undefined {
+  return value === "user" || value === "assistant" ? value : undefined;
 }
 
 /** Extract non-empty string values only. */
@@ -166,8 +237,28 @@ function _timestamp(value: string | undefined): number | undefined {
   return Number.isNaN(timestamp) ? undefined : timestamp;
 }
 
+/** Extract Claude Code text from legacy string or text content blocks. */
+function _claudeText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block): block is { type: string; text: string } => Boolean(block) && typeof block === "object" && (block as { type?: unknown }).type === "text" && typeof (block as { text?: unknown }).text === "string")
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+}
+
+/** Exclude Claude Code client-injected context from migrated user conversation. */
+function _isClaudeInjectedContext(text: string): boolean {
+  return text.startsWith("<command-name>")
+    || text.startsWith("<command-message>")
+    || text.startsWith("<local-command-")
+    || text.startsWith("<task-notification>")
+    || text.startsWith("This session is being continued from a previous conversation");
+}
+
 /** Join supported Codex text content blocks. */
-function _text(content: unknown): string {
+function _codexText(content: unknown): string {
   if (!Array.isArray(content)) return "";
   return content
     .filter((block): block is { type: string; text: string } => Boolean(block) && typeof block === "object" && typeof (block as { type?: unknown }).type === "string" && typeof (block as { text?: unknown }).text === "string")
@@ -177,6 +268,11 @@ function _text(content: unknown): string {
     .trim();
 }
 
+/** Read every non-empty JSONL line into its ordered JSON record. */
+function _readJsonl(path: string): Record<string, any>[] {
+  return readFileSync(path, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line) as Record<string, any>);
+}
+
 /** Recursively enumerate source JSONL files. */
 function _jsonlFiles(root: string): string[] {
   if (!existsSync(root)) return [];