opencode-claude-memory 2.1.3 → 2.2.1

package/README.md

@@ -86,7 +86,8 @@ All behaviour is configured through OpenCode's own configuration. There are no `
     ["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 }
+      "recall":    { "enabled": true, "waitMs": 1500, "timeoutMs": 30000, "maxMemories": 5 },
+      "readOnly":  false
     }]
   ],
   "agent": {
@@ -101,6 +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` 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
@@ -205,6 +208,10 @@ Everything the environment variables used to control now lives under `extract`,
 
 **Can I disable extraction, auto-dream or recall?** Yes — `extract.enabled`, `autodream.enabled`, `recall.enabled` in the plugin options.
 
+**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 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).
 
 **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.

package/dist/agents.d.ts

@@ -7,4 +7,4 @@ export type MemoryAgentDefaults = {
     steps?: number;
     allowedTools: readonly MemoryToolName[];
 };
-export declare function memoryAgentDefaults(agents: MemoryAgents): Record<string, MemoryAgentDefaults>;
+export declare function memoryAgentDefaults(agents: MemoryAgents, readOnly?: boolean): Record<string, MemoryAgentDefaults>;

package/dist/agents.js

@@ -7,13 +7,17 @@ export const MEMORY_TOOL_NAMES = [
     "memory_search",
     "memory_read",
 ];
-export function memoryAgentDefaults(agents) {
+export function memoryAgentDefaults(agents, readOnly = false) {
+    const recall = {
+        temperature: 0,
+        prompt: SELECT_MEMORIES_SYSTEM_PROMPT,
+        allowedTools: [],
+    };
+    // Read-only runs no extraction or auto-dream, so their agents (which may write) are not registered.
+    if (readOnly)
+        return { [agents.recall]: recall };
     return {
-        [agents.recall]: {
-            temperature: 0,
-            prompt: SELECT_MEMORIES_SYSTEM_PROMPT,
-            allowedTools: [],
-        },
+        [agents.recall]: recall,
         [agents.extract]: {
             prompt: EXTRACT_PROMPT,
             // A legitimate extraction is a handful of memory_save calls; the step cap terminates a model

package/dist/config.d.ts

@@ -51,6 +51,7 @@ export declare const MemoryOptionsSchema: z.ZodObject<{
         waitMs?: number | undefined;
         maxMemories?: number | undefined;
     }>>;
+    readOnly: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     extract: {
         enabled: boolean;
@@ -71,6 +72,7 @@ export declare const MemoryOptionsSchema: z.ZodObject<{
         waitMs: number;
         maxMemories: number;
     };
+    readOnly: boolean;
 }, {
     extract?: {
         enabled?: boolean | undefined;
@@ -91,6 +93,7 @@ export declare const MemoryOptionsSchema: z.ZodObject<{
         waitMs?: number | undefined;
         maxMemories?: number | undefined;
     } | undefined;
+    readOnly?: boolean | undefined;
 }>;
 export type MemoryOptions = z.infer<typeof MemoryOptionsSchema>;
 export declare const MEMORY_AGENTS: {

package/dist/config.js

@@ -36,6 +36,11 @@ export const MemoryOptionsSchema = z
     })
         .strict()
         .default({}),
+    // Use Claude Code's memory without ever writing to the Claude config directory: no memory_save /
+    // memory_delete tools, no extraction or auto-dream, no plugin state or log files, and the memory
+    // folder is not created. Recall and memory_list / memory_search / memory_read keep working. For
+    // hosts that may read what Claude Code remembers but must not add to it.
+    readOnly: z.boolean().default(false),
 })
     .strict();
 // Agent names are fixed. Users customise the agents themselves (`agent.opencode-memory-extract.model`
@@ -70,8 +75,13 @@ export function parseMemoryOptions(options) {
     return result.data;
 }
 export function parseConfig(options, env = process.env, homeDir = homedir()) {
+    const parsed = parseMemoryOptions(options);
     return {
-        ...parseMemoryOptions(options),
+        ...parsed,
+        // 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 } }
+            : {}),
         claudeConfigDir: resolveClaudeConfigDir(env),
         homeDir,
         agents: MEMORY_AGENTS,

package/dist/extraction/ExtractionCoordinator.js

@@ -136,6 +136,9 @@ export class ExtractionCoordinator {
         this.clearTimer(sessionID);
         this.busy.delete(sessionID);
         this.savedByMainAgent.delete(sessionID);
+        // Existing state may come from an earlier writable run; read-only mode must leave it untouched.
+        if (this.deps.config.readOnly)
+            return;
         // 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))

package/dist/host/generate.d.ts

@@ -0,0 +1,2 @@
+import type { GenerateInput } from "./types.js";
+export declare function buildGeneratePrompt(input: Pick<GenerateInput, "system" | "text" | "schema">): string;

package/dist/host/generate.js

@@ -0,0 +1,7 @@
+export function buildGeneratePrompt(input) {
+    const sections = [input.system?.trim(), input.text];
+    if (input.schema) {
+        sections.push(`Respond with only a JSON object matching this JSON schema, without code fences or commentary:\n${JSON.stringify(input.schema)}`);
+    }
+    return sections.filter((section) => Boolean(section)).join("\n\n");
+}

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

@@ -1,11 +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 buildAgentDefaults(agents: MemoryAgents, readOnly?: boolean): 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);
+    constructor(agents: MemoryAgents, readOnly?: boolean);
     register(config: PluginConfig): void;
     toolsFor(name: string): Record<string, boolean> | undefined;
 }

package/dist/host/v1/agents.js

@@ -1,8 +1,8 @@
 // V1 registration of the hidden memory agents. Users override any field in opencode.json
 // (`agent.opencode-memory-extract.model`, ...); the plugin only fills in what they did not set.
 import { memoryAgentDefaults } from "../../agents.js";
-export function buildAgentDefaults(agents) {
-    return Object.fromEntries(Object.entries(memoryAgentDefaults(agents)).map(([name, defaults]) => {
+export function buildAgentDefaults(agents, readOnly = false) {
+    return Object.fromEntries(Object.entries(memoryAgentDefaults(agents, readOnly)).map(([name, defaults]) => {
         const config = {
             mode: "all",
             hidden: true,
@@ -27,8 +27,8 @@ export function mergeAgentConfig(defaults, user) {
 export class AgentRegistry {
     defaults;
     merged;
-    constructor(agents) {
-        this.defaults = buildAgentDefaults(agents);
+    constructor(agents, readOnly = false) {
+        this.defaults = buildAgentDefaults(agents, readOnly);
         this.merged = { ...this.defaults };
     }
     // `config` hook: merge defaults under the user's own entries and remember the outcome so forks can

package/dist/host/v1/host.js

@@ -1,8 +1,9 @@
 // MemoryHost over the V1 SDK client (`server` plugin entry). Every call keeps the exact SDK traffic
 // the coordinators used to make directly: deadlines, `directory` query and the tool sandbox.
 import { withDeadline } from "../../util/timeout.js";
+import { buildGeneratePrompt } from "../generate.js";
 import { SDK_READ_TIMEOUT_MS } from "../types.js";
-import { runForkSession } from "./fork.js";
+import { ForkSessionError, runForkSession } from "./fork.js";
 import { unwrapData } from "./sdk.js";
 // Structured output when the server produced it, otherwise the text parts of the answer.
 export function forkAnswerText(response) {
@@ -25,6 +26,11 @@ export function forkAnswerText(response) {
         .filter((text) => typeof text === "string")
         .join("\n");
 }
+// A model or provider without structured output fails a json_schema request (the server reports a
+// StructuredOutputError) even though its text answer is fine, so recall silently selected nothing.
+function isStructuredOutputError(error) {
+    return error instanceof ForkSessionError && error.message.includes("StructuredOutputError");
+}
 export function createV1Host({ client, directory, toolsFor }) {
     return {
         async readTranscript(sessionID) {
@@ -58,7 +64,7 @@ export function createV1Host({ client, directory, toolsFor }) {
             });
         },
         async generate(input) {
-            const response = await runForkSession({
+            const run = (structured) => runForkSession({
                 client,
                 directory,
                 parentSessionID: input.parentSessionID,
@@ -66,14 +72,30 @@ export function createV1Host({ client, directory, toolsFor }) {
                 agent: input.agent,
                 system: input.system,
                 tools: toolsFor?.(input.agent) ?? { "*": false },
-                ...(input.schema ? { format: { type: "json_schema", schema: input.schema } } : {}),
-                parts: [{ type: "text", text: input.text }],
+                ...(structured && input.schema ? { format: { type: "json_schema", schema: input.schema } } : {}),
+                parts: [
+                    {
+                        type: "text",
+                        text: structured ? input.text : buildGeneratePrompt({ text: input.text, schema: input.schema }),
+                    },
+                ],
                 timeoutMs: input.timeoutMs,
                 onCreated: input.onCreated,
                 onFinished: input.onFinished,
                 onCleanupFailed: input.onCleanupFailed,
             });
-            return forkAnswerText(response);
+            if (input.schema) {
+                try {
+                    return forkAnswerText(await run(true));
+                }
+                catch (error) {
+                    if (!isStructuredOutputError(error))
+                        throw error;
+                    // 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/host/v1/plugin.js

@@ -18,7 +18,7 @@ export const createMemoryPlugin = (env, homeDir) => async ({ worktree, directory
     const store = new MemoryStore(resolveMemoryRoot(worktree, dir), config);
     const log = createLogger(client, dir);
     const owned = new OwnedSessions();
-    const agents = new AgentRegistry(config.agents);
+    const agents = new AgentRegistry(config.agents, config.readOnly);
     const host = client
         ? createV1Host({ client, directory: dir, toolsFor: (name) => agents.toolsFor(name) })
         : undefined;

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

@@ -7,7 +7,7 @@ export declare const PERMISSIONS_PROBE_AGENT = "opencode-memory-permissions-prob
 export declare function sandboxRules(allowedTools: readonly string[]): PermissionRule[];
 export declare const PROBE_RULES: readonly PermissionRule[];
 export declare function userRules(rules: readonly PermissionRule[], baseline: readonly PermissionRule[]): PermissionRule[];
-export declare function applyMemoryAgents(editor: AgentEditor, agents: MemoryAgents): void;
+export declare function applyMemoryAgents(editor: AgentEditor, agents: MemoryAgents, readOnly?: boolean): void;
 export declare function ownAgentRules(resolved: readonly PermissionRule[], sandbox: readonly PermissionRule[], probe: readonly PermissionRule[]): PermissionRule[] | undefined;
 export declare function forkSessionRules(sandbox: readonly PermissionRule[], resolved: readonly PermissionRule[] | undefined, probe: readonly PermissionRule[] | undefined): {
     rules: PermissionRule[];

package/dist/host/v2/agents.js

@@ -25,7 +25,7 @@ export function userRules(rules, baseline) {
     const base = new Set(baseline.map(ruleKey));
     return rules.filter((rule) => !base.has(ruleKey(rule))).map((rule) => ({ ...rule }));
 }
-export function applyMemoryAgents(editor, agents) {
+export function applyMemoryAgents(editor, agents, readOnly = false) {
     editor.update(BASELINE_PROBE_AGENT, () => { });
     const baseline = (editor.get(BASELINE_PROBE_AGENT)?.permissions ?? []).map((rule) => ({ ...rule }));
     editor.remove(BASELINE_PROBE_AGENT);
@@ -35,7 +35,7 @@ export function applyMemoryAgents(editor, agents) {
         agent.description = "opencode-claude-memory internal: permission probe, never runs";
         agent.permissions = PROBE_RULES.map((rule) => ({ ...rule }));
     });
-    for (const [name, defaults] of Object.entries(memoryAgentDefaults(agents))) {
+    for (const [name, defaults] of Object.entries(memoryAgentDefaults(agents, readOnly))) {
         applyAgent(editor, name, defaults, baseline);
     }
 }

package/dist/host/v2/host.d.ts

@@ -17,7 +17,6 @@ export type V2HostOptions = {
     sandboxFor: (name: string) => PermissionRule[];
     log?: Logger;
 };
-export declare function buildGeneratePrompt(input: Pick<GenerateInput, "system" | "text" | "schema">): string;
 export declare class V2Host implements MemoryHost {
     private readonly options;
     private readonly forkSystems;

package/dist/host/v2/host.js

@@ -1,4 +1,5 @@
 import { withDeadline } from "../../util/timeout.js";
+import { buildGeneratePrompt } from "../generate.js";
 import { SDK_READ_TIMEOUT_MS } from "../types.js";
 import { forkSessionRules, PERMISSIONS_PROBE_AGENT } from "./agents.js";
 import { runV2Fork } from "./fork.js";
@@ -7,13 +8,6 @@ import { toTranscript } from "./transcript.js";
 function bounded(what, timeoutMs, call) {
     return withDeadline(what, timeoutMs, () => call());
 }
-export function buildGeneratePrompt(input) {
-    const sections = [input.system?.trim(), input.text];
-    if (input.schema) {
-        sections.push(`Respond with only a JSON object matching this JSON schema, without code fences or commentary:\n${JSON.stringify(input.schema)}`);
-    }
-    return sections.filter((section) => Boolean(section)).join("\n\n");
-}
 export class V2Host {
     options;
     // Per-fork system prompt, injected by the context hook (V2 prompts carry no system field).

package/dist/host/v2/plugin.js

@@ -41,9 +41,10 @@ export const createV2Setup = (env, homeDir) => async (ctx) => {
     const directory = ctx.location.directory;
     const worktree = ctx.location.project?.directory ?? directory;
     const store = new MemoryStore(resolveMemoryRoot(worktree, directory), config);
-    const log = createFileLogger(store.stateDir);
+    // The log file lives under the Claude config directory, which read-only mode never writes.
+    const log = config.readOnly ? () => { } : createFileLogger(store.stateDir);
     const owned = new OwnedSessions();
-    const defaults = memoryAgentDefaults(config.agents);
+    const defaults = memoryAgentDefaults(config.agents, config.readOnly);
     const host = new V2Host({
         session: ctx.session,
         generateText: (input) => ctx.generate.text(input),
@@ -73,7 +74,7 @@ export const createV2Setup = (env, homeDir) => async (ctx) => {
         }
     };
     const registerHooks = async () => {
-        await register("agent.transform", () => ctx.agent.transform((editor) => applyMemoryAgents(editor, config.agents)));
+        await register("agent.transform", () => ctx.agent.transform((editor) => applyMemoryAgents(editor, config.agents, config.readOnly)));
         await register("tool.transform", () => ctx.tool.transform((editor) => {
             for (const spec of buildMemoryToolSpecs(store, extraction)) {
                 editor.add(toV2Tool(spec));

package/dist/prompt/sections.d.ts

@@ -2,6 +2,7 @@ export declare const FRONTMATTER_EXAMPLE: string[];
 export declare const TYPES_SECTION: string;
 export declare const WHAT_NOT_TO_SAVE: string;
 export declare const WHEN_TO_ACCESS: string;
+export declare const WHEN_TO_ACCESS_READ_ONLY: string;
 export declare const TRUSTING_RECALL: string;
 export declare const PERSISTENCE_SECTION: string;
 export declare function buildSearchingPastContextSection(memoryDir: string, projectDir: string): string[];

package/dist/prompt/sections.js

@@ -102,6 +102,14 @@ export const WHEN_TO_ACCESS = [
     "- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now and answer from that, not from the memory.",
     '- Do not delete a memory because it looks stale or because what it names cannot be found: it may live on another branch, in another checkout or outside the repo, and the note is still history. Update the memory with what you observed instead (e.g. "`scripts/deploy.sh` not found as of 2026-03-05"), so the next session does not repeat the check. Delete a memory only when the user asks you to forget it, or when a corrected or merged memory replaces it.',
 ].join("\n");
+// WHEN_TO_ACCESS for `readOnly`: the same reading rules, without the bullets that edit or delete.
+export const WHEN_TO_ACCESS_READ_ONLY = [
+    "## When to access memories",
+    "- When memories seem relevant, or the user references prior-conversation work.",
+    "- You MUST access memory when the user explicitly asks you to check or recall something.",
+    "- If the user says to *ignore* or *not use* memory: proceed as if MEMORY.md were empty. Do not apply remembered facts, cite, compare against, or mention memory content.",
+    "- Memory records can become stale over time. Use memory as context for what was true at a given point in time. Before answering the user or building assumptions based solely on information in memory records, verify that the memory is still correct and up-to-date by reading the current state of the files or resources. If a recalled memory conflicts with current information, trust what you observe now and answer from that, not from the memory.",
+].join("\n");
 // Port of Claude Code's TRUSTING_RECALL_SECTION from memoryTypes.ts
 export const TRUSTING_RECALL = [
     "## Before recommending from memory",

package/dist/prompt/systemPrompt.d.ts

@@ -4,4 +4,6 @@ export declare const RECALLED_MEMORIES_HEADING = "## Recalled Memories";
 export type BuildMemorySystemPromptOptions = {
     includeIndex?: boolean;
 };
-export declare function buildMemorySystemPrompt(store: Pick<MemoryStore, "memoryDir" | "projectDir" | "readIndex">, recalledMemoriesSection?: string, options?: BuildMemorySystemPromptOptions): string;
+export declare function buildMemorySystemPrompt(store: Pick<MemoryStore, "memoryDir" | "projectDir" | "readIndex"> & {
+    readOnly?: boolean;
+}, recalledMemoriesSection?: string, options?: BuildMemorySystemPromptOptions): string;

package/dist/prompt/systemPrompt.js

@@ -1,6 +1,6 @@
 import { truncateEntrypoint } from "../store/indexFile.js";
 import { ENTRYPOINT_NAME, MAX_ENTRYPOINT_LINES } from "../store/paths.js";
-import { buildSearchingPastContextSection, FRONTMATTER_EXAMPLE, PERSISTENCE_SECTION, TRUSTING_RECALL, TYPES_SECTION, WHAT_NOT_TO_SAVE, WHEN_TO_ACCESS, } from "./sections.js";
+import { buildSearchingPastContextSection, FRONTMATTER_EXAMPLE, PERSISTENCE_SECTION, TRUSTING_RECALL, TYPES_SECTION, WHAT_NOT_TO_SAVE, WHEN_TO_ACCESS, WHEN_TO_ACCESS_READ_ONLY, } from "./sections.js";
 // First line of every system prompt segment this plugin injects. The messages transform uses it to
 // find (and, on ignore-memory turns, strip) the plugin's own segment without guessing from headings.
 export const AUTO_MEMORY_MARKER = "<!-- opencode-claude-memory -->";
@@ -26,29 +26,44 @@ export function buildMemorySystemPrompt(store, recalledMemoriesSection, options
         "- Update memories that turn out to be outdated or wrong, recording what you found; delete one only when the user asks you to forget it or when a corrected or merged memory replaces it",
         "- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.",
     ].join("\n");
-    const lines = [
+    // Read-only (config `readOnly`): how to read the memory, nothing about writing it.
+    const readOnlyLines = [
         AUTO_MEMORY_MARKER,
         "# Auto Memory",
         "",
-        `You have a persistent, file-based memory system at \`${store.memoryDir}\`. This directory already exists — write to it directly (do not run mkdir or check for its existence).`,
+        `You have a persistent, file-based memory system at \`${store.memoryDir}\`, shared with Claude Code. In this session it is read-only: never create, edit or delete anything in that directory, even when the user asks you to remember or forget something — tell them memory is read-only here instead.`,
         "",
-        "You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.",
-        "",
-        "If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.",
-        "",
-        TYPES_SECTION,
-        WHAT_NOT_TO_SAVE,
-        "",
-        howToSave,
-        "",
-        WHEN_TO_ACCESS,
+        WHEN_TO_ACCESS_READ_ONLY,
         "",
         TRUSTING_RECALL,
         "",
-        PERSISTENCE_SECTION,
-        "",
         ...buildSearchingPastContextSection(store.memoryDir, store.projectDir),
     ];
