opencode-self-improvement 0.1.1 → 0.2.0

package/README.md

@@ -10,14 +10,56 @@ LLMs waste a lot of tokens reading and re-reading your code and asking you for c
 - **`memory_*` tools** — remember facts, decisions, and commands the agent should
   keep across sessions (`memory_init`, `memory_remember`, `memory_recall`,
   `memory_update`, `memory_forget`, `memory_list`, `memory_undo`,
-  `memory_evidence`).
+  `memory_evidence`, `memory_export`, `memory_import`, `memory_decay`).
 - **`/repo-init`** — for each repo: indexes the code graph and remembers the
   test/build commands, keyed to the git head. The command installs itself; no
   setup beyond the plugin.
+- **Memory-aware compaction** — durable memories are handed to the compaction
+  summarizer, so a long session doesn't get an amnesia wipe exactly when it
+  needs its memory most.
+- **Export / import (JSONL)** — `memory_export` / `memory_import` back the store
+  up or move it between machines. Every imported row re-enters through the same
+  write gates, so an export can't smuggle junk in.
+- **Decay** — `memory_decay` retires stale open threads. Dry run by default;
+  supersede-not-delete, snapshot-first, undoable.
+- **Auto-capture (opt-in)** — with `autoCapture` on, session-idle events get one
+  cheap model pass that proposes memory candidates; every candidate still faces
+  the same write gates. Off by default, so the install stays zero-token.
 - Automatically de-dupes similar memories and avoids contradictions by searching for existing memories before saving new ones.
 - Automatically looks for insights when you complete the verification gates (tests, linting, etc)
 - Always defaults to memories first before sending a prompt to the LLM, which saves tokens! 
 
+## Token cost, on purpose
+
+Memory plugins have a reputation for burning tokens and busting the provider's
+prompt cache on every message. This one is built the other way around:
+
+- **Epoch-frozen injection.** The "Relevant durable memory" block is computed
+  once per epoch — first prompt of a session, a change to the memory store, or
+  a compaction — and stays byte-identical in between. A stable system prefix
+  means the provider's prompt cache survives ordinary turns instead of being
+  invalidated on every message.
+- **Hard character budget.** The block is capped at 1200 characters by default
+  (see Options) and trimmed at whole-memory boundaries — never cut mid-sentence.
+- **Evidence is never injected**, and the standing system digest is two lines.
+
+Measured on a deterministic workload (50 memories, 20 prompts, 3 mid-session
+store writes) using the plugin's real injection code:
+
+| Policy | Recomputes | Injected chars (20 turns) | Avg/turn | Worst block |
+| --- | ---: | ---: | ---: | ---: |
+| A — recompute per prompt, uncapped (pre-0.2) | 20 | 27748 | 1387.4 | 1575 |
+| B — epoch freeze + 1200-char cap (0.2) | 4 | 20654 | 1032.7 | 1157 |
+
+Policy B injects 25.6% fewer characters — and the bigger saving isn't even in
+the character count: B's block is byte-identical between store changes, so the
+prompt cache stays warm across ordinary turns. Reproduce (byte-identical
+output):
+
+```sh
+bun bench/inject-cost.ts
+```
+
 ## Quick start
 
 1. Add the plugin to your Opencode config (see install below) and restart Opencode.
@@ -37,7 +79,7 @@ Add a `plugin` entry to your opencode config —
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-self-improvement@0.1.0"]
+  "plugin": ["opencode-self-improvement@0.1.1"]
 }
 ```
 
@@ -51,7 +93,7 @@ bump the version in the config and restart. On Opencode v2 you can also manage
 it with the CLI:
 
 ```sh
-opencode plugin add opencode-self-improvement@0.1.0
+opencode plugin add opencode-self-improvement@0.1.1
 opencode plugin update opencode-self-improvement
 ```
 
@@ -77,6 +119,24 @@ After changes, `git pull` and restart opencode.
 
 </details>
 
+## Options
+
+Zero configuration is the default. To tune the plugin, use the object form of
+the plugin entry in `opencode.json(c)` instead of the plain string:
+
+```json
+{
+  "plugins": [{ "package": "opencode-self-improvement", "options": { "injectBudget": 1200 } }]
+}
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `injectBudget` | `1200` | Character cap on the injected relevance block, trimmed at whole-memory boundaries. Env fallback: `OPENCODE_MEMORY_INJECT_BUDGET`. |
+| `autoCapture` | `false` (off) | When on, each session-idle event makes one cheap model pass that proposes memory candidates. Every candidate still goes through the 4-gate write pipeline — capture can never bypass the gates. Off by default: the zero-token install stays zero-token. |
+| `captureModel` | — | `"provider/id"` model used for auto-capture. Required when `autoCapture` is on; a missing or invalid value disables capture with a startup warning. |
+| `captureMax` | `3` | Maximum candidates proposed per idle event. |
+
 ## Code graph (optional)
 
 `/repo-init` also indexes the repo into a queryable knowledge graph via
