pi-session-memory 0.3.0 → 0.3.1

package/README.md

@@ -17,7 +17,7 @@ A local-first Pi extension that saves completed conversations to SQLite and give
 - 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.3.1
 ```
 
 ## Usage
@@ -106,9 +106,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 +132,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.
@@ -168,7 +168,8 @@ 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.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 +180,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.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.
 
 ## 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

@@ -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");
     },
   });
 
@@ -196,7 +197,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 +207,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 +225,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 +249,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 },
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-memory",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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/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. */