opencode-codex-memory 0.5.0 → 0.6.0

package/README.md

@@ -52,7 +52,7 @@ If you want the mental model before the details, jump to
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.5.0"]
+  "plugin": ["opencode-codex-memory@0.6.0"]
 }
 ```
 
@@ -191,6 +191,20 @@ them — it's yours. (The `memories/` folder also holds a few working files and
 an internal `.git/` the plugin uses for change tracking; `memory_reset` wipes
 those too.)
 
+### Backup and restore
+
+Back up the whole OpenCode data directory while OpenCode is stopped. The
+SQLite database and `memories/` workspace are a pair: restoring only one can
+leave job state, Git baseline, and memory files out of sync. Include hidden
+files, especially `memories/.git/`, and SQLite sidecars such as `memory.db-wal`
+or `memory.db-shm` when present.
+
+The directory is `$XDG_DATA_HOME/opencode` when `XDG_DATA_HOME` is set,
+otherwise `~/.local/share/opencode`. Copy that whole directory to a dated
+backup location. To restore, stop OpenCode, replace the current `opencode/`
+data directory with the backup copy, then start OpenCode again. Do not restore
+while OpenCode is running or copy only `memory.db` or only `memories/`.
+
 ## Privacy & safety
 
 - **Local only.** There is no remote storage option to enable, by accident or
@@ -240,7 +254,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.5.0", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.6.0", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -302,7 +316,7 @@ Off by default; no changes to Codex's own config are required.
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.5.0",
+      "opencode-codex-memory@0.6.0",
       { "codex_interop": { "import": true, "export": true } }
     ]
   ]
@@ -359,7 +373,7 @@ from the project memories Claude already keeps on your machine. **One-way only**
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.5.0", { "claude_import": { "enabled": true } }]
+    ["opencode-codex-memory@0.6.0", { "claude_import": { "enabled": true } }]
   ]
 }
 ```
