opencode-claude-memory 2.2.0 → 2.3.0

package/README.md

@@ -73,7 +73,7 @@ The hook names below are OpenCode 1.x's; on 2.x the same steps run on the V2 plu
 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 and, on OpenCode 2.x, the log file) 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 under `<CLAUDE_CONFIG_DIR>/opencode-memory/`, never inside the memory directory. The default location is `<project>/`; custom memory directories use the namespaces described below.
 
 ## 🔧 Configuration
 
@@ -102,7 +102,8 @@ All behaviour is configured through OpenCode's own configuration. There are no `
 - 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. 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.
-- `readOnly: true` uses Claude Code's memory without ever writing to the Claude config directory: no `memory_save` / `memory_delete`, no extraction or auto-dream (whatever `extract` / `autodream` say), no plugin state or log file, and the memory folder is not created. The index, recall and `memory_list` / `memory_search` / `memory_read` keep working, and the prompt tells the model the memory is read-only.
+- `readOnly: true` prevents this plugin from writing to the Claude config directory: no `memory_save` / `memory_delete`, no extraction or auto-dream (whatever `extract` / `autodream` say), no plugin state or log writes, and the memory folder is not created. The index, recall and `memory_list` / `memory_search` / `memory_read` keep working, and the prompt tells the model the memory is read-only.
+- This option does not restrict the host's shell or file-editing tools, or other plugins. To enforce read-only access for the entire host, also configure host permissions or filesystem access controls; the memory prompt alone does not enforce it.
 
 ```jsonc
 // opencode.json — OpenCode 2.x
@@ -124,9 +125,28 @@ All behaviour is configured through OpenCode's own configuration. There are no `
 - 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.
 