@@ -124,5 +184,6 @@ Run `bun memory-view` in your terminal and visit  http://127.0.0.1:8787 in your
 | `/repo-init` missing from the command list | The self-install couldn't write to `~/.config/opencode/commands/` (e.g. read-only config dir). Create it, restart, or just ask the model to "init memory for this repo" — it calls the same tool. |
 | Init says `Graph: unavailable` | `codebase-memory-mcp` couldn't start (not installed, or its once-only download is blocked). Install pinned `0.11.0` via the one-liner above, or point `OPENCODE_CBM_BIN` at the binary. Scripts are still remembered without it. |
 | Stale plugin after an update | Bump the pinned version in the `plugin` entry (or `opencode plugin update opencode-self-improvement` on v2) and restart opencode. |
+| Auto-capture does nothing | `autoCapture` needs a valid `captureModel` in `provider/id` form — a bad one disables capture with a startup warning. Candidates rejected by the write gates are logged as evidence, not errors; check `memory_evidence`. |
 | Reset all memories | Delete `~/.config/opencode/memory/`. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-self-improvement",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Durable memory for opencode: remember facts, decisions, and commands across sessions, plus a one-command per-repo setup (/repo-init).",
   "main": "index.ts",
   "exports": {
@@ -33,13 +33,12 @@
     "README.md",
     "LICENSE"
   ],
-  "dependencies": {
-    "@opencode-ai/plugin": "1.18.31"
-  },
   "optionalDependencies": {
     "codebase-memory-mcp": "0.11.0"
   },
   "devDependencies": {
+    "@opencode/plugin": "^2.0.32",
+    "@semantic-release/git": "^11.0.1",
     "@types/bun": "latest",
     "semantic-release": "^25.0.9",
     "typescript": "^7.0.2"
@@ -50,6 +49,7 @@
   "scripts": {
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
+    "bench": "bun bench/inject-cost.ts",
     "memory-view": "bun run src/viewer/server.ts"
   }
 }

package/src/capture.ts

