opencode-claude-memory 1.7.7 → 2.0.0

package/dist/store/paths.js

@@ -0,0 +1,187 @@
+// Claude Code compatible memory directory path resolution.
+// Directory: <CLAUDE_CONFIG_DIR>/projects/<sanitizePath(canonicalGitRoot)>/memory/
+// Pure functions only: no directory creation, no environment access. MemoryStore owns the side effects.
+import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+export const ENTRYPOINT_NAME = "MEMORY.md";
+export const MAX_ENTRYPOINT_LINES = 200;
+export const MAX_ENTRYPOINT_BYTES = 25_000;
+export const MAX_MEMORY_FILES = 200;
+export const MAX_MEMORY_FILE_BYTES = 40_000;
+const MAX_SANITIZED_LENGTH = 200;
+// Memory file names may be relative sub-paths (`team/conventions`), matching Claude Code, which reads
+// memory directories recursively. Every segment is validated; the result always uses `/`.
+export function validateMemoryFileName(fileName) {
+    if (typeof fileName !== "string" || fileName.length === 0) {
+        throw new Error("Memory file name cannot be empty");
+    }
+    if (fileName.includes("\0")) {
+        throw new Error(`Memory file name must not contain null bytes: ${fileName}`);
+    }
+    if (isAbsolute(fileName) || /^[A-Za-z]:/.test(fileName) || /^[\\/]/.test(fileName)) {
+        throw new Error(`Memory file name must be relative to the memory directory: ${fileName}`);
+    }
+    const segments = fileName.split(/[\\/]/);
+    const last = segments.length - 1;
+    for (let i = 0; i < segments.length; i++) {
+        let segment = segments[i] ?? "";
+        if (i === last && segment.endsWith(".md"))
+            segment = segment.slice(0, -3);
+        if (segment.length === 0) {
+            throw new Error(`Memory file name must not contain empty path segments: ${fileName}`);
+        }
+        if (segment === "." || segment.includes("..")) {
+            throw new Error(`Memory file name must not contain path traversal: ${fileName}`);
+        }
+        if (segment.startsWith(".")) {
+            throw new Error(`Memory file name segments must not start with '.': ${fileName}`);
+        }
+        segments[i] = segment;
+    }
+    if ((segments[last] ?? "").toUpperCase() === "MEMORY") {
+        throw new Error("'MEMORY' is a reserved name and cannot be used as a memory file name");
+    }
+    return `${segments.join("/")}.md`;
+}
+function canonical(path) {
+    try {
+        return realpathSync.native(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+function existsNoFollow(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isInside(path, root) {
+    return path === root || path.startsWith(root + sep);
+}
+// Validates the name and resolves it inside `memoryDir`, refusing anything that escapes it.
+//
+// Lexical containment (`resolve` + prefix) is not enough once sub-directories are allowed: a
+// symbolic link inside the memory directory (`team -> /elsewhere`) would let `team/x` read, overwrite
+// or delete a file outside it. The deepest existing path component is therefore resolved through
+// the filesystem and must land inside the *real* memory directory. Links that stay inside the
+// memory directory are fine; a dangling link is rejected because writing through it would create
+// a file wherever it points.
+export function resolveMemoryFilePath(memoryDir, fileName) {
+    const relativePath = validateMemoryFileName(fileName);
+    const root = resolve(memoryDir);
+    const filePath = resolve(root, ...relativePath.split("/"));
+    if (!filePath.startsWith(root + sep)) {
+        throw new Error(`Memory file name resolves outside the memory directory: ${fileName}`);
+    }
+    const realRoot = canonical(root);
+    if (realRoot !== undefined) {
+        let probe = filePath;
+        while (probe !== root && !existsNoFollow(probe))
+            probe = dirname(probe);
+        const realProbe = canonical(probe);
+        if (realProbe === undefined || !isInside(realProbe, realRoot)) {
+            throw new Error(`Memory file name resolves outside the memory directory: ${fileName}`);
+        }
+    }
+    return { relativePath, filePath };
+}
+// Exact copy of Claude Code's djb2Hash() from utils/hash.ts
+function djb2Hash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+    }
+    return hash;
+}
+function simpleHash(str) {
+    return Math.abs(djb2Hash(str)).toString(36);
+}
+// Exact copy of Claude Code's sanitizePath() from utils/sessionStoragePortable.ts
+export function sanitizePath(name) {
+    const sanitized = name.replace(/[^a-zA-Z0-9]/g, "-");
+    if (sanitized.length <= MAX_SANITIZED_LENGTH) {
+        return sanitized;
+    }
+    const hash = simpleHash(name);
+    return `${sanitized.slice(0, MAX_SANITIZED_LENGTH)}-${hash}`;
+}
+// Matches Claude Code's findGitRoot() from utils/git.ts
+export function findGitRoot(startPath) {
+    let current = resolve(startPath);
+    const root = current.substring(0, current.indexOf(sep) + 1) || sep;
+    while (current !== root) {
+        try {
+            const gitPath = join(current, ".git");
+            const s = statSync(gitPath);
+            if (s.isDirectory() || s.isFile()) {
+                return current.normalize("NFC");
+            }
+        }
+        catch { }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    try {
+        const gitPath = join(root, ".git");
+        const s = statSync(gitPath);
+        if (s.isDirectory() || s.isFile()) {
+            return root.normalize("NFC");
+        }
+    }
+    catch { }
+    return null;
+}
+// Matches Claude Code's resolveCanonicalRoot() from utils/git.ts
+// Resolves worktrees to the main repo root via .git -> gitdir -> commondir chain
+function resolveCanonicalRoot(gitRoot) {
+    try {
+        const gitContent = readFileSync(join(gitRoot, ".git"), "utf-8").trim();
+        if (!gitContent.startsWith("gitdir:")) {
+            return gitRoot;
+        }
+        const worktreeGitDir = resolve(gitRoot, gitContent.slice("gitdir:".length).trim());
+        const commonDir = resolve(worktreeGitDir, readFileSync(join(worktreeGitDir, "commondir"), "utf-8").trim());
+        // SECURITY: validate worktreeGitDir is a direct child of <commonDir>/worktrees/
+        if (resolve(dirname(worktreeGitDir)) !== join(commonDir, "worktrees")) {
+            return gitRoot;
+        }
+        // SECURITY: validate gitdir back-link points to our .git
+        const backlink = realpathSync(readFileSync(join(worktreeGitDir, "gitdir"), "utf-8").trim());
+        if (backlink !== join(realpathSync(gitRoot), ".git")) {
+            return gitRoot;
+        }
+        // `commondir` is written by git with `/` separators even on Windows, so both the platform
+        // separator and `/` are checked (they are the same check on POSIX).
+        if (commonDir.endsWith(`${sep}.git`) || commonDir.endsWith("/.git")) {
+            return dirname(commonDir).normalize("NFC");
+        }
+        return commonDir.normalize("NFC");
+    }
+    catch {
+        return gitRoot;
+    }
+}
+export function findCanonicalGitRoot(startPath) {
+    const root = findGitRoot(startPath);
+    if (!root)
+        return null;
+    return resolveCanonicalRoot(root);
+}
+export function isRootPath(path) {
+    const resolved = resolve(path);
+    return resolved === parse(resolved).root;
+}
+// OpenCode reports worktree "/" for directories outside any git repository; fall back to the
+// directory so memory is not shared by every non-git project on the machine.
+export function resolveMemoryRoot(worktree, directory) {
+    if (isRootPath(worktree) && !isRootPath(directory))
+        return directory;
+    return worktree;
+}

package/dist/store/scan.d.ts

@@ -0,0 +1,29 @@
+import { type MemoryType } from "./frontmatter.js";
+export type MemoryHeader = {
+    filename: string;
+    filePath: string;
+    mtimeMs: number;
+    name: string;
+    description: string;
+    type: MemoryType;
+    hasFrontmatter: boolean;
+};
+export type MemoryEntry = MemoryHeader & {
+    body: string;
+    raw: string;
+};
+export declare function toPosixRelative(relativePath: string): string;
+export declare function nameFromFilename(filename: string): string;
+export declare function surfaceKey(header: Pick<MemoryHeader, "name" | "type">): string;
+export declare function readMemoryHeader(memoryDir: string, filename: string): MemoryHeader | null;
+export declare function readMemoryEntry(memoryDir: string, filename: string): MemoryEntry | null;
+export declare function readMemoryBody(filePath: string): string;
+export type ScanOptions = {
+    recursive?: boolean;
+};
+/**
+ * Port of Claude Code's scanMemoryFiles(): recursive scan of the memory directory, header-only
+ * parsing, sorted by mtime desc and capped at MAX_MEMORY_FILES.
+ */
+export declare function scanMemoryFiles(memoryDir: string, options?: ScanOptions): MemoryHeader[];
+export declare function formatMemoryManifest(memories: readonly MemoryHeader[]): string;

package/dist/store/scan.js

@@ -0,0 +1,112 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, sep } from "node:path";
+import { parseFrontmatter, parseFrontmatterHeader, parseMemoryType } from "./frontmatter.js";
+import { ENTRYPOINT_NAME, MAX_MEMORY_FILES } from "./paths.js";
+export function toPosixRelative(relativePath) {
+    return sep === "/" ? relativePath : relativePath.split(sep).join("/");
+}
+export function nameFromFilename(filename) {
+    return basename(filename).replace(/\.md$/, "");
+}
+// Identity used to avoid surfacing the same memory twice in one conversation.
+export function surfaceKey(header) {
+    return `${header.name}|${header.type}`;
+}
+function headerFrom(filename, filePath, mtimeMs, parsed) {
+    return {
+        filename,
+        filePath,
+        mtimeMs,
+        name: parsed.frontmatter.name ?? nameFromFilename(filename),
+        description: parsed.frontmatter.description ?? "",
+        type: parseMemoryType(parsed.frontmatter.type) ?? "user",
+        hasFrontmatter: parsed.hasFrontmatter,
+    };
+}
+export function readMemoryHeader(memoryDir, filename) {
+    const filePath = join(memoryDir, ...filename.split("/"));
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const mtimeMs = statSync(filePath).mtimeMs;
+        return headerFrom(filename, filePath, mtimeMs, parseFrontmatterHeader(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export function readMemoryEntry(memoryDir, filename) {
+    const filePath = join(memoryDir, ...filename.split("/"));
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const mtimeMs = statSync(filePath).mtimeMs;
+        const parsed = parseFrontmatter(raw);
+        return { ...headerFrom(filename, filePath, mtimeMs, parsed), body: parsed.body, raw };
+    }
+    catch {
+        return null;
+    }
+}
+// Reads a memory body through the same parser the scanner uses.
+export function readMemoryBody(filePath) {
+    try {
+        return parseFrontmatter(readFileSync(filePath, "utf-8")).body;
+    }
+    catch {
+        return "";
+    }
+}
+// Own directory walk instead of `readdirSync({ recursive })`: symbolic links (files or directories)
+// are never followed, so a link planted in the memory directory cannot pull outside files into the
+// manifest or into recall. Whether the runtime's recursive readdir follows links is not relied on.
+function listMarkdownFiles(memoryDir, recursive) {
+    const out = [];
+    const walk = (dir, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const name = String(entry.name);
+            const relative = prefix ? `${prefix}/${name}` : name;
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (recursive)
+                    walk(join(dir, name), relative);
+            }
+            else if (entry.isFile() && name.endsWith(".md") && name !== ENTRYPOINT_NAME) {
+                out.push(relative);
+            }
+        }
+    };
+    walk(memoryDir, "");
+    return out;
+}
+/**
+ * Port of Claude Code's scanMemoryFiles(): recursive scan of the memory directory, header-only
+ * parsing, sorted by mtime desc and capped at MAX_MEMORY_FILES.
+ */
+export function scanMemoryFiles(memoryDir, options = {}) {
+    const headers = [];
+    for (const entry of listMarkdownFiles(memoryDir, options.recursive ?? true)) {
+        const header = readMemoryHeader(memoryDir, entry);
+        if (header)
+            headers.push(header);
+    }
+    return headers.sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MAX_MEMORY_FILES);
+}
+// Port of Claude Code's formatMemoryManifest():
+// `- [type] filename (ISO timestamp): description` per line
+export function formatMemoryManifest(memories) {
+    return memories
+        .map((m) => {
+        const ts = new Date(m.mtimeMs).toISOString();
+        return m.description
+            ? `- [${m.type}] ${m.filename} (${ts}): ${m.description}`
+            : `- [${m.type}] ${m.filename} (${ts})`;
+    })
+        .join("\n");
+}

package/dist/tools.d.ts

@@ -0,0 +1,9 @@
+import { type Hooks } from "@opencode-ai/plugin";
+import type { ExtractionCoordinator } from "./extraction/ExtractionCoordinator.js";
+import type { MemoryStore, SaveMemoryResult } from "./store/MemoryStore.js";
+export declare function formatMemorySaveResult(outcome: SaveMemoryResult, savedThisRun?: readonly string[]): string;
+export declare function memorySaveTitle(type: string, name: string): string | undefined;
+export declare function memoryListTitle(count: number): string;
+export declare function memorySearchTitle(query: string, count: number): string;
+export type MemoryTools = NonNullable<Hooks["tool"]>;
+export declare function buildMemoryTools(store: MemoryStore, extraction: Pick<ExtractionCoordinator, "recordSave">): MemoryTools;

package/dist/tools.js

@@ -0,0 +1,142 @@
+import { tool } from "@opencode-ai/plugin";
+import { MEMORY_TYPES } from "./store/frontmatter.js";
+// Tool result for memory_save. Inside an extraction fork, `savedThisRun` (file names already saved
+// by this fork, in order) is appended as an explicit done-signal so the model does not lose track on
+// long transcripts and re-save the same memories until the timeout kills it (#35).
+export function formatMemorySaveResult(outcome, savedThisRun) {
+    const inExtractionRun = savedThisRun !== undefined;
+    // The current file is recorded before formatting, so "earlier" means it appeared before this call.
+    const savedEarlierThisRun = inExtractionRun && savedThisRun.indexOf(outcome.fileName) < savedThisRun.length - 1;
+    let head;
+    if (outcome.unchanged) {
+        head = savedEarlierThisRun
+            ? `Skipped: "${outcome.fileName}" was already saved earlier in this extraction run with identical content — nothing written.`
+            : `Skipped: "${outcome.fileName}" already exists with identical content — nothing written (${outcome.filePath}).`;
+    }
+    else if (savedEarlierThisRun) {
+        head = `Updated "${outcome.fileName}" (first saved earlier in this extraction run) at ${outcome.filePath}`;
+    }
+    else {
+        head = `Memory saved to ${outcome.filePath}`;
+    }
+    if (!inExtractionRun)
+        return head;
+    const unique = Array.from(new Set(savedThisRun));
+    return (`${head}\n\n` +
+        `Saved so far in this extraction run (${unique.length}): ${unique.join(", ")}\n` +
+        "These memories are already persisted — do not call memory_save for them again. " +
+        "Once every distinct memory worth keeping is saved, stop calling tools and reply with a one-line summary.");
+}
+function plural(count, singular, pluralForm) {
+    return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+export function memorySaveTitle(type, name) {
+    if (type && name)
+        return `${type}: ${name}`;
+    return name || undefined;
+}
+export function memoryListTitle(count) {
+    return plural(count, "memory", "memories");
+}
+export function memorySearchTitle(query, count) {
+    return `"${query}" · ${plural(count, "match", "matches")}`;
+}
+const FILE_NAME_HINT = 'with or without the .md extension; sub-directories are allowed, e.g. "team/conventions"';
+export function buildMemoryTools(store, extraction) {
+    return {
+        memory_save: tool({
+            description: "Save or update a memory for future conversations. " +
+                "Each memory is stored as a markdown file with frontmatter. " +
+                "Use this when the user explicitly asks you to remember something, " +
+                "or when you observe important information worth preserving across sessions " +
+                "(user preferences, feedback, project context, external references). " +
+                "Check existing memories first with memory_list or memory_search to avoid duplicates.",
+            args: {
+                file_name: tool.schema
+                    .string()
+                    .describe('File name for the memory (without .md extension). Use snake_case, e.g. "user_role", "feedback_testing_style", "project_auth_rewrite"; a sub-directory prefix such as "team/conventions" is allowed'),
+                name: tool.schema.string().describe("Human-readable name for this memory"),
+                description: tool.schema
+                    .string()
+                    .describe("One-line description — used to decide relevance in future conversations, so be specific"),
+                type: tool.schema
+                    .enum(MEMORY_TYPES)
+                    .describe("Memory type: user (about the person), feedback (guidance on approach), project (ongoing work context), reference (pointers to external systems)"),
+                content: tool.schema
+                    .string()
+                    .describe("Memory content. For feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines"),
+            },
+            async execute(args, ctx) {
+                const outcome = store.save({
+                    fileName: args.file_name,
+                    name: args.name,
+                    description: args.description,
+                    type: args.type,
+                    content: args.content,
+                });
+                const savedThisRun = extraction.recordSave(ctx?.sessionID, outcome.fileName);
+                return {
+                    title: memorySaveTitle(args.type, args.name),
+                    output: formatMemorySaveResult(outcome, savedThisRun),
+                };
+            },
+        }),
+        memory_delete: tool({
+            description: "Delete a memory that is outdated, wrong, or no longer relevant. Also removes it from the index.",
+            args: {
+                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.`,
+                };
+            },
+        }),
+        memory_list: tool({
+            description: "List all saved memories with their names, types, and descriptions. " +
+                "Use this to check what memories exist before saving a new one (to avoid duplicates) " +
+                "or when you need to recall what's been stored.",
+            args: {},
+            async execute() {
+                const entries = store.list();
+                const title = memoryListTitle(entries.length);
+                if (entries.length === 0)
+                    return { title, output: "No memories saved yet." };
+                const lines = entries.map((e) => `- **${e.name}** (${e.type}) [${e.filename}]: ${e.description}`);
+                return { title, output: `${entries.length} memories found:\n${lines.join("\n")}` };
+            },
+        }),
+        memory_search: tool({
+            description: "Search memories by keyword. Searches across names, descriptions, and content. " +
+                "Use this to find relevant memories before answering questions or when the user references past conversations.",
+            args: {
+                query: tool.schema.string().describe("Search query — searches across name, description, and content"),
+            },
+            async execute(args) {
+                const results = store.search(args.query);
+                const title = memorySearchTitle(args.query, results.length);
+                if (results.length === 0)
+                    return { title, output: `No memories matching "${args.query}".` };
+                const lines = results.map((e) => `- **${e.name}** (${e.type}) [${e.filename}]: ${e.description}\n  Content: ${e.body.slice(0, 200)}${e.body.length > 200 ? "..." : ""}`);
+                return { title, output: `${results.length} matches for "${args.query}":\n${lines.join("\n")}` };
+            },
+        }),
+        memory_read: tool({
+            description: "Read the full content of a specific memory file.",
+            args: {
+                file_name: tool.schema.string().describe(`File name of the memory to read (${FILE_NAME_HINT})`),
+            },
+            async execute(args) {
+                const entry = store.read(args.file_name);
+                if (!entry)
+                    return { title: args.file_name, output: `Memory "${args.file_name}" not found.` };
+                return {
+                    title: args.file_name,
+                    output: `# ${entry.name}\n**Type:** ${entry.type}\n**Description:** ${entry.description}\n\n${entry.body}`,
+                };
+            },
+        }),
+    };
+}

package/dist/util/exclusiveFile.d.ts

@@ -0,0 +1,11 @@
+export declare function createExclusiveSync(path: string, content: string): boolean;
+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;
+export type FileLockOptions = {
+    timeoutMs?: number;
+    staleMs?: number;
+};
+export declare const FILE_LOCK_TIMEOUT_MS = 5000;
+export declare const FILE_LOCK_STALE_MS = 10000;
+export declare function withFileLock<T>(lockPath: string, fn: () => T, options?: FileLockOptions): T;

package/dist/util/exclusiveFile.js

@@ -0,0 +1,108 @@
+// Atomic "create this file with this content, fail if it exists" and a short-lived cross-process
+// mutex built on it. Used for the maintenance lock and for the extraction-state read-modify-write.
+//
+// `writeFileSync(path, content, { flag: "wx" })` creates the file first and writes the content
+// afterwards, so another process can observe an empty file in between and mistake it for garbage.
+// 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 { dirname } from "node:path";
+function errorCode(error) {
+    return error?.code;
+}
+export function createExclusiveSync(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    writeFileSync(tmp, content, "utf-8");
+    try {
+        linkSync(tmp, path);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST")
+            return false;
+        // Hard links unsupported here (exFAT, some network mounts): keep the wx fallback.
+        try {
+            writeFileSync(path, content, { encoding: "utf-8", flag: "wx" });
+            return true;
+        }
+        catch (fallbackError) {
+            if (errorCode(fallbackError) === "EEXIST")
+                return false;
+            throw fallbackError;
+        }
+    }
+    finally {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+export function fileAgeMs(path, now = Date.now()) {
+    try {
+        return now - statSync(path).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Synchronous, bounded wait for lock retries. Deliberately a busy-wait on the clock rather than
+// `Atomics.wait`: it is only reached while another process holds the state lock (a few
+// milliseconds), and a plain loop cannot block forever on a runtime where the timed wait
+// misbehaves (observed on Windows CI).
+export function sleepSync(ms) {
+    const until = Date.now() + Math.max(0, ms);
+    while (Date.now() < until) {
+        // spin
+    }
+}
+// Windows can refuse to unlink a file another process has open at that instant; retry briefly.
+export function unlinkWithRetry(path, attempts = 5) {
+    for (let i = 0; i < attempts; i++) {
+        try {
+            unlinkSync(path);
+            return true;
+        }
+        catch (error) {
+            if (errorCode(error) === "ENOENT")
+                return true;
+            if (i < attempts - 1)
+                sleepSync(2);
+        }
+    }
+    return false;
+}
+export const FILE_LOCK_TIMEOUT_MS = 5_000;
+export const FILE_LOCK_STALE_MS = 10_000;
+// Runs `fn` while holding `lockPath`. Contention waits (with short sleeps) instead of skipping,
+// because the critical sections are tiny (one JSON read-modify-write). A crashed holder is reaped
+// once its lock file is older than `staleMs`; two reapers can theoretically both succeed inside
+// that window, which is the same trade-off `proper-lockfile` makes.
+export function withFileLock(lockPath, fn, options = {}) {
+    const timeoutMs = options.timeoutMs ?? FILE_LOCK_TIMEOUT_MS;
+    const staleMs = options.staleMs ?? FILE_LOCK_STALE_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        if (createExclusiveSync(lockPath, String(process.pid))) {
+            try {
+                return fn();
+            }
+            finally {
+                unlinkWithRetry(lockPath);
+            }
+        }
+        const age = fileAgeMs(lockPath);
+        if (age !== undefined && age > staleMs) {
+            unlinkWithRetry(lockPath);
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for lock ${lockPath}`);
+        }
+        sleepSync(2 + Math.floor(Math.random() * 8));
+    }
+}

package/dist/util/legacyShellHook.d.ts

@@ -0,0 +1,3 @@
+export declare const V1_HOOK_START_MARKER = "# >>> opencode-memory auto-initialization >>>";
+export declare const V1_HOOK_RC_FILES: readonly [".zshrc", ".bashrc", ".bash_profile", ".profile"];
+export declare function findLegacyShellHooks(homeDir: string): string[];

package/dist/util/legacyShellHook.js

@@ -0,0 +1,23 @@
+// v1 installed a shell wrapper (`opencode-memory install`) that wrapped the `opencode` command and
+// ran extraction after the process exited. v2 extracts in-process, so a leftover wrapper would run
+// a second, competing extraction. The plugin only detects and warns; it never edits rc files.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+export const V1_HOOK_START_MARKER = "# >>> opencode-memory auto-initialization >>>";
+// The rc files v1's installer wrote to (zsh / bash), plus the two bash fallbacks it could be
+// sourced from. Fixed list: the plugin does not read `SHELL` or any other environment variable.
+export const V1_HOOK_RC_FILES = [".zshrc", ".bashrc", ".bash_profile", ".profile"];
+export function findLegacyShellHooks(homeDir) {
+    const found = [];
+    for (const name of V1_HOOK_RC_FILES) {
+        const path = join(homeDir, name);
+        try {
+            if (readFileSync(path, "utf-8").includes(V1_HOOK_START_MARKER))
+                found.push(path);
+        }
+        catch {
+            // rc file absent or unreadable
+        }
+    }
+    return found;
+}

package/dist/util/log.d.ts

@@ -0,0 +1,6 @@
+import type { OpencodeClient } from "../sdk.js";
+export declare const LOG_SERVICE = "opencode-claude-memory";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type Logger = (level: LogLevel, message: string, extra?: Record<string, unknown>) => void;
+export declare function getErrorMessage(error: unknown): string;
+export declare function createLogger(client: OpencodeClient | undefined, directory: string): Logger;

package/dist/util/log.js

@@ -0,0 +1,29 @@
+export const LOG_SERVICE = "opencode-claude-memory";
+export function getErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === "object") {
+        const message = error.message;
+        if (typeof message === "string")
+            return message;
+    }
+    return String(error);
+}
+// Logging goes through the OpenCode service log only. stderr is rendered into the chat UI, so a
+// failing background task must never write there. Every call is best-effort and never throws.
+export function createLogger(client, directory) {
+    return (level, message, extra) => {
+        const log = client?.app?.log;
+        if (typeof log !== "function")
+            return;
+        try {
+            void Promise.resolve(log.call(client?.app, {
+                body: { service: LOG_SERVICE, level, message, extra },
+                query: { directory },
+            })).catch(() => { });
+        }
+        catch {
+            // best-effort
+        }
+    };
+}