pi-session-memory 0.3.0 → 0.4.0

package/README.md

@@ -10,14 +10,14 @@ 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 `\\`.
 - 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.
-- Associates recalled durable memories with later source-session activity and newer query-relevant evidence from the same or another session, so users can explicitly compare, confirm, or supersede them without silent updates.
+- Associates recalled durable memories with later source-session activity and newer entity-relevant evidence from the same or another session, so users can explicitly compare, confirm, or supersede them 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.
 
@@ -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.0
+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
 
@@ -106,9 +107,9 @@ 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.
+`recall_memory` is the discovery step: it searches and ranks the complete active durable-memory and raw-turn match set using 2–8 high-signal literal entities. Entities are OR alternatives, so a result may match any entity; matching more entities ranks higher. Pi must not send the complete user request or generic conversational terms such as "问题", "开发", "有哪些", or "help". Where useful, it includes Chinese/English equivalents, aliases, or abbreviations—for example `["bug", "缺陷", "错误", "fix", "修复"]`. Exact project-directory, source, and time-window filters remain strict scope constraints. Each tool response deliberately renders five results and reports `totalResults` and `nextOffset`; when more candidates are needed, Pi repeats the exact same entities and scope 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 distinct entities selected from reasoned alternatives—such as abbreviations, expansions, aliases, translations, or likely task wording—while retaining the original scope filters.
 
-When recall returns a durable memory, Pi is instructed to naturally communicate a relevant remembered conclusion and provenance when useful. It reports later activity in the memory's source session separately from newer query-relevant evidence to compare; that evidence can come from the original session or another newer session. Pi compares the old memory with the evidence as a possible confirmation, supplement, conflict, or replacement, then asks whether you want to keep, confirm, or replace it. It never claims a memory was updated or superseded without your explicit choice.
+When recall returns a durable memory, Pi is instructed to naturally communicate a relevant remembered conclusion and provenance when useful. It reports later activity in the memory's source session separately from newer entity-relevant evidence to compare; that evidence can come from the original session or another newer session. Pi compares the old memory with the evidence as a possible confirmation, supplement, conflict, or replacement, then 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
 
@@ -132,7 +133,7 @@ Recall and freshness explanations are automatic model behavior. The commands bel
 - `/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 distinguishes later activity in a memory's source session from newer query-relevant evidence to compare. That evidence may come from the original session or another newer session; it is a review signal, not an automatic update.
+- Recall distinguishes later activity in a memory's source session from newer entity-relevant evidence to compare. That evidence may come from the original session or another newer session; it 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.
@@ -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,7 +171,9 @@ Conversation data is stored and queried locally. This package does not add a rem
 
 | Version | Highlights |
 | --- | --- |
-| `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 tool inputs, slash commands, SQLite data, and explicit user-controlled memory mutation compatible; no migration is required. |
+| `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. |
 | `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. |
@@ -179,18 +184,21 @@ Conversation data is stored and queried locally. This package does not add a rem
 
 ## Release compatibility review
 
