opencode-claude-memory 1.7.7 → 1.7.8

package/README.md

@@ -2,9 +2,9 @@
 
 # 🧠 Claude Code-compatible memory for OpenCode
 
-**Persistent, local-first shared memory for OpenCode and Claude Code — zero config and no migration required.**
+**Persistent, local-first shared memory for OpenCode and Claude Code — one plugin, zero migration.**
 
-This OpenCode memory plugin lets OpenCode read and write Claude Code-compatible Markdown memory files, so both CLIs share the same project context.
+This OpenCode plugin lets OpenCode read and write Claude Code-compatible Markdown memory files, so both CLIs share the same project context.
 
 Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Claude Code reads it.
 
@@ -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) • [Why this exists](#-why-this-exists) • [What makes this different](#-what-makes-this-different) • [How it works](#-how-it-works) • [Who this is for](#-who-this-is-for) • [FAQ](#-faq)
+[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)
 
 </div>
 
@@ -20,229 +20,95 @@ Claude Code writes memory → OpenCode reads it. OpenCode writes memory → Clau
 
 ## ✨ At a glance
 
-- **OpenCode plugin for Claude Code memory**
-  Adds persistent memory tools, system prompt injection, and post-session extraction to OpenCode.
-- **Claude Code-compatible memory**
-  Uses Claude Code’s existing memory paths, file format, and taxonomy.
-- **Zero config**
-  Install + enable plugin, then keep using `opencode` as usual.
-- **Local-first, no migration**
-  Memory stays as local Markdown files in the same directory Claude Code already uses.
-- **Auto-dream consolidation**
-  Periodically runs a background memory consolidation pass (Claude-style auto-dream gating).
+- **Memory tools** — `memory_save` / `memory_delete` / `memory_list` / `memory_search` / `memory_read`, plus the Claude Code memory instructions injected into every system prompt.
+- **LLM recall** — before each turn a hidden agent picks the memories relevant to the query; they appear in the *first* LLM call, including single-step questions.
+- **Automatic extraction** — after a session goes idle, a sandboxed fork reviews only the *new* part of the conversation and saves what is worth keeping. Sessions closed before the fork ran are caught up at the next start.
+- **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.
 
 ## 🚀 Quick Start
 
-### Prerequisites
-
-- `opencode`
-- `python3` available in `PATH`
-
-`python3` is a runtime dependency for the wrapper's scoped session detection and fork cleanup logic.
-If it is missing or not executable, post-session maintenance becomes less reliable: session targeting can fall back to less precise heuristics, and fork cleanup is skipped for safety.
-
-Common install commands:
-
-```bash
-# macOS (Homebrew)
-brew install python
-
-# Ubuntu / Debian
-sudo apt-get update && sudo apt-get install -y python3
-
-# Fedora
-sudo dnf install -y python3
-
-# Arch Linux
-sudo pacman -S python
-```
-
-### 1. Install
-
-```bash
-npm install -g opencode-claude-memory
-opencode-memory install   # one-time: installs shell hook
-```
-
-This installs:
-- The **plugin** — memory tools + system prompt injection
-- The `opencode-memory` **CLI** — wraps opencode with automatic memory extraction + auto-dream consolidation
-- A **shell hook** — defines an `opencode()` function in your `.zshrc`/`.bashrc` that delegates to `opencode-memory`
-
-If `python3` is not installed yet, install it first using the commands above before enabling the shell hook.
-
-### 2. Configure
+Requires OpenCode **≥ 1.18**.
 
 ```jsonc
-// opencode.json
+// opencode.json (project) or ~/.config/opencode/opencode.json (global)
 {
   "plugin": ["opencode-claude-memory"]
 }
 ```
 
-### 3. Use
-
-```bash
-opencode
-```
-
-That’s it. Memory extraction runs in the background after each session, and auto-dream consolidation is checked with time/session gates.
-
-To uninstall:
-
-```bash
-opencode-memory uninstall   # removes shell hook from .zshrc/.bashrc
-npm uninstall -g opencode-claude-memory
-```
-
-To print the wrapper package version:
-
-```bash
-opencode-memory self -v
-```
-
-This removes the shell hook, the CLI, and the plugin. Your saved memories in `~/.claude/projects/` are **not** deleted.
-
-## 💡 Why this exists
-
-If you use both Claude Code and OpenCode on the same repository, memory often ends up in separate silos.
-
-This project solves that by making OpenCode read and write memory in Claude Code’s existing structure, so your context carries over naturally between both tools.
-
-## 🧩 What makes this different
-
-Most memory plugins introduce a new storage model or migration step.
-
-This one is a **compatibility layer**, not a new memory system:
-
-- same memory directory conventions as Claude Code
-- same Markdown + frontmatter format
-- same memory taxonomy (`user`, `feedback`, `project`, `reference`)
-- same project/worktree resolution behavior
-
-The outcome: **shared context across Claude Code and OpenCode without maintaining two memory systems.**
+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
 
 ```mermaid
 graph LR
-    A[You run opencode] --> B[Shell hook calls opencode-memory]
-    B --> C[opencode-memory finds real binary]
-    C --> D[Runs opencode normally]
-    D --> E[You exit]
-    E --> F[Extract memories if needed]
-    F --> G[Evaluate auto-dream gate]
-    G --> H[Consolidate memories if gate passes]
-    H --> I[Memories saved to ~/.claude/projects/]
+    U[User turn] --> R[Hidden recall agent<br/>selects relevant memories]
+    R --> S[System prompt: instructions + MEMORY.md + recalled memories]
+    S --> A[Main agent answers<br/>memory_* tools available]
+    A --> I[session.idle]
+    I --> E[Extraction fork<br/>new messages only]
+    E --> M[(~/.claude/projects/&lt;project&gt;/memory/)]
+    E --> D{Auto-dream gate}
+    D -->|24h & 5 sessions| C[Consolidation fork]
+    C --> M
 ```
 
-The shell hook defines an `opencode()` function that delegates to `opencode-memory`:
-
-1. Shell function intercepts `opencode` command (higher priority than PATH)
-2. `opencode-memory` finds the real `opencode` binary in PATH
-3. Runs it with all your arguments
-4. After you exit, it checks whether the session already wrote memory files
-5. If needed, it forks the session with a memory extraction prompt
-6. It evaluates the auto-dream gate (default: at least 24h since last consolidation and 5 touched sessions)
-7. If the gate passes, it runs a background consolidation pass to merge/prune memories
-8. Maintenance runs **in the background** unless `OPENCODE_MEMORY_FOREGROUND=1`
-9. Terminal maintenance logs are shown in foreground mode by default, or can be forced on/off with `OPENCODE_MEMORY_TERMINAL_LOG=1|0`
-
-### Runtime dependencies
-
-The wrapper expects `python3` to be available at runtime.
-
-It is used for:
-
-- scoped session selection from `opencode session list`
-- parsing `opencode export` output to resolve session directories
-- safely identifying and cleaning up forked extraction / auto-dream sessions
-
-Without `python3`, the plugin tools still load, but wrapper maintenance is degraded and fork cleanup is intentionally skipped to avoid deleting the wrong session.
-
-### Compatibility details
-
-The implementation ports core logic from Claude Code for path hashing, git-root/worktree handling, memory format, and memory prompting behavior, so both tools can operate on the same files safely.
+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.
 
-Key modules ported from Claude Code's `src/memdir/`:
-
-| Module | Source | Purpose |
-|---|---|---|
-| `memoryScan.ts` | `memoryScan.ts` | Recursive directory scan + frontmatter header parsing |
-| `recall.ts` + `recallSelector.ts` | `findRelevantMemories.ts` | LLM-selected memory recall + selected memory formatting |
-| `prompt.ts` | `memoryTypes.ts` + `memdir.ts` | System prompt sections, type taxonomy, truncation |
-| `memory.ts` | `memdir.ts` | `truncateEntrypoint()` aligned with `truncateEntrypointContent()` |
-
-## 👥 Who this is for
-
-- You use **both Claude Code and OpenCode**.
-- You want **one shared memory context** across both tools.
-- You prefer **file-based, local-first memory** you can inspect in Git/worktrees.
-- You don’t want migration overhead or lock-in.
-
-## ❓ FAQ
-
-### Is this a new memory system?
-
-No. It is a compatibility layer that lets OpenCode use Claude Code-compatible memory layout and conventions.
-
-### Do I need to migrate existing memory?
-
-No migration required. If you already have Claude Code memory files, OpenCode can work with them directly.
-
-### Where is data stored?
-
-In local files under Claude-style project memory directories (for example, under `~/.claude/projects/<project>/memory/`).
-
-### Why file-based memory?
-
-File-based memory is transparent, local-first, easy to inspect/diff/back up, and works naturally with existing developer workflows.
-
-### Can I disable auto extraction?
-
-Yes. Set `OPENCODE_MEMORY_EXTRACT=0`.
-
-### Can I disable auto-dream?
-
-Yes. Set `OPENCODE_MEMORY_AUTODREAM=0`. You can also tune gates with:
-- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS`
-- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS`
+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.
 
 ## 🔧 Configuration
 
-### Environment variables
+All behaviour is configured through OpenCode's own configuration. There are no `OPENCODE_MEMORY_*` environment variables.
 
-- `OPENCODE_MEMORY_EXTRACT` (default `1`): set `0` to disable automatic memory extraction
-- `OPENCODE_MEMORY_FOREGROUND` (default `0`): set `1` to run maintenance in foreground
-- `OPENCODE_MEMORY_TERMINAL_LOG` (default `foreground-only`): set `1` to force terminal logs on, `0` to force them off
-- `OPENCODE_MEMORY_MODEL`: override model used for extraction
-- `OPENCODE_MEMORY_AGENT`: override agent used for extraction
-- `OPENCODE_MEMORY_EXTRACT_TIMEOUT_MS` (default `120000`): positive integer timeout for a native extraction request in milliseconds
-- `OPENCODE_MEMORY_EXTRACT_MAX_STEPS` (default `30`): max agentic steps for a native extraction fork before OpenCode forces a text-only reply; set `0` to remove the cap (the timeout is then the only backstop)
-- `OPENCODE_MEMORY_RECALL_MODEL`: override model used for LLM memory recall selection
-- `OPENCODE_MEMORY_RECALL_AGENT` (default `opencode-memory-recall`): override agent used for LLM memory recall selection
-- `OPENCODE_MEMORY_AUTODREAM` (default `1`): set `0` to disable auto-dream consolidation
-- `OPENCODE_MEMORY_AUTODREAM_MIN_HOURS` (default `24`): min hours between consolidation runs
-- `OPENCODE_MEMORY_AUTODREAM_MIN_SESSIONS` (default `5`): min touched sessions since last consolidation
-- `OPENCODE_MEMORY_AUTODREAM_MODEL`: override model used for auto-dream
-- `OPENCODE_MEMORY_AUTODREAM_AGENT`: override agent used for auto-dream
+```jsonc
+// opencode.json
+{
+  "plugin": [
+    ["opencode-claude-memory", {
+      "extract":   { "enabled": true, "timeoutMs": 120000, "debounceMs": 10000, "maxConversationChars": 60000, "catchUpLimit": 5 },
+      "autodream": { "enabled": true, "minHours": 24, "minSessions": 5, "timeoutMs": 300000 },
+      "recall":    { "enabled": true, "waitMs": 1500, "timeoutMs": 30000, "maxMemories": 5 }
+    }]
+  ],
+  "agent": {
+    "opencode-memory-extract": { "model": "anthropic/claude-haiku-4-5", "steps": 20 },
+    "opencode-memory-recall":  { "model": "anthropic/claude-haiku-4-5" },
+    "opencode-memory-dream":   { "model": "anthropic/claude-sonnet-5" }
+  }
+}
+```
 
-### Logs
+- 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.
+- `CLAUDE_CONFIG_DIR` is honoured exactly like Claude Code does, and is the only environment variable the plugin reads.
 
-Logs are written to `$TMPDIR/opencode-memory-logs/`:
-- `extract-*.log`: automatic memory extraction
-- `dream-*.log`: auto-dream consolidation
+Logs go to the OpenCode service log (`opencode` log directory, service `opencode-claude-memory`).
 
-By default, terminal log lines are only printed when maintenance runs in foreground (`OPENCODE_MEMORY_FOREGROUND=1`). Background runs stay quiet unless you explicitly set `OPENCODE_MEMORY_TERMINAL_LOG=1`.
+## 🤝 Compatibility with Claude Code
 
-### Concurrency safety
+| Aspect | Claude Code | This plugin |
+|---|---|---|
+| Memory directory | `~/.claude/projects/<sanitized canonical git root>/memory/` | identical (`sanitizePath`, worktree → main repo resolution ported byte for byte) |
+| File format | Markdown + `name` / `description` / `type` frontmatter | identical; frontmatter parsed only within the first 30 lines, as in Claude Code |
+| Taxonomy | `user`, `feedback`, `project`, `reference` | identical |
+| `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) |
+| Extraction / auto-dream | after session, gated | after `session.idle` + start-up catch-up, gated the same way |
 
-Lock files prevent concurrent extraction/consolidation runs per project root. Stale locks are cleaned up automatically.
+Memory files written by either tool need no conversion in either direction.
 
 ## 📝 Memory format
 
-Each memory is a Markdown file with YAML frontmatter:
-
 ```markdown
 ---
 name: User prefers terse responses
@@ -256,32 +122,56 @@ Skip post-action summaries. User reads diffs directly.
 **How to apply:** Don't summarize changes at the end of responses.
 ```
 
-Supported memory types:
-- `user`
-- `feedback`
-- `project`
-- `reference`
+## 🔁 Migrating from v1
 
-## 🔧 Tools reference
+v2 removes the shell wrapper, the `opencode-memory` CLI and every `OPENCODE_MEMORY_*` environment variable. Memory files are untouched and need no conversion.
 
-- `memory_save`: save/update a memory
-- `memory_delete`: delete a memory by filename
-- `memory_list`: list memory metadata
-- `memory_search`: search by keyword
-- `memory_read`: read full memory content
+```bash
+# 1. remove the v1 shell hook, then the v1 package (v2 no longer needs a global install)
+opencode-memory uninstall     # or delete the ">>> opencode-memory auto-initialization >>>" block from your rc file
+npm uninstall -g opencode-claude-memory
 
-## 🧪 Development
+# 2. drop OPENCODE_MEMORY_* from your shell configuration
+grep -n OPENCODE_MEMORY ~/.zshrc ~/.bashrc ~/.zshenv ~/.profile 2>/dev/null
+```
 
-```bash
-# Run tests
-bun test
+```jsonc
+// 3. pin the major in opencode.json — OpenCode caches npm plugins per specifier,
+//    so a bare "opencode-claude-memory" keeps serving the v1 it installed earlier
+{
+  "plugin": ["opencode-claude-memory@2"]
+}
+```
 
-# Build published artifacts
-bun run build
+Everything the environment variables used to control now lives under `extract`, `autodream`, `recall` and `agent.opencode-memory-*` in `opencode.json` — see [Configuration](#-configuration). The v1 documentation, including the full list of environment variables, stays available in the [v1 README](https://github.com/kuitos/opencode-claude-memory/blob/v1.7.7/README.md).
 
-# Release: push to main triggers semantic-release → npm publish
+## ❓ FAQ
+
+**Is this a new memory system?** No. It is a compatibility layer around Claude Code's memory layout and conventions.
+
+**Do I need to migrate existing memory?** No. Existing Claude Code memory files are used as they are.
+
+**Where is data stored?** `~/.claude/projects/<project>/memory/` (or `$CLAUDE_CONFIG_DIR/projects/...`). Plugin state lives in `$CLAUDE_CONFIG_DIR/opencode-memory/<project>/`.
+
+**Can I disable extraction, auto-dream or recall?** Yes — `extract.enabled`, `autodream.enabled`, `recall.enabled` in the plugin options.
+
+**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.
+
+## 🧪 Development
+
+```bash
+bun install
+bun test            # unit, integration and eval tests
+bun run evals       # readable task-eval report
+bun run lint        # biome
+bun run typecheck
+bun run build       # emits dist/
 ```
 
+Releases are cut by semantic-release on push to `main`.
+
 ## 📄 License
 
 [MIT](LICENSE) © [kuitos](https://github.com/kuitos)

package/dist/agents.d.ts

@@ -0,0 +1,12 @@
+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;
+}

package/dist/agents.js

@@ -0,0 +1,69 @@
+import { AUTODREAM_PROMPT, EXTRACT_PROMPT } from "./extraction/prompts.js";
+import { SELECT_MEMORIES_SYSTEM_PROMPT } from "./recall/selector.js";
+export const MEMORY_TOOL_NAMES = [
+    "memory_save",
+    "memory_delete",
+    "memory_list",
+    "memory_search",
+    "memory_read",
+];
+const ALL_MEMORY_TOOLS = Object.fromEntries(MEMORY_TOOL_NAMES.map((name) => [name, true]));
+export function buildAgentDefaults(agents) {
+    return {
+        [agents.recall]: {
+            mode: "all",
+            hidden: true,
+            temperature: 0,
+            prompt: SELECT_MEMORIES_SYSTEM_PROMPT,
+            tools: { "*": false },
+        },
+        [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 },
+        },
+        [agents.dream]: {
+            mode: "all",
+            hidden: true,
+            prompt: AUTODREAM_PROMPT,
+            steps: 60,
+            tools: { "*": false, ...ALL_MEMORY_TOOLS },
+        },
+    };
+}
+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/config.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+export declare const MemoryOptionsSchema: z.ZodObject<{
+    extract: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        debounceMs: z.ZodDefault<z.ZodNumber>;
+        maxConversationChars: z.ZodDefault<z.ZodNumber>;
+        catchUpLimit: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        timeoutMs: number;
+        debounceMs: number;
+        maxConversationChars: number;
+        catchUpLimit: number;
+    }, {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        debounceMs?: number | undefined;
+        maxConversationChars?: number | undefined;
+        catchUpLimit?: number | undefined;
+    }>>;
+    autodream: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        minHours: z.ZodDefault<z.ZodNumber>;
+        minSessions: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        timeoutMs: number;
+        minHours: number;
+        minSessions: number;
+    }, {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        minHours?: number | undefined;
+        minSessions?: number | undefined;
+    }>>;
+    recall: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        waitMs: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        maxMemories: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        timeoutMs: number;
+        waitMs: number;
+        maxMemories: number;
+    }, {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        waitMs?: number | undefined;
+        maxMemories?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    extract: {
+        enabled: boolean;
+        timeoutMs: number;
+        debounceMs: number;
+        maxConversationChars: number;
+        catchUpLimit: number;
+    };
+    autodream: {
+        enabled: boolean;
+        timeoutMs: number;
+        minHours: number;
+        minSessions: number;
+    };
+    recall: {
+        enabled: boolean;
+        timeoutMs: number;
+        waitMs: number;
+        maxMemories: number;
+    };
+}, {
+    extract?: {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        debounceMs?: number | undefined;
+        maxConversationChars?: number | undefined;
+        catchUpLimit?: number | undefined;
+    } | undefined;
+    autodream?: {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        minHours?: number | undefined;
+        minSessions?: number | undefined;
+    } | undefined;
+    recall?: {
+        enabled?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        waitMs?: number | undefined;
+        maxMemories?: number | undefined;
+    } | undefined;
+}>;
+export type MemoryOptions = z.infer<typeof MemoryOptionsSchema>;
+export declare const MEMORY_AGENTS: {
+    readonly extract: "opencode-memory-extract";
+    readonly recall: "opencode-memory-recall";
+    readonly dream: "opencode-memory-dream";
+};
+export type MemoryAgents = typeof MEMORY_AGENTS;
+export type MemoryConfig = MemoryOptions & {
+    claudeConfigDir: string;
+    homeDir: string;
+    agents: MemoryAgents;
+};
+export declare class MemoryConfigError extends Error {
+    constructor(message: string);
+}
+export declare function resolveClaudeConfigDir(env?: NodeJS.ProcessEnv): string;
+export declare function parseMemoryOptions(options: unknown): MemoryOptions;
+export declare function parseConfig(options: unknown, env?: NodeJS.ProcessEnv, homeDir?: string): MemoryConfig;

