@nguyenthdat/opencode-memory 0.2.0 → 0.3.0

package/dist/plugin.js

@@ -1,44 +1,56 @@
 import { tool } from "@opencode-ai/plugin";
 import { MEMORY_KINDS, MEMORY_SCOPES, WRITABLE_MEMORY_SCOPES, FEEDBACK_EVENTS, LOCK_ACTIONS, MEMORY_TAXONOMIES, } from "./contracts.js";
 import { NativeMemoryClient } from "./sidecar-client.js";
-import { MEMORY_POLICY, MEMORY_POLICY_MARKER, COMPACTION_CONTEXT, formatRecalledMemories, truncateText, contextBudgetChars, parseCuratedCandidates, } from "./policy.js";
+import { COMPACTION_CONTEXT, formatRecalledMemories, truncateText, contextBudgetChars, parseCuratedCandidates, deriveRecallQuery, } from "./policy.js";
+import { MEMORY_INSTRUCTIONS_MARKER, loadMemoryInstructions, registerMemoryInstructions, } from "./instructions.js";
 import { SHARED_MEMORY_RELATIVE_DIR, loadSharedMemories, writeSharedMemory, } from "./shared-markdown.js";
 import { SessionContext } from "./session-context.js";
-import { validateUpdateArgs } from "./validation.js";
+import { validateDeleteRecords, validateUpdateArgs } from "./validation.js";
 export function createMemoryPlugin(options) {
     return async ({ client: opencode, directory, worktree }) => {
-        const native = new NativeMemoryClient(options.root, worktree);
+        const settings = resolveMemoryPluginOptions(options);
+        const memoryProjectRoot = options.projectRoot ?? worktree;
+        const memoryInstructions = await loadMemoryInstructions(options.root);
+        const native = new NativeMemoryClient(options.root, memoryProjectRoot);
         const session = new SessionContext(native, (path, query) => opencode.session.get({ path, query }), directory);
         let sharedSignature;
         let sharedSync;
         const syncSharedMemories = async (force = false) => {
+            if (!settings.sharedSync)
+                return;
             if (sharedSync)
                 return await sharedSync;
             sharedSync = (async () => {
-                const loaded = await loadSharedMemories(worktree);
+                const loaded = await loadSharedMemories(memoryProjectRoot);
+                for (const error of loaded.errors) {
+                    session.warnOnce(new Error(`${error.source}: ${error.message}`));
+                }
                 if (!force && loaded.signature === sharedSignature)
                     return;
                 const response = await native.request("sync_shared", {
                     records: loaded.records,
                 });
                 if (response.rejected > 0) {
-                    throw new Error(`Rejected shared memories: ${response.rejected_sources.join(", ")}`);
+                    throw new Error(`Rejected shared memories: ${response.rejections
+                        .map((rejection) => `${rejection.source}: ${rejection.message}`)
+                        .join(", ")}`);
                 }
                 sharedSignature = loaded.signature;
-                session.recallCache.clear();
+                session.invalidateRecall();
             })().finally(() => {
                 sharedSync = undefined;
             });
             await sharedSync;
         };
-        if (options.warmup !== false) {
+        if (settings.warmup) {
             void Promise.all([native.request("status"), syncSharedMemories()]).catch(session.warnOnce);
         }
         return {
             dispose: async () => {
-                await Promise.all([...session.pendingRecall.keys()].map((sessID) => session.closePendingRecall(sessID, "ignored")));
+                for (const sessID of session.pendingRecall.keys())
+                    session.discardPendingRecall(sessID);
                 session.latestQuery.clear();
-                session.recallCache.clear();
+                session.invalidateRecall();
                 session.pendingRecall.clear();
                 session.sessionParents.clear();
                 session.sessionRoots.clear();
@@ -46,6 +58,7 @@ export function createMemoryPlugin(options) {
                 await native.dispose();
             },
             config: async (config) => {
+                await registerMemoryInstructions(config, memoryInstructions, directory);
                 config.command ??= {};
                 config.command.memory ??= {
                     description: "Inspect and manage project memory",
@@ -64,16 +77,16 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                 }
                 if (event.type === "session.deleted") {
                     const sessID = event.properties.info.id;
-                    await session.closePendingRecall(sessID, "ignored");
+                    session.discardPendingRecall(sessID);
                     session.latestQuery.delete(sessID);
-                    session.recallCache.delete(sessID);
+                    session.invalidateRecall(sessID);
                     session.sessionParents.delete(sessID);
                     session.sessionRoots.delete(sessID);
                     session.sessionAgents.delete(sessID);
                     return;
                 }
                 if (event.type === "session.idle") {
-                    await session.closePendingRecall(event.properties.sessionID, "ignored");
+                    session.discardPendingRecall(event.properties.sessionID);
                     return;
                 }
                 if (event.type === "session.error" && event.properties.sessionID) {
@@ -81,7 +94,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     return;
                 }
                 if (event.type === "file.edited" || event.type === "file.watcher.updated") {
-                    session.recallCache.clear();
+                    session.invalidateRecall();
                     const file = event.properties.file.replaceAll("\\", "/");
                     if (file.includes(`/${SHARED_MEMORY_RELATIVE_DIR}/`)) {
                         sharedSignature = undefined;
@@ -90,6 +103,8 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                 }
                 if (event.type !== "session.compacted")
                     return;
+                if (!settings.automaticCapture)
+                    return;
                 try {
                     const response = await opencode.session.messages({
                         path: { id: event.properties.sessionID },
@@ -107,33 +122,43 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     if (!content)
                         return;
                     const candidates = parseCuratedCandidates(content);
+                    let storedAny = false;
                     for (const candidate of candidates) {
                         try {
-                            await native.request("store", {
-                                ...candidate,
-                                source: `session:${event.properties.sessionID}:compaction`,
-                                scope: "project",
-                                origin: "auto_compaction",
-                                revive: false,
+                            const response = await native.request("capture", {
+                                candidate: {
+                                    ...candidate,
+                                    source: `session:${event.properties.sessionID}:compaction`,
+                                    scope: "project",
+                                    origin: "auto_compaction",
+                                    revive: false,
+                                },
+                                significance: candidate.importance,
+                                impact: candidate.kind === "decision" || candidate.kind === "gotcha" ? 0.8 : 0.6,
+                                rarity: candidate.code_paths.length > 0 ? 0.7 : 0.5,
+                                source_trust: "agent",
+                                has_valid_evidence: candidate.code_paths.length > 0,
+                                suggested_supersession_ids: [],
+                                suggested_conflict_ids: [],
                             });
+                            storedAny ||= response.stored !== undefined;
                         }
                         catch (error) {
                             session.warnOnce(error);
                         }
                     }
-                    if (candidates.length > 0)
-                        session.recallCache.clear();
+                    if (storedAny)
+                        session.invalidateRecall();
                 }
                 catch (error) {
                     session.warnOnce(error);
                 }
             },
             "chat.message": async (input, output) => {
-                await session.closePendingRecall(input.sessionID, "ignored");
-                const query = output.parts
-                    .flatMap((part) => part.type === "text" && !part.synthetic && !part.ignored ? [part.text] : [])
-                    .join("\n")
-                    .trim();
+                session.latestQuery.delete(input.sessionID);
+                session.invalidateRecall(input.sessionID);
+                session.discardPendingRecall(input.sessionID);
+                const query = deriveRecallQuery(output.parts);
                 if (!query)
                     return;
                 if (input.agent)
@@ -142,15 +167,17 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     query: truncateText(query, 2_000),
                     agent: input.agent,
                 });
-                session.recallCache.delete(input.sessionID);
             },
             "experimental.chat.system.transform": async (input, output) => {
-                if (!output.system.some((entry) => entry.includes(MEMORY_POLICY_MARKER))) {
-                    output.system.push(MEMORY_POLICY);
+                if (!output.system.some((entry) => entry.includes(MEMORY_INSTRUCTIONS_MARKER))) {
+                    output.system.push(memoryInstructions.content);
                 }
                 if (!input.sessionID)
                     return;
-                const latest = session.latestQuery.get(input.sessionID);
+                if (!settings.automaticRecall)
+                    return;
+                const sessionID = input.sessionID;
+                const latest = session.latestQuery.get(sessionID);
                 if (!latest)
                     return;
                 try {
@@ -159,33 +186,51 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                 catch (error) {
                     session.warnOnce(error);
                 }
+                if (session.latestQuery.get(input.sessionID) !== latest)
+                    return;
                 const rootSessionID = await session.resolveSessionRoot(input.sessionID);
                 const agent = latest.agent ?? session.sessionAgents.get(input.sessionID) ?? "unknown";
                 const budgetChars = contextBudgetChars(input.model);
+                const recallGeneration = session.recallGeneration(input.sessionID);
                 const cacheKey = [
                     latest.query,
                     rootSessionID,
                     agent,
                     budgetChars,
                     sharedSignature ?? "none",
+                    recallGeneration,
                 ].join("\0");
                 let cached = session.recallCache.get(input.sessionID);
                 if (!cached || cached.key !== cacheKey) {
+                    session.discardPendingRecall(input.sessionID);
+                    if (session.latestQuery.get(input.sessionID) !== latest ||
+                        session.recallGeneration(input.sessionID) !== recallGeneration) {
+                        return;
+                    }
                     try {
-                        const response = await native.request("search", {
-                            query: latest.query,
-                            max_results: 20,
-                            budget_chars: budgetChars,
-                            kinds: [],
-                            scopes: [],
-                            taxonomies: [],
-                            session_scope_key: rootSessionID,
-                            agent_scope_key: agent,
-                            min_score: 0.42,
-                            include_stale: false,
-                            include_superseded: false,
-                            track_feedback: true,
+                        const response = await session.searchRecallOnce(input.sessionID, cacheKey, async () => {
+                            const response = await native.request("search", {
+                                query: latest.query,
+                                max_results: 20,
+                                budget_chars: budgetChars,
+                                kinds: [],
+                                scopes: [],
+                                taxonomies: [],
+                                session_scope_key: rootSessionID,
+                                agent_scope_key: agent,
+                                min_score: settings.minScore,
+                                include_stale: false,
+                                include_superseded: false,
+                                track_feedback: settings.feedbackTracking,
+                            });
+                            for (const warning of response.warnings)
+                                session.warnOnce(new Error(warning));
+                            return response;
                         });
+                        if (session.latestQuery.get(input.sessionID) !== latest ||
+                            session.recallGeneration(input.sessionID) !== recallGeneration) {
+                            return;
+                        }
                         cached = { key: cacheKey, response };
                         session.recallCache.set(input.sessionID, cached);
                     }
@@ -195,15 +240,22 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     }
                 }
                 const formatted = formatRecalledMemories(cached.response, budgetChars);
-                if (!formatted || !cached.response.retrieval_id)
+                if (!formatted)
+                    return;
+                if (!settings.feedbackTracking || !cached.response.retrieval_id) {
+                    output.system.push(formatted.text);
                     return;
-                output.system.push(formatted.text);
+                }
                 const pending = {
                     retrievalID: cached.response.retrieval_id,
                     memoryIDs: formatted.memoryIDs,
                 };
-                await session.recordFeedback(pending, "injected");
-                session.pendingRecall.set(input.sessionID, pending);
+                const opened = await session.openPendingRecall(sessionID, pending, () => {
+                    return (session.latestQuery.get(sessionID) === latest &&
+                        session.recallGeneration(sessionID) === recallGeneration);
+                });
+                if (opened)
+                    output.system.push(formatted.text);
             },
             "experimental.session.compacting": async (_input, output) => {
                 output.context.push(COMPACTION_CONTEXT);
@@ -250,7 +302,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             .number()
                             .min(0)
                             .max(1)
-                            .default(0.42)
+                            .default(settings.minScore)
                             .describe("Minimum calibrated relevance score."),
                         include_stale: tool.schema
                             .boolean()
@@ -262,7 +314,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             .describe("Include historical memories replaced by a successor."),
                     },
                     async execute(args, context) {
-                        await session.closePendingRecall(context.sessionID, "ignored");
+                        session.discardPendingRecall(context.sessionID);
                         await syncSharedMemories();
                         const rootSessionID = await session.resolveSessionRoot(context.sessionID);
                         const response = await native.request("search", {
@@ -277,15 +329,18 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             min_score: args.min_score,
                             include_stale: args.include_stale,
                             include_superseded: args.include_superseded,
-                            track_feedback: true,
+                            track_feedback: settings.feedbackTracking,
                         }, context.abort);
-                        if (response.retrieval_id && response.memories.length > 0) {
+                        for (const warning of response.warnings)
+                            session.warnOnce(new Error(warning));
+                        if (settings.feedbackTracking &&
+                            response.retrieval_id &&
+                            response.memories.length > 0) {
                             const pending = {
                                 retrievalID: response.retrieval_id,
                                 memoryIDs: response.memories.map((memory) => memory.id),
                             };
-                            await session.recordFeedback(pending, "injected");
-                            session.pendingRecall.set(context.sessionID, pending);
+                            await session.openPendingRecall(context.sessionID, pending);
                         }
                         return result("Memory search", response, {
                             count: response.count,
@@ -370,7 +425,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             origin: "manual",
                             source: `session:${context.sessionID}`,
                         }, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result("Stored memory", response, {
                             id: response.id,
                             inserted: response.inserted,
@@ -475,7 +530,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             ? await session.scopeKey(args.scope, context.sessionID, context.agent)
                             : undefined;
                         const response = await native.request("update", { ...args, scope_key: key, ...keys }, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result("Updated memory", response, response);
                     },
                 }),
@@ -489,7 +544,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     async execute(args, context) {
                         const keys = await session.managementScopeKeys(context.sessionID, context.agent);
                         const response = await native.request("pin", { ...args, ...keys }, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result(args.pinned ? "Pinned memory" : "Unpinned memory", response, response);
                     },
                 }),
@@ -507,7 +562,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                         }
                         const keys = await session.managementScopeKeys(context.sessionID, context.agent);
                         const response = await native.request("lock", { ...args, ...keys }, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result(args.lock_action === "lock" ? "Locked memory" : "Unlocked memory", response, response);
                     },
                 }),
@@ -524,15 +579,17 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             .default("user_deleted"),
                     },
                     async execute(args, context) {
+                        const keys = await session.managementScopeKeys(context.sessionID, context.agent);
+                        const records = await native.request("get", { ids: args.ids, ...keys }, context.abort);
+                        validateDeleteRecords(records);
                         await context.ask({
                             permission: "memory_delete",
                             patterns: args.ids,
                             always: [],
                             metadata: { operation: "delete", ...args },
                         });
-                        const keys = await session.managementScopeKeys(context.sessionID, context.agent);
                         const response = await native.request("delete", { ...args, ...keys }, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result("Deleted memories", response, response);
                     },
                 }),
@@ -547,8 +604,9 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                         event: tool.schema.enum(FEEDBACK_EVENTS),
                         memory_ids: tool.schema
                             .array(tool.schema.string().regex(/^mem_[0-9a-f]{32}$/))
+                            .min(1)
                             .max(100)
-                            .default([]),
+                            .describe("Exact recalled memory IDs affected by this feedback."),
                     },
                     async execute(args, context) {
                         const pending = session.pendingRecall.get(context.sessionID);
@@ -593,11 +651,57 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                                 destination,
                             },
                         });
-                        const path = await writeSharedMemory(worktree, memory);
+                        const path = await writeSharedMemory(memoryProjectRoot, memory);
                         await syncSharedMemories(true);
                         return result("Promoted memory", { id: memory.id, path }, { id: memory.id, path });
                     },
                 }),
+                memory_export: tool({
+                    description: "Export visible memories, lifecycle relations, and tombstones as a portable JSON snapshot.",
+                    args: {
+                        include_expired: tool.schema.boolean().default(true),
+                        include_superseded: tool.schema.boolean().default(true),
+                    },
+                    async execute(args, context) {
+                        const keys = await session.managementScopeKeys(context.sessionID, context.agent);
+                        const snapshot = await native.request("export", { ...args, ...keys }, context.abort);
+                        return result("Memory snapshot", snapshot, {
+                            format_version: snapshot.format_version,
+                            source_project_id: snapshot.source_project_id,
+                        });
+                    },
+                }),
+                memory_import: tool({
+                    description: "Import a native-memory JSON snapshot after validating IDs, relations, lifecycle metadata, and content safety.",
+                    args: {
+                        snapshot_json: tool.schema
+                            .string()
+                            .min(2)
+                            .max(4_000_000)
+                            .describe("Exact JSON returned by memory_export."),
+                    },
+                    async execute(args, context) {
+                        let snapshot;
+                        try {
+                            snapshot = JSON.parse(args.snapshot_json);
+                        }
+                        catch (error) {
+                            throw new Error("snapshot_json is not valid JSON", { cause: error });
+                        }
+                        if (typeof snapshot !== "object" || snapshot === null || Array.isArray(snapshot)) {
+                            throw new Error("snapshot_json must contain a snapshot object");
+                        }
+                        await context.ask({
+                            permission: "memory_import",
+                            patterns: ["native-memory-snapshot"],
+                            always: [],
+                            metadata: { operation: "import" },
+                        });
+                        const response = await native.request("import", { snapshot }, context.abort);
+                        session.invalidateRecall();
+                        return result("Imported memory snapshot", response, response);
+                    },
+                }),
                 memory_purge: tool({
                     description: "Delete all local indexed memories for the current project. Shared Markdown files are preserved.",
                     args: {
@@ -615,7 +719,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             metadata: { operation: "purge", ...args },
                         });
                         const response = await native.request("purge", args, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         session.pendingRecall.clear();
                         sharedSignature = undefined;
                         return result("Purged memory", response, response);
@@ -626,7 +730,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     args: {},
                     async execute(_args, context) {
                         const response = await native.request("optimize", {}, context.abort);
-                        session.recallCache.clear();
+                        session.invalidateRecall();
                         return result("Optimized memory", response, response);
                     },
                 }),
@@ -639,6 +743,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                             .describe("Hash all code anchors to detect staleness."),
                     },
                     async execute(args, context) {
+                        await syncSharedMemories();
                         const response = await native.request("doctor", args, context.abort);
                         return result("Memory doctor", response, response);
                     },
@@ -647,6 +752,7 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
                     description: "Inspect the current project's native memory backend, collection, embedding model, indexes, and document count.",
                     args: {},
                     async execute(_args, context) {
+                        await syncSharedMemories();
                         const response = await native.request("status", {}, context.abort);
                         return result("Memory status", response, response);
                     },
@@ -655,6 +761,39 @@ Never modify repository-scoped memory through memory_update; edit its .opencode/
         };
     };
 }
