opencode-claude-memory 1.6.5 → 1.7.1

package/README.md

@@ -165,7 +165,7 @@ Key modules ported from Claude Code's `src/memdir/`:
 | Module | Source | Purpose |
 |---|---|---|
 | `memoryScan.ts` | `memoryScan.ts` | Recursive directory scan + frontmatter header parsing |
-| `recall.ts` | `findRelevantMemories.ts` | Memory recall via keyword scoring (heuristic, no LLM side-query) |
+| `recall.ts` + `recallSelector.ts` | `findRelevantMemories.ts` | LLM-selected memory recall + selected memory formatting |
 | `prompt.ts` | `memoryTypes.ts` + `memdir.ts` | System prompt sections, type taxonomy, truncation |
 | `memory.ts` | `memdir.ts` | `truncateEntrypoint()` aligned with `truncateEntrypointContent()` |
 
@@ -213,6 +213,8 @@ Yes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:
 - `OPENCODE_MEMORY_TERMINAL_LOG` (default `foreground-only`): set `1` to force terminal logs on, `0` to force them off
 - `OPENCODE_MEMORY_MODEL`: override model used for extraction
 - `OPENCODE_MEMORY_AGENT`: override agent used for extraction
+- `OPENCODE_MEMORY_RECALL_MODEL`: override model used for LLM memory recall selection
+- `OPENCODE_MEMORY_RECALL_AGENT` (default `opencode-memory-recall`): override agent used for LLM memory recall selection
 - `OPENCODE_MEMORY_AUTODREAM` (default `1`): set `0` to disable auto-dream consolidation
 - `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS` (default `24`): min hours between consolidation runs
 - `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS` (default `5`): min touched sessions since last consolidation

package/bin/opencode-memory

