opencode-claude-memory 2.0.0 → 2.0.1

package/README.md

@@ -151,7 +151,7 @@ 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>/`.
+**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 but did not create (Claude Code's, or another tool's) are copied to `trash/<timestamp>/` there first.
 
 **Can I disable extraction, auto-dream or recall?** Yes — `extract.enabled`, `autodream.enabled`, `recall.enabled` in the plugin options.
 

package/dist/store/MemoryStore.d.ts

@@ -12,11 +12,16 @@ export type SaveMemoryResult = {
     fileName: string;
     unchanged: boolean;
 };
+export type DeleteMemoryResult = {
+    deleted: boolean;
+    trashedTo?: string;
+};
 export type ListOptions = {
     sort?: "name" | "mtime";
 };
 export type MemoryStoreOptions = {
     claudeConfigDir: string;
+    now?: () => Date;
 };
 export declare class MemoryStore {
     readonly memoryRoot: string;
@@ -27,13 +32,14 @@ export declare class MemoryStore {
     readonly memoryDir: string;
     readonly entrypoint: string;
     readonly stateDir: string;
+    private readonly now;
     constructor(memoryRoot: string, options: MemoryStoreOptions);
     scan(): MemoryHeader[];
     manifest(): string;
     list(options?: ListOptions): MemoryEntry[];
     read(fileName: string): MemoryEntry | null;
     save(input: SaveMemoryInput): SaveMemoryResult;
-    delete(fileName: string): boolean;
+    delete(fileName: string): DeleteMemoryResult;
     search(query: string): MemoryEntry[];
     readIndex(): string;
     private writeIndex;

package/dist/store/MemoryStore.js

@@ -1,9 +1,10 @@
-import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { buildFrontmatter } from "./frontmatter.js";
+import { writeFileAtomicSync } from "../util/exclusiveFile.js";
+import { buildFrontmatter, editFrontmatter, FRONTMATTER_MAX_LINES, ORIGIN, parseFrontmatter, parseMemoryType, } from "./frontmatter.js";
 import { buildIndexPointer, indexHasPointer, readIndexFile, removeIndexLine, upsertIndexLine } from "./indexFile.js";
 import { ENTRYPOINT_NAME, findCanonicalGitRoot, findGitRoot, MAX_MEMORY_FILE_BYTES, resolveMemoryFilePath, sanitizePath, } from "./paths.js";
-import { formatMemoryManifest, readMemoryEntry, scanMemoryFiles } from "./scan.js";
+import { formatMemoryManifest, nameFromFilename, readMemoryEntry, scanMemoryFiles, } from "./scan.js";
 // 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 {
@@ -17,11 +18,13 @@ 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;
+    now;
     constructor(memoryRoot, options) {
         this.memoryRoot = memoryRoot;
         this.gitRoot = findGitRoot(memoryRoot);
         this.canonicalRoot = findCanonicalGitRoot(memoryRoot) ?? memoryRoot;
         this.claudeConfigDir = options.claudeConfigDir;
+        this.now = options.now ?? (() => new Date());
         const projectKey = sanitizePath(this.canonicalRoot);
         this.projectDir = join(this.claudeConfigDir, "projects", projectKey);
         this.memoryDir = join(this.projectDir, "memory");
@@ -56,29 +59,52 @@ export class MemoryStore {
         if (typeof input.name !== "string" || !input.name.trim()) {
             throw new Error("Memory name is required");
         }
-        const fileContent = `${buildFrontmatter(input)}\n\n${input.content.trim()}\n`;
+        const existing = readTextFile(filePath);
+        const parsed = existing === null ? null : parseFrontmatter(existing);
+        const pointer = buildIndexPointer(relativePath, input.name, input.description);
+        if (parsed !== null && this.isUnchanged(parsed, relativePath, input, pointer)) {
+            return { filePath, fileName: relativePath, unchanged: true };
+        }
+        const modified = this.now().toISOString();
+        const fileContent = existing === null || parsed === null
+            ? `${buildFrontmatter({ ...input, modified })}\n\n${input.content.trim()}\n`
+            : updatedFileContent(existing, parsed, input, modified);
         if (Buffer.byteLength(fileContent, "utf-8") > MAX_MEMORY_FILE_BYTES) {
             throw new Error(`Memory file content exceeds the ${MAX_MEMORY_FILE_BYTES}-byte limit`);
         }
-        const pointer = buildIndexPointer(relativePath, input.name, input.description);
-        if (this.isUnchanged(filePath, fileContent, pointer)) {
-            return { filePath, fileName: relativePath, unchanged: true };
+        // Line-level edits keep every other frontmatter line, so the block can outgrow the window both
+        // this plugin and Claude Code read it in; refuse rather than write a file they would both
+        // treat as having no frontmatter.
+        if (!parseFrontmatter(fileContent).hasFrontmatter) {
+            throw new Error(`Memory "${relativePath}" frontmatter would exceed ${FRONTMATTER_MAX_LINES} lines; trim its frontmatter first`);
         }
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, fileContent, "utf-8");
+        writeFileAtomicSync(filePath, fileContent);
         this.writeIndex(upsertIndexLine(this.readIndex(), relativePath, pointer));
         return { filePath, fileName: relativePath, unchanged: false };
     }
+    // Deleting a memory this plugin did not create (Claude Code's, dsh's, a hand-written one) first
+    // keeps a copy under the plugin's state directory, as dsh-unified-memory does, so an auto-dream
+    // prune can never silently destroy another tool's memory.
     delete(fileName) {
         const { relativePath, filePath } = resolveMemoryFilePath(this.memoryDir, fileName);
+        const existing = readTextFile(filePath);
+        if (existing === null)
+            return { deleted: false };
+        let trashedTo;
+        if (parseFrontmatter(existing).frontmatter.origin !== ORIGIN) {
+            const stamp = this.now().toISOString().replace(/[:.]/g, "-");
+            trashedTo = join(this.stateDir, "trash", stamp, relativePath);
+            mkdirSync(dirname(trashedTo), { recursive: true });
+            cpSync(filePath, trashedTo, { preserveTimestamps: true });
+        }
         try {
             unlinkSync(filePath);
         }
         catch {
-            return false;
+            return { deleted: false };
         }
         this.writeIndex(removeIndexLine(this.readIndex(), relativePath));
-        return true;
+        return trashedTo ? { deleted: true, trashedTo } : { deleted: true };
     }
     search(query) {
         const lowerQuery = query.toLowerCase();
@@ -90,16 +116,39 @@ export class MemoryStore {
         return readIndexFile(this.entrypoint);
     }
     writeIndex(content) {
-        writeFileSync(this.entrypoint, content, "utf-8");
+        writeFileAtomicSync(this.entrypoint, content);
     }
-    isUnchanged(filePath, fileContent, pointer) {
-        try {
-            if (readFileSync(filePath, "utf-8") !== fileContent)
-                return false;
-        }
-        catch {
+    // Unchanged means the same name, description, type and body, whatever else the frontmatter
+    // holds, so an identical re-save neither bumps `modified` nor stamps provenance.
+    isUnchanged(parsed, relativePath, input, pointer) {
+        const { frontmatter, body, hasFrontmatter } = parsed;
+        if (!hasFrontmatter)
             return false;
-        }
-        return indexHasPointer(this.readIndex(), pointer);
+        // Missing fields compare as the defaults the scanner (and `read()`) reports for them.
+        const same = (frontmatter.name ?? nameFromFilename(relativePath)) === input.name &&
+            (frontmatter.description ?? "") === input.description &&
+            (parseMemoryType(frontmatter.type) ?? "user") === input.type &&
+            body.replace(/\r\n/g, "\n") === input.content.trim().replace(/\r\n/g, "\n");
+        return same && indexHasPointer(this.readIndex(), pointer);
     }
 }
+function readTextFile(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+// Updates an existing memory in place: name, description, type and body change, every other
+// frontmatter line is kept. The type and `modified` are written wherever the file already keeps
+// them (top level in older files, under `metadata:` otherwise, both when it has both), and a file
+// this plugin did not create gains `metadata.updatedBy: opencode` while its own `origin` stays.
+function updatedFileContent(existing, parsed, input, modified) {
+    return editFrontmatter(existing, {
+        set: { name: input.name, description: input.description },
+        setWhereExists: { type: input.type, modified },
+        setMeta: parsed.frontmatter.origin === ORIGIN ? {} : { updatedBy: ORIGIN },
+        body: input.content,
+    });
+}

package/dist/store/frontmatter.d.ts

@@ -12,14 +12,25 @@ export type ParsedMemoryFile = {
     body: string;
     hasFrontmatter: boolean;
 };
+export declare function quoteScalar(value: string): string;
 export declare function parseFrontmatter(raw: string): ParsedMemoryFile;
 export declare function parseFrontmatterHeader(raw: string): {
     frontmatter: Frontmatter;
     hasFrontmatter: boolean;
 };
-export declare function buildFrontmatter(input: {
+export declare const ORIGIN = "opencode";
+export type NewMemoryFields = {
     name: string;
     description: string;
     type: MemoryType;
-}): string;
+    modified: string;
+};
+export declare function buildFrontmatter(input: NewMemoryFields): string;
+export type FrontmatterEdits = {
+    set?: Record<string, string>;
+    setWhereExists?: Record<string, string>;
+    setMeta?: Record<string, string>;
+    body?: string;
+};
+export declare function editFrontmatter(content: string, edits: FrontmatterEdits): string;
 export declare function parseMemoryType(raw: string | undefined): MemoryType | undefined;

package/dist/store/frontmatter.js

@@ -10,12 +10,41 @@ function parseFields(lines) {
         if (colonIdx === -1)
             continue;
         const key = line.slice(0, colonIdx).trim();
-        const value = line.slice(colonIdx + 1).trim();
+        const value = unquoteScalar(line.slice(colonIdx + 1).trim());
         if (key && value)
             frontmatter[key] = value;
     }
     return frontmatter;
 }
+// Reads back a quoted YAML scalar (Claude Code and other tools quote values that contain `: `, `#`
+// and the like); plain values are returned as they are.
+function unquoteScalar(raw) {
+    if (raw.length >= 2 && raw.startsWith('"') && raw.endsWith('"')) {
+        try {
+            const value = JSON.parse(raw);
+            if (typeof value === "string")
+                return value;
+        }
+        catch {
+            // Not a JSON-compatible quoted scalar (e.g. `"a" vs "b"` written verbatim): keep it as is.
+            return raw;
+        }
+    }
+    if (raw.length >= 2 && raw.startsWith("'") && raw.endsWith("'"))
+        return raw.slice(1, -1).replace(/''/g, "'");
+    return raw;
+}
+// Quotes a scalar only when YAML would otherwise misread it, so plain values stay plain.
+export function quoteScalar(value) {
+    const needsQuoting = value === "" ||
+        /^-?\d+(\.\d+)?$/.test(value) ||
+        /^(true|false|null|~)$/.test(value) ||
+        /^[\s\-?:,[\]{}#&*!|>'"%@`]/.test(value) ||
+        /[:#]\s|\s#|:$/.test(value) ||
+        value.includes("\n") ||
+        value !== value.trim();
+    return needsQuoting ? JSON.stringify(value) : value;
+}
 function findClosingLine(lines) {
     const limit = Math.min(lines.length, FRONTMATTER_MAX_LINES);
     for (let i = 1; i < limit; i++) {
@@ -51,8 +80,148 @@ export function parseFrontmatterHeader(raw) {
     const { frontmatter, hasFrontmatter } = parseFrontmatter(head);
     return { frontmatter, hasFrontmatter };
 }
+// Provenance written into files this plugin creates or edits, in the same `metadata:` shape that
+// Claude Code and dsh-unified-memory use, so any tool sharing the folder can tell who wrote what.
+export const ORIGIN = "opencode";
+// Frontmatter for a file this plugin creates. The type lives under `metadata:` as Claude Code
+// writes it today; the flat parser above still reads it.
 export function buildFrontmatter(input) {
-    return `---\nname: ${input.name}\ndescription: ${input.description}\ntype: ${input.type}\n---`;
+    return [
+        "---",
+        `name: ${quoteScalar(input.name)}`,
+        `description: ${quoteScalar(input.description)}`,
+        "metadata:",
+        `  type: ${input.type}`,
+        `  origin: ${ORIGIN}`,
+        `  modified: ${input.modified}`,
+        "---",
+    ].join("\n");
+}
+const FENCED_BLOCK = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(\r?\n|$)/;
+function indentOf(line) {
+    return line.length - line.trimStart().length;
+}
+function isKeyLine(line, key) {
+    const trimmed = line.trimStart();
+    if (!trimmed.startsWith(`${key}:`))
+        return false;
+    const next = trimmed[key.length + 1];
+    return next === undefined || /\s/.test(next);
+}
+// Index just past a key line and its continuation lines (more-indented lines, or blank lines
+// followed by more-indented ones).
+function endOfEntry(lines, start) {
+    const base = indentOf(lines[start] ?? "");
+    let end = start + 1;
+    while (end < lines.length) {
+        const line = lines[end] ?? "";
+        if (line.trim() === "") {
+            let next = end + 1;
+            while (next < lines.length && (lines[next] ?? "").trim() === "")
+                next++;
+            if (next < lines.length && indentOf(lines[next] ?? "") > base) {
+                end = next;
+                continue;
+            }
+            break;
+        }
+        if (indentOf(line) <= base)
+            break;
+        end++;
+    }
+    return end;
+}
+function findTopLevel(lines, key) {
+    return lines.findIndex((line) => indentOf(line) === 0 && isKeyLine(line, key));
+}
+function setTopLevel(lines, key, value) {
+    const at = findTopLevel(lines, key);
+    const rendered = `${key}: ${quoteScalar(value)}`;
+    if (at === -1)
+        lines.push(rendered);
+    else
+        lines.splice(at, endOfEntry(lines, at) - at, rendered);
+}
+// The `metadata:` line when it opens a block mapping; `undefined` when it is missing or holds an
+// inline value (a flow map such as `{type: user}`) that block children cannot be added under.
+function metadataBlock(lines) {
+    const at = findTopLevel(lines, "metadata");
+    if (at === -1)
+        return undefined;
+    const inline = (lines[at] ?? "").trimStart().slice("metadata:".length).trim();
+    return inline === "" || inline.startsWith("#") ? at : undefined;
+}
+function metadataChildIndent(lines, at) {
+    const children = lines.slice(at + 1, endOfEntry(lines, at)).filter((line) => line.trim() !== "");
+    return children.length > 0 ? " ".repeat(Math.min(...children.map(indentOf))) : "  ";
+}
+function findMetadataChild(lines, at, key) {
+    const indent = metadataChildIndent(lines, at).length;
+    const end = endOfEntry(lines, at);
+    for (let i = at + 1; i < end; i++) {
+        if (indentOf(lines[i] ?? "") === indent && isKeyLine(lines[i] ?? "", key))
+            return i;
+    }
+    return -1;
+}
+// Sets `metadata.<key>`, adding the block when missing and turning an empty `metadata: {}` into
+// one. Returns false, leaving the lines alone, when `metadata:` is a non-empty inline value.
+function setMetadataKey(lines, key, value) {
+    let at = metadataBlock(lines);
+    if (at === undefined) {
+        const existing = findTopLevel(lines, "metadata");
+        if (existing === -1) {
+            lines.push("metadata:");
+            at = lines.length - 1;
+        }
+        else if (/^metadata:\s*\{\s*\}\s*$/.test((lines[existing] ?? "").trim())) {
+            lines[existing] = "metadata:";
+            at = existing;
+        }
+        else {
+            return false;
+        }
+    }
+    const rendered = `${metadataChildIndent(lines, at)}${key}: ${quoteScalar(value)}`;
+    const hit = findMetadataChild(lines, at, key);
+    if (hit === -1)
+        lines.splice(endOfEntry(lines, at), 0, rendered);
+    else
+        lines.splice(hit, endOfEntry(lines, hit) - hit, rendered);
+    return true;
+}
+// Edits an existing file's frontmatter line by line: only the keys being set are rewritten, and
+// every other line (unknown keys, other tools' provenance, lists, comments) is kept byte for byte.
+// A file without frontmatter gets a new block.
+export function editFrontmatter(content, edits) {
+    const leading = content.length - content.trimStart().length;
+    const text = content.slice(leading);
+    const match = FENCED_BLOCK.exec(text);
+    const lines = match ? (match[1] ?? "").split(/\r?\n/) : [];
+    const newline = match?.[0].includes("\r\n") ? "\r\n" : "\n";
+    for (const [key, value] of Object.entries(edits.set ?? {}))
+        setTopLevel(lines, key, value);
+    for (const [key, value] of Object.entries(edits.setWhereExists ?? {})) {
+        const atTop = findTopLevel(lines, key) !== -1;
+        const meta = metadataBlock(lines);
+        const atMeta = meta !== undefined && findMetadataChild(lines, meta, key) !== -1;
+        if (atTop)
+            setTopLevel(lines, key, value);
+        if (atMeta)
+            setMetadataKey(lines, key, value);
+        if (!atTop && !atMeta && !setMetadataKey(lines, key, value))
+            setTopLevel(lines, key, value);
+    }
+    for (const [key, value] of Object.entries(edits.setMeta ?? {}))
+        setMetadataKey(lines, key, value);
+    const head = ["---", ...lines, "---"].join(newline);
+    const original = match ? text.slice(match[0].length) : text;
+    if (edits.body === undefined)
+        return `${head}${newline}${original}`;
+    // Replaced body: keep the file's own convention of a blank line after the fence and its own
+    // line endings.
+    const gap = !match || /^\r?\n/.test(original) ? newline : "";
+    return `${head}${newline}${gap}${edits.body.trim().replace(/\r?\n/g, newline)}${newline}`;
 }
 export function parseMemoryType(raw) {
     if (!raw)

package/dist/tools.js

@@ -87,11 +87,14 @@ export function buildMemoryTools(store, extraction) {
                 file_name: tool.schema.string().describe(`File name of the memory to delete (${FILE_NAME_HINT})`),
             },
             async execute(args) {
-                const deleted = store.delete(args.file_name);
-                return {
-                    title: args.file_name,
-                    output: deleted ? `Memory "${args.file_name}" deleted.` : `Memory "${args.file_name}" not found.`,
-                };
+                const { deleted, trashedTo } = store.delete(args.file_name);
+                let output = `Memory "${args.file_name}" not found.`;
+                if (deleted) {
+                    output = trashedTo
+                        ? `Memory "${args.file_name}" deleted (a copy was kept at ${trashedTo}).`
+                        : `Memory "${args.file_name}" deleted.`;
+                }
+                return { title: args.file_name, output };
             },
         }),
         memory_list: tool({

package/dist/util/exclusiveFile.d.ts

@@ -1,4 +1,5 @@
 export declare function createExclusiveSync(path: string, content: string): boolean;
+export declare function writeFileAtomicSync(path: string, content: string): void;
 export declare function fileAgeMs(path: string, now?: number): number | undefined;
 export declare function sleepSync(ms: number): void;
 export declare function unlinkWithRetry(path: string, attempts?: number): boolean;

package/dist/util/exclusiveFile.js

@@ -6,7 +6,7 @@
 // Writing the content to a private temp file and hard-linking it into place is atomic: `link(2)`
 // either creates the full file or fails with EEXIST. Filesystems without hard links fall back to `wx`.
 import { randomBytes } from "node:crypto";
-import { linkSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { linkSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 function errorCode(error) {
     return error?.code;
@@ -42,6 +42,25 @@ export function createExclusiveSync(path, content) {
         }
     }
 }
+// Replaces a file's content atomically (temp file + rename), so a reader such as Claude Code or
+// another plugin sharing the memory folder never sees a half-written file.
+export function writeFileAtomicSync(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, content, "utf-8");
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // never created
+        }
+        throw error;
+    }
+}
 export function fileAgeMs(path, now = Date.now()) {
     try {
         return now - statSync(path).mtimeMs;

package/package.json

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