-Before every significant release, review these compatibility surfaces and record any migration or versioning decision:
+Before every significant release, review these compatibility surfaces and record any migration or versioning decision. In this project, a breaking change means an updated extension conflicts with a user's existing SQLite table structure and errors after upgrade; changes to agent tool inputs or external direct callers are not breaking changes under this definition:
 
 1. **Install/package:** package name, Pi manifest, runtime dependencies, and published file allowlist.
 2. **Persistent data:** SQLite schema/migrations, JSONL-import compatibility, and any data rewrite.
 3. **Agent tools and commands:** tool names, input schemas, result/details contracts, and slash commands.
 4. **Retrieval and agent behavior:** ranking, pagination, freshness/evidence semantics, prompt policy, and automatic side effects.
 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.0` review found no installation, SQLite, command, or tool-input breaking change. It intentionally changes recall result semantics and adds evidence fields, so it is released as a minor `0.x` version rather than a patch.
+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
 
 ```bash
 npm test
 ```
+
+The test suite imports `extensions/index.ts` in addition to exercising core behavior. This catches extension-load syntax errors, including unescaped Markdown backticks inside template-literal tool descriptions.

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. */
@@ -62,8 +62,9 @@ export default function (pi: ExtensionAPI) {
     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");
+      const entities = [query];
+      const page = paginateRecallResults(recallMemories({ entities }));
+      ctx.ui.notify(formatRecallResults(page.results, { entities }, page), "info");
     },
   });
 
@@ -169,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,
       };
     },
@@ -196,7 +221,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. Use query for the user's full request and entities for its important identifiers. Filters only narrow the local search.
+    description: `Search this user's past conversation history across Pi, Claude Code, and Codex using high-signal literal entities. Entities are OR alternatives: any entity may recall a result, and results matching more entities rank higher. Scope 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:
@@ -206,12 +231,13 @@ 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.
+4. Use 2–8 specific, high-signal literal entities, not the user's entire request or generic conversational words such as "问题", "开发", "有哪些", or "help". Include useful aliases, abbreviations, or Chinese/English equivalents where relevant, for example ["bug", "缺陷", "错误", "fix", "修复"].
+5. 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 distinct 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.
+6. Preserve every source, project, and time filter from the original request on retries. Do not repeat equivalent entities, 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. A durable memory can report `source_session_changed` when its original session has later activity; this alone does not mean the memory is stale. When it includes **Newer evidence to compare**, compare that evidence with the memory: it may confirm, supplement, conflict with, or replace the old conclusion. Evidence can come from another newer session as well as the original session. Do not claim that the memory was updated, confirmed, or superseded unless the user explicitly chose that action.
+2. A durable memory can report \`source_session_changed\` when its original session has later activity; this alone does not mean the memory is stale. When it includes **Newer evidence to compare**, compare that evidence with the memory: it may confirm, supplement, conflict with, or replace the old conclusion. Evidence can come from another newer session as well as the original session. Do not claim that the memory was updated, confirmed, or superseded unless the user explicitly chose that action.
 3. After explaining a meaningful comparison, offer 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 comparison evidence, use it directly and avoid repeating its identical source turn. Do not mention memory mechanics unless provenance or evidence comparison 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.
@@ -223,21 +249,20 @@ Session-expansion policy:
 
 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.
+2. When the result reports a \`nextOffset\`, call \`recall_memory\` again with the exact same entities and scope 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–8 specific, high-signal entities from the user's topic: project names, tool names, technologies, domain terms, identifiers, and useful Chinese/English equivalents, aliases, or abbreviations.`,
     promptSnippet: "Search cross-client Pi, Claude Code, and Codex history when the user asks about prior discussions or work.",
 
     parameters: Type.Object({
-      query: Type.String({ minLength: 1, description: "The user's full memory request or its most specific literal phrase." }),
-      entities: Type.Optional(Type.Array(
+      entities: Type.Array(
         Type.String({ minLength: 1 }),
         {
-          description: 'Important identifiers from the request. E.g. ["payroll", "LangGraph", "A2A"]',
-          minItems: 1,
+          description: 'Two to eight high-signal literal search alternatives. Results may match any entity; include useful Chinese/English equivalents, aliases, or abbreviations. E.g. ["pi-session-memory", "bug", "缺陷", "错误", "fix", "修复"].',
+          minItems: 2,
           maxItems: 8,
         },
-      )),
+      ),
       sources: Type.Optional(Type.Array(Type.Union([
         Type.Literal("pi"), Type.Literal("claude"), Type.Literal("codex"),
       ]))),
@@ -248,13 +273,13 @@ Extract 2–5 specific entities from the user's topic: project names, tool names
     }),
 
     /** 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 });
+    async execute(_toolCallId, { entities, sources, cwd, after, before, offset }) {
+      const results = recallMemories({ entities, sources, cwd, after, before });
       const page = paginateRecallResults(results, offset);
-      const text = formatRecallResults(page.results, { query, entities, sources, cwd, after, before }, page);
+      const text = formatRecallResults(page.results, { entities, sources, cwd, after, before }, page);
       return {
         content: [{ type: "text" as const, text }],
-        details: { query, entities, sources, cwd, after, before, offset: page.offset, pageSize: page.results.length, totalResults: page.totalResults, nextOffset: page.nextOffset },
+        details: { entities, sources, cwd, after, before, offset: page.offset, pageSize: page.results.length, totalResults: page.totalResults, nextOffset: page.nextOffset },
       };
     },
   });
@@ -299,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.0",
+  "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/retriever.ts

@@ -4,8 +4,8 @@ import { getDb, type MemoryKind } from "./db.ts";
 export type MemorySource = "pi" | "claude" | "codex";
 
 export interface RecallOptions {
-  query: string;
-  entities?: string[];
+  /** High-signal literal alternatives; a result may match any entity. */
+  entities: string[];
   sources?: MemorySource[];
   cwd?: string;
   after?: number;
@@ -72,7 +72,7 @@ const RECENCY_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
 
 /** Retained for compatibility with the v0.1 public retrieval helper. */
 export function recallTurns(entities: string[]): RecallTurnResult[] {
-  return _recallTurns({ query: entities.join(" "), entities });
+  return _recallTurns({ entities });
 }
 
 /** Retrieve active durable memories, then raw turns not already represented by unchanged source evidence. */
@@ -105,8 +105,8 @@ export function paginateRecallResults(results: RecallResult[], offset = 0): Reca
   return { results: pageResults, offset, totalResults: results.length, nextOffset };
 }
 
