opencode-codex-memory 0.4.0 → 0.4.2

package/README.md

@@ -1,17 +1,29 @@
-# opencode-codex-memory
-
-Persistent memory for [opencode](https://opencode.ai). Your agent remembers what
+# OpenCode Codex Memory
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-codex-memory">
+    <img src="https://img.shields.io/npm/v/opencode-codex-memory?logo=npm&amp;label=latest" alt="Latest npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/opencode-codex-memory">
+    <img src="https://img.shields.io/npm/dt/opencode-codex-memory?logo=npm&amp;label=downloads" alt="npm downloads" />
+  </a>
+</p>
+
+Persistent memory for [OpenCode](https://opencode.ai): your agent remembers what
 it learned in past sessions — your conventions, your projects, the decisions you
 made — and brings that context into new conversations automatically.
 
-It's a single plugin. No core changes, no MCP server, no separate process, no
-cloud service. Everything stays on your machine under
-`~/.local/share/opencode/`.
-
-Despite the name: **no codex subscription or OpenAI account is needed.** This
-project ports the memory *design* from OpenAI's codex to opencode. It works out
+Despite the name: **no Codex subscription or OpenAI account is needed.** This
+project is a faithful port of the memory system in OpenAI's Codex. It works out
 of the box with zero extra configuration and uses whatever models you already
-have set up in opencode.
+have set up in OpenCode.
+
+**Local-first by design.** Memory is plain markdown files plus a small SQLite
+database on your own machine — no memory service to sign up for, no MCP server,
+no separate process, no sync. Installing it is one line in your `opencode.json`;
+from there everything lives under `~/.local/share/opencode/`, so you can read it,
+grep it, edit it, or delete it like anything else you own. Nothing leaves your
+machine beyond the model calls OpenCode already makes.
 
 If you *do* also use the Codex CLI: the plugin can share memory with Codex in
 both directions — what one assistant learns on your machine, the other picks
@@ -20,24 +32,17 @@ up. Off by default, one config flag per direction; see
 
 ## Why
 
-By default every opencode session starts from zero. You re-explain your build
+By default every OpenCode session starts from zero. You re-explain your build
 commands, your code style, and the quirks of each repo over and over.
 
-opencode-codex-memory closes that loop:
+This plugin closes that loop. It reviews finished sessions in the
+background, keeps what's durable — your preferences, how a repo is built, what
+worked and what didn't — and puts that context back in front of the agent in
+later conversations. You don't manage any of it; OpenCode just gets more useful
+the more you use it.
 
-- **It learns in the background.** Once a session has been idle for a while
-  (default 6 h), a later background pass reviews the transcript and extracts
-  durable facts — preferences, project structure, what worked and what didn't.
-- **It consolidates.** Periodically it merges those notes into a compact,
-  searchable memory, pruning what's stale.
-- **It remembers at the right time.** A short summary is injected into the system
-  prompt, and the agent can search the full memory on demand when a task looks
-  related to past work.
-- **It self-corrects.** When the agent actually uses a memory it cites the source,
-  so useful memories rank higher over time and unused ones fade.
-
-The result: opencode gets more useful the more you use it, without you managing
-anything.
+If you want the mental model before the details, jump to
+[How it works](#how-it-works).
 
 ## Install
 
@@ -45,19 +50,37 @@ anything.
 
    ```json
    {
-     "plugin": ["opencode-codex-memory"]
+  "plugin": ["opencode-codex-memory@0.4.2"]
    }
    ```
 
+   **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
+   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
+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`,
@@ -71,11 +94,11 @@ 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.
+without that grant OpenCode blocks the consolidator's file access.
 
 ## Try it
 
-Just use opencode normally. Sessions that have been idle for a few hours get
+Just use OpenCode normally. Sessions that have been idle for a few hours get
 reviewed in the background and memory starts building up — you don't have to do
 anything. Come back the next day and ask something like *"what do you know about how I
 work?"* or *"what was I doing in this repo?"* and the agent draws on what it
@@ -96,11 +119,59 @@ echo 'I prefer TypeScript strict mode and 2-space indentation.' \
   > ~/.local/share/opencode/memories/memory_summary.md
 ```
 
+## 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.
+
 ## Where your data lives
 
 ```
 ~/.local/share/opencode/
-├── memory.db                       # the plugin's own database (opencode's data is only accessed via its API)
+├── 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
@@ -109,7 +180,7 @@ echo 'I prefer TypeScript strict mode and 2-space indentation.' \
     └── extensions/ad_hoc/notes/    # things you explicitly asked it to remember
 ```
 
-The location follows opencode's own data directory — `$XDG_DATA_HOME/opencode`
+The location follows OpenCode's own data directory — `$XDG_DATA_HOME/opencode`
 when that's set, otherwise `~/.local/share/opencode` (same resolution on macOS,
 Linux, and Windows).
 
@@ -120,8 +191,12 @@ those too.)
 
 ## Privacy & safety
 
-- **Local only.** Nothing is sent anywhere except through your existing opencode
-  provider, using your existing credentials. The plugin holds no keys of its own.
+- **Local only.** There is no remote storage option to enable, by accident or
+  otherwise: Codex keeps memory storage behind a backend interface whose only
+  implementation today is the local filesystem, and this port implements that
+  path and nothing else. Nothing is sent anywhere except through your existing
+  OpenCode provider, using your existing credentials; the plugin holds no keys
+  of its own.
 - **Secrets are redacted** (API keys, tokens, private keys, passwords) from
   session transcripts and extracted memories before anything is written or sent
   to a model. Notes you explicitly dictate ("remember that ...") are stored as
@@ -133,14 +208,14 @@ those too.)
 - **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