@@ -0,0 +1,175 @@
+// Opt-in auto-capture core (Phase 4). Pure and dependency-free: no opencode
+// imports, no filesystem, no ambient clock — the transcript, the model call
+// and time are all injected by the caller (src/index.ts), so everything here
+// is unit-testable. Every candidate that leaves this module still flows
+// through runWriteGate in index.ts: capture NEVER writes memories directly,
+// so dupes/stale/canonical rules keep the moat (same as model-authored writes).
+// All parsing functions are TOTAL: any malformed input yields [] / "" / null,
+// never a throw.
+import { STATUSES, TYPES } from "./types.ts";
+
+export interface CaptureOptions {
+  model: string; // "provider/id"
+  max: number;
+}
+
+export interface CaptureDeps {
+  generate: (prompt: string) => Promise<string>;
+  sessionText: string;
+  now: () => Date;
+}
+
+export interface CaptureCandidate {
+  type: string;
+  scope: string;
+  content: string;
+  status?: "open" | "settled";
+}
+
+// Prompt for the cheap capture model. The output contract is a bare JSON
+// array so parseCandidates can trust it; anything else parses to [].
+export function buildCapturePrompt(transcript: string, max = 3): string {
+  return [
+    "You mine one coding-agent session transcript for durable memories worth keeping across future sessions.",
+    "",
+    `Output ONLY a JSON array of at most ${max} objects (a fenced json block is fine), each:`,
+    '{"type": "...", "scope": "...", "content": "...", "status": "..."}',
+    "",
+    "Rules:",
+    `- type: one of ${TYPES.join(", ")}.`,
+    "- scope: short area name (e.g. auth, api, build).",
+    '- status: "open" for a live planning thread; otherwise "settled".',
+    "- content: one self-contained fact, 20-600 characters, useful in a NEW session.",
+    "- Keep: decisions made, working commands, user preferences, blockers hit, durable context, conventions.",
+    "- Skip: anything derivable from the code or git history, small talk, and details that only mattered inside this conversation.",
+    "- If nothing is worth remembering, output [ ].",
+    "",
+    "Transcript:",
+    transcript,
+  ].join("\n");
+}
+
+const VALID_TYPES = new Set<string>(TYPES);
+
+// Remove markdown code-fence marker lines, keeping the fenced payload.
+function stripFences(text: string): string {
+  return text.replace(/^[ \t]*```[^\n]*$/gm, "");
+}
+
+// First balanced [...] span, string-literal aware. null when absent or
+// unbalanced (a model that truncates mid-array yields nothing, not garbage).
+function firstJsonArray(text: string): string | null {
+  const start = text.indexOf("[");
+  if (start === -1) return null;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "[") depth++;
+    else if (ch === "]") {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+// Extract memory candidates from a model reply. Never throws: any malformed
+// input yields []. Items missing fields, with unknown types, or with content
+// outside 20-600 chars are dropped; the result is clamped to `max`.
+export function parseCandidates(raw: string, max: number): CaptureCandidate[] {
+  try {
+    if (typeof raw !== "string" || !raw.trim() || !(max > 0)) return [];
+    const span = firstJsonArray(stripFences(raw));
+    if (!span) return [];
+    const parsed = JSON.parse(span);
+    if (!Array.isArray(parsed)) return [];
+    const out: CaptureCandidate[] = [];
+    for (const item of parsed) {
+      if (out.length >= max) break;
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const o = item as Record<string, unknown>;
+      const type = typeof o.type === "string" ? o.type.trim() : "";
+      const scope = typeof o.scope === "string" ? o.scope.trim() : "";
+      const content = typeof o.content === "string" ? o.content.trim() : "";
+      if (!type || !scope || !content) continue;
+      if (!VALID_TYPES.has(type)) continue;
+      if (content.length < 20 || content.length > 600) continue;
+      const status = o.status === "open" || o.status === "settled" ? o.status : undefined;
+      out.push(status ? { type, scope, content, status } : { type, scope, content });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+// "provider/id" -> { providerID, id }, splitting on the FIRST "/". Returns
+// null when the string has no slash or either half is empty — the caller then
+// skips capture entirely rather than guessing a model.
+export function parseModelRef(ref: unknown): { providerID: string; id: string } | null {
+  if (typeof ref !== "string") return null;
+  const i = ref.indexOf("/");
+  if (i <= 0) return null;
+  const providerID = ref.slice(0, i).trim();
+  const id = ref.slice(i + 1).trim();
+  if (!providerID || !id) return null;
+  return { providerID, id };
+}
+
+// Render an array of session-context messages of unknown shape into
+// "role: text" lines. Defensive by construction (the API shape varies and is
+// not ours to trust): non-arrays and junk entries are skipped; role comes
+// from info.role | role, text from parts[].text | text | content (strings
+// only); capped at 40 user turns. Never throws.
+const TRANSCRIPT_USER_TURN_CAP = 40;
+
+export function flattenTranscript(msgs: unknown): string {
+  try {
+    if (!Array.isArray(msgs)) return "";
+    const lines: string[] = [];
+    let userTurns = 0;
+    for (const msg of msgs) {
+      if (!msg || typeof msg !== "object") continue;
+      const m = msg as Record<string, unknown>;
+      const info =
+        m.info && typeof m.info === "object" ? (m.info as Record<string, unknown>) : undefined;
+      const role =
+        typeof info?.role === "string" ? info.role : typeof m.role === "string" ? m.role : "";
+      let text = "";
+      if (Array.isArray(m.parts)) {
+        text = m.parts
+          .map((p) =>
+            p && typeof p === "object" ? (p as Record<string, unknown>).text : undefined,
+          )
+          .filter((t): t is string => typeof t === "string" && t.length > 0)
+          .join(" ");
+      }
+      if (!text) {
+        for (const k of ["text", "content"]) {
+          if (typeof m[k] === "string") {
+            text = m[k] as string;
+            break;
+          }
+        }
+      }
+      if (!role || !text.trim()) continue;
+      if (role === "user") {
+        userTurns++;
+        if (userTurns > TRANSCRIPT_USER_TURN_CAP) break;
+      }
+      lines.push(`${role}: ${text.trim()}`);
+    }
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}

package/src/config.ts

@@ -41,6 +41,19 @@ export function dateStr(d: Date = new Date()): string {
   return d.toISOString().split("T")[0];
 }
 
+// Character budget for the injected "Relevant durable memory" block (Phase 2:
+// cache-safe epoch injection). Overridable via OPENCODE_MEMORY_INJECT_BUDGET
+// (plugin options take precedence — see src/index.ts); falls back to 1200 on
+// missing or invalid values.
+export function injectBudget(): number {
+  const raw = process.env.OPENCODE_MEMORY_INJECT_BUDGET;
+  if (raw) {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return 1200;
+}
+
 // Optional live-graph binary. When present the resolver cross-checks the local
 // source scan against the codebase-memory-mcp file graph; when absent the local
 // scan alone is authoritative (install-from-scratch requirement).

package/src/index.ts

@@ -6,26 +6,35 @@
 // V2 port: registers tools via `ctx.tool.transform` (JSON Schema), mirrors the
 // V1 hooks onto the OpenCode V2 session/tool hook API, and registers the
 // /repo-init command via `ctx.command.transform`. The plugin contract is a
-// default export object `{ id, setup(ctx) }` (OpenCode >= 2.0). All business
-// logic still lives in the decoupled helper modules.
+// default export object `{ id, setup(ctx) }` (OpenCode >= 2.0), pinned at
+// compile time against the real SDK type (`@opencode/plugin`, type-only — see
+// the note on `plugin` below). All business logic still lives in the decoupled
+// helper modules.
+import type { Cleanup, Plugin } from "@opencode/plugin/promise/plugin";
 import { join } from "node:path";
-import { evidenceDir, memoryRoot, dateStr } from "./config.ts";
+import { evidenceDir, injectBudget, memoryRoot, dateStr } from "./config.ts";
+import { STATUSES, TYPES } from "./types.ts";
 import {
   clearSuperseded,
   isActive,
   loadAll,
   markSuperseded,
   resolveMemoryTarget,
+  snapshotFiles,
   type Memory,
 } from "./memory.ts";
 import { runWriteGate, type GateContext, type WriteCandidate } from "./gates.ts";
 import { pruneMemory } from "./prune.ts";
+import { exportMemories, findStaleOpen, importMemories } from "./portable.ts";
 import { listSnapshots, restoreSnapshot } from "./undo.ts";
 import { record } from "./evidence.ts";
 import {
+  capToBudget,
+  compactionAnchor,
   contextualPull,
   formatMemory,
   relevantKnowledge,
+  storeVersion,
   systemDigest,
 } from "./inject.ts";
 import { formatInit, runInit } from "./init.ts";
@@ -43,9 +52,7 @@ import {
 } from "./triggers.ts";
 import { getCurrent, setCurrent } from "./state.ts";
 import { readLines } from "./logfmt.ts";
-
-const TYPES = ["decision", "learning", "preference", "blocker", "context", "pattern"] as const;
-const STATUSES = ["open", "settled"] as const;
+import { buildCapturePrompt, flattenTranscript, parseCandidates, parseModelRef } from "./capture.ts";
 
 // --- minimal JSON Schema helpers (OpenCode V2 tools take JSON Schema) --------
 type JSONSchema = Record<string, unknown>;
@@ -88,6 +95,7 @@ interface HookReg {
 }
 interface PluginCtx {
   location?: { directory?: string };
+  options?: Record<string, unknown>;
   tool?: {
     transform: (cb: (editor: ToolEditorLike) => void) => Promise<unknown>;
     hook: (name: string, cb: (event: any) => Promise<void> | void) => Promise<HookReg | void>;
@@ -102,6 +110,13 @@ interface PluginCtx {
       text: string;
       delivery?: "steer" | "queue";
     }) => Promise<unknown>;
+    context?: (input: { sessionID: string }) => Promise<unknown>;
+  };
+  event?: {
+    subscribe: (o?: { signal?: AbortSignal }) => AsyncIterable<unknown>;
+  };
+  generate?: {
+    text: (input: unknown) => Promise<{ text?: string } | string>;
   };
 }
 
@@ -133,11 +148,17 @@ function resultMeta(result: unknown): Record<string, unknown> {
 
 const PLUGIN_ID = "opencode-self-improvement";
 
-const plugin = {
-  id: PLUGIN_ID,
-  async setup(ctx: PluginCtx): Promise<void> {
+// The real setup implementation, written against the loose local PluginCtx
+// (the only members of the V2 context this plugin actually touches).
+const impl = {
+  async setup(ctx: PluginCtx): Promise<Cleanup | void> {
     const liveRoot = ctx?.location?.directory ?? process.cwd();
 
+    // Character budget for the epoch-frozen injection block: plugin options
+    // (object form in opencode.json(c)) win, then OPENCODE_MEMORY_INJECT_BUDGET,
+    // then the 1200 default.
+    const budget = Number(ctx.options?.injectBudget) || injectBudget();
+
     // Mirror the /repo-init slash command into opencode's global commands dir
     // (idempotent, write-if-missing). OpenCode 2.x loads `*.md` from
     // ~/.config/opencode/commands, so this is the canonical V2 install path.
@@ -425,11 +446,124 @@ const plugin = {
           };
         },
       });
+
+      editor.add({
+        name: "memory_export",
+        description:
+          "Export active memories as a JSONL file (one JSON object per line: {ts,type,scope,content,status,tags,issue}) for backup or transfer to another machine. Defaults to <memory-root>/exports/<timestamp>.jsonl; pass `file` to choose the path, `scope` to export one scope. Superseded rows are not exported (history stays in the store).",
+        options: direct,
+        input: obj({
+          scope: withDesc(str(), "Only export memories in this exact scope"),
+          file: withDesc(str(), "Destination path (default: <memory-root>/exports/)"),
+        }),
+        async execute(args: any): Promise<{ content: string }> {
+          const res = await exportMemories({ scope: args.scope, file: args.file });
+          return { content: `Exported ${res.count} memories -> ${res.path}` };
+        },
+      });
+
+      editor.add({
+        name: "memory_import",
+        description:
+          "Import memories from a JSONL export (see memory_export). Every row goes through the same 4-gate write pipeline as memory_remember (tagged `import`, original tags preserved), so duplicates collapse and ungrounded rows are blocked exactly as usual — those are normal tallied outcomes, not errors. Malformed lines are skipped and counted.",
+        options: direct,
+        input: obj({ file: withDesc(str(), "Path to a .jsonl export file") }, ["file"]),
+        async execute(args: any): Promise<{ content: string }> {
+          try {
+            const t = await importMemories(args.file, (c) =>
+              runWriteGate(
+                { ...c, tags: [...new Set([...(c.tags ?? []), "import"])] },
+                gateContext(),
+              ),
+            );
+            return {
+              content:
+                `Imported ${args.file}: ${t.promoted} promoted, ${t.collapsed} duplicates collapsed, ` +
+                `${t.blocked} blocked by the gate, ${t.skipped} malformed lines skipped.`,
+            };
+          } catch (err) {
+            return {
+              content: `memory_import failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+          }
+        },
+      });
+
+      editor.add({
+        name: "memory_decay",
+        description:
+          "Retire stale open threads (status=open older than olderThanDays) by superseding them — never deleting; rows stay recoverable via memory_undo. DRY RUN BY DEFAULT: without an explicit dryRun=false this only LISTS what would retire and mutates nothing (fail-closed). A real run snapshots every affected file before the first mutation.",
+        options: direct,
+        input: obj({
+          olderThanDays: withDesc(
+            { type: "number", default: 14 },
+            "Age threshold in days (default 14)",
+          ),
+          dryRun: withDesc(
+            { type: "boolean", default: true },
+            "Preview only (default true). Set false to actually supersede.",
+          ),
+        }),
+        async execute(args: any): Promise<{ content: string }> {
+          const days = Number(args.olderThanDays) > 0 ? Number(args.olderThanDays) : 14;
+          const dryRun = args.dryRun !== false; // only an explicit false mutates
+          const stale = await findStaleOpen(days);
+          if (!stale.length) {
+            return { content: `No active open threads older than ${days} days.` };
+          }
+          const listing = stale
+            .map((m) => `  ${m.ts} ${m.type}/${m.scope}: ${m.content.slice(0, 100)}`)
+            .join("\n");
+          if (dryRun) {
+            await record(
+              "decay_dry_run",
+              { days, stale: stale.length, mem: stale.map((m) => m.ts).join(",") },
+              false,
+            );
+            return {
+              content:
+                `Dry run: ${stale.length} open thread(s) older than ${days} days:\n${listing}\n` +
+                "Re-run with dryRun=false to supersede them (snapshot first; recoverable via memory_undo).",
+            };
+          }
+          // Snapshot-before-mutate: the SAME helper prune() uses in memory.ts,
+          // one whole-file copy per affected file, taken before the first
+          // mutation. markSuperseded also snapshots internally per row; this
+          // pass guarantees a pre-decay copy exists even if a later row fails.
+          const snapshot = await snapshotFiles([...new Set(stale.map((m) => m.file))]);
+          const retiredTs: string[] = [];
+          for (const m of stale) {
+            // Idempotent (a no-op on already-superseded rows), so a re-run
+            // cannot double-mark. No successor row exists — decay retires.
+            const ok = await markSuperseded(m.ts, { superseded_by: "decay", reason: "decay" });
+            if (ok) retiredTs.push(m.ts);
+          }
+          await record(
+            "decay_applied",
+            {
+              days,
+              retired: retiredTs.length,
+              mem: retiredTs.join(",") || "-",
+              snapshot: snapshot.join(",") || "-",
+            },
+            false,
+          );
+          return {
+            content:
+              `Decayed ${retiredTs.length} open thread(s) older than ${days} days ` +
+              `(superseded, not deleted; snapshot: ${snapshot[0] ?? "-"}). ` +
+              "Recover with memory_undo.",
+          };
+        },
+      });
     });
 
