opencode-claude-memory 1.7.5 → 1.7.7

package/README.md

@@ -217,6 +217,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_EXTRACT_TIMEOUT_MS` (default `120000`): positive integer timeout for a native extraction request in milliseconds
+- `OPENCODE_MEMORY_EXTRACT_MAX_STEPS` (default `30`): max agentic steps for a native extraction fork before OpenCode forces a text-only reply; set `0` to remove the cap (the timeout is then the only backstop)
 - `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

package/dist/index.js

@@ -4,8 +4,9 @@ import { buildMemorySystemPrompt } from "./prompt.js";
 import { formatRecalledMemories, recallSelectedMemories } from "./recall.js";
 import { isSupportedRecallSelectorClient, selectRelevantMemoryFilenames } from "./recallSelector.js";
 import { scanMemoryFiles } from "./memoryScan.js";
-import { saveMemory, deleteMemory, listMemories, searchMemories, readMemory, MEMORY_TYPES, } from "./memory.js";
+import { saveMemoryDetailed, deleteMemory, listMemories, searchMemories, readMemory, MEMORY_TYPES, } from "./memory.js";
 import { getMemoryDir } from "./paths.js";
+import { formatMemorySaveResult, getNativeExtractMaxSteps, getNativeExtractTimeoutMs, logNativeExtractionFailure, } from "./nativeExtraction.js";
 const turnContextBySession = new Map();
 const selectorSessionIDs = new Set();
 function shouldIgnoreMemoryContext(query) {
@@ -234,6 +235,12 @@ function getCallID(ctx) {
     const v = ctx.callID;
     return typeof v === "string" ? v : undefined;
 }
+function getSessionID(ctx) {
+    if (!ctx || typeof ctx !== "object")
+        return undefined;
+    const v = ctx.sessionID;
+    return typeof v === "string" ? v : undefined;
+}
 // ─── Native post-session extraction (optional) ───────────────────────────────
 // Architecture follows opencode-mem's proven pattern: hook `session.idle`,
 // fetch the conversation via ctx.client.session.messages(), then run extraction
@@ -280,14 +287,15 @@ For each memory worth saving, call \`memory_save\` with:
 3. Save each distinct memory as a separate entry
 4. If the conversation was trivial (e.g., just "hello" or a quick lookup), save nothing — that's fine
 5. Be selective: 0-3 memories per session is typical. Quality over quantity.
-6. Do NOT save a memory about the extraction process itself.`;
+6. Do NOT save a memory about the extraction process itself.
+7. Each \`memory_save\` call persists immediately and its result lists everything saved so far in this run. Never save the same \`file_name\` twice in one run. When nothing else is worth saving, stop calling tools and reply with a one-line summary.`;
 const NATIVE_EXTRACT_DEBOUNCE_MS = 10000;
-const NATIVE_EXTRACT_TIMEOUT_MS = 120000; // hard cap on a single extraction fork (prevents permanent leak on hang)
 const NATIVE_EXTRACT_MAX_CONV_CHARS = 60000;
 const NATIVE_EXTRACT_GRACE_MS = 60000; // keep forkID in the guard after delete — covers the idle-race window
 const nativeIdleTimer = new Map();
 const nativeExtractionSessions = new Set(); // sub-session IDs → skip their idle AND shield from transforms
 const nativeExtractionInFlight = new Set(); // parent sessionIDs with an extraction running → no overlap
+const nativeExtractionSavedFiles = new Map(); // fork sessionID → file names memory_save wrote this run (#35)
 function extractIDFromResponse(response) {
     const data = response?.data ?? response;
     const obj = data;
@@ -335,7 +343,7 @@ function buildConversationForExtraction(messages) {
 }
 // Security: the extraction fork runs on raw, potentially-untrusted transcript content (fetched web
 // pages, tool output). It MUST be sandboxed to the memory tools only (no bash/edit/write) and capped
-// by a timeout so a hang can't leak the sub-session forever.
+// by a timeout so a hung prompt stops blocking best-effort sub-session cleanup.
 async function runNativeExtraction(client, sessionID, directory) {
     const c = client;
     if (!c?.session?.messages || !c.session.create || !c.session.prompt)
@@ -344,6 +352,7 @@ async function runNativeExtraction(client, sessionID, directory) {
         return; // no overlapping runs against the same session
     nativeExtractionInFlight.add(sessionID);
     let forkID = null;
+    let promptSettled = false;
     try {
         // query.directory is required for correct resolution under multi-directory serve.
         const resp = await c.session.messages({ path: { id: sessionID }, query: { directory } });
@@ -368,16 +377,17 @@ async function runNativeExtraction(client, sessionID, directory) {
         const extractModel = getNativeExtractModel();
         if (extractModel)
             body.model = extractModel;
-        // Race the prompt against a hard timeout so a hung/permission-gated fork can't leak.
+        // Race the prompt against a timeout so a hung/permission-gated fork stops blocking cleanup.
         let timer;
         const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error("native extraction timed out")), NATIVE_EXTRACT_TIMEOUT_MS);
+            timer = setTimeout(() => reject(new Error("native extraction timed out")), getNativeExtractTimeoutMs());
         });
         try {
             await Promise.race([
                 c.session.prompt({ path: { id: forkID }, query: { directory }, body }),
                 timeout,
             ]);
+            promptSettled = true;
         }
         finally {
             if (timer)
@@ -385,15 +395,23 @@ async function runNativeExtraction(client, sessionID, directory) {
         }
     }
     catch (e) {
-        console.error("[opencode-claude-memory] native extraction failed:", e?.message ?? e);
+        logNativeExtractionFailure(client, directory, sessionID, e);
     }
     finally {
         if (forkID) {
+            // On timeout the server is still running the fork; stop it before deleting the session so it
+            // does not keep inserting parts/messages for a row that no longer exists (FK constraint errors).
+            if (!promptSettled) {
+                await c.session?.abort?.({ path: { id: forkID }, query: { directory } }).catch(() => { });
+            }
             await c.session?.delete?.({ path: { id: forkID }, query: { directory } }).catch(() => { });
             // Hold the guard past delete: the fork's session.idle can arrive on a separate channel after
             // the delete HTTP call resolves, and would otherwise re-trigger extraction of the fork itself.
             const id = forkID;
-            setTimeout(() => nativeExtractionSessions.delete(id), NATIVE_EXTRACT_GRACE_MS);
+            setTimeout(() => {
+                nativeExtractionSessions.delete(id);
+                nativeExtractionSavedFiles.delete(id);
+            }, NATIVE_EXTRACT_GRACE_MS);
         }
         nativeExtractionInFlight.delete(sessionID);
     }
@@ -428,11 +446,17 @@ export const MemoryPlugin = async ({ worktree, directory, client }) => {
             };
             // Dedicated hidden agent for native extraction: its system prompt IS the extraction instruction,
             // so the fork runs with an explicit system (not the build agent's) and tool-restricted to memory_*.
-            mutable.agent[getNativeExtractAgent()] ??= {
+            // `steps` caps the fork's agentic iterations so a model that keeps re-saving the same memories
+            // terminates cleanly (OpenCode forces a text-only reply) instead of spinning until the timeout (#35).
+            const extractAgent = (mutable.agent[getNativeExtractAgent()] ??= {
                 mode: "all",
                 hidden: true,
                 prompt: EXTRACT_PROMPT,
-            };
+            });
+            const maxSteps = getNativeExtractMaxSteps();
+            if (maxSteps !== undefined && extractAgent.steps === undefined && extractAgent.maxSteps === undefined) {
+                extractAgent.steps = maxSteps;
+            }
         },
         // Native post-session extraction. Enabled by default on Windows (where the
         // bash wrapper can't run) and via OPENCODE_MEMORY_NATIVE_EXTRACT=1 elsewhere;
@@ -460,7 +484,7 @@ export const MemoryPlugin = async ({ worktree, directory, client }) => {
             nativeIdleTimer.set(sessionID, setTimeout(() => {
                 nativeIdleTimer.delete(sessionID);
                 void runNativeExtraction(client, sessionID, directory).catch((e) => {
-                    console.error("[opencode-claude-memory] native extraction failed:", e?.message ?? e);
+                    logNativeExtractionFailure(client, directory, sessionID, e);
                 });
             }, NATIVE_EXTRACT_DEBOUNCE_MS));
         },
@@ -575,9 +599,17 @@ export const MemoryPlugin = async ({ worktree, directory, client }) => {
                         .string()
                         .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(memoryRoot, args.file_name, args.name, args.description, args.type, args.content);
-                    return `Memory saved to ${filePath}`;
+                async execute(args, ctx) {
+                    const outcome = saveMemoryDetailed(memoryRoot, args.file_name, args.name, args.description, args.type, args.content);
+                    const sessionID = getSessionID(ctx);
+                    if (!sessionID || !nativeExtractionSessions.has(sessionID))
+                        return formatMemorySaveResult(outcome);
+                    // Extraction fork: record every save so the tool result can carry a durable done-signal.
+                    let saved = nativeExtractionSavedFiles.get(sessionID);
+                    if (!saved)
+                        nativeExtractionSavedFiles.set(sessionID, (saved = []));
+                    saved.push(outcome.fileName);
+                    return formatMemorySaveResult(outcome, saved);
                 },
             }),
             memory_delete: tool({

package/dist/memory.d.ts

@@ -11,7 +11,13 @@ export type MemoryEntry = {
 };
 export declare function listMemories(worktree: string): MemoryEntry[];
 export declare function readMemory(worktree: string, fileName: string): MemoryEntry | null;
+export type SaveMemoryResult = {
+    filePath: string;
+    fileName: string;
+    unchanged: boolean;
+};
 export declare function saveMemory(worktree: string, fileName: string, name: string, description: string, type: MemoryType, content: string): string;
+export declare function saveMemoryDetailed(worktree: string, fileName: string, name: string, description: string, type: MemoryType, content: string): SaveMemoryResult;
 export declare function deleteMemory(worktree: string, fileName: string): boolean;
 export declare function searchMemories(worktree: string, query: string): MemoryEntry[];
 export declare function readIndex(worktree: string): string;

package/dist/memory.js

@@ -97,6 +97,11 @@ export function readMemory(worktree, fileName) {
     }
 }
 export function saveMemory(worktree, fileName, name, description, type, content) {
+    return saveMemoryDetailed(worktree, fileName, name, description, type, content).filePath;
+}
+// Same as saveMemory() but reports whether anything was actually written. An identical re-save is a
+// no-op: the extraction fork uses that signal to tell the model it is repeating itself (see #35).
+export function saveMemoryDetailed(worktree, fileName, name, description, type, content) {
     const safeName = validateMemoryFileName(fileName);
     if (typeof name !== "string" || !name.trim()) {
         throw new Error("Memory name is required");
@@ -107,9 +112,22 @@ export function saveMemory(worktree, fileName, name, description, type, content)
     if (Buffer.byteLength(fileContent, "utf-8") > MAX_MEMORY_FILE_BYTES) {
         throw new Error(`Memory file content exceeds the ${MAX_MEMORY_FILE_BYTES}-byte limit`);
     }
+    if (isMemoryUnchanged(worktree, filePath, fileContent, buildIndexPointer(safeName, name, description))) {
+        return { filePath, fileName: safeName, unchanged: true };
+    }
     writeFileSync(filePath, fileContent, "utf-8");
     updateIndex(worktree, safeName, name, description);
-    return filePath;
+    return { filePath, fileName: safeName, unchanged: false };
+}
+function isMemoryUnchanged(worktree, filePath, fileContent, pointer) {
+    try {
+        if (readFileSync(filePath, "utf-8") !== fileContent)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return readIndex(worktree).split("\n").some((line) => line.trimEnd() === pointer);
 }
 export function deleteMemory(worktree, fileName) {
     const safeName = validateMemoryFileName(fileName);
@@ -140,11 +158,14 @@ export function readIndex(worktree) {
         return "";
     }
 }
+function buildIndexPointer(fileName, name, description) {
+    return `- [${name}](${fileName}) — ${description}`;
+}
 function updateIndex(worktree, fileName, name, description) {
     const entrypoint = getMemoryEntrypoint(worktree);
     const existing = readIndex(worktree);
     const lines = existing.split("\n").filter((l) => l.trim());
-    const pointer = `- [${name}](${fileName}) — ${description}`;
+    const pointer = buildIndexPointer(fileName, name, description);
     const existingIdx = lines.findIndex((l) => l.includes(`(${fileName})`));
     if (existingIdx >= 0) {
         lines[existingIdx] = pointer;

package/dist/nativeExtraction.d.ts

@@ -0,0 +1,9 @@
+export declare function getNativeExtractTimeoutMs(raw?: string | undefined): number;
+export declare function getNativeExtractMaxSteps(raw?: string | undefined): number | undefined;
+export type MemorySaveOutcome = {
+    filePath: string;
+    fileName: string;
+    unchanged: boolean;
+};
+export declare function formatMemorySaveResult(outcome: MemorySaveOutcome, savedThisRun?: readonly string[]): string;
+export declare function logNativeExtractionFailure(client: unknown, directory: string, sessionID: string, error: unknown): void;

package/dist/nativeExtraction.js

@@ -0,0 +1,80 @@
+const DEFAULT_NATIVE_EXTRACT_TIMEOUT_MS = 120_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+// A legitimate extraction is 1 memory_list + a handful of memory_save calls; 30 agentic steps leaves
+// generous headroom while still terminating a model that keeps re-saving the same files (#35).
+const DEFAULT_NATIVE_EXTRACT_MAX_STEPS = 30;
+function getErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return String(error);
+}
+export function getNativeExtractTimeoutMs(raw = process.env.OPENCODE_MEMORY_EXTRACT_TIMEOUT_MS) {
+    const timeout = Number(raw);
+    return Number.isSafeInteger(timeout) && timeout > 0 && timeout <= MAX_TIMER_DELAY_MS
+        ? timeout
+        : DEFAULT_NATIVE_EXTRACT_TIMEOUT_MS;
+}
+// Step cap for the extraction agent (OpenCode `agent.<name>.steps`). Unset/invalid → default;
+// "0" → undefined, i.e. no cap (the wall-clock timeout becomes the only backstop).
+export function getNativeExtractMaxSteps(raw = process.env.OPENCODE_MEMORY_EXTRACT_MAX_STEPS) {
+    const trimmed = raw?.trim();
+    // Only a plain non-negative integer counts; "" / " " must not become Number("") === 0 (no cap).
+    if (!trimmed || !/^\d+$/.test(trimmed))
+        return DEFAULT_NATIVE_EXTRACT_MAX_STEPS;
+    const steps = Number(trimmed);
+    if (!Number.isSafeInteger(steps))
+        return DEFAULT_NATIVE_EXTRACT_MAX_STEPS;
+    return steps === 0 ? undefined : steps;
+}
+// Tool result for memory_save. Inside an extraction fork, `savedThisRun` (file names already saved
+// by this fork, in order) is appended as an explicit done-signal so the model does not lose track on
+// long transcripts and re-save the same memories until the timeout kills it (#35).
+export function formatMemorySaveResult(outcome, savedThisRun) {
+    const inExtractionRun = savedThisRun !== undefined;
+    // The current file is recorded before formatting, so "earlier" means it appeared before this call.
+    const savedEarlierThisRun = inExtractionRun && savedThisRun.indexOf(outcome.fileName) < savedThisRun.length - 1;
+    let head;
+    if (outcome.unchanged) {
+        head = savedEarlierThisRun
+            ? `Skipped: "${outcome.fileName}" was already saved earlier in this extraction run with identical content — nothing written.`
+            : `Skipped: "${outcome.fileName}" already exists with identical content — nothing written (${outcome.filePath}).`;
+    }
+    else if (savedEarlierThisRun) {
+        head = `Updated "${outcome.fileName}" (first saved earlier in this extraction run) at ${outcome.filePath}`;
+    }
+    else {
+        head = `Memory saved to ${outcome.filePath}`;
+    }
+    if (!inExtractionRun)
+        return head;
+    const unique = Array.from(new Set(savedThisRun));
+    return (`${head}\n\n` +
+        `Saved so far in this extraction run (${unique.length}): ${unique.join(", ")}\n` +
+        "These memories are already persisted — do not call memory_save for them again. " +
+        "Once every distinct memory worth keeping is saved, stop calling tools and reply with a one-line summary.");
+}
+export function logNativeExtractionFailure(client, directory, sessionID, error) {
+    const c = client;
+    if (!c?.app?.log)
+        return;
+    try {
+        const message = getErrorMessage(error);
+        void c.app.log({
+            body: {
+                service: "opencode-claude-memory",
+                level: "error",
+                message: "Native extraction failed",
+                extra: { error: message, sessionID },
+            },
+            query: { directory },
+        }).catch(() => { });
+    }
+    catch {
+        // Logging must stay best-effort: stderr is rendered into the OpenCode chat UI.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "type": "module",
   "description": "OpenCode plugin for Claude Code memory: persistent, local-first shared memory with Claude Code-compatible Markdown files, auto extraction, and auto-dream",
   "main": "dist/index.js",