opencode-codex-memory 0.6.3 → 0.6.5

package/README.md

@@ -48,55 +48,33 @@ If you want the mental model before the details, jump to
 
 ## Install
 
-1. Add the plugin to your `~/.config/opencode/opencode.json`:
+**1. Add the plugin** to your `~/.config/opencode/opencode.json`:
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.6.3"]
+  "plugin": ["opencode-codex-memory@0.6.5"]
 }
 ```
 
-   **Pin the version** (here and for any OpenCode plugin). OpenCode installs a
-   plugin spec once into its package cache and never re-resolves it, so a bare
-   `"opencode-codex-memory"` is not "always latest" — it freezes at whatever
-   was latest the first time OpenCode started. With a version tag you decide
-   which release runs, and bumping the tag installs the new one. Check
-   [npm](https://www.npmjs.com/package/opencode-codex-memory) for the current
-   version.
-
-   Since updating is then just editing version numbers, it's worth automating
-   with a custom command — one that reads your `opencode.json`, compares each
-   pin against npm, and rewrites the ones you confirm. If you'd rather not
-   write your own, this repo has one you can copy:
-   [`docs/commands/update-plugins.md`](./docs/commands/update-plugins.md) →
-   `~/.config/opencode/command/update-plugins.md`, then run `/update-plugins`.
-   It's documentation, not part of the package: nothing about it is installed
-   with the plugin, and it works for every pinned plugin in your config, not
-   just this one.
-
-   (While developing locally, point it at an absolute path to your checkout
-   instead of the package name.)
-
-2. That's it. The memory workspace is created on first use. Installing the
-   plugin is the opt-in: background learning and summary injection are active
-   immediately (Codex ships the same system behind a default-off feature flag
-   with a consent prompt; a standalone memory plugin *is* the consent).
-
-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
-is enabled. To choose which models
-they use, set the `extract_model` / `consolidation_model` plugin options (see
-[Configuration](#configuration)) — don't override the agents for that. Defining
-an agent with the same name in your own config is only for advanced tweaks
-(e.g. permissions); your definition then replaces the shipped one. If you
-override `memorize`, keep an `external_directory` allow for
-`~/.local/share/opencode/memories/*` (e.g.
-`"external_directory": { "$HOME/.local/share/opencode/memories/*": "allow" }`
-after the wildcard deny) — the memory folder lives outside your project, and
-without that grant OpenCode blocks the consolidator's file access.
+Pin the version — OpenCode installs a plugin spec once and never re-resolves
+it, so a bare `"opencode-codex-memory"` is not "always latest". Check
+[npm](https://www.npmjs.com/package/opencode-codex-memory) for the current
+version.
+
+**2. That's it.** The memory workspace is created on first use; background
+learning starts immediately.
+
+Requires OpenCode 1.18 or newer. Models and other options: see
+[Configuration](#configuration).
+
+### Installation hints
+
+To bump pins, copy
+[`docs/commands/update-plugins.md`](./docs/commands/update-plugins.md) to
+`~/.config/opencode/command/update-plugins.md` and run `/update-plugins`.
+This command is not part of the plugin package — nothing about it is
+installed with the plugin. It works for every pinned plugin in your config,
+not just this one.
 
 ## Try it
 
@@ -123,51 +101,20 @@ echo 'I prefer TypeScript strict mode and 2-space indentation.' \
 
 ## How it works
 
-You don't need to know any of this to use the plugin. The design is Codex's,
-ported as-is, and it does what any memory system has to do: decide what's worth
-keeping, write it down so it can be found again, surface the right piece at the
-right moment, and forget what stopped being useful.
-
-Think of it as three jobs: two background writers and one reader. **Nothing here
-runs while you're waiting for a reply** — an assistant that stops to take notes
-mid-answer would be slower and more expensive, so the learning happens after the
-fact, on transcripts of conversations that are already over.
-
-**Phase 1 — read one finished session, write notes about it.** Once a
-conversation has been idle long enough that it's clearly done (default 6 h), the
-plugin fetches that transcript, strips secrets out of it, and hands it to a
-cheap model with one question: *what from this is worth keeping?* The answer
-comes back as structured data — a detailed note plus a short recap of the
-session — and lands in a local SQLite database. One session in, one record out.
-Sessions are independent, so this part is easy to parallelize and to retry when
-it fails.
-
-**Phase 2 — merge all those notes into one memory.** Every few hours at most
-(and only one run at a time across all your OpenCode windows), a second pass
-takes the most relevant per-session notes and rewrites the actual memory files:
-`MEMORY.md` as the full index, `memory_summary.md` as the short version, and
-`skills/` for procedures worth repeating. This is where the interesting work
-happens — ten similar observations collapse into one rule, contradictions get
-resolved, and notes nothing ever used age out. Forgetting is a feature: memory
-that only grows is memory that stops being useful.
-
-The split exists because the two halves have opposite needs. Phase 1 is
-per-session and can run many at once; phase 2 touches the single shared memory,
-so it has to be serialized. Keeping them apart means one slow or failing session
-extraction can't corrupt or block the shared store.
-
-**The read path — actually remembering.** Every turn, the short summary is
-appended to the system prompt (capped at ~2500 tokens, so the cost is small and
-predictable). That's the always-on layer. When a task looks related to past
-work, the agent goes further and searches the full memory itself with the
-`memory_*` tools — the equivalent of "I've seen this before, let me look it up"
-rather than carrying everything around all the time.
-
-**The feedback loop.** When the agent uses a memory, it cites it. The citation
-is recorded and then stripped before it reaches your screen, and those usage
-counts feed back into phase 2's ranking. Memories that keep proving useful get
-kept and sharpened; memories nothing has touched in a month drop out. The system
-finds out which of its own notes were worth writing.
+You don't need to know any of this to use the plugin. In short: two background
+writers and one reader. Once a session has been idle long enough (default 6 h),
+a cheap model reviews its transcript and writes a structured note (**phase 1 —
+extraction**). Every few hours, a stronger model merges those notes into the
+actual memory files — the index, the short summary, reusable skills — resolving
+duplicates and dropping what went stale (**phase 2 — consolidation**). On every
+turn, the short summary goes into the system prompt, and the agent searches
+deeper layers itself when a task looks familiar (**read path**). When the agent
+uses a memory it cites it; those citations feed consolidation's ranking, so
+useful memories survive and unused ones age out.
+
+For the full architecture — learning, remembering, forgetting, and the
+trade-offs behind each — see
+[How OpenCode Codex Memory works](./docs/how-ai-memory-works.md).
 
 ## Where your data lives
 
@@ -254,7 +201,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.6.3", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.6.5", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -288,6 +235,11 @@ on your own `memorize-extract`/`memorize` agent definition, if you overrode
 one → the provider's default model. Note that the first two pass the model
 explicitly, so they win over an agent-level `model`.
 
+Reasoning effort follows Codex (`low` for extraction, `medium` for
+consolidation) when the model lists that name. Otherwise the plugin picks the
+nearest OpenCode variant on `none < minimal < low < medium < high < xhigh < max`
+(ties go higher). No listed efforts → no pin, host default.
+
 > Note: `dedicated_tools` defaults to `true` here (Codex defaults it to `false`).
 > This is the one intentional default difference — the tools are a core part of a
 > standalone memory plugin. Everything else matches Codex's defaults.
@@ -316,7 +268,7 @@ Off by default; no changes to Codex's own config are required.
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.6.3",
+      "opencode-codex-memory@0.6.5",
       { "codex_interop": { "import": true, "export": true } }
     ]
   ]
@@ -373,7 +325,7 @@ from the project memories Claude already keeps on your machine. **One-way only**
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.6.3", { "claude_import": { "enabled": true } }]
+    ["opencode-codex-memory@0.6.5", { "claude_import": { "enabled": true } }]
   ]
 }
 ```
@@ -400,7 +352,7 @@ Claude names each project with an opaque id (a folder under
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.6.3",
+      "opencode-codex-memory@0.6.5",
       {
         "claude_import": {
           "enabled": true,

package/dist/src/host-client.d.ts

@@ -10,6 +10,7 @@
  * - AssistantMessage.info.structured: structured extraction result
  * - client._client.get: experimental routes (no experimental.* namespace on V1)
  * - mcp.status: present on host client, weakly typed in plugin package
+ * - provider.list model.variants omitted from V1 OpenAPI types
  */
 import type { PluginInput } from "@opencode-ai/plugin";
 export type HostHttpGet = (opts: {
@@ -45,6 +46,13 @@ export interface SessionCreateBody {
     title?: string;
     metadata?: Record<string, unknown>;
 }
+/** GET /provider. V1 SDK types omit model.variants; parse the payload loosely. */
+export declare function hostProviderList(client: PluginInput["client"] | null | undefined, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
+    error?: unknown;
+    data?: unknown;
+}>;
 /** session.create with metadata (SDK body type is incomplete). */
 export declare function hostSessionCreate(client: PluginInput["client"], opts: {
     directory: string;

package/dist/src/host-client.js

@@ -10,6 +10,7 @@
  * - AssistantMessage.info.structured: structured extraction result
  * - client._client.get: experimental routes (no experimental.* namespace on V1)
  * - mcp.status: present on host client, weakly typed in plugin package
+ * - provider.list model.variants omitted from V1 OpenAPI types
  */
 /** Hey-api transport on PluginInput.client for routes the V1 surface lags on. */
 export function pluginHttpGet(client) {
@@ -64,6 +65,17 @@ export async function withHostTimeout(promise, ms, label, abort) {
         clearTimeout(timer);
     }
 }
+/** GET /provider. V1 SDK types omit model.variants; parse the payload loosely. */
+export async function hostProviderList(client, opts) {
+    const list = client?.provider?.list;
+    if (typeof list === "function") {
+        return (await list(opts?.signal ? { signal: opts.signal } : undefined));
+    }
+    const get = pluginHttpGet(client);
+    if (!get)
+        return { error: { message: "provider.list unavailable" } };
+    return get({ url: "/provider", ...(opts?.signal ? { signal: opts.signal } : {}) });
+}
 /** session.create with metadata (SDK body type is incomplete). */
 export async function hostSessionCreate(client, opts) {
     return client.session.create({

package/dist/src/index.js

@@ -326,6 +326,10 @@ async function classifyExternalContextTool(toolName) {
     }
     return false;
 }
+const TITLE_GENERATOR_MARKER = "You are a title generator. You output ONLY a thread title.";
+function isTitleGenerationPrompt(system) {
+    return system.some((block) => block.includes(TITLE_GENERATOR_MARKER));
+}
 /**
  * Registers the memorize / memorize-extract sub-agents through the config
  * hook so installing the plugin requires no manual agent setup. Definitions
@@ -383,9 +387,13 @@ function buildHooks() {
                 if (!pluginOptions.use_memories)
                     return;
                 // OpenCode also invokes this hook while generating agent definitions,
-                // without a session. Memory belongs only in real conversation prompts.
+                // without a session, and while naming a session (hidden `title` agent,
+                // same sessionID; hook has no agent field). Memory belongs only in
+                // real conversation prompts.
                 if (!input.sessionID || isMemorySubSession(input.sessionID))
                     return;
+                if (isTitleGenerationPrompt(output.system))
+                    return;
                 ensureMemoryLayout();
                 const memoryPrompt = buildMemorySystemPrompt(pluginOptions.dedicated_tools);
                 if (memoryPrompt) {

package/dist/src/llm.d.ts

@@ -11,6 +11,8 @@ export declare function setSubSessionCreateTimeoutForTest(ms?: number): void;
 /** Test seam. */
 export declare function setConfigGetTimeoutForTest(ms?: number): void;
 /** Test seam. */
+export declare function setProviderListTimeoutForTest(ms?: number): void;
+/** Test seam. */
 export declare function setStaleDeleteBatchTimeoutForTest(ms?: number): void;
 export declare function isMemorySubSession(sessionId: string): boolean;
 export declare function resolveExtractionModel(configured?: string): Promise<string | undefined>;

package/dist/src/llm.js

@@ -1,7 +1,8 @@
 import fs from "fs";
 import path from "path";
 import { memoryRoot } from "./paths.js";
-import { hostListSessionsGlobal, hostSessionCreate, hostSessionDeletionConfirmed, hostSessionPrompt, hostStructuredOutput, ignoreLateRejection, pluginHttpGet, withHostTimeout, } from "./host-client.js";
+import { hostListSessionsGlobal, hostProviderList, hostSessionCreate, hostSessionDeletionConfirmed, hostSessionPrompt, hostStructuredOutput, ignoreLateRejection, pluginHttpGet, withHostTimeout, } from "./host-client.js";
+import { catalogVariantKeys, nearestReasoningVariant } from "./reasoning-variant.js";
 import { isPluginShuttingDown, pluginShutdownSignal } from "./lifecycle.js";
 import { SCAN_LIMIT } from "./store.js";
 import { isProviderCapacityError, ProviderCapacityError } from "./ratelimit.js";
@@ -12,6 +13,8 @@ export function setPluginInput(input) {
     inputGeneration++;
     configModels = null;
     configModelsInFlight = null;
+    providerCatalog = null;
+    providerCatalogInFlight = null;
 }
 export function getPluginInput() {
     return inputRef;
@@ -27,10 +30,12 @@ const SUBSESSION_CONFIRM_TIMEOUT_MS = 1_000;
 const SUBSESSION_DELETE_TIMEOUT_MS = 10_000;
 const SUBSESSION_CREATE_TIMEOUT_MS = 10_000;
 const CONFIG_GET_TIMEOUT_MS = 5_000;
+const PROVIDER_LIST_TIMEOUT_MS = 5_000;
 const SUBSESSION_DELETE_CONCURRENCY = 8;
 const SUBSESSION_DELETE_BATCH_TIMEOUT_MS = 30_000;
 let createTimeoutMs = SUBSESSION_CREATE_TIMEOUT_MS;
 let configGetTimeoutMs = CONFIG_GET_TIMEOUT_MS;
+let providerListTimeoutMs = PROVIDER_LIST_TIMEOUT_MS;
 let staleDeleteBatchTimeoutMs = SUBSESSION_DELETE_BATCH_TIMEOUT_MS;
 /** Test seam. */
 export function setSubSessionCreateTimeoutForTest(ms) {
@@ -41,6 +46,10 @@ export function setConfigGetTimeoutForTest(ms) {
     configGetTimeoutMs = ms ?? CONFIG_GET_TIMEOUT_MS;
 }
 /** Test seam. */
+export function setProviderListTimeoutForTest(ms) {
+    providerListTimeoutMs = ms ?? PROVIDER_LIST_TIMEOUT_MS;
+}
+/** Test seam. */
 export function setStaleDeleteBatchTimeoutForTest(ms) {
     staleDeleteBatchTimeoutMs = ms ?? SUBSESSION_DELETE_BATCH_TIMEOUT_MS;
 }
@@ -142,6 +151,53 @@ function parseModelRef(ref) {
         return null;
     return { providerID: ref.slice(0, slash), modelID: ref.slice(slash + 1) };
 }
+const EXTRACT_VARIANT = "low";
+const CONSOLIDATE_VARIANT = "medium";
+let providerCatalog = null;
+let providerCatalogInFlight = null;
+async function getProviderCatalog() {
+    if (providerCatalog)
+        return providerCatalog.data;
+    if (providerCatalogInFlight)
+        return providerCatalogInFlight;
+    const input = getPluginInput();
+    if (!input)
+        return null;
+    const generation = inputGeneration;
+    const request = (async () => {
+        const controller = new AbortController();
+        try {
+            const res = await withHostTimeout(hostProviderList(input.client, { signal: controller.signal }), providerListTimeoutMs, "provider.list", controller);
+            if (res.error || res.data == null || generation !== inputGeneration)
+                return null;
+            providerCatalog = { data: res.data };
+            return res.data;
+        }
+        catch {
+            return null;
+        }
+    })();
+    providerCatalogInFlight = request;
+    try {
+        return await request;
+    }
+    finally {
+        if (providerCatalogInFlight === request)
+            providerCatalogInFlight = null;
+    }
+}
+async function resolveReasoningVariant(preferred, modelRef) {
+    const parsed = modelRef ? parseModelRef(modelRef) : null;
+    if (!parsed)
+        return preferred;
+    const catalog = await getProviderCatalog();
+    if (catalog == null)
+        return preferred;
+    const keys = catalogVariantKeys(catalog, parsed.providerID, parsed.modelID);
+    if (keys === undefined)
+        return preferred;
+    return nearestReasoningVariant(preferred, keys);
+}
 /**
  * Thrown when a sub-agent prompt exceeds its budget. A distinct type (rather
  * than matching on the message text) is what tells the catch below that the
@@ -338,9 +394,9 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
             // call (toolChoice: required) — which is why memorize-extract must allow
             // that one otherwise-denied tool.
             format: { type: "json_schema", schema: EXTRACTION_SCHEMA },
-            // Codex extraction ReasoningEffort::Low. Host maps variant → reasoningEffort;
-            // missing variant on the model is a no-op.
-            variant: "low",
+            // Codex extraction ReasoningEffort::Low. Host maps variant → reasoningEffort.
+            // If the model has no `low`, pick the nearest listed effort (host-only).
+            variant: await resolveReasoningVariant(EXTRACT_VARIANT, model),
         });
         // The captured JSON lands on AssistantMessage.structured (schema
         // v1/session.ts; absent from the generated SDK type — see host-client.ts).
@@ -376,8 +432,8 @@ export async function consolidateViaSubagent(memoryRoot, diffFileName, model, si
             model: resolved,
             timeoutMs: CONSOLIDATION_TIMEOUT_MS,
             signal,
-            // Codex consolidation ReasoningEffort::Medium.
-            variant: "medium",
+            // Codex consolidation ReasoningEffort::Medium. Nearest listed effort if missing.
+            variant: await resolveReasoningVariant(CONSOLIDATE_VARIANT, resolved),
         });
     }
     catch (err) {

package/dist/src/reasoning-variant.d.ts

@@ -0,0 +1,5 @@
+export declare const REASONING_VARIANT_LADDER: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ReasoningVariant = (typeof REASONING_VARIANT_LADDER)[number];
+export declare function nearestReasoningVariant(preferred: string, available: Iterable<string>): string | undefined;
+export declare function enabledVariantKeys(variants: unknown): string[];
+export declare function catalogVariantKeys(data: unknown, providerID: string, modelID: string): string[] | undefined;

package/dist/src/reasoning-variant.js

@@ -0,0 +1,53 @@
+export const REASONING_VARIANT_LADDER = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export function nearestReasoningVariant(preferred, available) {
+    const have = new Set(available);
+    if (have.has(preferred))
+        return preferred;
+    const prefIdx = REASONING_VARIANT_LADDER.indexOf(preferred);
+    if (prefIdx < 0)
+        return undefined;
+    let best;
+    let bestDist = Infinity;
+    let bestIdx = -1;
+    for (let idx = 0; idx < REASONING_VARIANT_LADDER.length; idx++) {
+        const name = REASONING_VARIANT_LADDER[idx];
+        if (!have.has(name))
+            continue;
+        const dist = Math.abs(idx - prefIdx);
+        if (dist < bestDist || (dist === bestDist && idx > bestIdx)) {
+            best = name;
+            bestDist = dist;
+            bestIdx = idx;
+        }
+    }
+    return best;
+}
+export function enabledVariantKeys(variants) {
+    if (!variants || typeof variants !== "object" || Array.isArray(variants))
+        return [];
+    const out = [];
+    for (const [name, value] of Object.entries(variants)) {
+        if (value && typeof value === "object" && !Array.isArray(value) && value.disabled === true) {
+            continue;
+        }
+        out.push(name);
+    }
+    return out;
+}
+export function catalogVariantKeys(data, providerID, modelID) {
+    if (!data || typeof data !== "object")
+        return undefined;
+    const root = data;
+    const all = Array.isArray(root.all) ? root.all : Array.isArray(root.providers) ? root.providers : undefined;
+    if (!all)
+        return undefined;
+    const provider = all.find((item) => item && typeof item === "object" && item.id === providerID);
+    if (!provider?.models || typeof provider.models !== "object")
+        return undefined;
+    const model = provider.models[modelID];
+    if (!model || typeof model !== "object" || Array.isArray(model))
+        return undefined;
+    if (!Object.prototype.hasOwnProperty.call(model, "variants"))
+        return undefined;
+    return enabledVariantKeys(model.variants);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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",