-    // Per-session durable-memory blocks stashed by the prompt hook and pushed
-    // onto the system prompt by the context hook (invisible to the user).
-    const pendingKnowledge = new Map<string, string>();
+    // Per-session frozen injection epochs: the relevance block plus the store
+    // fingerprint it was computed against. Recomputed ONLY on the first prompt
+    // of a session, when the store changes, or after a compaction (see the
+    // prompt/compaction hooks) — so the system prefix, and with it the
+    // provider prompt cache, survives ordinary turns.
+    const epoch = new Map<string, { version: string; block: string }>();
 
     // ---- hooks (all fail-closed) -------------------------------------------
     // Bookkeeping: track the active session/tool/call before a tool runs.
@@ -469,41 +603,158 @@ const plugin = {
         const parts: string[] = [];
         await systemDigest({ sessionID: event?.sessionID }, { system: parts });
         for (const text of parts) event?.system?.push?.({ type: "text", text });
-        // Deliver this turn's relevance-ranked memory via the system channel.
+        // Deliver this epoch's relevance-ranked memory via the system channel.
         // The UI never renders system parts, unlike appended prompt text.
         const sid = event?.sessionID;
-        const knowledge = typeof sid === "string" ? pendingKnowledge.get(sid) : undefined;
+        const knowledge = typeof sid === "string" ? epoch.get(sid)?.block : undefined;
         if (knowledge) event?.system?.push?.({ type: "text", text: knowledge });
       }),
     );
 
