opencode-codex-memory 0.1.2 → 0.1.5

package/dist/tools/control.js

@@ -0,0 +1,153 @@
+import fs from "fs";
+import path from "path";
+import { tool } from "@opencode-ai/plugin";
+import { memoryRoot, memorySummaryPath } from "../src/paths.js";
+import { MemoryStore } from "../src/store.js";
+import { invalidateCache } from "../src/source.js";
+import { estimateTokens } from "../src/token.js";
+function isSymlinkedRoot() {
+    const root = memoryRoot();
+    try {
+        return fs.lstatSync(root).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+// Mirrors codex clear_memory_root_contents: deletes EVERY entry including
+// .git, so previously deleted/redacted memory content is not recoverable
+// from git history after a reset.
+function wipeMemoriesDir() {
+    const root = memoryRoot();
+    if (!fs.existsSync(root))
+        return;
+    for (const entry of fs.readdirSync(root)) {
+        const abs = path.join(root, entry);
+        try {
+            const stat = fs.statSync(abs);
+            if (stat.isDirectory())
+                fs.rmSync(abs, { recursive: true, force: true });
+            else
+                fs.unlinkSync(abs);
+        }
+        catch { }
+    }
+}
+function listMemoriesDir() {
+    const root = memoryRoot();
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    const walk = (dir, prefix) => {
+        for (const name of fs.readdirSync(dir)) {
+            if (name === ".git")
+                continue;
+            const abs = path.join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            let stat;
+            try {
+                stat = fs.statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                out.push(`${rel}/`);
+                walk(abs, rel);
+            }
+            else {
+                out.push(rel);
+            }
+        }
+    };
+    walk(root, "");
+    return out;
+}
+export const memory_reset = tool({
+    description: "Reset all persistent memory. Wipes the plugin's extracted memories and jobs tables and the entire " +
+        "contents of the memories directory (including git history). Per-session memory modes are preserved, " +
+        "so disabled/polluted sessions stay excluded. Refuses to run if the memory root is a symlink.",
+    args: {
+        confirm: tool.schema.boolean().describe("Must be true to perform the reset."),
+    },
+    async execute(args) {
+        if (!args.confirm)
+            return { output: "Reset aborted: confirm=false." };
+        if (isSymlinkedRoot()) {
+            return { output: "Reset refused: memory root is a symlink. Remove it manually to be safe." };
+        }
+        try {
+            const store = new MemoryStore();
+            store.clearMemoryData();
+            wipeMemoriesDir();
+            // codex keeps its state DB pool open across resets (clear_memory_roots_contents
+            // only wipes directories); closing here would strand cached handles elsewhere.
+            invalidateCache();
+            return { output: "Memory reset complete. Extracted memories and jobs cleared, memories directory (incl. git history) wiped, cache invalidated. Per-session memory modes were preserved." };
+        }
+        catch (err) {
+            return { output: `memory_reset error: ${err.message}` };
+        }
+    },
+});
+export const memory_inspect = tool({
+    description: "Inspect the current memory state. Returns: stage1_outputs count, last Phase 2 success watermark, " +
+        "memory_summary token estimate, and a listing of the memories directory. Read-only.",
+    args: {},
+    async execute() {
+        try {
+            const store = new MemoryStore();
+            const outputs = store.stage1Outputs();
+            const summaryPath = memorySummaryPath();
+            let summaryChars = 0;
+            let summaryTokens = 0;
+            if (fs.existsSync(summaryPath)) {
+                const text = fs.readFileSync(summaryPath, "utf8");
+                summaryChars = text.length;
+                summaryTokens = estimateTokens(text);
+            }
+            const listing = listMemoriesDir();
+            const out = [
+                `stage1_outputs: ${outputs.length}`,
+                `memory_summary_chars: ${summaryChars}`,
+                `memory_summary_tokens_est: ${summaryTokens}`,
+                `memories_dir_entries: ${listing.length}`,
+                "",
+                "Files:",
+                listing.length > 0 ? listing.join("\n") : "(empty)",
+            ].join("\n");
+            return {
+                output: out,
+                metadata: {
+                    stage1_count: outputs.length,
+                    summary_chars: summaryChars,
+                    summary_tokens_est: summaryTokens,
+                    files: listing,
+                },
+            };
+        }
+        catch (err) {
+            return { output: `memory_inspect error: ${err.message}` };
+        }
+    },
+});
+export const memory_mode = tool({
+    description: "Set the memory mode for the current session. 'enabled' allows Phase 1 extraction. " +
+        "'disabled' excludes this session from extraction. 'polluted' marks it as having external context " +
+        "(websearch/webfetch) that should not be trusted for memory.",
+    args: {
+        mode: tool.schema.enum(["enabled", "disabled", "polluted"]).describe("The memory mode to set."),
+        sessionId: tool.schema.string().optional().describe("Session ID. Defaults to the current session."),
+    },
+    async execute(args, ctx) {
+        try {
+            const store = new MemoryStore();
+            const sid = args.sessionId ?? ctx.sessionID;
+            store.setMemoryMode(sid, args.mode);
+            return { output: `Memory mode for session ${sid} set to '${args.mode}'.`, metadata: { sessionId: sid, mode: args.mode } };
+        }
+        catch (err) {
+            return { output: `memory_mode error: ${err.message}` };
+        }
+    },
+});

package/dist/tools/memory.d.ts

@@ -0,0 +1,52 @@
+export declare const memory_read: {
+    description: string;
+    args: {
+        path: import("zod").ZodString;
+        line_offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+        max_lines: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        path: string;
+        line_offset?: number | undefined;
+        max_lines?: number | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export declare const memory_list: {
+    description: string;
+    args: {
+        path: import("zod").ZodDefault<import("zod").ZodString>;
+        max_results: import("zod").ZodDefault<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        path: string;
+        max_results: number;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export declare const memory_search: {
+    description: string;
+    args: {
+        query: import("zod").ZodOptional<import("zod").ZodString>;
+        case_sensitive: import("zod").ZodDefault<import("zod").ZodBoolean>;
+        since: import("zod").ZodOptional<import("zod").ZodString>;
+        until: import("zod").ZodOptional<import("zod").ZodString>;
+        limit: import("zod").ZodDefault<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        case_sensitive: boolean;
+        limit: number;
+        query?: string | undefined;
+        since?: string | undefined;
+        until?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};
+export declare const memory_add_note: {
+    description: string;
+    args: {
+        note: import("zod").ZodString;
+        title: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        note: string;
+        title?: string | undefined;
+    }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+};

package/dist/tools/memory.js

@@ -0,0 +1,322 @@
+import fs from "fs";
+import path from "path";
+import { safeResolveMemoryPath } from "../src/path-guard.js";
+import { memoryRoot } from "../src/paths.js";
+import { tool } from "@opencode-ai/plugin";
+const MAX_READ_BYTES = 256 * 1024;
+export const memory_read = tool({
+    description: "Read a file from the persistent memory workspace (MEMORY.md, rollout_summaries/*, skills/*, etc.). " +
+        "Paths are relative to the memory root and cannot escape it. Supports line_offset/max_lines for " +
+        "reading a window of a large file; output line numbers are 1-indexed.",
+    args: {
+        path: tool.schema.string().describe("Relative path inside the memory workspace (e.g. MEMORY.md, rollout_summaries/session-xyz.md)."),
+        line_offset: tool.schema.number().int().min(1).optional().describe("1-indexed line to start reading from."),
+        max_lines: tool.schema.number().int().min(1).optional().describe("Maximum number of lines to return."),
+    },
+    async execute(args, ctx) {
+        try {
+            const fullPath = safeResolveMemoryPath(args.path);
+            if (!fs.existsSync(fullPath)) {
+                return { output: `Not found: ${args.path}` };
+            }
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                const entries = fs.readdirSync(fullPath);
+                return {
+                    output: `Directory ${args.path}/\n` + entries.map((e) => `- ${e}`).join("\n") + "\n(use memory_list for sorted, typed listings)",
+                    metadata: { kind: "directory", entries },
+                };
+            }
+            const fd = fs.openSync(fullPath, "r");
+            let text;
+            let byteTruncated;
+            try {
+                const size = Math.min(stat.size, MAX_READ_BYTES);
+                const buf = Buffer.alloc(size);
+                fs.readSync(fd, buf, 0, size, 0);
+                text = buf.toString("utf8");
+                byteTruncated = stat.size > MAX_READ_BYTES;
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            // Line windowing mirrors codex memories/read: 1-indexed offset, bounded
+            // line count, and the start line reported so file:line citations work.
+            const startLine = args.line_offset ?? 1;
+            let lines = text.split(/\r?\n/);
+            const totalLines = lines.length;
+            if (startLine > totalLines) {
+                return { output: `memory_read error: line_offset ${startLine} exceeds file length (${totalLines} lines).` };
+            }
+            lines = lines.slice(startLine - 1);
+            let lineTruncated = false;
+            if (args.max_lines !== undefined && lines.length > args.max_lines) {
+                lines = lines.slice(0, args.max_lines);
+                lineTruncated = true;
+            }
+            const body = lines.join("\n");
+            const notes = [];
+            if (lineTruncated)
+                notes.push(`[stopped after ${args.max_lines} lines; file has ${totalLines}]`);
+            if (byteTruncated)
+                notes.push(`[truncated: ${stat.size - MAX_READ_BYTES} bytes omitted]`);
+            const header = startLine > 1 ? `[starting at line ${startLine}]\n` : "";
+            return {
+                output: header + body + (notes.length ? "\n\n" + notes.join("\n") : ""),
+                metadata: { path: args.path, bytes: stat.size, start_line_number: startLine, truncated: byteTruncated || lineTruncated },
+            };
+        }
+        catch (err) {
+            return { output: `memory_read error: ${err.message}` };
+        }
+    },
+});
+/** Skip hidden entries and symlinks, mirroring codex local/list.rs + local/search.rs walkers. */
+function visibleEntries(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        if (name.startsWith("."))
+            continue;
+        let st;
+        try {
+            st = fs.lstatSync(path.join(dir, name));
+        }
+        catch {
+            continue;
+        }
+        if (st.isSymbolicLink())
+            continue;
+        out.push({ name, isDir: st.isDirectory() });
+    }
+    return out;
+}
+const LIST_MAX_RESULTS = 2000;
+export const memory_list = tool({
+    description: "List the immediate entries of a directory in the persistent memory workspace, sorted by name, " +
+        "with entry types. Hidden files and symlinks are skipped. Use path '' (empty) for the memory root.",
+    args: {
+        path: tool.schema.string().default("").describe("Relative directory path inside the memory workspace ('' for the root)."),
+        max_results: tool.schema.number().int().min(1).max(LIST_MAX_RESULTS).default(LIST_MAX_RESULTS).describe("Maximum entries to return."),
+    },
+    async execute(args) {
+        try {
+            const fullPath = safeResolveMemoryPath(args.path || ".");
+            if (!fs.existsSync(fullPath))
+                return { output: `Not found: ${args.path}` };
+            if (!fs.statSync(fullPath).isDirectory())
+                return { output: `memory_list error: not a directory: ${args.path}` };
+            const entries = visibleEntries(fullPath).sort((a, b) => a.name.localeCompare(b.name));
+            const truncated = entries.length > args.max_results;
+            const shown = entries.slice(0, args.max_results);
+            const prefix = args.path ? `${args.path.replace(/\/+$/, "")}/` : "";
+            const listing = shown.map((e) => ({ path: `${prefix}${e.name}`, entry_type: e.isDir ? "directory" : "file" }));
+            if (listing.length === 0)
+                return { output: `Directory ${args.path || "."} is empty.` };
+            return {
+                output: listing.map((e) => `${e.entry_type === "directory" ? "d" : "f"} ${e.path}`).join("\n") +
+                    (truncated ? `\n[truncated: ${entries.length - args.max_results} more entries]` : ""),
+                metadata: { path: args.path, entries: listing, truncated },
+            };
+        }
+        catch (err) {
+            return { output: `memory_list error: ${err.message}` };
+        }
+    },
+});
+// Time-anchored memory files carry their session/note timestamp as a filename
+// prefix: 2026-07-03T05-11-22-<hash>-<slug>.md / 2026-07-03T05-11-22_<slug>.md
+function fileTimestamp(name) {
+    const m = name.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})/);
+    if (!m)
+        return null;
+    const ts = Date.parse(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}Z`);
+    return Number.isNaN(ts) ? null : ts;
+}
+// Accepts YYYY-MM-DD (whole-day boundary) or a full ISO datetime.
+function parseDateArg(value, endOfDay) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        const ts = Date.parse(`${value}T00:00:00Z`);
+        if (Number.isNaN(ts))
+            return null;
+        return endOfDay ? ts + 24 * 60 * 60 * 1000 - 1 : ts;
+    }
+    const ts = Date.parse(value);
+    return Number.isNaN(ts) ? null : ts;
+}
+// Walks every non-hidden, non-symlink file (codex searches all files, not an
+// extension allowlist), in sorted order for deterministic results.
+function collectSearchFiles(root) {
+    const files = [];
+    const walk = (dir, prefix) => {
+        const entries = visibleEntries(dir).sort((a, b) => a.name.localeCompare(b.name));
+        for (const { name, isDir } of entries) {
+            const abs = path.join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            if (isDir) {
+                walk(abs, rel);
+            }
+            else {
+                files.push({ rel, abs, ts: fileTimestamp(name) });
+            }
+        }
+    };
+    walk(root, "");
+    return files;
+}
+function firstContentLine(content) {
+    for (const line of content.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        // Skip the metadata header lines of summary/note files.
+        if (/^(session_id|updated_at|cwd|usage_count|created|session):/i.test(t))
+            continue;
+        return t.slice(0, 160);
+    }
+    return "(empty)";
+}
+export const memory_search = tool({
+    description: "Search across the persistent memory workspace (MEMORY.md, rollout_summaries/*, skills/*). " +
+        "Returns matching lines with file paths. Optional since/until restrict the search to " +
+        "time-anchored files (rollout summaries, ad-hoc notes) from that period — useful to recall " +
+        "what the user was working on around a given time. With since/until and no query, returns a " +
+        "chronological listing of that period's sessions/notes.",
+    args: {
+        query: tool.schema.string().min(1).optional().describe("Search query (substring match). Optional when since/until is set."),
+        case_sensitive: tool.schema.boolean().default(true).describe("Case-sensitive matching (default true, like codex memories/search)."),
+        since: tool.schema.string().optional().describe("Only time-anchored files at/after this time (YYYY-MM-DD or ISO datetime)."),
+        until: tool.schema.string().optional().describe("Only time-anchored files at/before this time (YYYY-MM-DD or ISO datetime; whole day for date-only)."),
+        limit: tool.schema.number().int().min(1).max(200).default(200).describe("Max matches to return (default/max 200, like codex)."),
+    },
+    async execute(args, ctx) {
+        try {
+            const root = memoryRoot();
+            if (!fs.existsSync(root))
+                return { output: "Memory workspace is empty." };
+            if (!args.query && !args.since && !args.until) {
+                return { output: "memory_search error: provide a query and/or since/until." };
+            }
+            const since = args.since ? parseDateArg(args.since, false) : null;
+            if (args.since && since === null)
+                return { output: `memory_search error: could not parse since="${args.since}".` };
+            const until = args.until ? parseDateArg(args.until, true) : null;
+            if (args.until && until === null)
+                return { output: `memory_search error: could not parse until="${args.until}".` };
+            let files = collectSearchFiles(root);
+            const timeFiltered = since !== null || until !== null;
+            if (timeFiltered) {
+                // Time filters only apply to time-anchored files; MEMORY.md etc. carry
+                // no single timestamp and are excluded from time-scoped recall.
+                files = files.filter((f) => f.ts !== null && (since === null || f.ts >= since) && (until === null || f.ts <= until));
+                files.sort((a, b) => (b.ts ?? 0) - (a.ts ?? 0));
+            }
+            const rangeLabel = timeFiltered ? ` in ${args.since ?? "..."}..${args.until ?? "..."}` : "";
+            if (!args.query) {
+                const listing = files.slice(0, args.limit).map((f) => {
+                    let content = "";
+                    try {
+                        content = fs.readFileSync(f.abs, "utf8");
+                    }
+                    catch {
+                    }
+                    return `${new Date(f.ts).toISOString()} ${f.rel} — ${firstContentLine(content)}`;
+                });
+                if (listing.length === 0)
+                    return { output: `No time-anchored memory files${rangeLabel}.` };
+                return {
+                    output: `${listing.length} memory file(s)${rangeLabel}:\n${listing.join("\n")}`,
+                    metadata: { count: listing.length, since: args.since, until: args.until },
+                };
+            }
+            const caseSensitive = args.case_sensitive ?? true;
+            const q = caseSensitive ? args.query : args.query.toLowerCase();
+            const matches = [];
+            // Files are walked in sorted order, so results are ordered by
+            // (path, line) like codex's search response.
+            for (const f of files) {
+                if (matches.length >= args.limit)
+                    break;
+                let content;
+                try {
+                    content = fs.readFileSync(f.abs, "utf8");
+                }
+                catch {
+                    continue;
+                }
+                for (const [i, line] of content.split(/\r?\n/).entries()) {
+                    if (matches.length >= args.limit)
+                        break;
+                    const haystack = caseSensitive ? line : line.toLowerCase();
+                    if (haystack.includes(q)) {
+                        matches.push({ file: f.rel, line: i + 1, text: line.slice(0, 240) });
+                    }
+                }
+            }
+            if (matches.length === 0)
+                return { output: `No matches for "${args.query}"${rangeLabel}.` };
+            const out = matches
+                .map((m) => `${m.file}:${m.line}: ${m.text}`)
+                .join("\n");
+            return {
+                output: `${matches.length} match(es) for "${args.query}"${rangeLabel}:\n${out}`,
+                metadata: { count: matches.length, query: args.query, since: args.since, until: args.until },
+            };
+        }
+        catch (err) {
+            return { output: `memory_search error: ${err.message}` };
+        }
+    },
+});
+const NOTES_DIR = "extensions/ad_hoc/notes";
+export const memory_add_note = tool({
+    description: "Append a short ad-hoc note to the persistent memory workspace under extensions/ad_hoc/notes/. " +
+        "Used when the user asks to remember something for future sessions.",
+    args: {
+        note: tool.schema.string().min(1).max(4000).describe("The note text to persist."),
+        title: tool.schema.string().max(120).optional().describe("Optional short title for the note."),
+    },
+    async execute(args, ctx) {
+        try {
+            const root = memoryRoot();
+            const notesDir = path.join(root, NOTES_DIR);
+            fs.mkdirSync(notesDir, { recursive: true });
+            const ts = new Date().toISOString();
+            const slug = (args.title ?? `note-${ts}`)
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-+|-+$/g, "")
+                .slice(0, 60);
+            // Filename layout matches codex: <YYYY-MM-DDTHH-MM-SS>-<slug>.md.
+            const stem = `${ts.slice(0, 19).replace(/[:.]/g, "-")}-${slug}`;
+            const header = `# ${args.title ?? "Ad-hoc note"}\n\n- created: ${ts}\n- session: ${ctx.sessionID}\n\n`;
+            // Notes are append-only (codex create_new semantics): never overwrite an
+            // existing note; disambiguate on collision instead.
+            let file = path.join(notesDir, `${stem}.md`);
+            for (let i = 2;; i++) {
+                try {
+                    fs.writeFileSync(file, header + args.note + "\n", { flag: "wx" });
+                    break;
+                }
+                catch (err) {
+                    if (err.code !== "EEXIST" || i > 20)
+                        throw err;
+                    file = path.join(notesDir, `${stem}-${i}.md`);
+                }
+            }
+            return {
+                output: `Note saved to ${path.relative(root, file)}`,
+                metadata: { file: path.relative(root, file), sessionID: ctx.sessionID },
+            };
+        }
+        catch (err) {
+            return { output: `memory_add_note error: ${err.message}` };
+        }
+    },
+});

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Persistent memory plugin for opencode — ports codex's two-phase memory system (extraction → consolidation → injection → citation feedback)",
   "type": "module",
-  "main": "src/index.ts",
+  "main": "./dist/src/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./tools/*": {
+      "import": "./dist/tools/*.js",
+      "types": "./dist/tools/*.d.ts"
+    }
+  },
   "files": [
-    "src",
-    "tools",
+    "dist",
     "opencode.json",
     "NOTICE"
   ],
@@ -20,11 +29,19 @@
   },
   "scripts": {
     "dev": "bun --watch src/index.ts",
-    "build": "bun build src/index.ts --outdir dist --target bun",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
     "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": ["opencode", "memory", "plugin", "ai", "persistent-context", "codex"],
+  "keywords": [
+    "opencode",
+    "memory",
+    "plugin",
+    "ai",
+    "persistent-context",
+    "codex"
+  ],
   "license": "Apache-2.0",
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.13",