opencode-claude-memory 2.0.1 → 2.0.2

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

package/dist/store/MemoryStore.js

@@ -1,7 +1,7 @@
-import { cpSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { cpSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { writeFileAtomicSync } from "../util/exclusiveFile.js";
-import { buildFrontmatter, editFrontmatter, FRONTMATTER_MAX_LINES, ORIGIN, parseFrontmatter, parseMemoryType, } from "./frontmatter.js";
+import { buildFrontmatter, editFrontmatter, FRONTMATTER_MAX_LINES, frontmatterKeys, 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, nameFromFilename, readMemoryEntry, scanMemoryFiles, } from "./scan.js";
@@ -59,6 +59,10 @@ export class MemoryStore {
         if (typeof input.name !== "string" || !input.name.trim()) {
             throw new Error("Memory name is required");
         }
+        // Writes follow links, so a memory file that links to the index would overwrite MEMORY.md itself.
+        if (isLinkTo(filePath, this.entrypoint)) {
+            throw new Error(`Memory "${relativePath}" is a link to ${ENTRYPOINT_NAME}; saving it would overwrite the index`);
+        }
         const existing = readTextFile(filePath);
         const parsed = existing === null ? null : parseFrontmatter(existing);
         const pointer = buildIndexPointer(relativePath, input.name, input.description);
@@ -82,16 +86,17 @@ export class MemoryStore {
         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.
+    // Deleting a memory that is not purely this plugin's (Claude Code's, dsh's, a hand-written one, or
+    // one of ours that another tool has since edited) 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 work.
     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) {
+        if (!isPurelyOwn(existing, filePath)) {
             const stamp = this.now().toISOString().replace(/[:.]/g, "-");
             trashedTo = join(this.stateDir, "trash", stamp, relativePath);
             mkdirSync(dirname(trashedTo), { recursive: true });
@@ -132,6 +137,45 @@ export class MemoryStore {
         return same && indexHasPointer(this.readIndex(), pointer);
     }
 }
+// The frontmatter keys of a memory this plugin creates (buildFrontmatter), each on one line; its own
+// later saves keep exactly this set.
+const OWN_KEYS = ["name", "description", "metadata", "type", "origin", "modified"];
+// How far a file's modification time may sit from this plugin's own `modified` stamp and still count
+// as that write: the stamp is taken just before the write, and filesystems with coarse timestamps
+// (FAT, HFS+) round the modification time down by up to 2 s.
+const OWN_WRITE_SLACK_MS = 2_000;
+// A memory is purely this plugin's when its frontmatter is exactly what this plugin writes, with
+// `origin: opencode`, and the file has not changed since the plugin last wrote it. Other writers are
+// recognised by what they leave: Claude Code's Write and Edit tools keep `origin` but add `node_type`
+// and `originSessionId` and restamp `modified`, other tools add `updatedBy` or keys of their own
+// (or a second `modified`), and an edit that stamps nothing moves the modification time away from
+// our `modified`. Any doubt counts as "not ours": an unneeded copy in the trash is harmless, a
+// missing one loses another tool's work.
+function isPurelyOwn(content, filePath) {
+    const keys = frontmatterKeys(content);
+    if (keys?.length !== OWN_KEYS.length || !OWN_KEYS.every((key) => keys.includes(key)))
+        return false;
+    const { frontmatter } = parseFrontmatter(content);
+    if (frontmatter.origin !== ORIGIN)
+        return false;
+    const stamped = Date.parse(frontmatter.modified ?? "");
+    if (Number.isNaN(stamped))
+        return false;
+    try {
+        return Math.abs(statSync(filePath).mtimeMs - stamped) <= OWN_WRITE_SLACK_MS;
+    }
+    catch {
+        return false;
+    }
+}
+function isLinkTo(path, other) {
+    try {
+        return lstatSync(path).isSymbolicLink() && realpathSync(path) === realpathSync(other);
+    }
+    catch {
+        return false;
+    }
+}
 function readTextFile(path) {
     try {
         return readFileSync(path, "utf-8");

package/dist/store/frontmatter.d.ts

@@ -14,6 +14,7 @@ export type ParsedMemoryFile = {
 };
 export declare function quoteScalar(value: string): string;
 export declare function parseFrontmatter(raw: string): ParsedMemoryFile;
+export declare function frontmatterKeys(raw: string): string[] | undefined;
 export declare function parseFrontmatterHeader(raw: string): {
     frontmatter: Frontmatter;
     hasFrontmatter: boolean;

package/dist/store/frontmatter.js

@@ -72,6 +72,25 @@ export function parseFrontmatter(raw) {
         hasFrontmatter: true,
     };
 }
+// The key of every non-blank frontmatter line, in order and with repeats, which the flat parser
+// above merges away; a line that is not `key: value` (a list item, a comment) yields "". `undefined`
+// when the file has no frontmatter.
+export function frontmatterKeys(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("---"))
+        return undefined;
+    const lines = trimmed.split("\n");
+    const closing = findClosingLine(lines);
+    if (closing === -1)
+        return undefined;
+    return lines
+        .slice(1, closing)
+        .filter((line) => line.trim() !== "")
+        .map((line) => {
+        const colonIdx = line.indexOf(":");
+        return colonIdx === -1 ? "" : line.slice(0, colonIdx).trim();
+    });
+}
 // Header-only variant for the directory scanner: parses the first FRONTMATTER_MAX_LINES lines and
 // never materialises the body. Leading whitespace is dropped before counting lines, exactly as the
 // full parser does, so both entry points agree on every file (leading blank lines included).

package/dist/util/exclusiveFile.d.ts

@@ -1,5 +1,5 @@
 export declare function createExclusiveSync(path: string, content: string): boolean;
-export declare function writeFileAtomicSync(path: string, content: string): void;
+export declare function writeFileAtomicSync(path: string, content: string, rename?: (from: string, to: string) => void): 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, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, linkSync, lstatSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 function errorCode(error) {
     return error?.code;
@@ -43,23 +43,115 @@ 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) {
+// another plugin sharing the memory folder never sees a half-written file. The file's permission
+// bits are carried over, and a symbolic link (a dotfiles-managed MEMORY.md) stays a link: the regular
+// file at the end of its chain is replaced instead. Where a rename cannot do the job it writes in
+// place, which is not atomic but is what `writeFileSync` did before: through a link whose target is
+// missing, is not a regular file or sits in a directory that takes no new files, and, on Windows,
+// over a file another process keeps open. A replaced file is a new inode, so unlike `writeFileSync`
+// it does not keep hard links, owner, ACLs or extended attributes, and write protection on the file
+// itself (rather than on its directory) does not stop it.
+//
+// Callers own containment: the memory store checks memory-file names with `resolveMemoryFilePath`
+// (links must stay inside the memory directory), while MEMORY.md is followed wherever it points.
+export function writeFileAtomicSync(path, content, rename = renameSync) {
+    const link = isSymbolicLink(path);
+    const target = link ? replaceableLinkTarget(path) : path;
+    if (target === undefined) {
+        writeFileSync(path, content, "utf-8");
+        return;
+    }
     mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const mode = existingMode(target);
+    const tmp = `${target}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    try {
+        // Created with the target's mode (the umask can only narrow it), so the new content is never
+        // more readable than the file it replaces, not even for a moment.
+        writeFileSync(tmp, content, { encoding: "utf-8", mode });
+    }
+    catch (error) {
+        unlinkWithRetry(tmp);
+        if (!link || !TEMP_REFUSED_CODES.includes(errorCode(error) ?? ""))
+            throw error;
+        writeFileSync(path, content, "utf-8");
+        return;
+    }
+    let renamed = false;
+    try {
+        if (mode !== undefined)
+            restoreMode(tmp, mode);
+        renamed = renameWithRetry(tmp, target, rename);
+        if (!renamed)
+            writeFileSync(target, content, "utf-8");
+    }
+    finally {
+        if (!renamed)
+            unlinkWithRetry(tmp);
+    }
+}
+// Codes meaning no temp file can be created next to a link's target (a read-only dotfiles directory,
+// /dev): the write then goes through the link instead.
+const TEMP_REFUSED_CODES = ["EACCES", "EPERM", "EROFS"];
+function isSymbolicLink(path) {
     try {
-        writeFileSync(tmp, content, "utf-8");
-        renameSync(tmp, path);
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+// The regular file at the end of a link's chain, which the rename replaces so the link survives.
+// `undefined` when there is none (a dangling link, a link to a device or a directory, or one Bun
+// cannot resolve, e.g. to an unreadable file): the write then goes through the link, which also
+// creates a missing target as `writeFileSync` did. A looping link is replaced like a plain file.
+function replaceableLinkTarget(path) {
+    try {
+        const target = realpathSync(path);
+        return statSync(target).isFile() ? target : undefined;
     }
     catch (error) {
+        return errorCode(error) === "ELOOP" ? path : undefined;
+    }
+}
+function existingMode(path) {
+    try {
+        return statSync(path).mode & 0o7777;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Puts back bits the umask stripped when the temp file was created. Best effort: some mounts (FAT,
+// exFAT or CIFS owned by another user, some FUSE filesystems) refuse chmod, and the file then keeps
+// the mode they give it, as it did before modes were carried over.
+function restoreMode(path, mode) {
+    try {
+        chmodSync(path, mode);
+    }
+    catch {
+        // the mount decides the mode
+    }
+}
+// Windows refuses to replace a file that another process holds open without FILE_SHARE_DELETE, as
+// EPERM, EBUSY or EACCES, usually for a few milliseconds. Elsewhere these codes are permanent
+// (immutable files, sticky directories, ACLs), so they are thrown at once.
+const RENAME_BUSY_CODES = ["EPERM", "EBUSY", "EACCES"];
+const RENAME_ATTEMPTS = 5;
+// False when Windows still refuses after RENAME_ATTEMPTS tries (2, 4, 6 and 8 ms apart).
+function renameWithRetry(tmp, target, rename) {
+    for (let attempt = 1; attempt <= RENAME_ATTEMPTS; attempt++) {
         try {
-            unlinkSync(tmp);
+            rename(tmp, target);
+            return true;
         }
-        catch {
-            // never created
+        catch (error) {
+            if (process.platform !== "win32" || !RENAME_BUSY_CODES.includes(errorCode(error) ?? ""))
+                throw error;
+            if (attempt < RENAME_ATTEMPTS)
+                sleepSync(2 * attempt);
         }
-        throw error;
     }
+    return false;
 }
 export function fileAgeMs(path, now = Date.now()) {
     try {

package/package.json

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