-    // Memory-first injection: compute relevance against each user prompt and
-    // stash the block for invisible delivery via the context hook. Never mutate
-    // event.prompt.text — it is stored verbatim and rendered in the UI.
+    // Memory-first injection, frozen per epoch (cache-safe). The block is
+    // relevance-scored against the prompt that STARTED the epoch — accepted
+    // staleness, traded for a stable system prefix across ordinary turns. An
+    // epoch is invalidated only on first prompt, store change, or compaction.
+    // Never mutate event.prompt.text — it is stored verbatim and rendered in
+    // the UI.
     await ctx.session?.hook("prompt", (event: any) =>
       guarded("session.prompt (inject)", async () => {
         const sid = event?.sessionID;
         if (typeof sid === "string") {
           markTurn(sid);
           await checkNewSession(sid);
-        }
-        const text = event?.prompt?.text ?? "";
-        const block = await relevantKnowledge(text);
-        if (typeof sid === "string") {
-          if (block) pendingKnowledge.set(sid, block);
-          else pendingKnowledge.delete(sid);
+          const version = await storeVersion();
+          const cached = epoch.get(sid);
+          if (!cached || cached.version !== version) {
+            const text = event?.prompt?.text ?? "";
+            const raw = await relevantKnowledge(text, 5); // widen candidate pool
+            const block = raw ? capToBudget(raw, budget) : "";
+            epoch.set(sid, { version, block });
+            await record(
+              "epoch_recompute",
+              {
+                session: sid,
+                reason: cached ? "store_changed" : "first",
+                chars: block.length,
+              },
+              false,
+            );
+          }
         }
       }),
     );
 
