opencode-claude-memory 1.7.7 → 2.0.0

package/dist/recall/selector.js

@@ -0,0 +1,92 @@
+// LLM memory selection, ported from Claude Code's findRelevantMemories.ts side query. Runs in a
+// hidden child session so the main conversation never sees the selector exchange.
+import { runForkSession } from "../extraction/forkSession.js";
+import { unwrapData } from "../sdk.js";
+import { formatMemoryManifest } from "../store/scan.js";
+export const SELECT_MEMORIES_SYSTEM_PROMPT = `You are selecting memories that will be useful to OpenCode as it processes a user's query. You will be given the user's query and a list of available memory files with their filenames and descriptions.
+
+Return a list of filenames for the memories that will clearly be useful to OpenCode as it processes the user's query (up to 5). Only include memories that you are certain will be helpful based on their name and description.
+- If you are unsure if a memory will be useful in processing the user's query, then do not include it in your list. Be selective and discerning.
+- If there are no memories in the list that would clearly be useful, feel free to return an empty list.
+- If a list of recently-used tools is provided, do not select memories that are usage reference or API documentation for those tools (OpenCode is already exercising them). DO still select memories containing warnings, gotchas, or known issues about those tools — active use is exactly when those matter.
+`;
+export const SELECT_MEMORIES_FORMAT = {
+    type: "json_schema",
+    schema: {
+        type: "object",
+        properties: {
+            selected_memories: { type: "array", items: { type: "string" } },
+        },
+        required: ["selected_memories"],
+        additionalProperties: false,
+    },
+};
+export const RECALL_SELECTOR_TITLE = "opencode-memory recall selector";
+function tryParseSelectedMemories(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.selected_memories))
+            return undefined;
+        return parsed.selected_memories.filter((item) => typeof item === "string");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractSelectedMemories(response) {
+    const data = unwrapData(response);
+    if (!data || typeof data !== "object")
+        return [];
+    const structured = data.info?.structured;
+    if (structured && typeof structured === "object") {
+        const selected = structured.selected_memories;
+        if (Array.isArray(selected)) {
+            return selected.filter((item) => typeof item === "string");
+        }
+    }
+    if (!Array.isArray(data.parts))
+        return [];
+    for (const part of data.parts) {
+        if (!part || typeof part !== "object")
+            continue;
+        const text = part.text;
+        if (typeof text !== "string")
+            continue;
+        const parsed = tryParseSelectedMemories(text);
+        if (parsed)
+            return parsed;
+    }
+    return [];
+}
+export function buildSelectorQuery(query, memories, recentTools) {
+    const toolsSection = recentTools.length > 0 ? `\n\nRecently used tools: ${recentTools.join(", ")}` : "";
+    return `Query: ${query}\n\nAvailable memories:\n${formatMemoryManifest(memories)}${toolsSection}`;
+}
+// Never throws: a failed or timed-out selector simply recalls nothing for this turn.
+export async function selectRelevantMemoryFilenames(input) {
+    if (input.memories.length === 0)
+        return [];
+    try {
+        const response = await runForkSession({
+            client: input.client,
+            directory: input.directory,
+            parentSessionID: input.parentSessionID,
+            title: RECALL_SELECTOR_TITLE,
+            agent: input.agent,
+            system: SELECT_MEMORIES_SYSTEM_PROMPT,
+            tools: input.tools ?? { "*": false },
+            format: SELECT_MEMORIES_FORMAT,
+            parts: [{ type: "text", text: buildSelectorQuery(input.query, input.memories, input.recentTools) }],
+            timeoutMs: input.timeoutMs,
+            onCreated: input.onSessionCreated,
+            onFinished: input.onSessionFinished,
+        });
+        const validFilenames = new Set(input.memories.map((memory) => memory.filename));
+        return extractSelectedMemories(response)
+            .filter((filename) => validFilenames.has(filename))
+            .slice(0, input.maxMemories);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/sdk.d.ts

@@ -0,0 +1,12 @@
+import type { Hooks, PluginInput } from "@opencode-ai/plugin";
+export type OpencodeClient = PluginInput["client"];
+export type PluginEvent = Parameters<NonNullable<Hooks["event"]>>[0]["event"];
+export type PluginConfig = Parameters<NonNullable<Hooks["config"]>>[0];
+export type AgentConfig = NonNullable<NonNullable<PluginConfig["agent"]>[string]>;
+export type ChatMessage = Parameters<NonNullable<Hooks["experimental.chat.messages.transform"]>>[1]["messages"][number];
+export type MessageInfo = ChatMessage["info"];
+export type MessagePart = ChatMessage["parts"][number];
+export type SessionInfo = Extract<PluginEvent, {
+    type: "session.deleted";
+}>["properties"]["info"];
+export declare function unwrapData<T = unknown>(response: unknown): T | undefined;

package/dist/sdk.js

@@ -0,0 +1,8 @@
+// hey-api responses are `{ data, error, request, response }`; tests mock the `{ data }` subset.
+export function unwrapData(response) {
+    if (!response || typeof response !== "object")
+        return response;
+    if ("data" in response)
+        return response.data;
+    return response;
+}

package/dist/store/MemoryStore.d.ts

@@ -0,0 +1,41 @@
+import { type MemoryType } from "./frontmatter.js";
+import { type MemoryEntry, type MemoryHeader } from "./scan.js";
+export type SaveMemoryInput = {
+    fileName: string;
+    name: string;
+    description: string;
+    type: MemoryType;
+    content: string;
+};
+export type SaveMemoryResult = {
+    filePath: string;
+    fileName: string;
+    unchanged: boolean;
+};
+export type ListOptions = {
+    sort?: "name" | "mtime";
+};
+export type MemoryStoreOptions = {
+    claudeConfigDir: string;
+};
+export declare class MemoryStore {
+    readonly memoryRoot: string;
+    readonly gitRoot: string | null;
+    readonly canonicalRoot: string;
+    readonly claudeConfigDir: string;
+    readonly projectDir: string;
+    readonly memoryDir: string;
+    readonly entrypoint: string;
+    readonly stateDir: string;
+    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;
+    search(query: string): MemoryEntry[];
+    readIndex(): string;
+    private writeIndex;
+    private isUnchanged;
+}

package/dist/store/MemoryStore.js

@@ -0,0 +1,105 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { buildFrontmatter } 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";
+// 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 {
+    memoryRoot;
+    gitRoot;
+    canonicalRoot;
+    claudeConfigDir;
+    projectDir;
+    memoryDir;
+    entrypoint;
+    // Plugin-private state (extraction watermarks, auto-dream gate) lives next to, not inside, the
+    // Claude Code project directory so Claude Code never sees it.
+    stateDir;
+    constructor(memoryRoot, options) {
+        this.memoryRoot = memoryRoot;
+        this.gitRoot = findGitRoot(memoryRoot);
+        this.canonicalRoot = findCanonicalGitRoot(memoryRoot) ?? memoryRoot;
+        this.claudeConfigDir = options.claudeConfigDir;
+        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 });
+    }
+    scan() {
+        return scanMemoryFiles(this.memoryDir);
+    }
+    manifest() {
+        return formatMemoryManifest(this.scan());
+    }
+    list(options = {}) {
+        const entries = [];
+        for (const header of this.scan()) {
+            const entry = readMemoryEntry(this.memoryDir, header.filename);
+            if (entry)
+                entries.push(entry);
+        }
+        if ((options.sort ?? "name") === "name") {
+            entries.sort((a, b) => (a.filename < b.filename ? -1 : a.filename > b.filename ? 1 : 0));
+        }
+        return entries;
+    }
+    read(fileName) {
+        const { relativePath } = resolveMemoryFilePath(this.memoryDir, fileName);
+        return readMemoryEntry(this.memoryDir, relativePath);
+    }
+    save(input) {
+        const { relativePath, filePath } = resolveMemoryFilePath(this.memoryDir, input.fileName);
+        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`;
+        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 };
+        }
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, fileContent, "utf-8");
+        this.writeIndex(upsertIndexLine(this.readIndex(), relativePath, pointer));
+        return { filePath, fileName: relativePath, unchanged: false };
+    }
+    delete(fileName) {
+        const { relativePath, filePath } = resolveMemoryFilePath(this.memoryDir, fileName);
+        try {
+            unlinkSync(filePath);
+        }
+        catch {
+            return false;
+        }
+        this.writeIndex(removeIndexLine(this.readIndex(), relativePath));
+        return true;
+    }
+    search(query) {
+        const lowerQuery = query.toLowerCase();
+        return this.list().filter((entry) => entry.name.toLowerCase().includes(lowerQuery) ||
+            entry.description.toLowerCase().includes(lowerQuery) ||
+            entry.body.toLowerCase().includes(lowerQuery));
+    }
+    readIndex() {
+        return readIndexFile(this.entrypoint);
+    }
+    writeIndex(content) {
+        writeFileSync(this.entrypoint, content, "utf-8");
+    }
+    isUnchanged(filePath, fileContent, pointer) {
+        try {
+            if (readFileSync(filePath, "utf-8") !== fileContent)
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return indexHasPointer(this.readIndex(), pointer);
+    }
+}

package/dist/store/frontmatter.d.ts

@@ -0,0 +1,25 @@
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export declare const FRONTMATTER_MAX_LINES = 30;
+export type Frontmatter = {
+    name?: string;
+    description?: string;
+    type?: string;
+    [key: string]: string | undefined;
+};
+export type ParsedMemoryFile = {
+    frontmatter: Frontmatter;
+    body: string;
+    hasFrontmatter: boolean;
+};
+export declare function parseFrontmatter(raw: string): ParsedMemoryFile;
+export declare function parseFrontmatterHeader(raw: string): {
+    frontmatter: Frontmatter;
+    hasFrontmatter: boolean;
+};
+export declare function buildFrontmatter(input: {
+    name: string;
+    description: string;
+    type: MemoryType;
+}): string;
+export declare function parseMemoryType(raw: string | undefined): MemoryType | undefined;

package/dist/store/frontmatter.js

@@ -0,0 +1,61 @@
+// The single definition of the memory file format. Every code path that reads or writes a memory
+// file goes through this module, so a file can never be interpreted differently by two features.
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+// Matches Claude Code's memoryScan.ts: the closing `---` must appear within the first 30 lines.
+export const FRONTMATTER_MAX_LINES = 30;
+function parseFields(lines) {
+    const frontmatter = {};
+    for (const line of lines) {
+        const colonIdx = line.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key && value)
+            frontmatter[key] = value;
+    }
+    return frontmatter;
+}
+function findClosingLine(lines) {
+    const limit = Math.min(lines.length, FRONTMATTER_MAX_LINES);
+    for (let i = 1; i < limit; i++) {
+        if (lines[i]?.trimEnd() === "---")
+            return i;
+    }
+    return -1;
+}
+export function parseFrontmatter(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("---")) {
+        return { frontmatter: {}, body: trimmed, hasFrontmatter: false };
+    }
+    const lines = trimmed.split("\n");
+    const closing = findClosingLine(lines);
+    if (closing === -1) {
+        return { frontmatter: {}, body: trimmed, hasFrontmatter: false };
+    }
+    return {
+        frontmatter: parseFields(lines.slice(1, closing)),
+        body: lines
+            .slice(closing + 1)
+            .join("\n")
+            .trim(),
+        hasFrontmatter: true,
+    };
+}
+// 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).
+export function parseFrontmatterHeader(raw) {
+    const head = raw.trimStart().split("\n").slice(0, FRONTMATTER_MAX_LINES).join("\n");
+    const { frontmatter, hasFrontmatter } = parseFrontmatter(head);
+    return { frontmatter, hasFrontmatter };
+}
+export function buildFrontmatter(input) {
+    return `---\nname: ${input.name}\ndescription: ${input.description}\ntype: ${input.type}\n---`;
+}
+export function parseMemoryType(raw) {
+    if (!raw)
+        return undefined;
+    return MEMORY_TYPES.find((t) => t === raw);
+}

package/dist/store/indexFile.d.ts

@@ -0,0 +1,15 @@
+export declare const POINTER_RE: RegExp;
+export declare function readIndexFile(entrypoint: string): string;
+export declare function buildIndexPointer(fileName: string, name: string, description: string): string;
+export declare function indexHasPointer(raw: string, pointer: string): boolean;
+export declare function pointerTarget(line: string): string | undefined;
+export declare function upsertIndexLine(raw: string, fileName: string, pointer: string): string;
+export declare function removeIndexLine(raw: string, fileName: string): string;
+export type EntrypointTruncation = {
+    content: string;
+    lineCount: number;
+    byteCount: number;
+    wasLineTruncated: boolean;
+    wasByteTruncated: boolean;
+};
+export declare function truncateEntrypoint(raw: string): EntrypointTruncation;

package/dist/store/indexFile.js

@@ -0,0 +1,153 @@
+// MEMORY.md is shared with Claude Code and may be hand-organised (headings, blank-line groups,
+// comments). Edits are therefore line-level: only the pointer line for the target file changes.
+import { readFileSync } from "node:fs";
+import { ENTRYPOINT_NAME, MAX_ENTRYPOINT_BYTES, MAX_ENTRYPOINT_LINES } from "./paths.js";
+// Only markdown list items of the form `- [Title](file.md) ...` count as index pointers. The label
+// is matched lazily so titles containing brackets (`[Use [Bun]](x.md)`) resolve to the first
+// `](target)` that looks like a file reference; the target may not contain whitespace or parens.
+export const POINTER_RE = /^\s*[-*]\s+\[(.*?)\]\(([^()\s]+)\)/;
+export function readIndexFile(entrypoint) {
+    try {
+        return readFileSync(entrypoint, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+export function buildIndexPointer(fileName, name, description) {
+    return `- [${name}](${fileName}) — ${description}`;
+}
+export function indexHasPointer(raw, pointer) {
+    return raw.split(/\r?\n/).some((line) => line.trimEnd() === pointer);
+}
+function detectEol(raw) {
+    return raw.includes("\r\n") ? "\r\n" : "\n";
+}
+export function pointerTarget(line) {
+    const match = POINTER_RE.exec(line);
+    return match?.[2];
+}
+function splitIndex(raw) {
+    const eol = detectEol(raw);
+    const lines = raw.split(/\r?\n/);
+    const trailingNewline = raw.endsWith("\n");
+    if (trailingNewline)
+        lines.pop();
+    return { lines, eol, trailingNewline };
+}
+// Re-joins with the file's own line-ending style and its original end-of-file newline state: a
+// file that did not end with a newline keeps not ending with one (05 §"MEMORY.md 最小编辑").
+function joinIndex(parts) {
+    if (parts.lines.length === 0)
+        return "";
+    return parts.lines.join(parts.eol) + (parts.trailingNewline ? parts.eol : "");
+}
+// Removes every line except the first one that points at `fileName`; returns the index of the
+// kept line (or -1). Duplicate pointers arise from hand edits or from older writers that failed to
+// recognise a line, and would otherwise accumulate and leave dangling entries behind on delete.
+function dedupePointers(lines, fileName, keepFirst) {
+    let kept = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (pointerTarget(lines[i] ?? "") !== fileName)
+            continue;
+        if (kept === -1 && keepFirst) {
+            kept = i;
+            continue;
+        }
+        lines.splice(i, 1);
+        i -= 1;
+    }
+    return kept;
+}
+// Replaces the pointer line for `fileName` in place, or appends it after the last pointer line
+// (keeping any grouping intact). Blank lines and unrelated lines are never touched.
+export function upsertIndexLine(raw, fileName, pointer) {
+    if (!raw.trim())
+        return `${pointer}\n`;
+    const parts = splitIndex(raw);
+    const { lines } = parts;
+    const existingIdx = dedupePointers(lines, fileName, true);
+    if (existingIdx >= 0) {
+        const indent = /^\s*/.exec(lines[existingIdx] ?? "")?.[0] ?? "";
+        lines[existingIdx] = indent + pointer;
+        return joinIndex(parts);
+    }
+    let lastPointerIdx = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (POINTER_RE.test(lines[i] ?? "")) {
+            lastPointerIdx = i;
+            break;
+        }
+    }
+    if (lastPointerIdx >= 0) {
+        lines.splice(lastPointerIdx + 1, 0, pointer);
+    }
+    else {
+        // No pointers yet (e.g. only a heading): append, separated from the existing text by one blank line.
+        if (lines.length > 0 && (lines[lines.length - 1] ?? "").trim() !== "")
+            lines.push("");
+        lines.push(pointer);
+    }
+    return joinIndex(parts);
+}
+// Removes the pointer line(s) for `fileName`; collapses the blank lines around it so the removal
+// never leaves two consecutive blank lines behind.
+export function removeIndexLine(raw, fileName) {
+    if (!raw)
+        return raw;
+    const parts = splitIndex(raw);
+    const { lines } = parts;
+    const idx = lines.findIndex((line) => pointerTarget(line) === fileName);
+    if (idx === -1)
+        return raw;
+    dedupePointers(lines, fileName, false);
+    const before = idx - 1;
+    const after = idx;
+    const isBlank = (i) => i >= 0 && i < lines.length && (lines[i] ?? "").trim() === "";
+    if (isBlank(before) && (isBlank(after) || after >= lines.length)) {
+        lines.splice(before, 1);
+    }
+    else if (isBlank(after) && before < 0) {
+        lines.splice(after, 1);
+    }
+    if (lines.every((line) => line.trim() === ""))
+        return "";
+    return joinIndex(parts);
+}
+function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    return `${(bytes / 1024).toFixed(1)}KB`;
+}
+// Port of Claude Code's truncateEntrypointContent() from memdir.ts.
+// Uses .length (char count, same as Claude Code) for byte measurement.
+export function truncateEntrypoint(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { content: "", lineCount: 0, byteCount: 0, wasLineTruncated: false, wasByteTruncated: false };
+    const contentLines = trimmed.split("\n");
+    const lineCount = contentLines.length;
+    const byteCount = trimmed.length;
+    const wasLineTruncated = lineCount > MAX_ENTRYPOINT_LINES;
+    const wasByteTruncated = byteCount > MAX_ENTRYPOINT_BYTES;
+    if (!wasLineTruncated && !wasByteTruncated) {
+        return { content: trimmed, lineCount, byteCount, wasLineTruncated, wasByteTruncated };
+    }
+    let truncated = wasLineTruncated ? contentLines.slice(0, MAX_ENTRYPOINT_LINES).join("\n") : trimmed;
+    if (truncated.length > MAX_ENTRYPOINT_BYTES) {
+        const cutAt = truncated.lastIndexOf("\n", MAX_ENTRYPOINT_BYTES);
+        truncated = truncated.slice(0, cutAt > 0 ? cutAt : MAX_ENTRYPOINT_BYTES);
+    }
+    const reason = wasByteTruncated && !wasLineTruncated
+        ? `${formatFileSize(byteCount)} (limit: ${formatFileSize(MAX_ENTRYPOINT_BYTES)}) — index entries are too long`
+        : wasLineTruncated && !wasByteTruncated
+            ? `${lineCount} lines (limit: ${MAX_ENTRYPOINT_LINES})`
+            : `${lineCount} lines and ${formatFileSize(byteCount)}`;
+    return {
+        content: `${truncated}\n\n> WARNING: ${ENTRYPOINT_NAME} is ${reason}. Only part of it was loaded. Keep index entries to one line under ~200 chars; move detail into topic files.`,
+        lineCount,
+        byteCount,
+        wasLineTruncated,
+        wasByteTruncated,
+    };
+}

package/dist/{paths.d.ts → store/paths.d.ts}

@@ -3,12 +3,13 @@ export declare const MAX_ENTRYPOINT_LINES = 200;
 export declare const MAX_ENTRYPOINT_BYTES = 25000;
 export declare const MAX_MEMORY_FILES = 200;
 export declare const MAX_MEMORY_FILE_BYTES = 40000;
-export declare const FRONTMATTER_MAX_LINES = 30;
 export declare function validateMemoryFileName(fileName: string): string;
+export declare function resolveMemoryFilePath(memoryDir: string, fileName: string): {
+    relativePath: string;
+    filePath: string;
+};
 export declare function sanitizePath(name: string): string;
+export declare function findGitRoot(startPath: string): string | null;
 export declare function findCanonicalGitRoot(startPath: string): string | null;
-export declare function getProjectDir(worktree: string): string;
-export declare function getMemoryDir(worktree: string): string;
-export declare function getMemoryEntrypoint(worktree: string): string;
-export declare function isMemoryPath(absolutePath: string, worktree: string): boolean;
-export declare function ensureDir(dir: string): void;
+export declare function isRootPath(path: string): boolean;
+export declare function resolveMemoryRoot(worktree: string, directory: string): string;