-  tools are still eligible for memory (matching codex). If you'd rather exclude
+  tools are still eligible for memory (matching Codex). If you'd rather exclude
   them so scraped or external content can't enter your memory, set
   `disable_on_external_context: true`.
 
 ## Configuration
 
 Optional plugin options (all have sensible defaults). Names and defaults match
-codex's `[memories]` config so the two stay easy to compare:
+Codex's `[memories]` config so the two stay easy to compare:
 
 | Option | Default | Meaning |
 |---|---|---|
@@ -148,8 +223,8 @@ codex's `[memories]` config so the two stay easy to compare:
 | `use_memories` | `true` | Inject the memory summary into the system prompt |
 | `dedicated_tools` | `true` | Expose the `memory_read`/`memory_search`/`memory_list`/`memory_add_note` tools |
 | `disable_on_external_context` | `false` | Exclude sessions that used web/MCP tools from memory |
-| `extract_model` | opencode `small_model`, else see below | Model used for per-session extraction |
-| `consolidation_model` | opencode `model`, else see below | Model used for consolidation |
+| `extract_model` | OpenCode `small_model`, else see below | Model used for per-session extraction |
+| `consolidation_model` | OpenCode `model`, else see below | Model used for consolidation |
 | `max_raw_memories_for_consolidation` | `256` | How many raw memories feed each consolidation pass |
 | `max_rollout_age_days` | `10` | Ignore sessions older than this for extraction |
 | `min_rollout_idle_hours` | `6` | How long a session must be idle before it's eligible |
@@ -162,16 +237,16 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.4.2", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
 