-    // Session-convergence rollup at compaction.
+    // Session-convergence rollup at compaction. The epoch is dropped so the
+    // next prompt re-scores against the post-compaction store. Memory-aware
+    // compaction: the durable-memory anchor is pushed onto the hook's system
+    // parts (visible to the summarizer model, which runs AFTER hooks) so the
+    // summary preserves the facts. Never sets event.result — that would skip
+    // the summarizer call entirely.
     await ctx.session?.hook("compaction", (event: any) =>
       guarded("session.compaction (onCompacting)", async () => {
         await onCompacting({ sessionID: event?.sessionID });
+        if (typeof event?.sessionID === "string") epoch.delete(event.sessionID);
+        const anchor = await compactionAnchor();
+        if (anchor) event?.system?.push?.({ type: "text", text: anchor });
       }),
     );
+
+    // ---- opt-in auto-capture on session idle --------------------------------
+    // Default OFF: zero-token installs never subscribe to anything. When
+    // enabled (options.autoCapture === true AND a valid captureModel), each
+    // session.idle event runs ONE cheap ctx.generate.text call whose reply is
+    // parsed into candidates that go through the SAME runWriteGate as
+    // model-authored writes — capture can never bypass the moat, and it only
+    // ever writes through the gate. A per-session cooldown bounds the cost.
+    // Every failure inside the loop is swallowed: capture must never be able
+    // to break a session.
+    let captureCleanup: Cleanup | undefined;
+    if (ctx.options?.autoCapture === true) {
+      const captureModel =
+        typeof ctx.options.captureModel === "string" ? ctx.options.captureModel : "";
+      const captureMax = Number(ctx.options.captureMax) || 3;
+      const modelRef = parseModelRef(captureModel);
+      if (!modelRef) {
+        // Invalid/missing model: skip registering the whole subscription
+        // rather than guess (and warn once, at setup).
+        console.warn(
+          `[opencode-self-improvement] autoCapture is on but captureModel ${JSON.stringify(captureModel)} is invalid (expected "provider/id"); auto-capture disabled.`,
+        );
+      } else if (!ctx.event?.subscribe || !ctx.generate?.text || !ctx.session?.context) {
+        console.warn(
+          "[opencode-self-improvement] autoCapture is on but this OpenCode context lacks event.subscribe/generate.text/session.context; auto-capture disabled.",
+        );
+      } else {
+        const controller = new AbortController();
+        const lastRun = new Map<string, number>();
+        const eventApi = ctx.event;
+        const generateApi = ctx.generate;
+        // Arrow wrapper: keep the receiver bound. The harness fakes are closures,
+        // but a real client method that reads `this` would break if detached —
+        // and the fail-closed catch below would hide it. Optional call: the
+        // setup guard proves it exists, but property narrowing does not survive
+        // into the closure, and undefined degrades safely (empty transcript).
+        const contextFn = (input: { sessionID: string }) => ctx.session?.context?.(input);
+        void (async () => {
+          try {
+            for await (const raw of eventApi.subscribe({ signal: controller.signal })) {
+              const event = raw as Record<string, any>;
+              if (event?.type !== "session.idle") continue;
+              const sid = event.sessionID ?? event.properties?.sessionID;
+              if (typeof sid !== "string") continue;
+              const now = Date.now();
+              if (now - (lastRun.get(sid) ?? 0) < 5 * 60_000) continue; // 5-min cooldown
+              lastRun.set(sid, now);
+              try {
+                const msgs = await contextFn({ sessionID: sid });
+                const transcript = flattenTranscript(msgs);
+                if (transcript.length < 200) continue; // too thin to mine reliably
+                const out = await generateApi.text({
+                  model: modelRef,
+                  prompt: buildCapturePrompt(transcript.slice(-8000), captureMax),
+                });
+                const text = typeof out === "string" ? out : out?.text ?? "";
+                for (const c of parseCandidates(text, captureMax)) {
+                  const outcome = await runWriteGate(
+                    { ...c, tags: ["auto-capture"] },
+                    gateContext(),
+                  );
+                  await record(
+                    `auto_capture_${outcome.action}`,
+                    { session: sid, type: c.type, scope: c.scope, reason: outcome.reason ?? "" },
+                    false,
+                  );
+                }
+              } catch {
+                // fail-closed: a broken capture attempt is invisible to the session
+              }
+            }
+          } catch {
+            // the subscription itself ended (abort or host error); nothing to do
+          }
+        })();
+        captureCleanup = () => controller.abort();
+      }
+    }
+    // Single cleanup returned by setup: tears down the capture subscription.
+    // Future teardowns merge into this same function.
+    return captureCleanup;
   },
 };
 
