opencode-codex-memory 0.3.1 → 0.4.1

package/README.md

@@ -1,38 +1,39 @@
-# opencode-codex-memory
+# OpenCode Codex Memory
 
-Persistent memory for [opencode](https://opencode.ai). Your agent remembers what
+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
+up. Off by default, one config flag per direction; see
+[Sharing memory with the Codex CLI](#sharing-memory-with-the-codex-cli).
 
 ## 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:
-
-- **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.
+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.
 
-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
 
@@ -40,19 +41,37 @@ anything.
 
    ```json
    {
-     "plugin": ["opencode-codex-memory"]
+     "plugin": ["opencode-codex-memory@0.4.1"]
    }
    ```
 
+   **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`,
@@ -66,11 +85,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
@@ -91,11 +110,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
@@ -104,7 +171,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).
 
@@ -115,8 +182,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
@@ -128,14 +199,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 |
 |---|---|---|
@@ -143,84 +214,143 @@ 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 |
 | `max_rollouts_per_startup` | `2` | Max sessions extracted per pass |
 | `max_unused_days` | `30` | Prune memories unused for this long |
+| `codex_interop` | `{ "import": false, "export": false }` | Two-way memory exchange with a local Codex CLI (see below) |
 
 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.1", { "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.
-
-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
+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
+echoes the effective options (after parsing and clamping), lists warnings for
+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
 `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
 > maintenance tools (`memory_reset`, `memory_inspect`, `memory_mode`) stay
 > available either way.
 
-## Under the hood
+### Sharing memory with the Codex CLI
 
-opencode-codex-memory is a faithful port of the memory system from OpenAI's codex.
+If you switch between OpenCode and OpenAI's Codex CLI on the same machine, the
+plugin can exchange consolidated memories with Codex — in either or both
+directions:
 
-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.
+```json
+{
+  "plugin": [
+    ["opencode-codex-memory@0.4.1", { "codex_interop": { "import": true, "export": true } }]
+  ]
+}
+```
 
-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.
+- `import` copies Codex's consolidated `MEMORY.md` / `memory_summary.md` into a
+  memory extension (`extensions/codex_import/`) before each consolidation pass.
+  The consolidator merges what's new, tagging it `[from codex]`.
+- `export` copies this plugin's consolidated memory into Codex's memory
+  workspace as an extension (`extensions/opencode_import/`) after each
+  successful consolidation, together with instructions for Codex's own
+  consolidator. Codex picks it up on its next consolidation — no Codex
+  configuration needed. Nothing is exported until Codex's memory feature has
+  created `$CODEX_HOME/memories`, and Codex's own files are never modified.
+  (After a `memory_reset` here, the last export stays in Codex until your
+  next successful consolidation replaces it.)
+- `codex_home` overrides where Codex lives (default: `$CODEX_HOME`, else
+  `~/.codex`).
+
+Both sides mark imported content with a provenance tag (`[from codex]` /
+`[from opencode]`) and skip content carrying the other side's tag, so memories
+don't ping-pong between the two systems. This follows the same extension
+mechanism Codex itself uses to import Claude memories.
+
+## 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.
+
+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.
+
+## Contributing
+
+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/codex-interop.d.ts

@@ -0,0 +1,38 @@
+export declare const IMPORT_EXTENSION = "codex_import";
+export declare const EXPORT_EXTENSION = "opencode_import";
+export interface CodexInteropOptions {
+    import: boolean;
+    export: boolean;
+    codex_home?: string;
+}
+export interface ResolvedCodexInterop {
+    codexMemoryRoot: string;
+    importEnabled: boolean;
+    exportEnabled: boolean;
+}
+/**
+ * Resolves the Codex memory root and validates it against the plugin memory
+ * root. Precedence for the Codex home: explicit option > CODEX_HOME env >
+ * `~/.codex` (codex-rs find_codex_home). Overlapping roots would let one
+ * side's sync recurse into the other's workspace, so interop fails closed
+ * (returns null) with a warning.
+ */
+export declare function resolveCodexInterop(opts: CodexInteropOptions): ResolvedCodexInterop | null;
+/**
+ * Import direction: Codex consolidated memory -> our
+ * `extensions/codex_import/`. Call inside the claimed phase-2 job, after the
+ * git baseline exists (codex prepare_memory_workspace ordering) and before
+ * the workspace diff is captured, so copies are consolidated in the same run.
+ * Returns true when the plugin workspace changed.
+ */
+export declare function syncCodexImport(codexMemoryRoot: string): boolean;
+/**
+ * Export direction: our consolidated memory -> Codex's
+ * `extensions/opencode_import/`. Strictly additive: never bootstraps the
+ * Codex memory workspace (missing `<codex_home>/memories` means Codex's
+ * memory feature is not in use) and never touches Codex's state DB — Codex
+ * discovers the files through its own workspace diff on its next
+ * consolidation. Only valid consolidated artifacts are exported; the seeded
+ * placeholder MEMORY.md / empty summary would just be noise.
+ */
+export declare function exportToCodexMemory(codexMemoryRoot: string): boolean;