@@ -386,7 +400,7 @@ Claude names each project with an opaque id (a folder under
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.5.0",
+      "opencode-codex-memory@0.6.0",
       {
         "claude_import": {
           "enabled": true,
@@ -475,6 +489,7 @@ It reports:
 - phase-2 status / last error / cooldown
 - last session-discovery outcome
 - effective options (after clamping) and config warnings
+- effective memory-agent health, including user overrides and required permissions
 - a short eligibility reminder (`min_rollout_idle_hours`, default **6h**)
 
 Common causes:

package/dist/src/agent-health.d.ts

@@ -0,0 +1,21 @@
+declare const AGENT_NAMES: readonly ["memorize", "memorize-extract"];
+type AgentName = (typeof AGENT_NAMES)[number];
+export interface AgentHealthEntry {
+    source: "shipped" | "user_override" | "missing";
+    healthy: boolean;
+    issues: string[];
+}
+export interface AgentHealthSnapshot {
+    observed: boolean;
+    generationEnabled: boolean | null;
+    agents: Record<AgentName, AgentHealthEntry>;
+}
+export declare function loadBundledAgentDefinitions(): Record<string, unknown>;
+/** Record the effective agent config after the plugin config hook runs. */
+export declare function recordAgentConfig(config: {
+    agent?: Record<string, unknown>;
+}, generationEnabled: boolean, shipped: Record<string, unknown>): void;
+export declare function getAgentHealth(): AgentHealthSnapshot;
+/** Test seam and boot boundary. */
+export declare function resetAgentHealth(): void;
+export {};

package/dist/src/agent-health.js

@@ -0,0 +1,133 @@
+import fs from "fs";
+import path from "path";
+import { memoryRoot } from "./paths.js";
+const AGENT_NAMES = ["memorize", "memorize-extract"];
+const REQUIRED_ALLOWS = {
+    memorize: ["read", "edit", "write", "glob", "grep"],
+    "memorize-extract": ["StructuredOutput"],
+};
+const SAFE_ALLOWS = {
+    memorize: new Set(["read", "edit", "write", "glob", "grep", "external_directory"]),
+    "memorize-extract": new Set(["StructuredOutput"]),
+};
+const initialEntry = () => ({ source: "missing", healthy: false, issues: ["config hook has not run"] });
+let snapshot = {
+    observed: false,
+    generationEnabled: null,
+    agents: {
+        memorize: initialEntry(),
+        "memorize-extract": initialEntry(),
+    },
+};
+export function loadBundledAgentDefinitions() {
+    const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
+    return JSON.parse(raw).agent ?? {};
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hasNonDenyAction(value) {
+    const rules = asRecord(value);
+    return rules ? Object.values(rules).some((action) => action !== "deny") : value !== "deny";
+}
+/** Structural compare — config reload re-parses shipped defs into new objects. */
+function definitionsEqual(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function permissionIssues(name, definition) {
+    const issues = [];
+    const record = asRecord(definition);
+    if (record?.mode !== "subagent")
+        issues.push("agent mode must be 'subagent'");
+    const permission = asRecord(record?.permission);
+    if (!permission) {
+        issues.push("missing permission map");
+        return issues;
+    }
+    const keys = Object.keys(permission);
+    if (keys[0] !== "*")
+        issues.push("permission wildcard '*' must be the first rule");
+    if (permission["*"] !== "deny")
+        issues.push("permission wildcard '*' must be 'deny'");
+    for (const toolName of REQUIRED_ALLOWS[name]) {
+        if (permission[toolName] !== "allow") {
+            issues.push(`required permission '${toolName}: allow' is missing`);
+        }
+    }
+    for (const [toolName, value] of Object.entries(permission)) {
+        if (toolName === "*")
+            continue;
+        if (!SAFE_ALLOWS[name].has(toolName)) {
+            if (hasNonDenyAction(value))
+                issues.push(`unexpected permission '${toolName}' must be denied`);
+        }
+    }
+    if (name === "memorize") {
+        const external = asRecord(permission.external_directory);
+        const expectedPath = path.join(memoryRoot(), "*");
+        if (external?.[expectedPath] !== "allow") {
+            issues.push(`consolidator must allow external_directory '${expectedPath}'`);
+        }
+        if (external) {
+            for (const [grantedPath, action] of Object.entries(external)) {
+                if (grantedPath === expectedPath)
+                    continue;
+                if (hasNonDenyAction(action)) {
+                    issues.push(`consolidator must deny extra external_directory '${grantedPath}'`);
+                }
+            }
+        }
+    }
+    else if (permission.external_directory !== undefined) {
+        issues.push("extractor must not have external_directory access");
+    }
+    return issues;
+}
+function inspectAgent(name, definition, source) {
+    const issues = permissionIssues(name, definition);
+    return { source, healthy: issues.length === 0, issues };
+}
+/** Record the effective agent config after the plugin config hook runs. */
+export function recordAgentConfig(config, generationEnabled, shipped) {
+    const configured = asRecord(config.agent);
+    const agents = {};
+    for (const name of AGENT_NAMES) {
+        const definition = configured?.[name];
+        const source = definition === undefined
+            ? "missing"
+            : definitionsEqual(shipped[name], definition)
+                ? "shipped"
+                : "user_override";
+        agents[name] = inspectAgent(name, definition, source);
+        if (!generationEnabled && definition === undefined) {
+            agents[name] = { source: "missing", healthy: true, issues: ["generation disabled; agent not injected"] };
+        }
+    }
+    snapshot = { observed: true, generationEnabled, agents };
+}
+export function getAgentHealth() {
+    return {
+        observed: snapshot.observed,
+        generationEnabled: snapshot.generationEnabled,
+        agents: {
+            memorize: { ...snapshot.agents.memorize, issues: [...snapshot.agents.memorize.issues] },
+            "memorize-extract": { ...snapshot.agents["memorize-extract"], issues: [...snapshot.agents["memorize-extract"].issues] },
+        },
+    };
+}
+/** Test seam and boot boundary. */
+export function resetAgentHealth() {
+    snapshot = {
+        observed: false,
+        generationEnabled: null,
+        agents: {
+            memorize: initialEntry(),
+            "memorize-extract": initialEntry(),
+        },
+    };
+}

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 import { MemoryStore } from "./store.js";
 import type { PluginInput, PluginOptions } from "@opencode-ai/plugin";
+/** Test seam: wait for all hook-launched work, including follow-up phase 2. */
+export declare function waitForBackgroundTasks(): Promise<void>;
 export declare function takeNewCitations(partKey: string, ids: string[]): string[];
 export declare function markTurnSeen(sessionId: string): boolean;
 export declare function shouldHandleIdle(sessionId: string, now?: number): boolean;
@@ -58,11 +60,13 @@ declare const _default: {
                 description: string;
                 args: {
                     path: import("zod").ZodDefault<import("zod").ZodString>;
+                    cursor: import("zod").ZodOptional<import("zod").ZodString>;
                     max_results: import("zod").ZodDefault<import("zod").ZodNumber>;
                 };
                 execute(args: {
                     path: string;
                     max_results: number;
+                    cursor?: string | undefined;
                 }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
             };
             memory_add_note: {

package/dist/src/index.js

@@ -11,10 +11,26 @@ import { pluginOptions, recordConfigWarning, clearConfigWarnings, resetPluginOpt
 import { beginPluginShutdown, isPluginShuttingDown, resetPluginLifecycle } from "./lifecycle.js";
 import { hostMcpStatus } from "./host-client.js";
 import { recordDiagnostic } from "./diagnostics.js";
-import fs from "fs";
+import { loadBundledAgentDefinitions, recordAgentConfig, resetAgentHealth } from "./agent-health.js";
 import path from "path";
 let phase1InFlight = false;
 let pluginClient = null;
+const backgroundTasks = new Set();
+function trackBackgroundTask(task) {
+    // Hooks must remain non-blocking, but test teardown needs a way to wait until
+    // work started by a hook has released its DB handle.
+    const tracked = task.catch((err) => {
+        console.error("[opencode-codex-memory] background task error:", err);
+    });
+    backgroundTasks.add(tracked);
+    void tracked.then(() => backgroundTasks.delete(tracked));
+}
+/** Test seam: wait for all hook-launched work, including follow-up phase 2. */
+export async function waitForBackgroundTasks() {
+    while (backgroundTasks.size > 0) {
+        await Promise.all([...backgroundTasks]);
+    }
+}
 // Single-flight guard for mcp.status(); see mcpToolPrefixes below.
 let mcpStatusInFlight = null;
 const MCP_STATUS_TIMEOUT_MS = 1_000;
@@ -83,7 +99,7 @@ export function handleSessionDeleted(sessionId, store = getStore(),
 // enqueued job runs when generation is re-enabled (codex: delete only
 // enqueues; the pipeline itself is gated elsewhere).
 schedulePhase2 = () => { if (pluginOptions.generate_memories)
-    void triggerPhase2(); }) {
+    trackBackgroundTask(triggerPhase2()); }) {
     if (store.deleteSessionMemory(sessionId))
         schedulePhase2();
 }
@@ -94,6 +110,7 @@ export default {
         resetPluginLifecycle();
         setPluginInput(input);
         pluginClient = input.client;
+        resetAgentHealth();
         mcpStatusInFlight = null;
         // Unconditional, like the caches above: a boot WITHOUT options must not
         // inherit the previous boot's warnings (opencode can host several
@@ -320,8 +337,7 @@ async function classifyExternalContextTool(toolName) {
 export function injectAgentDefinitions(config) {
     let defs;
     try {
-        const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
-        defs = JSON.parse(raw).agent ?? {};
+        defs = loadBundledAgentDefinitions();
     }
     catch (err) {
         console.warn("[opencode-codex-memory] could not load bundled agent definitions:", err);
@@ -339,6 +355,7 @@ export function injectAgentDefinitions(config) {
         if (!config.agent[name])
             config.agent[name] = def;
     }
+    recordAgentConfig(config, true, defs);
 }
 function buildHooks() {
     const base = {
@@ -346,8 +363,15 @@ function buildHooks() {
             try {
                 // The write pipeline is the only consumer of the sub-agents; with
                 // generation off they would just pollute the user's agent list.
-                if (!pluginOptions.generate_memories)
+                if (!pluginOptions.generate_memories) {
+                    try {
+                        recordAgentConfig(input, false, loadBundledAgentDefinitions());
+                    }
+                    catch (err) {
+                        console.warn("[opencode-codex-memory] could not inspect bundled agent definitions:", err);
+                    }
                     return;
+                }
                 injectAgentDefinitions(input);
             }
             catch (err) {
@@ -450,7 +474,7 @@ function buildHooks() {
                 catch (e) {
                     console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
                 }
-                void triggerPhase1(sid);
+                trackBackgroundTask(triggerPhase1(sid));
             }
             catch (err) {
                 console.error("[opencode-codex-memory] chat.message error:", err);
@@ -578,7 +602,7 @@ function buildHooks() {
         catch (e) {
             console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
         }
-        void triggerPhase1(sid);
+        trackBackgroundTask(triggerPhase1(sid));
     }
     // Control tools (reset/inspect/mode) are always available. The memory
     // read/search/list/add-note tools require BOTH use_memories and
@@ -622,7 +646,7 @@ async function triggerPhase1(currentSessionId) {
     finally {
         phase1InFlight = false;
     }
-    void triggerPhase2();
+    trackBackgroundTask(triggerPhase2());
 }
 async function triggerPhase2() {
     if (isPluginShuttingDown())

package/dist/tools/control.js

@@ -12,6 +12,7 @@ import { codexInteropMtimes, resolveCodexInterop } from "../src/codex-interop.js
 import { claudeImportStatus, resolveClaudeHome } from "../src/claude-import.js";
 import { formatDiagnosticLine, getDiscoveryStatus, getRecentDiagnostics, } from "../src/diagnostics.js";
 import { isPluginShuttingDown } from "../src/lifecycle.js";
+import { getAgentHealth } from "../src/agent-health.js";
 function isSymlinkedRoot() {
     try {
         assertMemoryRootSafe();
@@ -137,6 +138,18 @@ function listMemoriesDir() {
     walk(root, "");
     return out;
 }
+function renderAgentHealth() {
+    const health = getAgentHealth();
+    const lines = [
+        `agent_config: ${health.observed ? "observed" : "not observed (config hook has not run)"}`,
+        `agent_generation_enabled: ${health.generationEnabled ?? "unknown"}`,
+    ];
+    for (const name of ["memorize", "memorize-extract"]) {
+        const entry = health.agents[name];
+        lines.push(`  agent_${name}: source=${entry.source} status=${entry.healthy ? "healthy" : "degraded"}`, ...entry.issues.map((issue) => `    issue: ${issue}`));
+    }
+    return lines;
+}
 export const memory_reset = tool({
     description: "Reset all persistent memory. Wipes the plugin's extracted memories and jobs tables and the entire " +
         "contents of the memories directory (including git history). Per-session memory modes are preserved, " +
@@ -264,6 +277,8 @@ export const memory_inspect = tool({
                 "",
                 ...renderEffectiveConfig(),
                 "",
+                ...renderAgentHealth(),
+                "",
                 ...diagnosticLines,
                 "",
                 "Files:",
@@ -298,6 +313,7 @@ export const memory_inspect = tool({
                         },
                     },
                     config_warnings: [...getConfigWarnings()],
+                    agent_health: getAgentHealth(),
                     recent_events: diagnostics,
                 },
             };

package/dist/tools/memory.d.ts

@@ -15,11 +15,13 @@ export declare const memory_list: {
     description: string;
     args: {
         path: import("zod").ZodDefault<import("zod").ZodString>;
+        cursor: import("zod").ZodOptional<import("zod").ZodString>;
         max_results: import("zod").ZodDefault<import("zod").ZodNumber>;
     };
     execute(args: {
         path: string;
         max_results: number;
+        cursor?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
 };
 export declare const memory_search: {

package/dist/tools/memory.js

@@ -92,15 +92,23 @@ function visibleEntries(dir) {
     return out;
 }
 const LIST_MAX_RESULTS = 2000;
+// Codex sorts paths lexically (`Path` ordering), not with locale collation.
+// Keep ordering stable across hosts and match ASCII path ordering.
+function comparePathNames(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
 export const memory_list = tool({
     description: "List the immediate entries of a directory in the persistent memory workspace, sorted by name, " +
-        "with entry types. Hidden files and symlinks are skipped. Use path '' (empty) for the memory root.",
+        "with entry types. Hidden files and symlinks are skipped. Supports cursor pagination and listing " +
+        "a single file. Use path '' (empty) for the memory root.",
     args: {
         path: tool.schema.string().default("").describe("Relative directory path inside the memory workspace ('' for the root)."),
+        cursor: tool.schema.string().optional().describe("Pagination cursor from a previous response's next_cursor."),
         max_results: tool.schema.number().int().min(1).max(LIST_MAX_RESULTS).default(LIST_MAX_RESULTS).describe("Maximum entries to return."),
     },
     async execute(args) {
         try {
+            const root = assertMemoryRootSafe();
             const fullPath = safeResolveMemoryPath(args.path || ".");
             if (!fs.existsSync(fullPath))
                 return { output: `Not found: ${args.path}` };
@@ -111,19 +119,49 @@ export const memory_list = tool({
             if (st.isSymbolicLink()) {
                 return { output: `memory_list error: symlinks are not allowed in the memory workspace: ${args.path}` };
             }
-            if (!st.isDirectory())
-                return { output: `memory_list error: not a directory: ${args.path}` };
-            const entries = visibleEntries(fullPath).sort((a, b) => a.name.localeCompare(b.name));
-            const truncated = entries.length > args.max_results;
-            const shown = entries.slice(0, args.max_results);
-            const prefix = args.path ? `${args.path.replace(/\/+$/, "")}/` : "";
-            const listing = shown.map((e) => ({ path: `${prefix}${e.name}`, entry_type: e.isDir ? "directory" : "file" }));
-            if (listing.length === 0)
-                return { output: `Directory ${args.path || "."} is empty.` };
+            const entries = st.isFile()
+                ? [{ path: path.relative(root, fullPath).split(path.sep).join("/"), entry_type: "file" }]
+                : st.isDirectory()
+                    ? visibleEntries(fullPath)
+                        .sort((a, b) => comparePathNames(a.name, b.name))
+                        .map((e) => ({
+                        path: path.relative(root, path.join(fullPath, e.name)).split(path.sep).join("/"),
+                        entry_type: e.isDir ? "directory" : "file",
+                    }))
+                    : [];
+            let startIndex = 0;
+            if (args.cursor !== undefined) {
+                if (!/^\d+$/.test(args.cursor)) {
+                    return { output: `memory_list error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                }
+                startIndex = Number(args.cursor);
+                if (!Number.isSafeInteger(startIndex)) {
+                    return { output: `memory_list error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                }
+            }
+            if (startIndex > entries.length) {
+                return { output: `memory_list error: cursor ${args.cursor} exceeds result count ${entries.length}.` };
+            }
+            const maxResults = args.max_results ?? LIST_MAX_RESULTS;
+            const endIndex = Math.min(startIndex + maxResults, entries.length);
+            const nextCursor = endIndex < entries.length ? String(endIndex) : null;
+            const truncated = nextCursor !== null;
+            const listing = entries.slice(startIndex, endIndex);
+            if (listing.length === 0) {
+                const output = st.isDirectory()
+                    ? entries.length === 0
+                        ? `Directory ${args.path || "."} is empty.`
+                        : `No entries at cursor ${startIndex} for directory ${args.path || "."}.`
+                    : "";
+                return {
+                    output,
+                    metadata: { path: args.path, entries: [], next_cursor: nextCursor, truncated },
+                };
+            }
             return {
                 output: listing.map((e) => `${e.entry_type === "directory" ? "d" : "f"} ${e.path}`).join("\n") +
-                    (truncated ? `\n[truncated: ${entries.length - args.max_results} more entries]` : ""),
-                metadata: { path: args.path, entries: listing, truncated },
+                    (truncated ? `\n[truncated: ${entries.length - endIndex} more entries; pass cursor=${nextCursor}]` : ""),
+                metadata: { path: args.path, entries: listing, next_cursor: nextCursor, truncated },
             };
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Persistent memory plugin for opencode — ports codex's two-phase memory system (extraction → consolidation → injection → citation feedback)",
   "type": "module",
   "main": "./dist/src/index.js",