+// The plain object IS the V2 contract ({ id, setup }); the SDK's `Plugin` type
+// pins its shape at compile time. The import is deliberately type-only:
+// opencode installs npm plugins with runtime dependencies only (verified in
+// ~/.cache/opencode/npm/<pkg>@<ver>/), so a value import of @opencode/plugin —
+// a devDependency here — would fail to resolve at load time for published
+// consumers, and making it a runtime dependency would pull effect +
+// @opencode/client into every install, the exact dead-weight problem dropping
+// the V1 SDK fixes. `Plugin.define` is an identity function at runtime, so this
+// annotation buys the same compile-time contract for zero runtime cost.
+const plugin: Plugin = {
+  id: PLUGIN_ID,
+  setup: async (ctx) => impl.setup(ctx as unknown as PluginCtx),
+};
+
 export const SelfImprovement = plugin;
 export default plugin;

package/src/inject.ts

@@ -135,6 +135,65 @@ export async function relevantKnowledge(message: string, limit = 3): Promise<str
   return `## Relevant durable memory\n${top.map(formatMemory).join("\n")}`;
 }
 
+// Deterministic fingerprint of the active store: `${activeCount}:${maxActiveTs}`.
+// Cheap change detector for the per-session epoch cache in index.ts: the frozen
+// injection block is recomputed only when this string changes (or after a
+// compaction). Evidence and superseded rows never affect it (I3, memory.ts).
+export async function storeVersion(): Promise<string> {
+  const mems = (await loadAll()).filter(isActive);
+  let max = "";
+  for (const m of mems) if (m.ts > max) max = m.ts;
+  return `${mems.length}:${max}`;
+}
+
+// Trim an injection block to `budget` characters at WHOLE-line boundaries:
+// keep lines while the joined length stays <= budget, drop the rest, never cut
+// mid-line. Returns "" when even the header line exceeds the budget (the block
+// is not worth injecting).
+export function capToBudget(block: string, budget: number): string {
+  const kept: string[] = [];
+  let len = 0;
+  for (const line of block.split("\n")) {
+    const add = kept.length ? line.length + 1 : line.length;
+    if (len + add > budget) break;
+    kept.push(line);
+    len += add;
+  }
+  return kept.join("\n");
+}
+
+// Memory-aware compaction (Phase 3): a durable-memory block pushed onto the
+// V2 compaction hook's `system` parts, where the summarizer model can see it
+// (OpenCode appends its own summary prompt AFTER hooks). Deterministic, zero
+// extra model calls; fixes "compaction amnesia". Composition: up to 10 open
+// threads newest-first, then up to 5 newest settled memories, total rows
+// capped by `limit`; the whole block capped at 2500 chars at whole-line
+// boundaries. "" when the store has no active memories.
+const ANCHOR_OPEN_LIMIT = 10;
+const ANCHOR_SETTLED_LIMIT = 5;
+const ANCHOR_BUDGET = 2500;
+
+export async function compactionAnchor(limit = 12): Promise<string> {
+  const mems = (await loadAll()).filter(isActive);
+  if (!mems.length) return "";
+  const byNewest = (a: Memory, b: Memory) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0);
+  const open = mems
+    .filter((m) => m.status === "open")
+    .sort(byNewest)
+    .slice(0, Math.min(ANCHOR_OPEN_LIMIT, Math.max(0, limit)));
+  const settled = mems
+    .filter((m) => m.status !== "open")
+    .sort(byNewest)
+    .slice(0, Math.min(ANCHOR_SETTLED_LIMIT, Math.max(0, limit - open.length)));
+  const rows = [...open, ...settled];
+  if (!rows.length) return "";
+  const block =
+    "## Durable memory to preserve in this summary\n" +
+    "Preserve these facts verbatim (dates, commands, ids) in the compaction summary:\n" +
+    rows.map(formatMemory).join("\n");
+  return capToBudget(block, ANCHOR_BUDGET);
+}
+
 export async function contextualPull(input: PullInput, output: PullOutput): Promise<void> {
   const tool = typeof input.tool === "string" ? input.tool : "";
   if (!["grep", "glob", "read"].includes(tool)) return;

package/src/portable.ts

@@ -0,0 +1,121 @@
+// Portability (Phase 5): JSONL export/import of the durable store, plus the
+// stale-open-thread query that backs memory_decay. Import NEVER writes: every
+// row flows through the caller-provided gate callback (index.ts wires it to
+// runWriteGate), so moving memories between machines cannot bypass the 4-gate
+// moat. Decay is supersede-not-delete and snapshot-first, mirroring prune.
+import { join } from "node:path";
+import { memoryRoot } from "./config.ts";
+import { isActive, loadAll, type Memory } from "./memory.ts";
+import { TYPES } from "./types.ts";
+import type { WriteCandidate } from "./gates.ts";
+
+// --- export -------------------------------------------------------------------
+
+export interface ExportOptions {
+  /** Only export rows from this exact scope. */
+  scope?: string;
+  /** Destination path; defaults to <memory-root>/exports/<stamp>.jsonl. */
+  file?: string;
+}
+
+export interface ExportResult {
+  path: string;
+  count: number;
+}
+
+// Filesystem-safe YYYY-MM-DDTHHMMSS (no colons).
+function stamp(d: Date = new Date()): string {
+  return d.toISOString().slice(0, 19).replace(/:/g, "");
+}
+
+// Write the ACTIVE store as JSONL — one JSON object per line carrying
+// {ts,type,scope,content,status,tags,issue}. Superseded rows are not exported:
+// the export is the live store, and history stays auditable where it lives
+// (the original logfmt files + snapshots).
+export async function exportMemories(opts: ExportOptions = {}): Promise<ExportResult> {
+  let mems = (await loadAll()).filter(isActive);
+  if (opts.scope) mems = mems.filter((m) => m.scope === opts.scope);
+  const path = opts.file ?? join(memoryRoot(), "exports", `${stamp()}.jsonl`);
+  const lines = mems.map((m) =>
+    JSON.stringify({
+      ts: m.ts,
+      type: m.type,
+      scope: m.scope,
+      content: m.content,
+      status: m.status,
+      tags: m.tags,
+      issue: m.issue,
+    }),
+  );
+  await Bun.write(path, lines.length ? lines.join("\n") + "\n" : "");
+  return { path, count: mems.length };
+}
+
+// --- import -------------------------------------------------------------------
+
+export interface ImportTally {
+  promoted: number;
+  collapsed: number;
+  blocked: number;
+  skipped: number;
+}
+
+// A line is malformed (skipped, never gated) unless it is a JSON object with a
+// known type, a non-empty scope, and non-empty content. Optional fields are
+// sanitized rather than fatal: an unusable status/tags/issue is dropped.
+function parseRow(line: string): WriteCandidate | null {
+  let row: unknown;
+  try {
+    row = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+  const r = row as Record<string, unknown>;
+  if (typeof r.type !== "string" || !(TYPES as readonly string[]).includes(r.type)) return null;
+  if (typeof r.scope !== "string" || !r.scope.trim()) return null;
+  if (typeof r.content !== "string" || !r.content.trim()) return null;
+  const c: WriteCandidate = { type: r.type, scope: r.scope, content: r.content };
+  if (r.status === "open" || r.status === "settled") c.status = r.status;
+  if (Array.isArray(r.tags) && r.tags.every((t) => typeof t === "string")) c.tags = r.tags;
+  if (typeof r.issue === "string" && r.issue) c.issue = r.issue;
+  return c;
+}
+
+// Read a JSONL export and run every valid row through `gate`. The CALLER owns
+// promotion (index.ts passes runWriteGate with the "import" tag), so imported
+// rows face the same canonical/stale/dedup/ambiguity gates as any other write.
+// Blocked and collapsed rows are normal outcomes, tallied rather than raised.
+// Only a missing file throws.
+export async function importMemories(
+  path: string,
+  gate: (c: WriteCandidate) => Promise<{ action: string }>,
+): Promise<ImportTally> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) throw new Error(`import file not found: ${path}`);
+  const tally: ImportTally = { promoted: 0, collapsed: 0, blocked: 0, skipped: 0 };
+  for (const line of (await file.text()).split("\n")) {
+    if (!line.trim()) continue;
+    const c = parseRow(line);
+    if (!c) {
+      tally.skipped++;
+      continue;
+    }
+    const outcome = await gate(c);
+    if (outcome.action === "promoted") tally.promoted++;
+    else if (outcome.action === "collapsed") tally.collapsed++;
+    else tally.blocked++;
+  }
+  return tally;
+}
+
+// --- decay support --------------------------------------------------------------
+
+// Active open threads with ts older than `days` days, oldest first (both sides
+// are UTC-Z ISO strings, so plain lexicographic compare is correct).
+export async function findStaleOpen(days: number): Promise<Memory[]> {
+  const cutoff = new Date(Date.now() - days * 86_400_000).toISOString();
+  return (await loadAll())
+    .filter((m) => isActive(m) && m.status === "open" && m.ts < cutoff)
+    .sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+// Shared memory-row enums. Lives outside index.ts so the pure capture core
+// (src/capture.ts) can reference the admissible values without importing the
+// plugin entry. index.ts feeds these into the tool JSON Schemas; capture.ts
+// uses them to prompt and validate.
+export const TYPES = ["decision", "learning", "preference", "blocker", "context", "pattern"] as const;
+export const STATUSES = ["open", "settled"] as const;