opencode-codex-memory 0.1.3 → 0.1.6

package/dist/src/index.d.ts

@@ -0,0 +1,163 @@
+import type { PluginInput, PluginOptions } from "@opencode-ai/plugin";
+export declare function takeNewCitations(partKey: string, ids: string[]): string[];
+declare const _default: {
+    id: string;
+    server(input: PluginInput, opts?: PluginOptions): Promise<{
+        tool: {
+            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>;
+            };
+            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>;
+            };
+            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>;
+            };
+            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>;
+            };
+            memory_reset: {
+                description: string;
+                args: {
+                    confirm: import("zod").ZodBoolean;
+                };
+                execute(args: {
+                    confirm: boolean;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            memory_inspect: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            memory_mode: {
+                description: string;
+                args: {
+                    mode: import("zod").ZodEnum<{
+                        enabled: "enabled";
+                        disabled: "disabled";
+                        polluted: "polluted";
+                    }>;
+                    sessionId: import("zod").ZodOptional<import("zod").ZodString>;
+                };
+                execute(args: {
+                    mode: "enabled" | "disabled" | "polluted";
+                    sessionId?: string | undefined;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+        } | {
+            memory_reset: {
+                description: string;
+                args: {
+                    confirm: import("zod").ZodBoolean;
+                };
+                execute(args: {
+                    confirm: boolean;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            memory_inspect: {
+                description: string;
+                args: {};
+                execute(args: Record<string, never>, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            memory_mode: {
+                description: string;
+                args: {
+                    mode: import("zod").ZodEnum<{
+                        enabled: "enabled";
+                        disabled: "disabled";
+                        polluted: "polluted";
+                    }>;
+                    sessionId: import("zod").ZodOptional<import("zod").ZodString>;
+                };
+                execute(args: {
+                    mode: "enabled" | "disabled" | "polluted";
+                    sessionId?: string | undefined;
+                }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+            };
+            memory_read?: undefined;
+            memory_search?: undefined;
+            memory_list?: undefined;
+            memory_add_note?: undefined;
+        };
+        config(input: {
+            agent?: Record<string, unknown>;
+        }): Promise<void>;
+        "experimental.chat.system.transform"(input: {
+            sessionID?: string;
+            model: unknown;
+        }, output: {
+            system: string[];
+        }): Promise<void>;
+        "experimental.chat.messages.transform"(_input: unknown, output: {
+            messages: {
+                info: {
+                    role?: string;
+                };
+                parts: {
+                    type: string;
+                    text?: string;
+                }[];
+            }[];
+        }): Promise<void>;
+        event(input: {
+            event: {
+                type: string;
+                properties: unknown;
+            };
+        }): Promise<void>;
+        dispose(): Promise<void>;
+    }>;
+};
+export default _default;
+/**
+ * Registers the memorize / memorize-extract sub-agents through the config
+ * hook so installing the plugin requires no manual agent setup. Definitions
+ * are read from the plugin's bundled opencode.json (single source of truth
+ * with the dev checkout). A user-defined agent of the same name always wins —
+ * only missing entries are filled. opencode-specific packaging: codex ships
+ * its memory agents inside the binary.
+ */
+export declare function injectAgentDefinitions(config: {
+    agent?: Record<string, unknown>;
+}): void;

package/dist/src/index.js

@@ -0,0 +1,365 @@
+import { ensureMemoryLayout, buildMemorySystemPrompt, invalidateCache } from "./source.js";
+import { stripCitations, extractCitedSessionIds } from "./citation.js";
+import { memory_read, memory_search, memory_list, memory_add_note } from "../tools/memory.js";
+import { memory_reset, memory_inspect, memory_mode } from "../tools/control.js";
+import { MemoryStore } from "./store.js";
+import { runPhase1 } from "./phase1.js";
+import { runPhase2 } from "./phase2.js";
+import { setPluginInput, cleanupOldSubSessions, isMemorySubSession } from "./llm.js";
+import fs from "fs";
+import path from "path";
+let phase1InFlight = false;
+let pluginClient = null;
+// Configured MCP server names, fetched lazily; null until first successful fetch.
+let mcpServerNames = null;
+// Option names and defaults mirror codex's MemoriesToml/MemoriesConfig
+// (codex-rs/config/src/types.rs). Keep them 1:1 so the drift script and manual
+// syncing stay trivial; do not rename for taste.
+let pluginOptions = {
+    generate_memories: true,
+    use_memories: true,
+    dedicated_tools: true,
+    disable_on_external_context: false,
+    max_raw_memories_for_consolidation: 256,
+    max_unused_days: 30,
+    max_rollout_age_days: 10,
+    max_rollouts_per_startup: 2,
+    min_rollout_idle_hours: 6,
+};
+// Deliberately uncached: openDb() is already a singleton, and caching a store
+// here would hold a stale handle across closeDb() (e.g. after memory_reset).
+function getStore() {
+    return new MemoryStore();
+}
+// Citation blocks arrive via message.part.updated once per streaming delta,
+// so the same completed block is seen many times. Track which session ids
+// were already recorded per part to count each citation once.
+const recordedCitations = new Map();
+const MAX_TRACKED_PARTS = 500;
+export function takeNewCitations(partKey, ids) {
+    let seen = recordedCitations.get(partKey);
+    if (!seen) {
+        seen = new Set();
+        recordedCitations.set(partKey, seen);
+        if (recordedCitations.size > MAX_TRACKED_PARTS) {
+            const oldest = recordedCitations.keys().next().value;
+            if (oldest !== undefined)
+                recordedCitations.delete(oldest);
+        }
+    }
+    const fresh = ids.filter((id) => !seen.has(id));
+    for (const id of fresh)
+        seen.add(id);
+    return fresh;
+}
+export default {
+    id: "opencode-codex-memory",
+    async server(input, opts) {
+        setPluginInput(input);
+        pluginClient = input.client;
+        if (opts)
+            applyPluginOptions(opts);
+        void cleanupOldSubSessions().catch(() => { });
+        return buildHooks();
+    },
+};
+const KNOWN_OPTION_KEYS = new Set([
+    "generate_memories",
+    "use_memories",
+    "dedicated_tools",
+    "disable_on_external_context",
+    "extract_model",
+    "consolidation_model",
+    "max_raw_memories_for_consolidation",
+    "max_unused_days",
+    "max_rollout_age_days",
+    "max_rollouts_per_startup",
+    "min_rollout_idle_hours",
+]);
+// codex clamps numeric knobs in From<MemoriesToml> for MemoriesConfig
+// (config/src/types.rs); mirror the exact ranges. Non-finite values fall back
+// to the default.
+function clampInt(value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function applyPluginOptions(opts) {
+    for (const key of Object.keys(opts)) {
+        if (!KNOWN_OPTION_KEYS.has(key)) {
+            // codex uses deny_unknown_fields; a plugin can only warn. Covers typos
+            // and the deliberately unimplemented min_rate_limit_remaining_percent.
+            console.warn(`[opencode-codex-memory] unknown/unsupported option '${key}' ignored`);
+        }
+    }
+    if (typeof opts.generate_memories === "boolean")
+        pluginOptions.generate_memories = opts.generate_memories;
+    if (typeof opts.use_memories === "boolean")
+        pluginOptions.use_memories = opts.use_memories;
+    if (typeof opts.dedicated_tools === "boolean")
+        pluginOptions.dedicated_tools = opts.dedicated_tools;
+    if (typeof opts.disable_on_external_context === "boolean")
+        pluginOptions.disable_on_external_context = opts.disable_on_external_context;
+    if (typeof opts.extract_model === "string")
+        pluginOptions.extract_model = opts.extract_model;
+    if (typeof opts.consolidation_model === "string")
+        pluginOptions.consolidation_model = opts.consolidation_model;
+    if ("max_raw_memories_for_consolidation" in opts)
+        pluginOptions.max_raw_memories_for_consolidation = clampInt(opts.max_raw_memories_for_consolidation, 1, 4096, 256);
+    if ("max_unused_days" in opts)
+        pluginOptions.max_unused_days = clampInt(opts.max_unused_days, 0, 365, 30);
+    if ("max_rollout_age_days" in opts)
+        pluginOptions.max_rollout_age_days = clampInt(opts.max_rollout_age_days, 0, 90, 10);
+    if ("max_rollouts_per_startup" in opts)
+        pluginOptions.max_rollouts_per_startup = clampInt(opts.max_rollouts_per_startup, 1, 128, 2);
+    if ("min_rollout_idle_hours" in opts)
+        pluginOptions.min_rollout_idle_hours = clampInt(opts.min_rollout_idle_hours, 1, 48, 6);
+}
+/**
+ * codex marks every MCP server as memory-polluting unconditionally
+ * (codex-mcp server.rs pollutes_memory: true). opencode registers MCP tools
+ * as "<server>_<tool>", so match tool names against the configured server
+ * list. Fails closed to the web-tools-only check when the list is unavailable.
+ */
+async function isExternalContextTool(toolName) {
+    if (toolName === "websearch" || toolName === "webfetch")
+        return true;
+    if (!mcpServerNames && pluginClient) {
+        try {
+            const res = await pluginClient.mcp.status();
+            const servers = res?.data ?? res;
+            if (servers && typeof servers === "object") {
+                mcpServerNames = new Set(Object.keys(servers));
+            }
+        }
+        catch {
+            // MCP status unavailable (older opencode); keep web-tools-only checks.
+        }
+    }
+    if (!mcpServerNames)
+        return false;
+    for (const server of mcpServerNames) {
+        if (toolName.startsWith(`${server}_`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Registers the memorize / memorize-extract sub-agents through the config
+ * hook so installing the plugin requires no manual agent setup. Definitions
+ * are read from the plugin's bundled opencode.json (single source of truth
+ * with the dev checkout). A user-defined agent of the same name always wins —
+ * only missing entries are filled. opencode-specific packaging: codex ships
+ * its memory agents inside the binary.
+ */
+export function injectAgentDefinitions(config) {
+    let defs;
+    try {
+        const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
+        defs = JSON.parse(raw).agent ?? {};
+    }
+    catch (err) {
+        console.warn("[opencode-codex-memory] could not load bundled agent definitions:", err);
+        return;
+    }
+    config.agent ??= {};
+    for (const [name, def] of Object.entries(defs)) {
+        if (!config.agent[name])
+            config.agent[name] = def;
+    }
+}
+function buildHooks() {
+    const base = {
+        async config(input) {
+            try {
+                // The write pipeline is the only consumer of the sub-agents; with
+                // generation off they would just pollute the user's agent list.
+                if (!pluginOptions.generate_memories)
+                    return;
+                injectAgentDefinitions(input);
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] config hook error:", err);
+            }
+        },
+        async "experimental.chat.system.transform"(input, output) {
+            try {
+                if (!pluginOptions.use_memories)
+                    return;
+                if (input.sessionID && isMemorySubSession(input.sessionID))
+                    return;
+                ensureMemoryLayout();
+                const memoryPrompt = buildMemorySystemPrompt();
+                if (memoryPrompt) {
+                    output.system.push(memoryPrompt);
+                }
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] system.transform error:", err);
+            }
+        },
+        async "experimental.chat.messages.transform"(_input, output) {
+            try {
+                for (const msg of output.messages) {
+                    if (msg.info?.role !== "assistant")
+                        continue;
+                    for (const part of msg.parts) {
+                        if (part.type === "text" && typeof part.text === "string" && part.text.includes("<memory-citation>")) {
+                            const before = part.text;
+                            part.text = stripCitations(part.text);
+                            if (part.text.includes("<memory-citation>")) {
+                                console.warn("[opencode-codex-memory] citation marker still present after stripCitations — hook contract may have changed");
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] messages.transform error:", err);
+            }
+        },
+        async event(input) {
+            try {
+                const ev = input.event;
+                if (ev.type === "message.part.updated") {
+                    const part = ev.properties.part;
+                    if (!part || part.type !== "text" || typeof part.text !== "string")
+                        return;
+                    if (part.sessionID && isMemorySubSession(part.sessionID))
+                        return;
+                    if (!part.text.includes("<memory-citation>"))
+                        return;
+                    let ids = [];
+                    try {
+                        ids = extractCitedSessionIds(part.text);
+                    }
+                    catch {
+                        return;
+                    }
+                    const fresh = takeNewCitations(`${part.sessionID ?? ""}:${part.id ?? ""}`, ids);
+                    if (fresh.length > 0) {
+                        try {
+                            getStore().recordUsage(fresh);
+                        }
+                        catch (e) {
+                            console.error("[opencode-codex-memory] recordUsage failed:", e);
+                        }
+                    }
+                    return;
+                }
+                if (ev.type === "tool.execute.after") {
+                    // Mirrors codex: external context (web search or any MCP tool) only
+                    // pollutes the session's memory when disable_on_external_context is
+                    // enabled. Off by default.
+                    if (!pluginOptions.disable_on_external_context)
+                        return;
+                    const props = ev.properties;
+                    const toolName = props?.tool ?? "";
+                    if (props.sessionID && (await isExternalContextTool(toolName))) {
+                        try {
+                            getStore().markPolluted(props.sessionID);
+                        }
+                        catch (e) {
+                            console.error("[opencode-codex-memory] markPolluted failed:", e);
+                        }
+                    }
+                    return;
+                }
+                if (ev.type === "session.deleted") {
+                    // Mirrors codex delete_thread_memory: drop the extracted memory and
+                    // its job when the session is deleted; the file disappears at the
+                    // next phase-2 rebuild and the diff drives forgetting.
+                    const props = ev.properties;
+                    const sid = props?.info?.id;
+                    if (sid) {
+                        try {
+                            getStore().deleteSessionMemory(sid);
+                        }
+                        catch (e) {
+                            console.error("[opencode-codex-memory] deleteSessionMemory failed:", e);
+                        }
+                    }
+                    return;
+                }
+                if (ev.type === "session.idle") {
+                    const props = ev.properties;
+                    const sid = props?.sessionID;
+                    if (!sid || isMemorySubSession(sid))
+                        return;
+                    // codex stamps memory_mode at thread creation from generate_memories:
+                    // sessions seen while generation is off stay excluded permanently,
+                    // even if the option is re-enabled later.
+                    try {
+                        getStore().stampMemoryModeIfAbsent(sid, pluginOptions.generate_memories ? "enabled" : "disabled");
+                    }
+                    catch (e) {
+                        console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
+                    }
+                    void triggerPhase1(sid);
+                    return;
+                }
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] event error:", err);
+            }
+        },
+        async dispose() {
+            invalidateCache();
+        },
+    };
+    // Control tools (reset/inspect/mode) are always available. The memory
+    // read/search/list/add-note tools require BOTH use_memories and
+    // dedicated_tools, mirroring codex's MemoriesExtension: use_memories=false
+    // disables the whole extension including its tools (extension.rs).
+    const tool = pluginOptions.use_memories && pluginOptions.dedicated_tools
+        ? {
+            memory_read,
+            memory_search,
+            memory_list,
+            memory_add_note,
+            memory_reset,
+            memory_inspect,
+            memory_mode,
+        }
+        : {
+            memory_reset,
+            memory_inspect,
+            memory_mode,
+        };
+    return { ...base, tool };
+}
+async function triggerPhase1(currentSessionId) {
+    if (phase1InFlight || !pluginOptions.generate_memories)
+        return;
+    phase1InFlight = true;
+    try {
+        await runPhase1(getStore(), {
+            maxAgeDays: pluginOptions.max_rollout_age_days,
+            minIdleHours: pluginOptions.min_rollout_idle_hours,
+            maxClaimed: pluginOptions.max_rollouts_per_startup,
+            excludeSession: currentSessionId,
+            extractModel: pluginOptions.extract_model,
+        });
+    }
+    catch (err) {
+        console.error("[opencode-codex-memory] phase1 error:", err);
+    }
+    finally {
+        phase1InFlight = false;
+    }
+    void triggerPhase2();
+}
+async function triggerPhase2() {
+    try {
+        // runPhase2 has its own in-flight guard
+        await runPhase2(getStore(), {
+            maxRaw: pluginOptions.max_raw_memories_for_consolidation,
+            maxUnusedDays: pluginOptions.max_unused_days,
+            extensionRetentionDays: 7,
+            consolidationModel: pluginOptions.consolidation_model,
+        });
+    }
+    catch (err) {
+        console.error("[opencode-codex-memory] phase2 error:", err);
+    }
+}

package/dist/src/llm.d.ts

@@ -0,0 +1,19 @@
+import type { PluginInput } from "@opencode-ai/plugin";
+export interface ExtractionResult {
+    raw_memory: string;
+    rollout_summary: string;
+    rollout_slug: string | null;
+}
+export declare function setPluginInput(input: PluginInput): void;
+export declare function isMemorySubSession(sessionId: string): boolean;
+export interface ExtractOptions {
+    cwd?: string;
+    model?: string;
+}
+/** Returns null when the extractor reported a no-op (nothing worth remembering). */
+export declare function extractViaSubagent(sessionId: string, transcript: string, opts?: ExtractOptions): Promise<ExtractionResult | null>;
+export declare function consolidateViaSubagent(memoryRoot: string, diffFileName: string, model?: string): Promise<void>;
+export declare function cleanupOldSubSessions(maxAgeMinutes?: number): Promise<void>;
+export declare function fillTemplate(tmpl: string, vars: Record<string, string>): string;
+/** Parses the stage-1 JSON output. Returns null for the all-empty no-op response. */
+export declare function parseExtraction(raw: string): ExtractionResult | null;