opencode-codex-memory 0.2.0 → 0.3.0

package/README.md

@@ -52,8 +52,8 @@ anything.
    immediately (codex ships the same system behind a default-off feature flag
    with a consent prompt; a standalone memory plugin *is* the consent).
 
-Requires only opencode (official release). Git is bundled (`isomorphic-git`) —
-no `git` binary or any other external tool needed.
+Requires opencode 1.18 or newer (official release). Git is bundled
+(`isomorphic-git`) — no `git` binary or any other external tool needed.
 
 The two restricted sub-agents that do the background learning (`memorize`,
 `memorize-extract`) register themselves automatically while background learning
@@ -95,7 +95,7 @@ echo 'I prefer TypeScript strict mode and 2-space indentation.' \
 
 ```
 ~/.local/share/opencode/
-├── memory.db                       # the plugin's own database (opencode's is only ever read)
+├── memory.db                       # the plugin's own database (opencode's data is only accessed via its API)
 └── memories/
     ├── memory_summary.md           # compact summary injected into the system prompt
     ├── MEMORY.md                   # searchable index of everything learned
@@ -117,8 +117,10 @@ those too.)
   session transcripts and extracted memories before anything is written or sent
   to a model. Notes you explicitly dictate ("remember that ...") are stored as
   you said them.
-- **The learning agents are sandboxed** — every tool except reading and editing
-  the memory files is denied, including shell and network access.
+- **The learning agents are sandboxed** — the extraction agent can't touch your
+  filesystem (the transcript is handed to it inline; it only emits its structured
+  result), and the consolidation agent gets only file tools plus access to the
+  memory folder. Shell, network, IDE, and MCP tools are denied for both.
 - **Reset is safe.** `memory_reset` refuses to run if the memory folder is a
   symlink, so it can't be tricked into deleting something else.
 - **Web/MCP sessions:** by default, sessions that used web search, fetch, or MCP
@@ -196,6 +198,17 @@ explicitly, so they win over an agent-level `model`.
 ## Under the hood
 
 opencode-codex-memory is a faithful port of the memory system from OpenAI's codex.
+
+One design choice is worth calling out, because it shapes everything else: **memory
+is global.** There's a single store for all your work, not one per project. That's
+not an accident of the port — it's codex's own hard-won shape. codex *started* with
+per-project memory (a separate bucket per directory, plus a user scope) and
+**deliberately removed it** in early 2026, collapsing everything into one global
+root for simplicity: one store, one lock, one consolidation pass. Project awareness
+didn't disappear — it moved out of storage and into the prompt, as soft "this looks
+like it belongs to that project" hints rather than hard partitions. This port
+mirrors that exactly.
+
 If you want to understand the design, the trade-offs, or contribute, see
 [`ARCHITECTURE.md`](./ARCHITECTURE.md). Contributor guidance lives in
 [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`AGENTS.md`](./AGENTS.md) —

package/dist/opencode.json

@@ -32,7 +32,8 @@
         "write": "deny",
         "edit": "deny",
         "glob": "deny",
-        "grep": "deny"
+        "grep": "deny",
+        "StructuredOutput": "allow"
       }
     }
   }

package/dist/src/capture.js

@@ -49,8 +49,10 @@ export async function listRecentSessions(limit = SCAN_LIMIT) {
             continue;
         try {
             const res = await withTimeout(client.session.list({
-                // scope/roots/limit are in the server's ListQuery since 1.17; the
-                // pinned SDK types lag behind, hence the cast at the call site.
+                // scope/roots/limit are in the server's ListQuery (accepted since
+                // opencode 1.14.30, well under our 1.18 floor); the pinned SDK types
+                // still omit them (SessionListData.query is just { directory } as of
+                // 1.18.1), hence the cast at the call site.
                 query: { directory: project.worktree, scope: "project", roots: true, limit },
             }), API_TIMEOUT_MS, "session.list");
             if (!res || res.error || !Array.isArray(res.data))

package/dist/src/llm.d.ts

@@ -17,5 +17,14 @@ export declare function consolidateViaSubagent(memoryRoot: string, diffFileName:
 export declare function cleanupOldSubSessions(maxAgeMinutes?: number): Promise<void>;
 export declare function fillTemplate(tmpl: string, vars: Record<string, string>): string;
 export declare function buildConsolidationPrompt(memoryRoot: string, diffFileName: string): string;
-/** Parses the stage-1 JSON output. Returns null for the all-empty no-op response. */
+/**
+ * Validates a parsed stage-1 object into an ExtractionResult, or null for the
+ * all-empty no-op. Shared by the structured-output path (AssistantMessage.
+ * structured) and the text parser below.
+ */
+export declare function validateExtraction(obj: Partial<ExtractionResult>): ExtractionResult | null;
+/**
+ * Parses stage-1 JSON from assistant text. Fallback for when structured output
+ * is unavailable; the primary path reads AssistantMessage.structured directly.
+ */
 export declare function parseExtraction(raw: string): ExtractionResult | null;

package/dist/src/llm.js

@@ -63,7 +63,8 @@ function parseModelRef(ref) {
         return null;
     return { providerID: ref.slice(0, slash), modelID: ref.slice(slash + 1) };
 }
-async function promptSession(sessionId, prompt, agent, opts = {}) {
+/** Runs a sub-agent prompt and returns the raw response data (`{ info, parts }`). */
+async function runPrompt(sessionId, prompt, agent, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 300_000;
     const input = getPluginInput();
     if (!input)
@@ -71,10 +72,13 @@ async function promptSession(sessionId, prompt, agent, opts = {}) {
     const model = opts.model ? parseModelRef(opts.model) : null;
     const promptPromise = input.client.session.prompt({
         path: { id: sessionId },
+        // `format` lives in the server's PromptInput but not the generated SDK body
+        // type yet (same OpenAPI lag as session.list scope/roots), hence the cast.
         body: {
             agent,
             ...(opts.system ? { system: opts.system } : {}),
             ...(model ? { model } : {}),
+            ...(opts.format ? { format: opts.format } : {}),
             parts: [{ type: "text", text: prompt }],
         },
     });
@@ -88,12 +92,15 @@ async function promptSession(sessionId, prompt, agent, opts = {}) {
         ]);
         if (!res.data)
             throw new Error(`prompt failed: ${JSON.stringify(res.error ?? {})}`);
-        return extractAssistantText(res.data);
+        return res.data;
     }
     finally {
         clearTimeout(timer);
     }
 }
+async function promptSession(sessionId, prompt, agent, opts = {}) {
+    return extractAssistantText(await runPrompt(sessionId, prompt, agent, opts));
+}
 function extractAssistantText(body) {
     if (!body)
         return "";
@@ -116,6 +123,19 @@ function extractAssistantText(body) {
         return body.output;
     return JSON.stringify(body);
 }
+// JSON Schema for structured stage-1 output. Mirrors the deliverables in
+// stage_one_system.md (three required string fields; all-empty = no-op) and is
+// opencode's equivalent of codex's output_schema + output_schema_strict.
+const EXTRACTION_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        raw_memory: { type: "string" },
+        rollout_summary: { type: "string" },
+        rollout_slug: { type: "string" },
+    },
+    required: ["raw_memory", "rollout_summary", "rollout_slug"],
+};
 /** Returns null when the extractor reported a no-op (nothing worth remembering). */
 export async function extractViaSubagent(sessionId, transcript, opts = {}) {
     const agent = "memorize-extract";
@@ -124,15 +144,27 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
         const prompt = buildExtractionInput(sessionId, opts.cwd ?? "unknown", transcript);
         // extract_model option > opencode small_model > session default.
         const model = opts.model ?? (await getConfigModels()).smallModel;
-        const raw = await promptSession(subId, prompt, agent, {
+        const data = await runPrompt(subId, prompt, agent, {
             // Mirrors the stage-1 job lease (1h): codex has no per-request timeout,
             // and a near-600k-char transcript on a slow model can easily exceed a
             // short one — repeated timeouts would exhaust the job's retries.
             timeoutMs: 3600_000,
             system: readTemplate("stage_one_system.md"),
             model,
+            // opencode enforces json_schema output via a forced StructuredOutput tool
+            // call (toolChoice: required) — which is why memorize-extract must allow
+            // that one otherwise-denied tool.
+            format: { type: "json_schema", schema: EXTRACTION_SCHEMA },
         });
-        return parseExtraction(raw);
+        // The captured JSON lands on AssistantMessage.structured (schema
+        // v1/session.ts; absent from the generated SDK type, so read it untyped).
+        // Fall back to text parsing when structured output is unavailable (a host
+        // without the feature, or a model that emitted JSON as plain text).
+        const structured = data?.info?.structured;
+        if (structured && typeof structured === "object") {
+            return validateExtraction(structured);
+        }
+        return parseExtraction(extractAssistantText(data));
     }
     finally {
         void deleteSession(subId).catch(() => { });
@@ -257,16 +289,12 @@ export function buildConsolidationPrompt(memoryRoot, diffFileName) {
 function readTemplate(name) {
     return fs.readFileSync(path.join(import.meta.dirname, "templates", name), "utf8");
 }
-/** Parses the stage-1 JSON output. Returns null for the all-empty no-op response. */
-export function parseExtraction(raw) {
-    const cleaned = raw.replace(/^```(?:json)?/gim, "").replace(/```$/gim, "").trim();
-    const start = cleaned.indexOf("{");
-    const end = cleaned.lastIndexOf("}");
-    if (start === -1 || end === -1 || end <= start) {
-        throw new Error("extraction response contained no JSON object");
-    }
-    const json = cleaned.slice(start, end + 1);
-    const obj = JSON.parse(json);
+/**
+ * Validates a parsed stage-1 object into an ExtractionResult, or null for the
+ * all-empty no-op. Shared by the structured-output path (AssistantMessage.
+ * structured) and the text parser below.
+ */
+export function validateExtraction(obj) {
     if (typeof obj.raw_memory !== "string" || typeof obj.rollout_summary !== "string") {
         throw new Error("extraction response missing required fields");
     }
@@ -289,3 +317,16 @@ export function parseExtraction(raw) {
         rollout_slug: typeof obj.rollout_slug === "string" && obj.rollout_slug.trim() ? obj.rollout_slug : null,
     };
 }
+/**
+ * Parses stage-1 JSON from assistant text. Fallback for when structured output
+ * is unavailable; the primary path reads AssistantMessage.structured directly.
+ */
+export function parseExtraction(raw) {
+    const cleaned = raw.replace(/^```(?:json)?/gim, "").replace(/```$/gim, "").trim();
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start) {
+        throw new Error("extraction response contained no JSON object");
+    }
+    return validateExtraction(JSON.parse(cleaned.slice(start, end + 1)));
+}

package/opencode.json

@@ -32,7 +32,8 @@
         "write": "deny",
         "edit": "deny",
         "glob": "deny",
-        "grep": "deny"
+        "grep": "deny",
+        "StructuredOutput": "allow"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -45,7 +45,7 @@
   ],
   "license": "Apache-2.0",
   "dependencies": {
-    "@opencode-ai/plugin": "^1.17.13",
+    "@opencode-ai/plugin": "^1.18.0",
     "diff": "^9.0.0",
     "isomorphic-git": "^1.38.6"
   },