-See the [opencode plugin docs](https://opencode.ai/docs/plugins/) for details.
+See the [OpenCode plugin docs](https://opencode.ai/docs/plugins/) for details.
 
-Numeric options are clamped to codex's valid ranges; unknown option keys are
+Numeric options are clamped to Codex's valid ranges; unknown option keys are
 ignored with a warning. Setting `use_memories: false` also hides the memory
-tools, matching codex's extension gating.
+tools, matching Codex's extension gating.
 
 **Verifying your configuration:** the plugin never hard-fails on bad options.
 To check what actually took effect, ask the agent to run `memory_inspect` — it
@@ -180,32 +255,32 @@ unknown or malformed keys (typos included), and shows the resolved Codex
 interop state. A mistyped option shows up there twice: as a warning, and as
 the default value appearing where you expected your setting.
 
-Model selection mirrors codex's cheap-extraction / capable-consolidation
-split using opencode's own concepts: when `extract_model` is unset, the
-`small_model` from your `opencode.json` is used (codex uses `gpt-5.4-mini`);
-when `consolidation_model` is unset, your main `model` is used (codex uses
+Model selection mirrors Codex's cheap-extraction / capable-consolidation
+split using OpenCode's own concepts: when `extract_model` is unset, the
+`small_model` from your `opencode.json` is used (Codex uses `gpt-5.4-mini`);
+when `consolidation_model` is unset, your main `model` is used (Codex uses
 `gpt-5.4`). If neither is configured, the learning sub-agents fall back to
 their own agent-level `model` (if you defined one), else the provider default.
-(opencode's *automatic* small-model pick is internal to opencode and not
+(OpenCode's *automatic* small-model pick is internal to OpenCode and not
 exposed to plugins — set `small_model` explicitly to get the cheap extraction
 path.)
 
 The full precedence per phase: plugin option (`extract_model` /
-`consolidation_model`) → opencode config (`small_model` / `model`) → a `model`
+`consolidation_model`) → OpenCode config (`small_model` / `model`) → a `model`
 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`.
 
-> Note: `dedicated_tools` defaults to `true` here (codex defaults it to `false`).
+> 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.
+> standalone memory plugin. Everything else matches Codex's defaults.
 >
 > Turning `dedicated_tools` off keeps background learning, summary injection,
-> and citation tracking working. The injected guidance switches to codex's
+> and citation tracking working. The injected guidance switches to Codex's
 > file-based mode — the agent reads the memory files with its normal file
 > tools and writes "remember this" notes directly into
 > `extensions/ad_hoc/notes/`. Caveat: the memory folder lives outside your
-> project, so opencode raises an `external_directory` permission prompt the
+> project, so OpenCode raises an `external_directory` permission prompt the
 > first time an agent touches it (allow-always covers later access); agents
 > whose permissions deny that ask cannot use file-based mode. The dedicated
 > tools have no such friction — that's why they are the default. The
@@ -221,7 +296,7 @@ directions:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory", { "codex_interop": { "import": true, "export": true } }]
+    ["opencode-codex-memory@0.4.2", { "codex_interop": { "import": true, "export": true } }]
   ]
 }
 ```
@@ -245,28 +320,46 @@ Both sides mark imported content with a provenance tag (`[from codex]` /
 don't ping-pong between the two systems. This follows the same extension
 mechanism Codex itself uses to import Claude memories.
 
-## Under the hood
+## Why one global memory?
+
+There's a single store for everything you do, not one per project — and that's
+the design choice most likely to surprise you, so it's worth explaining where it
+came from.
+
+Codex *started* with per-project memory: a separate bucket per directory, plus a
+user-level scope on top. It **deliberately removed that** in early 2026 and
+collapsed everything into one global root — one store, one lock, one
+consolidation pass — for simplicity.
+
+Simplicity is easy to underrate here — until you try to draw the boundaries
+yourself. Scoping forces a question that often has no good answer: which project does
+"prefers table-driven tests" belong to? Monorepos, worktrees, and sibling repos
+of the same stack all blur the line, and the most valuable lessons — the ones
+about how *you* work — belong to no project at all. Per-scope stores also each
+consolidate over a thinner slice of evidence than the whole.
+
+Project awareness didn't disappear; it moved out of storage and into the prompt.
+Memories carry the project they came from, and the consolidator is told to keep
+per-project detail separable — soft "this looks like it belongs to that project"
+hints rather than hard partitions. You get the cross-project transfer (your
+conventions follow you into a new repo on day one) while project-specific facts
+stay recognizable as such.
 
-opencode-codex-memory is a faithful port of the memory system from OpenAI's codex.
+The cost is real: with one store, an unrelated project's details can surface in
+the summary. Codex judged that cheaper than the alternative, and this port
+mirrors that decision rather than layering scoping back on top.
 
-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.
+## Contributing
 
-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) —
-in short: this repo exists to port codex's memory system to opencode, and
-PRs that break that parity will be rejected.
+The port follows Codex closely: same two-phase pipeline, same on-disk artifacts,
+same prompts (adapted only where OpenCode differs). If you want the full design
+and the trade-offs, see [`ARCHITECTURE.md`](./ARCHITECTURE.md); contributor
+guidance lives in [`CONTRIBUTING.md`](./CONTRIBUTING.md) and
+[`AGENTS.md`](./AGENTS.md) — in short: this repo exists to port Codex's memory
+system to OpenCode, and PRs that break that parity will be rejected.
 
 ## License
 
 Apache 2.0 — the same license as [OpenAI Codex](https://github.com/openai/codex),
 whose memory system this project ports. See [`LICENSE`](./LICENSE) and
-[`NOTICE`](./NOTICE). Not affiliated with the codex project.
+[`NOTICE`](./NOTICE). Not affiliated with the Codex project.

package/dist/src/capture.js

@@ -127,6 +127,11 @@ function extractText(msg) {
     // parts carry `text`, so they must be dropped before the text check.
     if (msg.type === "reasoning")
         return undefined;
+    // opencode itself drops `ignored` text parts when building model messages
+    // (session/message-v2.ts), e.g. ACP content addressed only to the user.
+    // The assistant never saw them, so they are not conversation.
+    if (msg.ignored === true)
+        return undefined;
     if (typeof msg.text === "string")
         return msg.text;
     if (msg.type === "tool") {
@@ -135,8 +140,16 @@ function extractText(msg) {
         // the extractor's strongest evidence — do not slice them per call.
         const tool = msg.tool ?? "unknown";
         const input = msg.state?.input ? JSON.stringify(msg.state.input) : "";
-        const output = typeof msg.state?.output === "string" ? msg.state.output : "";
-        return `[tool: ${tool}] ${input}${output ? "\n" + output : ""}`;
+        // `output` exists only on status:"completed"; a failed call carries
+        // `error` instead (schema v1/session.ts ToolStateError). codex persists
+        // failed calls too (rollout policy: FunctionCallOutput => true), and "X
+        // failed with Y" is often the most memorable part of a session.
+        const result = typeof msg.state?.output === "string"
+            ? msg.state.output
+            : typeof msg.state?.error === "string"
+                ? `[error] ${msg.state.error}`
+                : "";
+        return `[tool: ${tool}] ${input}${result ? "\n" + result : ""}`;
     }
     if (msg.type === "step-start" || msg.type === "step-finish")
         return undefined;

package/dist/src/codex-interop.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { memoryRoot } from "./paths.js";
+import { safeResolveUnderRoot } from "./path-guard.js";
 /**
  * Codex interop: memory exchange with an upstream Codex CLI installation on
  * the same machine, in both directions, through the generic extensions
@@ -235,8 +236,7 @@ function writeIfChanged(file, content) {
  * target workspace changed. Never creates the extension while the source has
  * nothing to offer.
  */
-function syncExtension(sourceRoot, extDir, subdir, instructions) {
-    const resDir = path.join(extDir, "resources", subdir);
+function syncExtension(sourceRoot, targetRoot, extension, subdir, instructions) {
     // An unreachable source ROOT is not a deletion signal: a missing/mistyped
     // codex home (or an env context without CODEX_HOME) must not trigger the
     // forgetting path. Keep existing copies untouched and do nothing.
@@ -247,6 +247,8 @@ function syncExtension(sourceRoot, extDir, subdir, instructions) {
     catch { }
     if (!rootIsDir)
         return false;
+    const extensionDir = safeResolveUnderRoot(targetRoot, path.join("extensions", extension));
+    const resDir = safeResolveUnderRoot(targetRoot, path.join("extensions", extension, "resources", subdir));
     const sourceAvailable = ARTIFACTS.some((name) => readIfFile(path.join(sourceRoot, name)) !== null);
     if (!sourceAvailable) {
         // Root exists but the artifacts are gone (e.g. codex memory cleared):
@@ -259,19 +261,18 @@ function syncExtension(sourceRoot, extDir, subdir, instructions) {
         return true;
     }
     let changed = false;
-    if (writeIfChanged(path.join(extDir, "instructions.md"), instructions))
+    if (writeIfChanged(path.join(extensionDir, "instructions.md"), instructions))
         changed = true;
     for (const name of ARTIFACTS) {
         const source = readIfFile(path.join(sourceRoot, name));
         const target = path.join(resDir, name);
         if (source === null) {
-            if (readIfFile(target) !== null) {
-                try {
-                    fs.unlinkSync(target);
-                    changed = true;
-                }
-                catch { }
+            try {
+                fs.lstatSync(target);
+                fs.rmSync(target, { recursive: true, force: true });
+                changed = true;
             }
+            catch { }
             continue;
         }
         if (writeIfChanged(target, source))
@@ -287,8 +288,7 @@ function syncExtension(sourceRoot, extDir, subdir, instructions) {
  * Returns true when the plugin workspace changed.
  */
 export function syncCodexImport(codexMemoryRoot) {
-    const extDir = path.join(memoryRoot(), "extensions", IMPORT_EXTENSION);
-    return syncExtension(codexMemoryRoot, extDir, "codex", IMPORT_INSTRUCTIONS);
+    return syncExtension(codexMemoryRoot, memoryRoot(), IMPORT_EXTENSION, "codex", IMPORT_INSTRUCTIONS);
 }
 /**
  * Export direction: our consolidated memory -> Codex's
@@ -312,6 +312,5 @@ export function exportToCodexMemory(codexMemoryRoot) {
     const summary = readIfFile(path.join(memoryRoot(), "memory_summary.md"));
     if (summary === null || summary.toString("utf8").split(/\r?\n/, 1)[0] !== "v1")
         return false;
-    const extDir = path.join(codexMemoryRoot, "extensions", EXPORT_EXTENSION);
-    return syncExtension(memoryRoot(), extDir, "opencode", EXPORT_INSTRUCTIONS);
+    return syncExtension(memoryRoot(), codexMemoryRoot, EXPORT_EXTENSION, "opencode", EXPORT_INSTRUCTIONS);
 }

package/dist/src/db.js

@@ -47,18 +47,24 @@ export function openDb() {
         return dbInstance;
     const dbPath = memoryDbPath();
     const db = new Database(dbPath, { create: true, readwrite: true, strict: false });
-    // Match codex's memories-DB open options (runtime.rs): WAL, NORMAL sync,
-    // 5s busy timeout for cross-process access, incremental auto-vacuum.
-    db.exec("PRAGMA journal_mode=WAL");
-    db.exec("PRAGMA synchronous=NORMAL");
-    db.exec("PRAGMA busy_timeout=5000");
-    db.exec("PRAGMA auto_vacuum=INCREMENTAL");
-    runMigrations(db);
-    dbInstance = db;
-    return db;
+    try {
+        // Match codex's memories-DB open options (runtime.rs): WAL, NORMAL sync,
+        // 5s busy timeout for cross-process access, incremental auto-vacuum.
+        db.run("PRAGMA journal_mode=WAL");
+        db.run("PRAGMA synchronous=NORMAL");
+        db.run("PRAGMA busy_timeout=5000");
+        db.run("PRAGMA auto_vacuum=INCREMENTAL");
+        runMigrations(db);
+        dbInstance = db;
+        return db;
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
 }
 function runMigrations(db) {
-    db.exec(`CREATE TABLE IF NOT EXISTS schema_version (
+    db.run(`CREATE TABLE IF NOT EXISTS schema_version (
     version INTEGER NOT NULL,
     applied_at INTEGER NOT NULL
   )`);
@@ -67,7 +73,7 @@ function runMigrations(db) {
     if (currentVersion >= 1)
         return;
     for (const stmt of SCHEMA_V1)
-        db.exec(stmt);
+        db.run(stmt);
     db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (?, ?)").run(1, Date.now());
 }
 export function closeDb() {

package/dist/src/git-baseline.js

@@ -17,10 +17,32 @@ function removeDiffArtifact(dir) {
 }
 async function ensureInit(dir) {
     const gitDir = path.join(dir, ".git");
+    let recreate = false;
+    try {
+        recreate = containsSymlink(gitDir) || !fs.lstatSync(gitDir).isDirectory();
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (recreate)
+        fs.rmSync(gitDir, { recursive: true, force: true });
     if (!fs.existsSync(gitDir)) {
         await isogit.init({ fs, dir });
     }
 }
+function containsSymlink(root) {
+    const st = fs.lstatSync(root);
+    if (st.isSymbolicLink())
+        return true;
+    if (!st.isDirectory())
+        return false;
+    for (const name of fs.readdirSync(root)) {
+        if (containsSymlink(path.join(root, name)))
+            return true;
+    }
+    return false;
+}
 // statusMatrix rows are [filepath, head, workdir, stage]; head !== workdir
 // means the working tree differs from HEAD (added, modified, or deleted).
 async function stageAll(dir) {

package/dist/src/index.d.ts

@@ -189,7 +189,23 @@ declare const _default: {
         "chat.message"(input: {
             sessionID?: string;
         }): Promise<void>;
-        "tool.execute.after"(input: {
+        /**
+         * Dedicated plugin hook (NOT an event-bus type). Marks the session polluted
+         * at INVOCATION, mirroring codex: mcp_tool_call.rs calls
+         * maybe_mark_thread_memory_mode_polluted inside handle_approved_mcp_tool_call
+         * BEFORE the call runs, and web search marks on the completed response item
+         * (stream_events_utils.rs response_item_may_include_external_context).
+         *
+         * Deliberately not tool.execute.after: opencode does not guarantee that hook
+         * (session/tools.ts awaits execute() with no ensuring/catchAll, and an abort
+         * interrupts the fiber), so a failed or cancelled websearch/webfetch/MCP call
+         * left the session unmarked while its output had already entered the
+         * transcript. Marking early over-marks a permission-denied call, which is the
+         * safe direction for an opt-in guard.
+         *
+         * Pollution remains gated by disable_on_external_context, off by default.
+         */
+        "tool.execute.before"(input: {
             tool: string;
             sessionID: string;
             callID: string;