+    const lines = store.readOnly
+        ? readOnlyLines
+        : [
+            AUTO_MEMORY_MARKER,
+            "# Auto Memory",
+            "",
+            `You have a persistent, file-based memory system at \`${store.memoryDir}\`. This directory already exists — write to it directly (do not run mkdir or check for its existence).`,
+            "",
+            "You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.",
+            "",
+            "If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.",
+            "",
+            TYPES_SECTION,
+            WHAT_NOT_TO_SAVE,
+            "",
+            howToSave,
+            "",
+            WHEN_TO_ACCESS,
+            "",
+            TRUSTING_RECALL,
+            "",
+            PERSISTENCE_SECTION,
+            "",
+            ...buildSearchingPastContextSection(store.memoryDir, store.projectDir),
+        ];
     if (includeIndex) {
         const indexContent = store.readIndex();
         if (indexContent.trim()) {
@@ -56,7 +71,9 @@ export function buildMemorySystemPrompt(store, recalledMemoriesSection, options
             lines.push(`## ${ENTRYPOINT_NAME}`, "", truncated);
         }
         else {
-            lines.push(`## ${ENTRYPOINT_NAME}`, "", `Your ${ENTRYPOINT_NAME} is currently empty. When you save new memories, they will appear here.`);
+            lines.push(`## ${ENTRYPOINT_NAME}`, "", store.readOnly
+                ? `${ENTRYPOINT_NAME} is currently empty.`
+                : `Your ${ENTRYPOINT_NAME} is currently empty. When you save new memories, they will appear here.`);
         }
     }
     if (recalledMemoriesSection?.trim()) {

package/dist/recall/selector.js

@@ -16,6 +16,9 @@ export const SELECT_MEMORIES_SCHEMA = {
 };
 export const RECALL_SELECTOR_TITLE = "opencode-memory recall selector";
 function selectedFrom(value) {
+    // A text answer often drops the wrapper object and gives the list alone.
+    if (Array.isArray(value))
+        return value.filter((item) => typeof item === "string");
     if (!value || typeof value !== "object")
         return undefined;
     const selected = value.selected_memories;

package/dist/store/MemoryStore.d.ts

@@ -22,6 +22,7 @@ export type ListOptions = {
 };
 export type MemoryStoreOptions = {
     claudeConfigDir: string;
+    readOnly?: boolean;
     now?: () => Date;
 };
 export declare class MemoryStore {
@@ -33,6 +34,7 @@ export declare class MemoryStore {
     readonly memoryDir: string;
     readonly entrypoint: string;
     readonly stateDir: string;
+    readonly readOnly: boolean;
     private readonly now;
     constructor(memoryRoot: string, options: MemoryStoreOptions);
     scan(): MemoryHeader[];
@@ -44,4 +46,5 @@ export declare class MemoryStore {
     search(query: string): MemoryEntry[];
     readIndex(): string;
     private writeIndex;
+    private assertWritable;
 }

package/dist/store/MemoryStore.js

@@ -18,19 +18,22 @@ export class MemoryStore {
     // 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;
+    readOnly;
     now;
     constructor(memoryRoot, options) {
         this.memoryRoot = memoryRoot;
         this.gitRoot = findGitRoot(memoryRoot);
         this.canonicalRoot = findCanonicalGitRoot(memoryRoot) ?? memoryRoot;
         this.claudeConfigDir = options.claudeConfigDir;
+        this.readOnly = options.readOnly ?? false;
         this.now = options.now ?? (() => new Date());
         const projectKey = sanitizePath(this.canonicalRoot);
         this.projectDir = join(this.claudeConfigDir, "projects", projectKey);
         this.memoryDir = join(this.projectDir, "memory");
         this.entrypoint = join(this.memoryDir, ENTRYPOINT_NAME);
         this.stateDir = join(this.claudeConfigDir, "opencode-memory", projectKey);
-        mkdirSync(this.memoryDir, { recursive: true });
+        if (!this.readOnly)
+            mkdirSync(this.memoryDir, { recursive: true });
     }
     scan() {
         return scanMemoryFiles(this.memoryDir);
@@ -55,6 +58,7 @@ export class MemoryStore {
         return readMemoryEntry(this.memoryDir, relativePath);
     }
     save(input) {
+        this.assertWritable();
         const { relativePath, filePath } = resolveMemoryFilePath(this.memoryDir, input.fileName);
         if (typeof input.name !== "string" || !input.name.trim()) {
             throw new Error("Memory name is required");
@@ -97,6 +101,7 @@ export class MemoryStore {
     // directory, as dsh-unified-memory does, so an auto-dream prune can never silently destroy
     // another tool's work.
     delete(fileName) {
+        this.assertWritable();
         const { relativePath, filePath } = resolveMemoryFilePath(this.memoryDir, fileName);
         const existing = readTextFile(filePath);
         if (existing === null)
@@ -129,6 +134,12 @@ export class MemoryStore {
     writeIndex(content) {
         writeFileAtomicSync(this.entrypoint, content);
     }
+    // Defence in depth: in read-only mode nothing registers a writing tool or runs a writing fork, so
+    // reaching this is a bug, and it must fail rather than touch Claude Code's files.
+    assertWritable() {
+        if (this.readOnly)
+            throw new Error("Memory is read-only (readOnly: true)");
+    }
 }
 // A memory's name and description as the scanner (and `read()`) reports them: missing fields
 // count as their defaults.

package/dist/tools.js

@@ -51,8 +51,10 @@ function str(args, key) {
     const value = args[key];
     return typeof value === "string" ? value : "";
 }
+// The tools that change memory files; a read-only store (config `readOnly`) does not offer them.
+const WRITING_TOOLS = ["memory_save", "memory_delete"];
 export function buildMemoryToolSpecs(store, extraction) {
-    return [
+    const specs = [
         {
             name: "memory_save",
             description: "Save or update a memory for future conversations. " +
@@ -175,4 +177,5 @@ export function buildMemoryToolSpecs(store, extraction) {
             },
         },
     ];
+    return store.readOnly ? specs.filter((spec) => !WRITING_TOOLS.includes(spec.name)) : specs;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-claude-memory",
-  "version": "2.1.3",
+  "version": "2.2.1",
   "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",