-/** Render the exact query inputs and recall results as concise Markdown for a command notification or tool response. */
-export function formatRecallResults(results: RecallResult[], options?: Pick<RecallOptions, "query" | "entities" | "sources" | "cwd" | "after" | "before">, page?: Omit<RecallPage, "results">): string {
+/** Render the exact entity inputs and recall results as concise Markdown for a command notification or tool response. */
+export function formatRecallResults(results: RecallResult[], options?: Pick<RecallOptions, "entities" | "sources" | "cwd" | "after" | "before">, page?: Omit<RecallPage, "results">): string {
   const lines = options ? [_formatRecallQuery(options), ""] : [];
   if (results.length === 0) return [...lines, page && page.totalResults > 0 ? `No results at offset ${page.offset}; the matching result set contains ${page.totalResults} result(s).` : "No relevant past conversations found."].join("\n");
 
@@ -142,16 +142,15 @@ export function formatRecallResults(results: RecallResult[], options?: Pick<Reca
   return lines.join("\n");
 }
 
-/** Make each tool invocation auditable by showing its exact literal terms and scopes. */
-function _formatRecallQuery(options: Pick<RecallOptions, "query" | "entities" | "sources" | "cwd" | "after" | "before">): string {
-  const filters = [
-    options.entities?.length ? `entities: ${options.entities.map((entity) => `\`${entity}\``).join(", ")}` : null,
+/** Make each tool invocation auditable by showing its literal entities separately from its scope. */
+function _formatRecallQuery(options: Pick<RecallOptions, "entities" | "sources" | "cwd" | "after" | "before">): string {
+  const scope = [
     options.sources?.length ? `sources: ${options.sources.join(", ")}` : null,
     options.cwd ? `cwd: \`${options.cwd}\`` : null,
     options.after !== undefined ? `after: ${new Date(options.after).toISOString()}` : null,
     options.before !== undefined ? `before: ${new Date(options.before).toISOString()}` : null,
   ].filter(Boolean);
-  return `**Search query:** \`${options.query}\`${filters.length ? `  \\n**Filters:** ${filters.join(" · ")}` : ""}`;
+  return `**Search entities:** ${options.entities.map((entity) => `\`${entity}\``).join(", ")}${scope.length ? `  \\n**Scope:** ${scope.join(" · ")}` : ""}`;
 }
 
 /** Keep discovery results small; full persisted turn text belongs to fetch_session. */
@@ -166,7 +165,7 @@ function _recallDurableMemories(options: RecallOptions): RecallDurableMemoryResu
   if (terms.length === 0) return [];
   const scoreExpression = terms.map(() => "CASE WHEN LOWER(content) LIKE ? ESCAPE '\\' THEN 1 ELSE 0 END").join(" + ");
   const parameters = terms.map(_likePattern);
-  const filters = terms.map(() => "LOWER(content) LIKE ? ESCAPE '\\'");
+  const filters = [`(${terms.map(() => "LOWER(content) LIKE ? ESCAPE '\\'").join(" OR ")})`];
   const filterParameters: Array<string | number> = terms.map(_likePattern);
   filters.push("superseded_by IS NULL");
   if (options.cwd) {
@@ -237,7 +236,7 @@ function _recallTurns(options: RecallOptions): RecallTurnResult[] {
   const scoreParameters = terms.flatMap((term) => _likeParameters(term));
   const whereExpressions = terms.map(() => "(LOWER(turns.user_text) LIKE ? ESCAPE '\\' OR LOWER(turns.reply_text) LIKE ? ESCAPE '\\')");
   const whereParameters = terms.flatMap((term) => _likeParameters(term));
-  const filters = [...whereExpressions];
+  const filters = [`(${whereExpressions.join(" OR ")})`];
   const filterParameters: Array<string | number> = [...whereParameters];
   if (options.sources?.length) {
     filters.push(`sessions.source IN (${options.sources.map(() => "?").join(", ")})`);
@@ -272,9 +271,9 @@ function _turnContentHash(turn: RecallTurnResult): string {
   return createHash("sha256").update(JSON.stringify([turn.user_text, turn.reply_text])).digest("hex");
 }
 
-/** Build a de-duplicated set of non-empty literal search terms from the request. */
+/** Build a de-duplicated set of non-empty literal search entities from the request. */
 function _terms(options: RecallOptions): string[] {
-  return [...new Set([options.query, ...(options.entities ?? [])].map((term) => term.trim()).filter(Boolean))];
+  return [...new Set(options.entities.map((entity) => entity.trim()).filter(Boolean))];
 }
 
 /** Produce matching user and assistant SQL LIKE parameters for one term. */

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 [];