+**Custom memory directory.** Set `autoMemoryDirectory` in the plugin options to use a fixed memory directory, matching [Claude Code's setting](https://code.claude.com/docs/en/settings-reference#automemorydirectory). For example, on OpenCode 2.x:
+
+```jsonc
+{
+  "plugins": [
+    { "package": "opencode-claude-memory", "options": { "autoMemoryDirectory": "~/shared-memory" } }
+  ]
+}
+```
+
+The same option works in the 1.x plugin options. Configure the same path as `autoMemoryDirectory` in Claude Code's settings to share this store between both tools; this plugin reads OpenCode options, not Claude Code settings files. OpenCode's plugin declaration precedence above still applies.
+
+- The value is the **final memory directory**: `~/shared-memory/MEMORY.md` and its topic files. No project name or `memory/` suffix is appended. All projects configured with the same path share that store; it replaces their default memory directories rather than merging with them. Existing memories are not moved.
+- Path handling matches Claude Code **2.1.292**: expand `~/` (also `~\`), normalise the path and Unicode (NFC), and retain one trailing separator. The directory is not resolved against a Git root. Relative or empty paths, filesystem roots, home-only `~/`, tilde paths escaping the home directory, NUL bytes and network/device roots disable the override and fall back to the default project directory. Whitespace is not trimmed and environment variables are not expanded. Non-string values remain configuration errors.
+- Working directories and session/event handling retain their actual project scope. Watermarks, the auto-dream gate, trash and logs remain project-scoped and are also keyed by the target directory (`<project>/memory-stores/<directory-hash>/`), so switching stores does not reuse another store's watermarks. Within one `CLAUDE_CONFIG_DIR`, extraction and auto-dream targeting the same physical directory share a maintenance lock, including directory symlinks and overrides pointing to a default project store. Auto-dream thresholds remain per project.
+- A symlink alias of this project's default memory directory retains its existing watermarks and auto-dream gate.
+- The memory directory must not equal, contain or reside inside the plugin's private state root (`<CLAUDE_CONFIG_DIR>/opencode-memory/`), including through symlinks. Such a configuration is rejected before creating directories, so deleted-memory backups cannot be scanned as live memories.
+- `readOnly: true` applies to a custom directory too: it is not created, memory writes are disabled, and no plugin state or logs are written.
+
 **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).
+**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 `opencode-memory.log` in its state directory instead (rotated at about 1 MB). This is `<CLAUDE_CONFIG_DIR>/opencode-memory/<project>/` by default, or the custom-store state namespace described above.
 
 ## 🆕 Differences on OpenCode 2.x
 
@@ -143,7 +163,7 @@ The V2 plugin API exposes less than V1, so a few behaviours differ:
 
 | Aspect | Claude Code | This plugin |
 |---|---|---|
-| Memory directory | `~/.claude/projects/<sanitized canonical git root>/memory/` | identical (`sanitizePath`, worktree → main repo resolution ported byte for byte) |
+| Memory directory | `~/.claude/projects/<sanitized canonical git root>/memory/`, or `autoMemoryDirectory` | same default layout and custom-directory path semantics (verified against Claude Code 2.1.292) |
 | File format | Markdown + `name` (kebab-case slug) / `description` / `metadata.type` frontmatter | identical; older top-level `type:` still read; 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, hand-written pointer lines are never replaced |
@@ -203,13 +223,13 @@ Everything the environment variables used to control now lives under `extract`,
 
 **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>/`. Memories the plugin deletes that are not purely its own (Claude Code's, another tool's, or one of its own that another tool has since edited) are copied to `trash/<timestamp>/` there first.
+**Where is data stored?** `~/.claude/projects/<project>/memory/` (or `$CLAUDE_CONFIG_DIR/projects/...`), unless `autoMemoryDirectory` selects a custom store. Plugin state lives under `$CLAUDE_CONFIG_DIR/opencode-memory/`, scoped by project and, for custom stores, target directory. Memories the plugin deletes that are not purely its own (Claude Code's, another tool's, or one of its own that another tool has since edited) are copied to `trash/<timestamp>/` in that state directory first.
 
 **Can I disable extraction, auto-dream or recall?** Yes — `extract.enabled`, `autodream.enabled`, `recall.enabled` in the plugin options.
 
-**Can OpenCode read Claude Code's memory without adding to it?** Yes — `readOnly: true`. Nothing is written under `CLAUDE_CONFIG_DIR`; see [Configuration](#-configuration).
+**Can I make this plugin read Claude Code's memory without changing it?** Yes — `readOnly: true`. The plugin does not write under `CLAUDE_CONFIG_DIR`. Enforcing read-only access for the entire host also requires host permissions or filesystem access controls; see [Configuration](#-configuration).
 
-**My recall model has no structured output.** On 1.x the selector asks for structured output first; when the server answers with a `StructuredOutputError` the plugin retries once with the schema described in the prompt and parses the text, and keeps doing that for the rest of the session.
+**My recall model has no structured output.** On 1.x each selector request asks for structured output first. If the server answers with a `StructuredOutputError`, the plugin retries that request once with the schema described in the prompt and parses the text. Later requests still try structured output: a single failure does not establish that the model lacks support. A model that consistently fails structured output therefore needs two attempts per recall request. Other errors are not retried.
 
 **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).
 

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 export declare const MemoryOptionsSchema: z.ZodObject<{
+    autoMemoryDirectory: z.ZodOptional<z.ZodString>;
     extract: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         timeoutMs: z.ZodDefault<z.ZodNumber>;
@@ -73,7 +74,9 @@ export declare const MemoryOptionsSchema: z.ZodObject<{
         maxMemories: number;
     };
     readOnly: boolean;
+    autoMemoryDirectory?: string | undefined;
 }, {
+    autoMemoryDirectory?: string | undefined;
     extract?: {
         enabled?: boolean | undefined;
         timeoutMs?: number | undefined;

package/dist/config.js

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { z } from "zod";
+import { resolveAutoMemoryDirectory } from "./store/autoMemoryDirectory.js";
 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", { ... }]]`.
@@ -8,6 +9,8 @@ const timeoutMs = (fallback) => z.number().int().positive().max(MAX_TIMER_DELAY_
 // falling back to defaults.
 export const MemoryOptionsSchema = z
     .object({
+    // Final memory directory, with Claude Code's autoMemoryDirectory path semantics.
+    autoMemoryDirectory: z.string().optional(),
     extract: z
         .object({
         enabled: z.boolean().default(true),
@@ -78,6 +81,7 @@ export function parseConfig(options, env = process.env, homeDir = homedir()) {
     const parsed = parseMemoryOptions(options);
     return {
         ...parsed,
+        autoMemoryDirectory: resolveAutoMemoryDirectory(parsed.autoMemoryDirectory, homeDir),
         // Read-only switches off everything that writes, whatever the per-feature options say.
         ...(parsed.readOnly
             ? { extract: { ...parsed.extract, enabled: false }, autodream: { ...parsed.autodream, enabled: false } }

package/dist/extraction/ExtractionCoordinator.js

@@ -98,7 +98,7 @@ export class ExtractionCoordinator {
         this.deps = deps;
         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.lock = deps.lock ?? new MaintenanceLock(deps.store.maintenanceLockPath, this.now);
         this.autodream = deps.host
             ? new AutoDream({ ...deps, host: deps.host, state: this.state, now: this.now, lock: this.lock })
             : undefined;
@@ -192,11 +192,14 @@ export class ExtractionCoordinator {
         if (!host)
             return;
         this.warnLegacyShellHook();
-        migrateLegacyAutodreamState(this.state, `${store.claudeConfigDir}/opencode-memory`, [
-            store.gitRoot ?? store.memoryRoot,
-            store.memoryRoot,
-            store.canonicalRoot,
-        ]);
+        // The old shell hook maintained the default project store, never a custom destination.
+        if (store.usesDefaultMemoryDirectory) {
+            migrateLegacyAutodreamState(this.state, `${store.claudeConfigDir}/opencode-memory`, [
+                store.gitRoot ?? store.memoryRoot,
+                store.memoryRoot,
+                store.canonicalRoot,
+            ]);
+        }
         if (config.extract.catchUpLimit <= 0)
             return;
         let sessions;

package/dist/extraction/autodream.js

@@ -21,7 +21,7 @@ export class AutoDream {
     constructor(deps) {
         this.deps = deps;
         this.now = deps.now ?? Date.now;
-        this.lock = deps.lock ?? new MaintenanceLock(deps.state.lockPath, this.now);
+        this.lock = deps.lock ?? new MaintenanceLock(deps.store.maintenanceLockPath, this.now);
     }
     // Called from the extraction coordinator's persisted update after a session was extracted.
     static noteSession(state, sessionID) {

package/dist/host/v1/host.js

@@ -32,9 +32,6 @@ function isStructuredOutputError(error) {
     return error instanceof ForkSessionError && error.message.includes("StructuredOutputError");
 }
 export function createV1Host({ client, directory, toolsFor }) {
-    // Cleared by the first StructuredOutputError: from then on this host describes the schema in the
-    // prompt and the caller parses the text, as the V2 host always does.
-    let structuredOutput = true;
     return {
         async readTranscript(sessionID) {
             const response = await withDeadline("session.messages", SDK_READ_TIMEOUT_MS, (signal) => client.session.messages({ path: { id: sessionID }, query: { directory }, signal }));
@@ -87,14 +84,15 @@ export function createV1Host({ client, directory, toolsFor }) {
                 onFinished: input.onFinished,
                 onCleanupFailed: input.onCleanupFailed,
             });
-            if (structuredOutput && input.schema) {
+            if (input.schema) {
                 try {
                     return forkAnswerText(await run(true));
                 }
                 catch (error) {
                     if (!isStructuredOutputError(error))
                         throw error;
-                    structuredOutput = false;
+                    // One failed answer does not establish a model capability. Retry only this request as
+                    // text, leaving later requests (in this session or another) free to use structured output.
                 }
             }
             return forkAnswerText(await run(false));

package/dist/store/MemoryStore.d.ts

@@ -22,6 +22,8 @@ export type ListOptions = {
 };
 export type MemoryStoreOptions = {
     claudeConfigDir: string;
+    autoMemoryDirectory?: string;
+    homeDir?: string;
     readOnly?: boolean;
     now?: () => Date;
 };
@@ -32,8 +34,10 @@ export declare class MemoryStore {
     readonly claudeConfigDir: string;
     readonly projectDir: string;
     readonly memoryDir: string;
+    readonly usesDefaultMemoryDirectory: boolean;
     readonly entrypoint: string;
     readonly stateDir: string;
+    readonly maintenanceLockPath: string;
     readonly readOnly: boolean;
     private readonly now;
     constructor(memoryRoot: string, options: MemoryStoreOptions);

package/dist/store/MemoryStore.js

@@ -1,10 +1,29 @@
+import { createHash } from "node:crypto";
 import { cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { writeFileAtomicSync } from "../util/exclusiveFile.js";
+import { resolveAutoMemoryDirectory } from "./autoMemoryDirectory.js";
 import { buildFrontmatter, editFrontmatter, FRONTMATTER_MAX_LINES, frontmatterKeys, ORIGIN, parseFrontmatter, parseMemoryType, } from "./frontmatter.js";
 import { buildIndexPointer, findIndexPointerLine, readIndexFile, removeIndexLine, upsertIndexLine, } from "./indexFile.js";
 import { ENTRYPOINT_NAME, findCanonicalGitRoot, findGitRoot, MAX_MEMORY_FILE_BYTES, resolveMemoryFilePath, sanitizePath, } from "./paths.js";
 import { formatMemoryManifest, nameFromFilename, readMemoryEntry, scanMemoryFiles, } from "./scan.js";
+function realDirectory(directory) {
+    const absolute = resolve(directory);
+    try {
+        // Filesystems such as ext4 can keep canonically equivalent Unicode names distinct.
+        return realpathSync.native(absolute);
+    }
+    catch {
+        // Resolve existing ancestors too: read-only stores and private state may not exist yet,
+        // but their parents can still contain symlinks.
+        const parent = dirname(absolute);
+        return parent === absolute ? absolute : join(realDirectory(parent), basename(absolute));
+    }
+}
+function containsDirectory(root, directory) {
+    const fromRoot = relative(root, directory);
+    return fromRoot === "" || (!isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`));
+}
 // Owns the resolved memory paths for one project. Path resolution (git root, worktree canonical
 // root, sanitised project key) happens exactly once, in the constructor.
 export class MemoryStore {
@@ -14,10 +33,13 @@ export class MemoryStore {
     claudeConfigDir;
     projectDir;
     memoryDir;
+    usesDefaultMemoryDirectory;
     entrypoint;
     // Plugin-private state (extraction watermarks, auto-dream gate) lives next to, not inside, the
     // Claude Code project directory so Claude Code never sees it.
     stateDir;
+    // Shared by every project targeting this memory directory; watermarks stay project-scoped.
+    maintenanceLockPath;
     readOnly;
     now;
     constructor(memoryRoot, options) {
@@ -29,11 +51,29 @@ export class MemoryStore {
         this.now = options.now ?? (() => new Date());
         const projectKey = sanitizePath(this.canonicalRoot);
         this.projectDir = join(this.claudeConfigDir, "projects", projectKey);
-        this.memoryDir = join(this.projectDir, "memory");
+        const defaultMemoryDir = join(this.projectDir, "memory");
+        this.memoryDir = resolveAutoMemoryDirectory(options.autoMemoryDirectory, options.homeDir ?? "") ?? defaultMemoryDir;
         this.entrypoint = join(this.memoryDir, ENTRYPOINT_NAME);
-        this.stateDir = join(this.claudeConfigDir, "opencode-memory", projectKey);
+        const directory = realDirectory(this.memoryDir);
+        const privateRoot = join(this.claudeConfigDir, "opencode-memory");
+        const privateDirectory = realDirectory(privateRoot);
+        if (containsDirectory(directory, privateDirectory) || containsDirectory(privateDirectory, directory)) {
+            throw new Error(`Memory directory must not overlap the plugin state directory: ${privateRoot}`);
+        }
         if (!this.readOnly)
             mkdirSync(this.memoryDir, { recursive: true });
+        this.usesDefaultMemoryDirectory = directory === realDirectory(defaultMemoryDir);
+        const key = createHash("sha256").update(directory).digest("hex");
+        const projectStateDir = join(privateRoot, projectKey);
+        this.stateDir = this.usesDefaultMemoryDirectory ? projectStateDir : join(projectStateDir, "memory-stores", key);
+        // Recognise the default Claude directory layout too, so an explicit override pointing to
+        // another project's default store shares its existing maintenance lock.
+        const fromProjects = relative(realDirectory(join(this.claudeConfigDir, "projects")), directory);
+        const parts = fromProjects.split(sep);
+        this.maintenanceLockPath =
+            !isAbsolute(fromProjects) && parts.length === 2 && parts[0] !== ".." && parts[1] === "memory"
+                ? join(privateRoot, parts[0] ?? "", "maintenance.lock")
+                : join(privateRoot, "memory-stores", key, "maintenance.lock");
     }
     scan() {
         return scanMemoryFiles(this.memoryDir);

package/dist/store/autoMemoryDirectory.d.ts

@@ -0,0 +1,4 @@
+import * as path from "node:path";
+type DirectoryPaths = Pick<typeof path, "isAbsolute" | "join" | "normalize" | "sep">;
+export declare function resolveAutoMemoryDirectory(value: string | undefined, homeDir: string, paths?: DirectoryPaths): string | undefined;
+export {};

package/dist/store/autoMemoryDirectory.js

@@ -0,0 +1,52 @@
+import * as path from "node:path";
+// Matches Claude Code 2.1.292's custom auto-memory directory resolver: expand only ~/ (or ~\),
+// normalise lexically, reject unsafe roots, then return an NFC path with one trailing separator.
+// No git discovery, realpath, cwd-relative resolution, whitespace trimming or environment expansion.
+// An invalid string disables the override; it does not make the plugin fail to load.
+export function resolveAutoMemoryDirectory(value, homeDir, paths = path) {
+    if (!value)
+        return undefined;
+    let directory = value;
+    if (directory.startsWith("~/") || directory.startsWith("~\\")) {
+        const suffix = directory.slice(2);
+        const relative = paths.normalize(suffix || ".");
+        if (relative === "." ||
+            relative === ".." ||
+            relative.startsWith(`..${paths.sep}`) ||
+            relative.startsWith("../") ||
+            relative.startsWith("..\\")) {
+            return undefined;
+        }
+        directory = paths.join(homeDir, suffix);
+    }
+    const normalized = paths.normalize(directory).replace(/[/\\]+$/, "");
+    if (!paths.isAbsolute(normalized) ||
+        normalized.length < 3 ||
+        /^[A-Za-z]:$/.test(normalized) ||
+        normalized.includes("\0") ||
+        isNetworkOrDevicePath(normalized)) {
+        return undefined;
+    }
+    return `${normalized}${paths.sep}`.normalize("NFC");
+}
+// Claude Code also rejects UNC/NT namespaces, POSIX network automounts and macOS filesystem
+// pseudo-paths. These checks apply on every platform, after the platform's path normalisation.
+function isNetworkOrDevicePath(directory) {
+    const ntNamespace = /^[\\/]\?\?[\\/]/;
+    if (/^[\\/]{2}/.test(directory) || ntNamespace.test(directory))
+        return true;
+    if (directory.includes("??") && ntNamespace.test(path.win32.normalize(directory)))
+        return true;
+    if (!directory.startsWith("/"))
+        return false;
+    const parts = directory.split("/").filter(Boolean);
+    const first = parts[0] ?? "";
+    if (first.toLowerCase() === "network" || /^\.(vol|file|nofollow|resolve)$/i.test(first))
+        return true;
+    const fold = (part) => part
+        .replace(/[\u200c-\u200f\u202a-\u202e\u206a-\u206f\ufeff]/g, "")
+        .toUpperCase()
+        .toLowerCase();
+    return ((parts.length >= 2 && fold(first) === "net") ||
+        (parts.length >= 3 && fold(first) === "network" && fold(parts[1] ?? "") === "servers"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "type": "module",
   "description": "OpenCode plugin for Claude Code memory: persistent, local-first shared memory with Claude Code-compatible Markdown files, LLM recall, in-process auto extraction, and auto-dream consolidation",
   "main": "dist/index.js",