opencode-claude-memory 2.0.2 → 2.1.1

package/README.md

@@ -12,7 +12,7 @@ Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Clau
 [![npm downloads](https://img.shields.io/npm/dm/opencode-claude-memory.svg?style=flat-square)](https://www.npmjs.com/package/opencode-claude-memory)
 [![License](https://img.shields.io/npm/l/opencode-claude-memory.svg?style=flat-square)](https://github.com/kuitos/opencode-claude-memory/blob/main/LICENSE)
 
-[Quick Start](#-quick-start) • [How it works](#-how-it-works) • [Configuration](#-configuration) • [Compatibility](#-compatibility-with-claude-code) • [Migrating from v1](#-migrating-from-v1) • [FAQ](#-faq)
+[Quick Start](#-quick-start) • [How it works](#-how-it-works) • [Configuration](#-configuration) • [OpenCode 2.x](#-differences-on-opencode-2x) • [Compatibility](#-compatibility-with-claude-code) • [Migrating from v1](#-migrating-from-v1) • [FAQ](#-faq)
 
 </div>
 
@@ -26,18 +26,28 @@ Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Clau
 - **Auto-dream** — periodic consolidation (merge / prune / rewrite) gated on time and session count, like Claude Code.
 - **Claude Code-compatible** — same directory, same file format, same taxonomy, same worktree handling. `MEMORY.md` is edited line by line so hand-organised indexes stay intact.
 - **Cross-platform, no shell hook** — everything runs inside the OpenCode process through the plugin SDK. No `python3`, no `jq`, no wrapper.
+- **OpenCode 1.x and 2.x** — one package serves both plugin APIs (V1 `server`, V2 `setup`) with the same options.
 
 ## 🚀 Quick Start
 
-Requires OpenCode **≥ 1.18**.
+Requires OpenCode **≥ 1.18.29** (V1 plugin API) or OpenCode **2.x** (`@opencode/cli`, tested on 2.0.22). The package exports one `{ id, server, setup }` object: 1.x loads `server`, 2.x loads `setup`; 1.x accepts that dual object only from 1.18.29 on.
 
 ```jsonc
-// opencode.json (project) or ~/.config/opencode/opencode.json (global)
+// OpenCode 1.x — opencode.json (project) or ~/.config/opencode/opencode.json (global)
 {
   "plugin": ["opencode-claude-memory"]
 }
 ```
 
+```jsonc
+// OpenCode 2.x — opencode.json
+{
+  "plugins": [{ "package": "opencode-claude-memory" }]
+}
+```
+
+OpenCode 2.x also accepts (and normalises) the 1.x `plugin` key.
+
 That's it. Start `opencode` and use it as usual. Memories live in `~/.claude/projects/<project>/memory/` (or under `$CLAUDE_CONFIG_DIR`), exactly where Claude Code keeps them.
 
 ## ⚙️ How it works
@@ -55,20 +65,22 @@ graph LR
     C --> M
 ```
 
+The hook names below are OpenCode 1.x's; on 2.x the same steps run on the V2 plugin API, with the differences listed in [Differences on OpenCode 2.x](#-differences-on-opencode-2x).
+
 1. **Recall** — `experimental.chat.messages.transform` starts a selector prefetch for each new user turn (a hidden child session running `opencode-memory-recall`). `experimental.chat.system.transform` waits for it up to `recall.waitMs` (default 1.5 s) and injects the selected memories. Memories already in the conversation are not re-injected; after compaction they can surface again.
 2. **Extraction** — every `session.idle` is debounced (`extract.debounceMs`). The plugin fetches the session's messages, slices them after the per-session watermark, and — only if there is a new user message — runs `opencode-memory-extract` in a child session restricted to `memory_save` / `memory_list` / `memory_read`. On success the watermark advances; if the main agent already saved memory in that stretch the fork is skipped.
 3. **Catch-up** — on start-up the plugin lists the project's sessions and extracts the ones updated after their watermark (at most `extract.catchUpLimit`). This covers "answer, then quit immediately".
 4. **Auto-dream** — after each extracted session the gate is evaluated (`autodream.minHours` since the last pass **and** `autodream.minSessions` extracted since). When it passes, `opencode-memory-dream` runs with all five memory tools. A lock file prevents two OpenCode processes from consolidating at once.
 5. **Ignore memory** — "ignore memory" in a user message switches memory off for the rest of the session (no index, no recall); "use memory again" switches it back on.
 
-State that is private to the plugin (watermarks, auto-dream gate, lock) lives in `<CLAUDE_CONFIG_DIR>/opencode-memory/<project>/`, never inside the Claude Code project directory.
+State that is private to the plugin (watermarks, auto-dream gate, lock and, on OpenCode 2.x, the log file) lives in `<CLAUDE_CONFIG_DIR>/opencode-memory/<project>/`, never inside the Claude Code project directory.
 
 ## 🔧 Configuration
 
-All behaviour is configured through OpenCode's own configuration. There are no `OPENCODE_MEMORY_*` environment variables.
+All behaviour is configured through OpenCode's own configuration. There are no `OPENCODE_MEMORY_*` environment variables. The plugin options are identical on OpenCode 1.x and 2.x; only the surrounding keys differ.
 
 ```jsonc
-// opencode.json
+// opencode.json — OpenCode 1.x
 {
   "plugin": [
     ["opencode-claude-memory", {
@@ -87,10 +99,43 @@ All behaviour is configured through OpenCode's own configuration. There are no `
 
 - Every option above is optional; the values shown are the defaults. Unknown keys are rejected when the plugin loads.
 - When the same plugin is listed in both the global and the project `opencode.json`, OpenCode keeps the **last** declaration (project wins); options are not merged across files.
-- The three agents are registered hidden with a memory-only tool sandbox. Override any field (`model`, `steps`, `temperature`, …) under `agent.<name>`; the plugin fills in the rest.
+- The three agents are registered hidden with a memory-only tool sandbox. On 1.x, override any field (`model`, `steps`, `temperature`, …) under `agent.<name>`; the plugin fills in the rest.
 - `CLAUDE_CONFIG_DIR` is honoured exactly like Claude Code does, and is the only environment variable the plugin reads.
 
-Logs go to the OpenCode service log (`opencode` log directory, service `opencode-claude-memory`).
+```jsonc
+// opencode.json — OpenCode 2.x
+{
+  "plugins": [
+    { "package": "opencode-claude-memory", "options": { "extract": { "debounceMs": 10000 } } }
+  ],
+  "agents": {
+    "opencode-memory-extract": {
+      "model": "opencode/gpt-6-luna",
+      "steps": 20,
+      "permissions": [{ "action": "webfetch", "resource": "*", "effect": "allow" }]
+    }
+  }
+}
+```
+
+- `options` takes the same keys as the 1.x example above.
+- Agent overrides live under `agents.<name>` and use 2.x agent fields (`model`, `steps`, `permissions`, …). The plugin's sandbox rules (`*` deny, then allow for the agent's memory tools) come first and your own `permissions` after them; 2.x applies the last matching rule, so your rule wins.
+- The main agent needs no extra permission on 2.x's default `build` agent, which allows everything. If you restrict permissions (for example `*` → `ask` or `deny`), add `{ "action": "memory_*", "resource": "*", "effect": "allow" }` to your `permissions` so the memory tools are neither blocked nor prompted for.
+
+**Models for the memory agents.** OpenCode Zen's free models (e.g. `opencode/big-pickle`) reject every request whose tool list lacks OpenCode's `shell` tool (HTTP 403, *"OpenCode's free tier can only be used from within OpenCode"*). The sandboxed extraction and auto-dream forks are exactly such requests on both 1.x and 2.x, and so is recall on 2.x. On a free Zen model, extraction, auto-dream and (on 2.x) recall therefore fail. Configure a paid model for `opencode-memory-extract`, `opencode-memory-dream` and `opencode-memory-recall` (e.g. `opencode/gpt-6-luna`); the main agent can stay on a free model.
+
+**Logs.** On 1.x logs go to the OpenCode service log (`opencode` log directory, service `opencode-claude-memory`). 2.x gives plugins no log API, so the plugin writes `<CLAUDE_CONFIG_DIR>/opencode-memory/<project>/opencode-memory.log` instead (rotated at about 1 MB).
+
+## 🆕 Differences on OpenCode 2.x
+
+The V2 plugin API exposes less than V1, so a few behaviours differ:
+
+- **Extraction only sees messages after the last compaction.** V2 plugins cannot read the full message history. If the extraction watermark was compacted away, extraction restarts from the start of the remaining context; anything before it that was not extracted yet is lost (a warning is logged).
+- **Catch-up only covers known sessions.** V2 plugins cannot list sessions, so start-up catch-up only covers sessions already recorded in `extraction-state.json`. A session created and finished while the plugin was not running is not caught up.
+- **One sandbox layer instead of two.** Forks are restricted by the agents' permission rules (also passed to the fork as session permissions); V2 has no per-prompt tool map.
+- **Recall is a one-shot `generate.text` call** instead of a child session with structured output. The selector's answer is parsed as JSON text, and an answer that does not parse recalls nothing. The recall agent's `model` is used if set; temperature is not configurable.
+- **Logs go to a file** in the plugin state directory, not to the OpenCode log (see [Logs](#-configuration)).
+- **Free Zen models break recall too**, not only extraction and auto-dream (see [Models for the memory agents](#-configuration)).
 
 ## 🤝 Compatibility with Claude Code
 
@@ -102,7 +147,7 @@ Logs go to the OpenCode service log (`opencode` log directory, service `opencode
 | `MEMORY.md` | one-line pointers, hand-organisable | read with the same truncation rules; written with minimal line-level edits |
 | Sub-directories | `team/x.md` etc. | scanned, recalled and addressable from every tool |
 | System prompt | memory instructions + index + recalled memories | ported sections (`memoryTypes.ts`, `memdir.ts`) |
-| Recall | LLM side query | LLM side query in a hidden child session (`findRelevantMemories.ts` port) |
+| Recall | LLM side query | LLM side query (`findRelevantMemories.ts` port): a hidden child session on 1.x, a `generate.text` call on 2.x |
 | Extraction / auto-dream | after session, gated | after `session.idle` + start-up catch-up, gated the same way |
 
 Memory files written by either tool need no conversion in either direction.
@@ -157,7 +202,7 @@ Everything the environment variables used to control now lives under `extract`,
 
 **Why did my first answer take a moment longer?** The system prompt waits up to `recall.waitMs` for the selector. Set it to `0` to never wait (recalled memories then appear from the second LLM call of a turn onwards).
 
-**Does the extraction fork see my whole conversation?** Only the messages after the last extraction, capped at `extract.maxConversationChars` (newest first). The fork can only call memory tools.
+**Does the extraction fork see my whole conversation?** Only the messages after the last extraction, capped at `extract.maxConversationChars` (newest first); on OpenCode 2.x only those after the last compaction. The fork can only call memory tools.
 
 ## 🧪 Development
 
@@ -170,6 +215,18 @@ bun run typecheck
 bun run build       # emits dist/
 ```
 
+To try an unpublished build, run `bun run build` and point OpenCode at the checkout:
+
+```jsonc
+// OpenCode 1.x — reads package.json "main" (dist/index.js)
+{ "plugin": [["file:///abs/path/to/opencode-claude-memory", { "extract": { "debounceMs": 10000 } }]] }
+```
+
+```jsonc
+// OpenCode 2.x — resolves a directory as <dir>/server or <dir>/index, not via package.json
+{ "plugins": [{ "package": "file:///abs/path/to/opencode-claude-memory/dist" }] }
+```
+
 Releases are cut by semantic-release on push to `main`.
 
 ## 📄 License

package/dist/agents.d.ts

@@ -1,12 +1,10 @@
 import type { MemoryAgents } from "./config.js";
-import type { AgentConfig, PluginConfig } from "./sdk.js";
 export declare const MEMORY_TOOL_NAMES: readonly ["memory_save", "memory_delete", "memory_list", "memory_search", "memory_read"];
-export declare function buildAgentDefaults(agents: MemoryAgents): Record<string, AgentConfig>;
-export declare function mergeAgentConfig(defaults: AgentConfig, user: AgentConfig | undefined): AgentConfig;
-export declare class AgentRegistry {
-    private readonly defaults;
-    private readonly merged;
-    constructor(agents: MemoryAgents);
-    register(config: PluginConfig): void;
-    toolsFor(name: string): Record<string, boolean> | undefined;
-}
+export type MemoryToolName = (typeof MEMORY_TOOL_NAMES)[number];
+export type MemoryAgentDefaults = {
+    prompt: string;
+    temperature?: number;
+    steps?: number;
+    allowedTools: readonly MemoryToolName[];
+};
+export declare function memoryAgentDefaults(agents: MemoryAgents): Record<string, MemoryAgentDefaults>;

package/dist/agents.js

@@ -7,63 +7,24 @@ export const MEMORY_TOOL_NAMES = [
     "memory_search",
     "memory_read",
 ];
-const ALL_MEMORY_TOOLS = Object.fromEntries(MEMORY_TOOL_NAMES.map((name) => [name, true]));
-export function buildAgentDefaults(agents) {
+export function memoryAgentDefaults(agents) {
     return {
         [agents.recall]: {
-            mode: "all",
-            hidden: true,
             temperature: 0,
             prompt: SELECT_MEMORIES_SYSTEM_PROMPT,
-            tools: { "*": false },
+            allowedTools: [],
         },
         [agents.extract]: {
-            mode: "all",
-            hidden: true,
             prompt: EXTRACT_PROMPT,
             // A legitimate extraction is a handful of memory_save calls; the step cap terminates a model
             // that keeps re-saving the same files instead of letting it spin until the timeout (#35).
             steps: 30,
-            tools: { "*": false, memory_save: true, memory_list: true, memory_read: true },
+            allowedTools: ["memory_save", "memory_list", "memory_read"],
         },
         [agents.dream]: {
-            mode: "all",
-            hidden: true,
             prompt: AUTODREAM_PROMPT,
             steps: 60,
-            tools: { "*": false, ...ALL_MEMORY_TOOLS },
+            allowedTools: MEMORY_TOOL_NAMES,
         },
     };
 }
-export function mergeAgentConfig(defaults, user) {
-    if (!user)
-        return { ...defaults };
-    const merged = { ...defaults, ...user };
-    // `maxSteps` is the deprecated spelling of `steps`; a user who only set the old name must not be
-    // overridden by the default `steps`.
-    if (user.steps === undefined && user.maxSteps !== undefined)
-        delete merged.steps;
-    return merged;
-}
-export class AgentRegistry {
-    defaults;
-    merged;
-    constructor(agents) {
-        this.defaults = buildAgentDefaults(agents);
-        this.merged = { ...this.defaults };
-    }
-    // `config` hook: merge defaults under the user's own entries and remember the outcome so forks can
-    // pass the effective tool sandbox explicitly (defence in depth, see forkSession.ts).
-    register(config) {
-        config.agent ??= {};
-        const agent = config.agent;
-        for (const [name, defaults] of Object.entries(this.defaults)) {
-            const merged = mergeAgentConfig(defaults, agent[name]);
-            agent[name] = merged;
-            this.merged[name] = merged;
-        }
-    }
-    toolsFor(name) {
-        return this.merged[name]?.tools;
-    }
-}

package/dist/extraction/ExtractionCoordinator.d.ts

@@ -1,35 +1,32 @@
-import type { AgentRegistry } from "../agents.js";
 import type { MemoryConfig } from "../config.js";
-import { type ChatMessage, type OpencodeClient, type PluginEvent } from "../sdk.js";
+import { type MemoryHost, SDK_READ_TIMEOUT_MS, type TranscriptMessage } from "../host/types.js";
 import type { MemoryStore } from "../store/MemoryStore.js";
 import { type Logger } from "../util/log.js";
 import type { OwnedSessions } from "../util/ownedSessions.js";
 import { AutoDream } from "./autodream.js";
 import { MaintenanceLock } from "./lock.js";
 import { ExtractionStateStore, type SessionExtractionState } from "./state.js";
+export { SDK_READ_TIMEOUT_MS };
 export declare const EXTRACTION_TITLE = "opencode-memory extraction";
 export declare const FORK_GRACE_MS = 60000;
 export declare const MAX_EXTRACTION_FAILURES = 3;
 export declare const MIN_CONVERSATION_CHARS = 20;
-export declare const SDK_READ_TIMEOUT_MS = 30000;
-export declare function sliceNewMessages(messages: readonly ChatMessage[], state: SessionExtractionState | undefined): ChatMessage[];
-export declare function trimIncompleteTail(messages: readonly ChatMessage[]): ChatMessage[];
-export declare function hasExtractableUserMessage(messages: readonly ChatMessage[]): boolean;
-export declare function buildConversationForExtraction(messages: readonly ChatMessage[], maxChars: number): string;
+export declare function sliceNewMessages<M extends TranscriptMessage>(messages: readonly M[], state: SessionExtractionState | undefined): M[];
+export declare function trimIncompleteTail<M extends TranscriptMessage>(messages: readonly M[]): M[];
+export declare function hasExtractableUserMessage(messages: readonly TranscriptMessage[]): boolean;
+export declare function buildConversationForExtraction(messages: readonly TranscriptMessage[], maxChars: number): string;
 export type ExtractionCoordinatorDeps = {
     store: MemoryStore;
     config: MemoryConfig;
-    client: OpencodeClient | undefined;
-    directory: string;
+    host: MemoryHost | undefined;
     owned: OwnedSessions;
-    agents: AgentRegistry;
     log: Logger;
     now?: () => number;
     state?: ExtractionStateStore;
     lock?: MaintenanceLock;
 };
 export declare class ExtractionCoordinator {
-    private readonly deps;
+    protected readonly deps: ExtractionCoordinatorDeps;
     readonly state: ExtractionStateStore;
     readonly autodream: AutoDream | undefined;
     private readonly lock;
@@ -44,7 +41,6 @@ export declare class ExtractionCoordinator {
     private disposed;
     constructor(deps: ExtractionCoordinatorDeps);
     get enabled(): boolean;
-    onEvent(event: PluginEvent): void;
     onSessionIdle(sessionID: string): void;
     onSessionStatus(sessionID: string, status: string): void;
     onSessionDeleted(sessionID: string): void;
@@ -53,6 +49,8 @@ export declare class ExtractionCoordinator {
     idle(): Promise<void>;
     catchUp(): Promise<void>;
     dispose(): void;
+    private updatedSessions;
+    private knownSessions;
     private clearTimer;
     private warnLegacyShellHook;
     private enqueue;

package/dist/extraction/ExtractionCoordinator.js

@@ -1,21 +1,21 @@
-import { roleOf } from "../hooks/messages.js";
-import { unwrapData } from "../sdk.js";
+import { SDK_READ_TIMEOUT_MS } from "../host/types.js";
 import { findLegacyShellHooks } from "../util/legacyShellHook.js";
 import { getErrorMessage } from "../util/log.js";
-import { TimeoutError, withDeadline } from "../util/timeout.js";
+import { TimeoutError } from "../util/timeout.js";
 import { AutoDream } from "./autodream.js";
-import { runForkSession } from "./forkSession.js";
 import { MaintenanceLock } from "./lock.js";
 import { buildExtractionSystemPrompt } from "./prompts.js";
 import { ExtractionStateStore, migrateLegacyAutodreamState } from "./state.js";
+export { SDK_READ_TIMEOUT_MS };
 export const EXTRACTION_TITLE = "opencode-memory extraction";
-// Keep the fork in the owned-session guard past delete: its `session.idle` can arrive after the
-// delete HTTP call resolved and would otherwise trigger an extraction of the fork itself.
+// Keep the fork in the owned-session guard past delete: its idle event can arrive after the delete
+// call resolved and would otherwise trigger an extraction of the fork itself.
 export const FORK_GRACE_MS = 60_000;
 export const MAX_EXTRACTION_FAILURES = 3;
 export const MIN_CONVERSATION_CHARS = 20;
-// Deadline for the plain SDK reads (`session.messages`, `session.list`); see util/timeout.ts.
-export const SDK_READ_TIMEOUT_MS = 30_000;
+function roleOf(message) {
+    return String(message.info?.role ?? "");
+}
 function messageTime(message) {
     const time = message.info?.time;
     return {
@@ -53,10 +53,7 @@ export function hasExtractableUserMessage(messages) {
     return messages.some((message) => {
         if (roleOf(message) !== "user" || !Array.isArray(message.parts))
             return false;
-        return message.parts.some((part) => {
-            const p = part;
-            return p.type === "text" && typeof p.text === "string" && p.text.trim().length > 0 && !p.synthetic;
-        });
+        return message.parts.some((p) => p.type === "text" && typeof p.text === "string" && p.text.trim().length > 0 && !p.synthetic);
     });
 }
 export function buildConversationForExtraction(messages, maxChars) {
@@ -65,8 +62,7 @@ export function buildConversationForExtraction(messages, maxChars) {
         const role = roleOf(message);
         if (!role || !Array.isArray(message.parts))
             continue;
-        for (const part of message.parts) {
-            const p = part;
+        for (const p of message.parts) {
             if (p.type === "text" && typeof p.text === "string" && !p.synthetic) {
                 lines.push(`### ${role === "user" ? "User" : "Assistant"}\n${p.text}`);
             }
@@ -102,20 +98,12 @@ export class ExtractionCoordinator {
         this.now = deps.now ?? Date.now;
         this.state = deps.state ?? new ExtractionStateStore(deps.store.stateDir, this.now);
         this.lock = deps.lock ?? new MaintenanceLock(this.state.lockPath, this.now);
-        this.autodream = deps.client
-            ? new AutoDream({ ...deps, client: deps.client, state: this.state, now: this.now, lock: this.lock })
+        this.autodream = deps.host
+            ? new AutoDream({ ...deps, host: deps.host, state: this.state, now: this.now, lock: this.lock })
             : undefined;
     }
     get enabled() {
-        return this.deps.config.extract.enabled && this.deps.client !== undefined;
-    }
-    onEvent(event) {
-        if (event.type === "session.idle")
-            this.onSessionIdle(event.properties.sessionID);
-        else if (event.type === "session.deleted")
-            this.onSessionDeleted(event.properties.info.id);
-        else if (event.type === "session.status")
-            this.onSessionStatus(event.properties.sessionID, event.properties.status.type);
+        return this.deps.config.extract.enabled && this.deps.host !== undefined;
     }
     onSessionIdle(sessionID) {
         if (!this.enabled || this.disposed || !sessionID)
@@ -147,6 +135,18 @@ export class ExtractionCoordinator {
         this.clearTimer(sessionID);
         this.busy.delete(sessionID);
         this.savedByMainAgent.delete(sessionID);
+        // A deleted session never needs catching up: hosts that cannot list sessions (V2) would otherwise
+        // keep spending catch-up slots and a failing transcript read on it until the 30-day prune.
+        if (!this.state.getSession(sessionID))
+            return;
+        try {
+            this.state.update((data) => {
+                delete data.sessions[sessionID];
+            });
+        }
+        catch {
+            // best-effort: the entry is pruned with the session TTL anyway
+        }
     }
     // memory_save reports every write. Inside an extraction fork the list of files saved so far is
     // returned so the tool result can carry the done-signal (#35); a save by the main agent marks the
@@ -177,8 +177,8 @@ export class ExtractionCoordinator {
         if (this.caughtUp || !this.enabled)
             return;
         this.caughtUp = true;
-        const { client, config, directory, store, log } = this.deps;
-        if (!client)
+        const { host, config, store, log } = this.deps;
+        if (!host)
             return;
         this.warnLegacyShellHook();
         migrateLegacyAutodreamState(this.state, `${store.claudeConfigDir}/opencode-memory`, [
@@ -190,33 +190,46 @@ export class ExtractionCoordinator {
             return;
         let sessions;
         try {
-            sessions =
-                unwrapData(await withDeadline("session.list", SDK_READ_TIMEOUT_MS, (signal) => client.session.list({ query: { directory }, signal }))) ?? [];
+            sessions = await host.listSessions();
         }
         catch (error) {
             log("warn", "Extraction catch-up could not list sessions", { error: getErrorMessage(error) });
             return;
         }
-        const pending = sessions
+        const pending = sessions === undefined ? this.knownSessions() : this.updatedSessions(sessions);
+        for (const sessionID of pending.slice(0, config.extract.catchUpLimit))
+            await this.enqueue(sessionID);
+    }
+    dispose() {
+        this.disposed = true;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        this.busy.clear();
+    }
+    // Listed sessions whose last update is newer than their watermark, newest first.
+    updatedSessions(sessions) {
+        return sessions
             .filter((session) => !session.parentID && !this.deps.owned.has(session.id))
             .filter((session) => {
             const known = this.state.getSession(session.id);
             // Compare against the watermark *message* time, not the fork's finish time: a turn that
             // completed while the previous fork was running must still be caught up.
             const boundary = known?.lastMessageAt ?? known?.updatedAt ?? 0;
-            return (session.time?.updated ?? 0) > boundary;
+            return (session.updatedAt ?? 0) > boundary;
         })
-            .sort((a, b) => (b.time?.updated ?? 0) - (a.time?.updated ?? 0))
-            .slice(0, config.extract.catchUpLimit);
-        for (const session of pending)
-            await this.enqueue(session.id);
+            .sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+            .map((session) => session.id);
     }
-    dispose() {
-        this.disposed = true;
-        for (const timer of this.timers.values())
-            clearTimeout(timer);
-        this.timers.clear();
-        this.busy.clear();
+    // Hosts that cannot list sessions: re-check the sessions extraction-state.json knows about, most
+    // recently extracted first. A session without new messages costs one transcript read.
+    knownSessions() {
+        const known = this.state.read().sessions;
+        return Object.entries(known)
+            .filter(([id]) => !this.deps.owned.has(id))
+            .sort(([, a], [, b]) => Math.max(b.lastMessageAt ?? 0, b.attemptedAt ?? 0, b.updatedAt) -
+            Math.max(a.lastMessageAt ?? 0, a.attemptedAt ?? 0, a.updatedAt))
+            .map(([id]) => id);
     }
     clearTimer(sessionID) {
         const existing = this.timers.get(sessionID);
@@ -274,8 +287,8 @@ export class ExtractionCoordinator {
         return advanced;
     }
     async runIncremental(sessionID) {
-        const { client, config, store, directory, owned, agents, log } = this.deps;
-        if (!client || this.disposed || this.inFlight.has(sessionID))
+        const { host, config, store, owned, log } = this.deps;
+        if (!host || this.disposed || this.inFlight.has(sessionID))
             return;
         // Re-check at dequeue time: the debounce may have fired just before the session went busy, or
         // the session may have started a new turn while this job waited in the queue.
@@ -283,10 +296,16 @@ export class ExtractionCoordinator {
             return;
         this.inFlight.add(sessionID);
         try {
-            const response = await withDeadline("session.messages", SDK_READ_TIMEOUT_MS, (signal) => client.session.messages({ path: { id: sessionID }, query: { directory }, signal }));
-            const messages = unwrapData(response) ?? [];
+            const { messages, truncated } = await host.readTranscript(sessionID, this.state.getSession(sessionID)?.lastExtractedMessageID);
             if (this.busy.has(sessionID))
                 return;
+            if (truncated) {
+                // The host only returns the messages after the last compaction and the watermark message is
+                // gone: extraction continues from the start of what is left, earlier turns are lost.
+                log("warn", "Extraction watermark is no longer in the session context; extracting from its start", {
+                    sessionID,
+                });
+            }
             let snapshot = this.snapshot(messages, this.state.getSession(sessionID));
             if (!snapshot)
                 return;
@@ -320,15 +339,12 @@ export class ExtractionCoordinator {
                     return;
                 }
                 try {
-                    await runForkSession({
-                        client,
-                        directory,
+                    await host.runFork({
                         parentSessionID: sessionID,
                         title: EXTRACTION_TITLE,
                         agent: config.agents.extract,
                         system: buildExtractionSystemPrompt(store.manifest()),
-                        tools: agents.toolsFor(config.agents.extract),
-                        parts: [{ type: "text", text: conversation }],
+                        text: conversation,
                         timeoutMs: config.extract.timeoutMs,
                         onCreated: (forkID) => {
                             owned.add(forkID);

package/dist/extraction/autodream.d.ts

@@ -1,6 +1,5 @@
-import type { AgentRegistry } from "../agents.js";
 import type { MemoryConfig } from "../config.js";
-import type { OpencodeClient } from "../sdk.js";
+import type { MemoryHost } from "../host/types.js";
 import type { MemoryStore } from "../store/MemoryStore.js";
 import { type Logger } from "../util/log.js";
 import type { OwnedSessions } from "../util/ownedSessions.js";
@@ -13,11 +12,9 @@ export declare function shouldRunAutodream(state: AutodreamState, gate: Autodrea
 export type AutoDreamDeps = {
     store: MemoryStore;
     config: MemoryConfig;
-    client: OpencodeClient;
-    directory: string;
+    host: MemoryHost;
     state: ExtractionStateStore;
     owned: OwnedSessions;
-    agents: AgentRegistry;
     log: Logger;
     now?: () => number;
     lock?: MaintenanceLock;

package/dist/extraction/autodream.js

@@ -1,5 +1,4 @@
 import { getErrorMessage } from "../util/log.js";
-import { runForkSession } from "./forkSession.js";
 import { MaintenanceLock } from "./lock.js";
 import { AUTODREAM_PROMPT, AUTODREAM_USER_MESSAGE } from "./prompts.js";
 export const AUTODREAM_TITLE = "opencode-memory auto-dream";
@@ -39,7 +38,7 @@ export class AutoDream {
             this.deps.log("info", "Auto-dream skipped: another process holds the maintenance lock");
             return false;
         }
-        const { client, config, directory, owned, agents, state, log } = this.deps;
+        const { host, config, owned, state, log } = this.deps;
         try {
             // Re-check under the lock: another process may have consolidated while we waited to acquire.
             if (!this.shouldRun())
@@ -49,15 +48,12 @@ export class AutoDream {
                 sessionsSince: autodream.sessionsSince.length,
                 lastConsolidatedAt: autodream.lastConsolidatedAt,
             });
-            await runForkSession({
-                client,
-                directory,
+            await host.runFork({
                 parentSessionID,
                 title: AUTODREAM_TITLE,
                 agent: config.agents.dream,
                 system: AUTODREAM_PROMPT,
-                tools: agents.toolsFor(config.agents.dream),
-                parts: [{ type: "text", text: AUTODREAM_USER_MESSAGE }],
+                text: AUTODREAM_USER_MESSAGE,
                 timeoutMs: config.autodream.timeoutMs,
                 onCreated: (id) => owned.add(id),
                 onFinished: (id) => owned.release(id, AUTODREAM_FORK_GRACE_MS),

package/dist/host/types.d.ts

@@ -0,0 +1,52 @@
+export declare const SDK_READ_TIMEOUT_MS = 30000;
+export type TranscriptPart = {
+    type?: string;
+    text?: string;
+    synthetic?: boolean;
+    tool?: string;
+    state?: {
+        status?: string;
+        output?: string;
+    };
+};
+export type TranscriptMessage = {
+    info: {
+        id: string;
+        role?: string;
+        time?: {
+            created?: number;
+            completed?: number;
+        };
+    };
+    parts?: readonly TranscriptPart[];
+};
+export type Transcript = {
+    messages: TranscriptMessage[];
+    truncated: boolean;
+};
+export type SessionSummary = {
+    id: string;
+    parentID?: string;
+    updatedAt?: number;
+};
+export type ForkCleanupStage = "abort" | "delete";
+export type ForkInput = {
+    agent: string;
+    title: string;
+    system?: string;
+    text: string;
+    parentSessionID?: string;
+    timeoutMs: number;
+    onCreated?: (forkID: string) => void;
+    onFinished?: (forkID: string) => void;
+    onCleanupFailed?: (forkID: string, stage: ForkCleanupStage, error: unknown) => void;
+};
+export type GenerateInput = ForkInput & {
+    schema?: Record<string, unknown>;
+};
+export interface MemoryHost {
+    readTranscript(sessionID: string, afterMessageID?: string): Promise<Transcript>;
+    listSessions(): Promise<SessionSummary[] | undefined>;
+    runFork(input: ForkInput): Promise<void>;
+    generate(input: GenerateInput): Promise<string>;
+}

package/dist/host/types.js

@@ -0,0 +1,6 @@
+// The capabilities the coordinators need from the OpenCode host. Each host generation (V1 `server`,
+// V2 `setup`) implements it in its own adapter under src/host/<version>/; nothing outside src/host
+// knows which SDK it runs on. Differences that cannot be papered over are part of the return values
+// (`truncated`, `listSessions() === undefined`) so the coordinators know which guarantees they have.
+// Deadline for plain SDK reads (transcript, session list); see util/timeout.ts.
+export const SDK_READ_TIMEOUT_MS = 30_000;

package/dist/host/v1/agents.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryAgents } from "../../config.js";
+import type { AgentConfig, PluginConfig } from "./sdk.js";
+export declare function buildAgentDefaults(agents: MemoryAgents): Record<string, AgentConfig>;
+export declare function mergeAgentConfig(defaults: AgentConfig, user: AgentConfig | undefined): AgentConfig;
+export declare class AgentRegistry {
+    private readonly defaults;
+    private readonly merged;
+    constructor(agents: MemoryAgents);
+    register(config: PluginConfig): void;
+    toolsFor(name: string): Record<string, boolean> | undefined;
+}