package/dist/config.js

@@ -0,0 +1,79 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const timeoutMs = (fallback) => z.number().int().positive().max(MAX_TIMER_DELAY_MS).default(fallback);
+// Plugin options come from `opencode.json`: `"plugin": [["opencode-claude-memory", { ... }]]`.
+// The schema is strict at every level so a misspelled key fails at plugin load instead of silently
+// falling back to defaults.
+export const MemoryOptionsSchema = z
+    .object({
+    extract: z
+        .object({
+        enabled: z.boolean().default(true),
+        timeoutMs: timeoutMs(120_000),
+        debounceMs: z.number().int().nonnegative().max(MAX_TIMER_DELAY_MS).default(10_000),
+        maxConversationChars: z.number().int().positive().default(60_000),
+        catchUpLimit: z.number().int().nonnegative().default(5),
+    })
+        .strict()
+        .default({}),
+    autodream: z
+        .object({
+        enabled: z.boolean().default(true),
+        minHours: z.number().positive().default(24),
+        minSessions: z.number().int().positive().default(5),
+        timeoutMs: timeoutMs(300_000),
+    })
+        .strict()
+        .default({}),
+    recall: z
+        .object({
+        enabled: z.boolean().default(true),
+        waitMs: z.number().int().nonnegative().max(MAX_TIMER_DELAY_MS).default(1_500),
+        timeoutMs: timeoutMs(30_000),
+        maxMemories: z.number().int().positive().max(20).default(5),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
+// Agent names are fixed. Users customise the agents themselves (`agent.opencode-memory-extract.model`
+// in opencode.json) instead of pointing the plugin at a differently named agent.
+export const MEMORY_AGENTS = {
+    extract: "opencode-memory-extract",
+    recall: "opencode-memory-recall",
+    dream: "opencode-memory-dream",
+};
+export class MemoryConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MemoryConfigError";
+    }
+}
+function formatIssue(issue) {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+    return `${path}: ${issue.message}`;
+}
+// `CLAUDE_CONFIG_DIR` is the only environment variable the plugin reads: it is shared with Claude Code
+// and decides where both tools keep memory. Everything else is plugin options.
+export function resolveClaudeConfigDir(env = process.env) {
+    const raw = env.CLAUDE_CONFIG_DIR?.trim();
+    return (raw ? raw : join(homedir(), ".claude")).normalize("NFC");
+}
+export function parseMemoryOptions(options) {
+    const result = MemoryOptionsSchema.safeParse(options ?? {});
+    if (!result.success) {
+        const issues = result.error.issues.map(formatIssue).join("; ");
+        throw new MemoryConfigError(`opencode-claude-memory: invalid plugin options (${issues})`);
+    }
+    return result.data;
+}
+export function parseConfig(options, env = process.env, homeDir = homedir()) {
+    return {
+        ...parseMemoryOptions(options),
+        claudeConfigDir: resolveClaudeConfigDir(env),
+        homeDir,
+        agents: MEMORY_AGENTS,
+    };
+}