+export function resolveMemoryPluginOptions(options) {
+    const minScore = options.minScore ?? envNumber("OPENCODE_MEMORY_MIN_SCORE", 0.42);
+    if (!Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+        throw new Error("memory minScore must be between 0 and 1");
+    }
+    return {
+        warmup: options.warmup ?? envBoolean("OPENCODE_MEMORY_WARMUP", true),
+        automaticRecall: options.automaticRecall ?? envBoolean("OPENCODE_MEMORY_AUTO_RECALL", true),
+        automaticCapture: options.automaticCapture ?? envBoolean("OPENCODE_MEMORY_AUTO_CAPTURE", true),
+        sharedSync: options.sharedSync ?? envBoolean("OPENCODE_MEMORY_SHARED_SYNC", true),
+        feedbackTracking: options.feedbackTracking ?? envBoolean("OPENCODE_MEMORY_FEEDBACK_TRACKING", true),
+        minScore,
+    };
+}
+function envBoolean(name, fallback) {
+    const value = process.env[name];
+    if (value === undefined || value === "")
+        return fallback;
+    if (["1", "true", "yes", "on"].includes(value.toLowerCase()))
+        return true;
+    if (["0", "false", "no", "off"].includes(value.toLowerCase()))
+        return false;
+    throw new Error(`${name} must be a boolean`);
+}
+function envNumber(name, fallback) {
+    const value = process.env[name];
+    if (value === undefined || value === "")
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${name} must be a finite number`);
+    return parsed;
+}
 function result(title, value, metadata) {
     return {
         title,