@@ -441,7 +441,7 @@ has_new_memories() {
 }
 
 cleanup_timestamp() {
-  rm -f "$TIMESTAMP_FILE"
+  rm -f "$TIMESTAMP_FILE" "${TRANSCRIPT_CHECKPOINT_FILE:-}"
 }
 
 get_session_list_json() {
@@ -1126,6 +1126,122 @@ session_has_conversation() {
   return 0
 }
 
+transcript_fingerprint() {
+  local transcript_file="$1"
+  local stat_output
+
+  if [ ! -f "$transcript_file" ]; then
+    return 1
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$transcript_file" <<'PY'
+import os
+import sys
+
+path = sys.argv[1]
+
+try:
+    file_stat = os.stat(path)
+except OSError:
+    raise SystemExit(1)
+
+mtime = getattr(file_stat, "st_mtime_ns", int(file_stat.st_mtime * 1_000_000_000))
+print(f"{file_stat.st_size}\t{mtime}")
+PY
+    return $?
+  fi
+
+  if stat_output=$(stat -f '%z	%m' "$transcript_file" 2>/dev/null); then
+    printf '%s\n' "$stat_output"
+    return 0
+  fi
+
+  if stat_output=$(stat -c '%s	%Y' "$transcript_file" 2>/dev/null); then
+    printf '%s\n' "$stat_output"
+    return 0
+  fi
+
+  return 1
+}
+
+write_transcript_checkpoint() {
+  local output_file="$1"
+  local transcripts_dir
+  transcripts_dir="$(get_transcripts_dir)"
+
+  : > "$output_file"
+  [ -d "$transcripts_dir" ] || return 0
+
+  if command -v python3 >/dev/null 2>&1; then
+    python3 - "$transcripts_dir" > "$output_file" <<'PY'
+import os
+import stat
+import sys
+
+transcripts_dir = sys.argv[1]
+
+try:
+    filenames = os.listdir(transcripts_dir)
+except OSError:
+    raise SystemExit(0)
+
+for filename in filenames:
+    if not filename.endswith(".jsonl"):
+        continue
+    path = os.path.join(transcripts_dir, filename)
+    try:
+        file_stat = os.stat(path)
+    except OSError:
+        continue
+    if not stat.S_ISREG(file_stat.st_mode):
+        continue
+    session_id = filename[:-6]
+    if not session_id:
+        continue
+    mtime = getattr(file_stat, "st_mtime_ns", int(file_stat.st_mtime * 1_000_000_000))
+    print(f"{session_id}\t{file_stat.st_size}\t{mtime}")
+PY
+    return 0
+  fi
+
+  find "$transcripts_dir" -maxdepth 1 -type f -name '*.jsonl' -print 2>/dev/null | while IFS= read -r transcript_file; do
+    local filename session_id fingerprint
+    filename="$(basename "$transcript_file")"
+    session_id="${filename%.jsonl}"
+    fingerprint="$(transcript_fingerprint "$transcript_file" || true)"
+    [ -n "$session_id" ] && [ -n "$fingerprint" ] || continue
+    printf '%s\t%s\n' "$session_id" "$fingerprint"
+  done > "$output_file"
+}
+
+read_transcript_checkpoint() {
+  local session_id="$1"
+
+  [ -f "$TRANSCRIPT_CHECKPOINT_FILE" ] || return 1
+  awk -F '\t' -v id="$session_id" '$1 == id { print $2 "\t" $3; found=1; exit } END { exit found ? 0 : 1 }' "$TRANSCRIPT_CHECKPOINT_FILE"
+}
+
+session_has_incremental_activity() {
+  local session_id="$1"
+  local transcript_file previous current
+  transcript_file="$(get_transcripts_dir)/${session_id}.jsonl"
+
+  if [ -f "$transcript_file" ]; then
+    current="$(transcript_fingerprint "$transcript_file" || true)"
+    previous="$(read_transcript_checkpoint "$session_id" || true)"
+    if [ -z "$previous" ]; then
+      return 0
+    fi
+    [ "$current" != "$previous" ]
+    return $?
+  fi
+
+  # If no transcript is available, keep the existing conservative behavior:
+  # session_diff/session-list discovery may still have found a valid new turn.
+  return 0
+}
+
 run_extraction_if_needed() {
   local session_id="$1"
   local memory_written_during_session="$2"
@@ -1246,12 +1362,51 @@ run_post_session_tasks() {
   run_autodream_if_needed "$session_id"
 }
 
+run_post_session_for_invocation() {
+  local session_id
+  local memory_written_during_session
+
+  # Capture the session ID for this invocation. In background mode this wait
+  # must not delay the visible exit of the wrapped opencode process.
+  session_id=$(wait_for_session_target_id "$PRE_SESSION_JSON" "$SESSION_CAPTURE_STARTED_AT_MS" "$SESSION_WAIT_SECONDS" || true)
+  if [ -z "$session_id" ]; then
+    log "No session found, skipping post-session memory maintenance"
+    cleanup_timestamp
+    return 0
+  fi
+
+  # Skip if session had no real conversation (e.g. user opened TUI and exited).
+  if ! session_has_conversation "$session_id"; then
+    log "Session $session_id has no conversation, skipping post-session memory maintenance"
+    cleanup_timestamp
+    return 0
+  fi
+
+  if ! session_has_incremental_activity "$session_id"; then
+    log "Session $session_id has no new transcript activity, skipping post-session memory maintenance"
+    cleanup_timestamp
+    return 0
+  fi
+
+  memory_written_during_session=0
+  if has_new_memories; then
+    memory_written_during_session=1
+  fi
+
+  # Timestamp file is no longer needed after the check above.
+  cleanup_timestamp
+
+  run_post_session_tasks "$session_id" "$memory_written_during_session"
+}
+
 # ============================================================================
 # Main
 # ============================================================================
 
 # Step 0: Create timestamp marker before running opencode
 TIMESTAMP_FILE=$(mktemp)
+TRANSCRIPT_CHECKPOINT_FILE=$(mktemp)
+write_transcript_checkpoint "$TRANSCRIPT_CHECKPOINT_FILE"
 SESSION_CAPTURE_STARTED_AT_MS=$(( $(date +%s) * 1000 ))
 PRE_SESSION_JSON=$(get_session_list_json "$AUTODREAM_SCAN_LIMIT" 2>/dev/null || true)
 
@@ -1269,35 +1424,11 @@ if [ "$EXTRACT_ENABLED" = "0" ] && [ "$AUTODREAM_ENABLED" = "0" ]; then
   exit $opencode_exit
 fi
 
-# Step 3: Capture the session ID for this invocation
-session_id=$(wait_for_session_target_id "$PRE_SESSION_JSON" "$SESSION_CAPTURE_STARTED_AT_MS" "$SESSION_WAIT_SECONDS" || true)
-if [ -z "$session_id" ]; then
-  log "No session found, skipping post-session memory maintenance"
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-
-# Step 3.5: Skip if session had no real conversation (e.g. user opened TUI and exited)
-if ! session_has_conversation "$session_id"; then
-  log "Session $session_id has no conversation, skipping post-session memory maintenance"
-  cleanup_timestamp
-  exit $opencode_exit
-fi
-
-# Step 4: Check whether main session already wrote memory files
-memory_written_during_session=0
-if has_new_memories; then
-  memory_written_during_session=1
-fi
-
-# Timestamp file is no longer needed after the check above.
-cleanup_timestamp
-
-# Step 5: Run tasks (foreground for debug, background by default)
+# Step 3: Run post-session maintenance (foreground for debug, background by default).
 if [ "$FOREGROUND" = "1" ]; then
-  run_post_session_tasks "$session_id" "$memory_written_during_session"
+  run_post_session_for_invocation
 else
-  run_post_session_tasks "$session_id" "$memory_written_during_session" &
+  run_post_session_for_invocation &
   disown
   log "Post-session memory maintenance started in background (PID $!)"
 fi

package/dist/index.js

@@ -1,9 +1,13 @@
 import { tool } from "@opencode-ai/plugin";
+import { parse, resolve } from "path";
 import { buildMemorySystemPrompt } from "./prompt.js";
-import { recallRelevantMemories, formatRecalledMemories } from "./recall.js";
+import { formatRecalledMemories, recallSelectedMemories } from "./recall.js";
+import { assertSupportedRecallSelectorClient, selectRelevantMemoryFilenames } from "./recallSelector.js";
+import { scanMemoryFiles } from "./memoryScan.js";
 import { saveMemory, deleteMemory, listMemories, searchMemories, readMemory, MEMORY_TYPES, } from "./memory.js";
 import { getMemoryDir } from "./paths.js";
 const turnContextBySession = new Map();
+const selectorSessionIDs = new Set();
 function shouldIgnoreMemoryContext(query) {
     if (process.env.OPENCODE_MEMORY_IGNORE === "1")
         return true;
@@ -50,7 +54,8 @@ function getLastUserQuery(messages) {
             continue;
         const query = extractUserQuery(message);
         const sessionID = typeof message.info?.sessionID === "string" ? message.info.sessionID : undefined;
-        return { query, sessionID };
+        const messageID = typeof message.info?.id === "string" ? message.info.id : undefined;
+        return { query, sessionID, messageID, messageIndex: i };
     }
     return {};
 }
@@ -98,6 +103,85 @@ function extractRecentTools(messages) {
     }
     return tools;
 }
+function getRecallAgent() {
+    return process.env.OPENCODE_MEMORY_RECALL_AGENT || "opencode-memory-recall";
+}
+function getRecallModel() {
+    const raw = process.env.OPENCODE_MEMORY_RECALL_MODEL;
+    if (!raw)
+        return undefined;
+    const slashIdx = raw.indexOf("/");
+    if (slashIdx <= 0 || slashIdx === raw.length - 1)
+        return undefined;
+    return {
+        providerID: raw.slice(0, slashIdx),
+        modelID: raw.slice(slashIdx + 1),
+    };
+}
+function isRootPath(path) {
+    const resolved = resolve(path);
+    return resolved === parse(resolved).root;
+}
+function resolveMemoryRoot(worktree, directory) {
+    if (isRootPath(worktree) && !isRootPath(directory))
+        return directory;
+    return worktree;
+}
+function isUsefulRecallQuery(query) {
+    const trimmed = query?.trim();
+    if (!trimmed)
+        return false;
+    if (/\s/.test(trimmed))
+        return true;
+    return /[\u3400-\u9fff]/.test(trimmed) && trimmed.length >= 4;
+}
+function buildTurnID(sessionID, messageID, messageIndex, query) {
+    return `${sessionID}:${messageID ?? `${messageIndex ?? -1}:${query ?? ""}`}`;
+}
+function alreadySurfacedKey(header) {
+    return `${header.name ?? header.filename.replace(/\.md$/, "").replace(/.*\//, "")}|${header.type ?? "user"}`;
+}
+function startRecallPrefetch(input) {
+    if (!input.client || !isUsefulRecallQuery(input.query))
+        return undefined;
+    assertSupportedRecallSelectorClient(input.client);
+    const memoryDir = getMemoryDir(input.worktree);
+    const headers = scanMemoryFiles(memoryDir).filter((header) => !input.alreadySurfaced.has(alreadySurfacedKey(header)));
+    if (headers.length === 0)
+        return undefined;
+    const handle = {
+        turnID: input.turnID,
+        settled: false,
+        consumed: false,
+        result: [],
+    };
+    const promise = selectRelevantMemoryFilenames({
+        client: input.client,
+        directory: input.directory,
+        parentSessionID: input.parentSessionID,
+        query: input.query,
+        memories: headers,
+        recentTools: input.recentTools,
+        selectorSessionIDs,
+        agent: getRecallAgent(),
+        model: getRecallModel(),
+    })
+        .then((selectedFilenames) => recallSelectedMemories(headers, selectedFilenames, input.alreadySurfaced))
+        .catch(() => []);
+    void promise.then((result) => {
+        handle.result = result;
+    }).finally(() => {
+        handle.settled = true;
+    });
+    return handle;
+}
+function consumeRecallPrefetch(ctx) {
+    const prefetch = ctx?.recallPrefetch;
+    if (!prefetch || !prefetch.settled || prefetch.consumed)
+        return [];
+    prefetch.consumed = true;
+    return prefetch.result;
+}
 // Tracks how many memory entries a memory_list call saw so tool.execute.after
 // can render a meaningful title without re-reading the filesystem. Keyed by
 // callID, which uniquely identifies a single tool invocation.
@@ -149,9 +233,30 @@ function getCallID(ctx) {
     const v = ctx.callID;
     return typeof v === "string" ? v : undefined;
 }
-export const MemoryPlugin = async ({ worktree }) => {
-    getMemoryDir(worktree);
+export const MemoryPlugin = async ({ worktree, directory, client }) => {
+    directory ??= worktree;
+    const memoryRoot = resolveMemoryRoot(worktree, directory);
+    getMemoryDir(memoryRoot);
     return {
+        config: async (config) => {
+            const agentName = getRecallAgent();
+            const mutable = config;
+            mutable.agent ??= {};
+            mutable.agent[agentName] ??= {
+                mode: "all",
+                hidden: true,
+                prompt: "Select up to 5 relevant memory filenames for the current user query. Return only the requested structured output.",
+            };
+        },
+        "chat.params": async (input, output) => {
+            if (input.agent !== getRecallAgent())
+                return;
+            output.temperature = 0;
+            output.options = {
+                ...output.options,
+                maxOutputTokens: 256,
+            };
+        },
         "tool.execute.after": async (input, output) => {
             if (!input.tool.startsWith("memory_"))
                 return;
@@ -160,7 +265,9 @@ export const MemoryPlugin = async ({ worktree }) => {
                 output.title = title;
         },
         "experimental.chat.messages.transform": async (_input, output) => {
-            const { query, sessionID } = getLastUserQuery(output.messages);
+            const { query, sessionID, messageID, messageIndex } = getLastUserQuery(output.messages);
+            if (sessionID && selectorSessionIDs.has(sessionID))
+                return;
             if (sessionID) {
                 const alreadySurfaced = new Set();
                 for (const message of output.messages) {
@@ -179,7 +286,25 @@ export const MemoryPlugin = async ({ worktree }) => {
                     }
                 }
                 const recentTools = extractRecentTools(output.messages);
-                turnContextBySession.set(sessionID, { query, alreadySurfaced, recentTools });
+                const turnID = buildTurnID(sessionID, messageID, messageIndex, query);
+                const existing = turnContextBySession.get(sessionID);
+                const ignoreMemoryContext = process.env.OPENCODE_MEMORY_IGNORE === "1" || shouldIgnoreMemoryContext(query);
+                let recallPrefetch;
+                if (!ignoreMemoryContext) {
+                    recallPrefetch = existing?.turnID === turnID
+                        ? existing.recallPrefetch
+                        : startRecallPrefetch({
+                            client: client,
+                            directory,
+                            worktree: memoryRoot,
+                            parentSessionID: sessionID,
+                            turnID,
+                            query,
+                            alreadySurfaced,
+                            recentTools,
+                        });
+                }
+                turnContextBySession.set(sessionID, { turnID, query, alreadySurfaced, recentTools, recallPrefetch });
             }
             if (shouldIgnoreMemoryContext(query)) {
                 output.messages = output.messages
@@ -196,18 +321,18 @@ export const MemoryPlugin = async ({ worktree }) => {
         "experimental.chat.system.transform": async (_input, output) => {
             let sessionID;
             if (_input && typeof _input === "object") {
-                sessionID = (typeof _input.sessionID === "string"
+                sessionID = typeof _input.sessionID === "string"
                     ? _input.sessionID
-                    : undefined);
+                    : undefined;
             }
+            if (sessionID && selectorSessionIDs.has(sessionID))
+                return;
             const ctx = sessionID ? turnContextBySession.get(sessionID) : undefined;
             const query = ctx?.query;
-            const alreadySurfaced = ctx?.alreadySurfaced ?? new Set();
-            const recentTools = ctx?.recentTools ?? [];
             const ignoreMemoryContext = process.env.OPENCODE_MEMORY_IGNORE === "1" || shouldIgnoreMemoryContext(query);
-            const recalled = ignoreMemoryContext ? [] : recallRelevantMemories(worktree, query, alreadySurfaced, recentTools);
+            const recalled = ignoreMemoryContext ? [] : consumeRecallPrefetch(ctx);
             const recalledSection = formatRecalledMemories(recalled);
-            const memoryPrompt = buildMemorySystemPrompt(worktree, recalledSection, {
+            const memoryPrompt = buildMemorySystemPrompt(memoryRoot, recalledSection, {
                 includeIndex: !ignoreMemoryContext,
             });
             output.system.push(memoryPrompt);
@@ -236,7 +361,7 @@ export const MemoryPlugin = async ({ worktree }) => {
                         .describe("Memory content. For feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines"),
                 },
                 async execute(args, _ctx) {
-                    const filePath = saveMemory(worktree, args.file_name, args.name, args.description, args.type, args.content);
+                    const filePath = saveMemory(memoryRoot, args.file_name, args.name, args.description, args.type, args.content);
                     return `Memory saved to ${filePath}`;
                 },
             }),
@@ -246,7 +371,7 @@ export const MemoryPlugin = async ({ worktree }) => {
                     file_name: tool.schema.string().describe("File name of the memory to delete (with or without .md extension)"),
                 },
                 async execute(args, _ctx) {
-                    const deleted = deleteMemory(worktree, args.file_name);
+                    const deleted = deleteMemory(memoryRoot, args.file_name);
                     return deleted ? `Memory "${args.file_name}" deleted.` : `Memory "${args.file_name}" not found.`;
                 },
             }),
@@ -256,7 +381,7 @@ export const MemoryPlugin = async ({ worktree }) => {
                     "or when you need to recall what's been stored.",
                 args: {},
                 async execute(_args, ctx) {
-                    const entries = listMemories(worktree);
+                    const entries = listMemories(memoryRoot);
                     const callID = getCallID(ctx);
                     if (callID)
                         memoryListCountByCallID.set(callID, entries.length);
@@ -274,7 +399,7 @@ export const MemoryPlugin = async ({ worktree }) => {
                     query: tool.schema.string().describe("Search query — searches across name, description, and content"),
                 },
                 async execute(args, ctx) {
-                    const results = searchMemories(worktree, args.query);
+                    const results = searchMemories(memoryRoot, args.query);
                     const callID = getCallID(ctx);
                     if (callID)
                         memorySearchCountByCallID.set(callID, results.length);
@@ -291,7 +416,7 @@ export const MemoryPlugin = async ({ worktree }) => {
                     file_name: tool.schema.string().describe("File name of the memory to read (with or without .md extension)"),
                 },
                 async execute(args, _ctx) {
-                    const entry = readMemory(worktree, args.file_name);
+                    const entry = readMemory(memoryRoot, args.file_name);
                     if (!entry) {
                         return `Memory "${args.file_name}" not found.`;
                     }

package/dist/recall.d.ts

@@ -1,3 +1,4 @@
+import type { MemoryHeader } from "./memoryScan.js";
 export type RecalledMemory = {
     fileName: string;
     filePath: string;
@@ -7,5 +8,5 @@ export type RecalledMemory = {
     content: string;
     ageInDays: number;
 };
-export declare function recallRelevantMemories(worktree: string, query?: string, alreadySurfaced?: ReadonlySet<string>, recentTools?: readonly string[]): RecalledMemory[];
+export declare function recallSelectedMemories(headers: readonly MemoryHeader[], selectedFilenames: readonly string[], alreadySurfaced?: ReadonlySet<string>): RecalledMemory[];
 export declare function formatRecalledMemories(memories: RecalledMemory[]): string;

package/dist/recall.js

@@ -1,13 +1,8 @@
 import { readFileSync } from "fs";
-import { scanMemoryFiles } from "./memoryScan.js";
-import { getMemoryDir } from "./paths.js";
 const MAX_RECALLED_MEMORIES = 5;
 const MAX_MEMORY_LINES = 200;
 const MAX_MEMORY_BYTES = 4096;
 const encoder = new TextEncoder();
-function tokenizeQuery(query) {
-    return [...new Set(query.toLowerCase().split(/\s+/).map((token) => token.trim()).filter((token) => token.length >= 2))];
-}
 function readMemoryContent(filePath) {
     try {
         const raw = readFileSync(filePath, "utf-8");
@@ -28,26 +23,6 @@ function readMemoryContent(filePath) {
         return "";
     }
 }
-function scoreHeader(header, content, terms) {
-    if (terms.length === 0)
-        return 0;
-    const nameHaystack = (header.name ?? "").toLowerCase();
-    const descHaystack = (header.description ?? "").toLowerCase();
-    const filenameHaystack = header.filename.toLowerCase();
-    const contentHaystack = content.toLowerCase();
-    let score = 0;
-    for (const term of terms) {
-        if (nameHaystack.includes(term))
-            score += 3;
-        if (descHaystack.includes(term))
-            score += 3;
-        if (filenameHaystack.includes(term))
-            score += 1;
-        if (contentHaystack.includes(term))
-            score += 1;
-    }
-    return score;
-}
 function truncateMemoryContent(content) {
     const maxLines = content.split("\n").slice(0, MAX_MEMORY_LINES);
     const lineTruncated = maxLines.join("\n");
@@ -67,54 +42,40 @@ function truncateMemoryContent(content) {
     }
     return kept.join("\n");
 }
-// Port of Claude Code's findRelevantMemories pattern, adapted for
-// keyword-based selection (no LLM side query available in plugin context).
-function isToolReferenceMemory(header, content, recentTools) {
-    if (recentTools.length === 0)
-        return false;
-    const type = header.type;
-    if (type !== "reference")
-        return false;
-    const haystack = `${header.name ?? ""}\n${header.description ?? ""}\n${content}`.toLowerCase();
-    const warningSignals = ["warning", "gotcha", "issue", "bug", "caveat", "pitfall", "known issue"];
-    if (warningSignals.some((w) => haystack.includes(w)))
-        return false;
-    const toolHaystack = recentTools.map((t) => t.toLowerCase());
-    return toolHaystack.some((tool) => haystack.includes(tool));
+function memorySurfaceKey(header) {
+    return `${header.name ?? header.filename.replace(/\.md$/, "").replace(/.*\//, "")}|${header.type ?? "user"}`;
+}
+function recalledMemoryFromHeader(header, content, now) {
+    const nameFromFilename = header.filename.replace(/\.md$/, "").replace(/.*\//, "");
+    return {
+        fileName: header.filename,
+        filePath: header.filePath,
+        name: header.name ?? nameFromFilename,
+        type: header.type ?? "user",
+        description: header.description ?? "",
+        content: truncateMemoryContent(content),
+        ageInDays: Math.max(0, Math.floor((now - header.mtimeMs) / (1000 * 60 * 60 * 24))),
+    };
 }
-export function recallRelevantMemories(worktree, query, alreadySurfaced = new Set(), recentTools = []) {
-    const memoryDir = getMemoryDir(worktree);
-    const headers = scanMemoryFiles(memoryDir).filter((h) => !alreadySurfaced.has(`${h.name ?? h.filename.replace(/\.md$/, "").replace(/.*\//, "")}|${h.type ?? "user"}`));
-    if (headers.length === 0)
+export function recallSelectedMemories(headers, selectedFilenames, alreadySurfaced = new Set()) {
+    if (selectedFilenames.length === 0)
         return [];
     const now = Date.now();
-    const terms = query ? tokenizeQuery(query) : [];
-    const scored = headers.map((header) => {
-        const content = readMemoryContent(header.filePath);
-        return {
-            header,
-            content,
-            score: scoreHeader(header, content, terms),
-        };
-    }).filter(({ header, content }) => !isToolReferenceMemory(header, content, recentTools));
-    if (terms.length > 0 && scored.some((s) => s.score > 0)) {
-        scored.sort((a, b) => b.score - a.score || b.header.mtimeMs - a.header.mtimeMs);
-    }
-    else {
-        scored.sort((a, b) => b.header.mtimeMs - a.header.mtimeMs);
+    const byFilename = new Map(headers.map((header) => [header.filename, header]));
+    const recalled = [];
+    const seen = new Set();
+    for (const filename of selectedFilenames) {
+        if (seen.has(filename))
+            continue;
+        seen.add(filename);
+        const header = byFilename.get(filename);
+        if (!header || alreadySurfaced.has(memorySurfaceKey(header)))
+            continue;
+        recalled.push(recalledMemoryFromHeader(header, readMemoryContent(header.filePath), now));
+        if (recalled.length >= MAX_RECALLED_MEMORIES)
+            break;
     }
-    return scored.slice(0, MAX_RECALLED_MEMORIES).map(({ header, content }) => {
-        const nameFromFilename = header.filename.replace(/\.md$/, "").replace(/.*\//, "");
-        return {
-            fileName: header.filename,
-            filePath: header.filePath,
-            name: header.name ?? nameFromFilename,
-            type: header.type ?? "user",
-            description: header.description ?? "",
-            content: truncateMemoryContent(content),
-            ageInDays: Math.max(0, Math.floor((now - header.mtimeMs) / (1000 * 60 * 60 * 24))),
-        };
-    });
+    return recalled;
 }
 function formatAgeWarning(ageInDays) {
     if (ageInDays <= 1)

package/dist/recallSelector.d.ts

@@ -0,0 +1,27 @@
+import { type MemoryHeader } from "./memoryScan.js";
+export declare const SELECT_MEMORIES_SYSTEM_PROMPT = "You are selecting memories that will be useful to OpenCode as it processes a user's query. You will be given the user's query and a list of available memory files with their filenames and descriptions.\n\nReturn a list of filenames for the memories that will clearly be useful to OpenCode as it processes the user's query (up to 5). Only include memories that you are certain will be helpful based on their name and description.\n- If you are unsure if a memory will be useful in processing the user's query, then do not include it in your list. Be selective and discerning.\n- If there are no memories in the list that would clearly be useful, feel free to return an empty list.\n- If a list of recently-used tools is provided, do not select memories that are usage reference or API documentation for those tools (OpenCode is already exercising them). DO still select memories containing warnings, gotchas, or known issues about those tools \u2014 active use is exactly when those matter.\n";
+export declare const UNSUPPORTED_RECALL_SELECTOR_CLIENT_MESSAGE = "opencode-claude-memory LLM recall requires an OpenCode SDK with structured output session.prompt support. Please upgrade OpenCode/@opencode-ai/plugin.";
+export type SessionClient = {
+    session?: {
+        create?: (...args: unknown[]) => Promise<unknown>;
+        prompt?: (...args: unknown[]) => Promise<unknown>;
+        delete?: (...args: unknown[]) => Promise<unknown>;
+    };
+};
+export type SelectRelevantMemoryFilenamesInput = {
+    client: SessionClient | undefined;
+    directory: string;
+    parentSessionID: string;
+    query: string;
+    memories: MemoryHeader[];
+    recentTools: readonly string[];
+    selectorSessionIDs: Set<string>;
+    agent: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+};
+export declare function isSupportedRecallSelectorClient(client: SessionClient | undefined): boolean;
+export declare function assertSupportedRecallSelectorClient(client: SessionClient | undefined): asserts client is SessionClient;
+export declare function selectRelevantMemoryFilenames(input: SelectRelevantMemoryFilenamesInput): Promise<string[]>;

package/dist/recallSelector.js

@@ -0,0 +1,148 @@
+import { formatMemoryManifest } from "./memoryScan.js";
+export const SELECT_MEMORIES_SYSTEM_PROMPT = `You are selecting memories that will be useful to OpenCode as it processes a user's query. You will be given the user's query and a list of available memory files with their filenames and descriptions.
+
+Return a list of filenames for the memories that will clearly be useful to OpenCode as it processes the user's query (up to 5). Only include memories that you are certain will be helpful based on their name and description.
+- If you are unsure if a memory will be useful in processing the user's query, then do not include it in your list. Be selective and discerning.
+- If there are no memories in the list that would clearly be useful, feel free to return an empty list.
+- If a list of recently-used tools is provided, do not select memories that are usage reference or API documentation for those tools (OpenCode is already exercising them). DO still select memories containing warnings, gotchas, or known issues about those tools — active use is exactly when those matter.
+`;
+const SELECT_MEMORIES_FORMAT = {
+    type: "json_schema",
+    schema: {
+        type: "object",
+        properties: {
+            selected_memories: { type: "array", items: { type: "string" } },
+        },
+        required: ["selected_memories"],
+        additionalProperties: false,
+    },
+};
+export const UNSUPPORTED_RECALL_SELECTOR_CLIENT_MESSAGE = "opencode-claude-memory LLM recall requires an OpenCode SDK with structured output session.prompt support. Please upgrade OpenCode/@opencode-ai/plugin.";
+function unwrapData(response) {
+    if (!response || typeof response !== "object")
+        return response;
+    if ("data" in response)
+        return response.data;
+    return response;
+}
+function extractSessionID(response) {
+    const data = unwrapData(response);
+    if (!data || typeof data !== "object")
+        return undefined;
+    const id = data.id ?? data.sessionID;
+    return typeof id === "string" ? id : undefined;
+}
+function tryParseSelectedMemories(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.selected_memories))
+            return undefined;
+        return parsed.selected_memories.filter((item) => typeof item === "string");
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractSelectedMemories(response) {
+    const data = unwrapData(response);
+    if (!data || typeof data !== "object")
+        return [];
+    const structured = data.info?.structured;
+    if (structured && typeof structured === "object") {
+        const selected = structured.selected_memories;
+        if (Array.isArray(selected)) {
+            return selected.filter((item) => typeof item === "string");
+        }
+    }
+    const parts = data.parts;
+    if (!Array.isArray(parts))
+        return [];
+    for (const part of parts) {
+        if (!part || typeof part !== "object")
+            continue;
+        const text = part.text;
+        if (typeof text !== "string")
+            continue;
+        const parsed = tryParseSelectedMemories(text);
+        if (parsed)
+            return parsed;
+    }
+    return [];
+}
+export function isSupportedRecallSelectorClient(client) {
+    const session = client?.session;
+    return Boolean(session?.create &&
+        session?.prompt &&
+        session?.delete &&
+        session.create.length >= 2 &&
+        session.prompt.length >= 2 &&
+        session.delete.length >= 2);
+}
+export function assertSupportedRecallSelectorClient(client) {
+    if (!isSupportedRecallSelectorClient(client)) {
+        throw new Error(UNSUPPORTED_RECALL_SELECTOR_CLIENT_MESSAGE);
+    }
+}
+async function createSelectorSession(client, directory, parentSessionID) {
+    if (!client.session?.create)
+        return undefined;
+    const response = await client.session.create({
+        directory,
+        parentID: parentSessionID,
+        title: "opencode-memory recall selector",
+    });
+    return extractSessionID(response);
+}
+async function promptSelectorSession(client, sessionID, directory, agent, model, content) {
+    if (!client.session?.prompt)
+        return undefined;
+    const body = {
+        agent,
+        ...(model ? { model } : {}),
+        tools: {},
+        system: SELECT_MEMORIES_SYSTEM_PROMPT,
+        format: SELECT_MEMORIES_FORMAT,
+        parts: [{ type: "text", text: content }],
+    };
+    return client.session.prompt({ sessionID, directory, ...body });
+}
+async function deleteSelectorSession(client, sessionID, directory) {
+    if (!client.session?.delete)
+        return;
+    try {
+        await client.session.delete({ sessionID, directory });
+    }
+    catch {
+        // Best-effort cleanup. A failed selector deletion should not affect recall.
+    }
+}
+export async function selectRelevantMemoryFilenames(input) {
+    if (input.memories.length === 0)
+        return [];
+    assertSupportedRecallSelectorClient(input.client);
+    let selectorSessionID;
+    try {
+        selectorSessionID = await createSelectorSession(input.client, input.directory, input.parentSessionID);
+        if (!selectorSessionID)
+            return [];
+        input.selectorSessionIDs.add(selectorSessionID);
+        const toolsSection = input.recentTools.length > 0
+            ? `\n\nRecently used tools: ${input.recentTools.join(", ")}`
+            : "";
+        const manifest = formatMemoryManifest(input.memories);
+        const response = await promptSelectorSession(input.client, selectorSessionID, input.directory, input.agent, input.model, `Query: ${input.query}\n\nAvailable memories:\n${manifest}${toolsSection}`);
+        const validFilenames = new Set(input.memories.map((memory) => memory.filename));
+        return extractSelectedMemories(response)
+            .filter((filename) => validFilenames.has(filename))
+            .slice(0, 5);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (selectorSessionID) {
+            input.selectorSessionIDs.delete(selectorSessionID);
+            await deleteSelectorSession(input.client, selectorSessionID, input.directory);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "1.6.5",
+  "version": "1.7.1",
   "type": "module",
   "description": "Claude Code-compatible memory compatibility layer for OpenCode — zero config, local-first, no migration",
   "main": "dist/index.js",