opencode-codex-memory 0.1.2 → 0.1.5

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;

package/dist/src/llm.js

@@ -0,0 +1,251 @@
+import fs from "fs";
+import path from "path";
+let inputRef = null;
+export function setPluginInput(input) {
+    inputRef = input;
+}
+function getPluginInput() {
+    return inputRef;
+}
+// Sessions this plugin spawned for extraction/consolidation. The main
+// hooks skip these so the plugin never injects memory into (or memorizes) its
+// own sub-agents.
+const activeSubSessions = new Set();
+export function isMemorySubSession(sessionId) {
+    return activeSubSessions.has(sessionId);
+}
+async function createSession(agent, title) {
+    const input = getPluginInput();
+    if (!input)
+        throw new Error("plugin input not initialized");
+    const res = await input.client.session.create({
+        body: { title: title ?? `codex-memory-${agent}` },
+    });
+    if (!res.data)
+        throw new Error(`session create failed: ${JSON.stringify(res.error ?? {})}`);
+    const body = res.data;
+    const id = body.id;
+    if (!id)
+        throw new Error(`session create returned no id: ${JSON.stringify(body)}`);
+    activeSubSessions.add(id);
+    return id;
+}
+/**
+ * opencode's config carries the same split codex expresses with provider
+ * model preferences: `small_model` for cheap background work (codex:
+ * memory_extraction_preferred_model = gpt-5.4-mini) and `model` for capable
+ * work (codex: memory_consolidation_preferred_model = gpt-5.4). Cached per
+ * plugin instance — opencode reloads plugins on config change.
+ */
+let configModels = null;
+async function getConfigModels() {
+    if (configModels)
+        return configModels;
+    const input = getPluginInput();
+    if (!input)
+        return {};
+    try {
+        const res = await input.client.config.get();
+        const cfg = res?.data;
+        configModels = { model: cfg?.model, smallModel: cfg?.small_model };
+    }
+    catch {
+        // Config endpoint unavailable: leave models unset so the sub-agent runs
+        // on the session default, the previous behavior.
+        configModels = {};
+    }
+    return configModels;
+}
+// extract_model / consolidation model strings are "providerID/modelID".
+function parseModelRef(ref) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash === ref.length - 1)
+        return null;
+    return { providerID: ref.slice(0, slash), modelID: ref.slice(slash + 1) };
+}
+async function promptSession(sessionId, prompt, agent, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const input = getPluginInput();
+    if (!input)
+        throw new Error("plugin input not initialized");
+    const model = opts.model ? parseModelRef(opts.model) : null;
+    const promptPromise = input.client.session.prompt({
+        path: { id: sessionId },
+        body: {
+            agent,
+            ...(opts.system ? { system: opts.system } : {}),
+            ...(model ? { model } : {}),
+            parts: [{ type: "text", text: prompt }],
+        },
+    });
+    let timer;
+    try {
+        const res = await Promise.race([
+            promptPromise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`sub-agent prompt timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        if (!res.data)
+            throw new Error(`prompt failed: ${JSON.stringify(res.error ?? {})}`);
+        return extractAssistantText(res.data);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function extractAssistantText(body) {
+    if (!body)
+        return "";
+    if (typeof body === "string")
+        return body;
+    if (Array.isArray(body))
+        return body.map(extractAssistantText).join("\n");
+    if (typeof body.text === "string")
+        return body.text;
+    if (body.parts && Array.isArray(body.parts))
+        return body.parts.map((p) => p?.text ?? "").filter(Boolean).join("\n");
+    if (body.messages && Array.isArray(body.messages)) {
+        return body.messages
+            .filter((m) => m?.info?.role === "assistant")
+            .flatMap((m) => (m.parts ?? []).map((p) => p?.text ?? ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    if (body.output && typeof body.output === "string")
+        return body.output;
+    return JSON.stringify(body);
+}
+/** Returns null when the extractor reported a no-op (nothing worth remembering). */
+export async function extractViaSubagent(sessionId, transcript, opts = {}) {
+    const agent = "memorize-extract";
+    const subId = await createSession(agent, `codex-memory-extract-${sessionId}`);
+    try {
+        const prompt = buildExtractionInput(sessionId, opts.cwd ?? "unknown", transcript);
+        // extract_model option > opencode small_model > session default.
+        const model = opts.model ?? (await getConfigModels()).smallModel;
+        const raw = await promptSession(subId, prompt, agent, {
+            timeoutMs: 180_000,
+            system: readTemplate("stage_one_system.md"),
+            model,
+        });
+        return parseExtraction(raw);
+    }
+    finally {
+        void deleteSession(subId).catch(() => { });
+    }
+}
+// codex runs the consolidation agent under a 1h job lease with heartbeats;
+// its INIT pass is explicitly allowed to run long ("do not be lazy"). A short
+// timeout here would fail the job after the workspace was already synced.
+const CONSOLIDATION_TIMEOUT_MS = 3600_000;
+export async function consolidateViaSubagent(memoryRoot, diffFileName, model) {
+    const agent = "memorize";
+    const subId = await createSession(agent, "codex-memory-consolidate");
+    try {
+        const prompt = buildConsolidationPrompt(memoryRoot, diffFileName);
+        // consolidation_model option > opencode model (main) > session default.
+        const resolved = model ?? (await getConfigModels()).model;
+        await promptSession(subId, prompt, agent, { model: resolved, timeoutMs: CONSOLIDATION_TIMEOUT_MS });
+    }
+    finally {
+        void deleteSession(subId).catch(() => { });
+    }
+}
+// Must exceed the longest legitimate sub-session lifetime (consolidation may
+// run up to CONSOLIDATION_TIMEOUT_MS = 60min), or a second opencode instance /
+// plugin reload would delete a working sub-session mid-run.
+export async function cleanupOldSubSessions(maxAgeMinutes = 90) {
+    const input = getPluginInput();
+    if (!input)
+        return;
+    try {
+        const res = await input.client.session.list();
+        if (!res.data)
+            return;
+        const list = res.data;
+        const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
+        for (const s of list) {
+            if (s.title && s.title.startsWith("codex-memory-")) {
+                const created = s.time?.created ?? 0;
+                if (created && created < cutoff) {
+                    await deleteSession(s.id);
+                }
+            }
+        }
+    }
+    catch {
+        // best effort only
+    }
+}
+async function deleteSession(id) {
+    activeSubSessions.delete(id);
+    const input = getPluginInput();
+    if (!input)
+        return;
+    try {
+        const res = await input.client.session.delete({ path: { id } });
+        if (res.error) {
+            console.warn(`[opencode-codex-memory] failed to delete sub-session ${id}: ${JSON.stringify(res.error)}`);
+        }
+    }
+    catch (err) {
+        console.warn(`[opencode-codex-memory] error deleting sub-session ${id}:`, err);
+    }
+}
+// Substitute with a function so `$&`/`$'` sequences in the value are not
+// expanded as String.replace replacement patterns.
+export function fillTemplate(tmpl, vars) {
+    let out = tmpl;
+    for (const [key, value] of Object.entries(vars)) {
+        out = out.replaceAll(`{{ ${key} }}`, () => value);
+    }
+    return out;
+}
+function buildExtractionInput(sessionId, cwd, transcript) {
+    return fillTemplate(readTemplate("stage_one_input.md"), {
+        session_id: sessionId,
+        session_cwd: cwd,
+        transcript,
+    });
+}
+function buildConsolidationPrompt(memoryRoot, diffFileName) {
+    return fillTemplate(readTemplate("consolidation.md"), {
+        memory_root: memoryRoot,
+        phase2_workspace_diff_file: diffFileName,
+    });
+}
+function readTemplate(name) {
+    return fs.readFileSync(path.join(import.meta.dirname, "templates", name), "utf8");
+}
+/** Parses the stage-1 JSON output. Returns null for the all-empty no-op response. */
+export function parseExtraction(raw) {
+    const cleaned = raw.replace(/^```(?:json)?/gim, "").replace(/```$/gim, "").trim();
+    const start = cleaned.indexOf("{");
+    const end = cleaned.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start) {
+        throw new Error("extraction response contained no JSON object");
+    }
+    const json = cleaned.slice(start, end + 1);
+    const obj = JSON.parse(json);
+    if (typeof obj.raw_memory !== "string" || typeof obj.rollout_summary !== "string") {
+        throw new Error("extraction response missing required fields");
+    }
+    if (!obj.raw_memory.trim() && !obj.rollout_summary.trim()) {
+        return null;
+    }
+    // Guard against the model echoing the format skeleton from the system prompt.
+    const templateArtifacts = [
+        "<success|partial|fail|uncertain>",
+        "<primary task signature>",
+        "<short quote or near-verbatim request>",
+    ];
+    if (templateArtifacts.some((a) => obj.raw_memory.includes(a))) {
+        throw new Error("extraction returned template placeholder text instead of actual content");
+    }
+    return {
+        raw_memory: obj.raw_memory,
+        rollout_summary: obj.rollout_summary,
+        rollout_slug: typeof obj.rollout_slug === "string" && obj.rollout_slug.trim() ? obj.rollout_slug : null,
+    };
+}

package/dist/src/path-guard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Safe path resolution that cannot escape the memory root, mirroring codex
+ * ext/memories/src/local/path.rs + local.rs resolve_scoped_path:
+ * - absolute paths and `..` components are rejected lexically
+ * - hidden (dot) components are invisible (reported as not found), so .git
+ *   and other dotfiles are unreachable through the tools
+ * - every existing component is lstat-checked: symlinks are rejected, so a
+ *   link placed inside the workspace cannot lead reads outside it
+ */
+export declare function safeResolveMemoryPath(rel: string): string;

package/dist/src/path-guard.js

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { memoryRoot } from "./paths.js";
+/**
+ * Safe path resolution that cannot escape the memory root, mirroring codex
+ * ext/memories/src/local/path.rs + local.rs resolve_scoped_path:
+ * - absolute paths and `..` components are rejected lexically
+ * - hidden (dot) components are invisible (reported as not found), so .git
+ *   and other dotfiles are unreachable through the tools
+ * - every existing component is lstat-checked: symlinks are rejected, so a
+ *   link placed inside the workspace cannot lead reads outside it
+ */
+export function safeResolveMemoryPath(rel) {
+    const root = memoryRoot();
+    if (path.isAbsolute(rel)) {
+        throw new Error(`path escapes memory root: ${rel}`);
+    }
+    const parts = rel.split(/[\\/]+/).filter((p) => p.length > 0 && p !== ".");
+    let current = root;
+    for (const part of parts) {
+        if (part === "..") {
+            throw new Error(`path escapes memory root: ${rel}`);
+        }
+        if (part.startsWith(".")) {
+            throw new Error(`not found: ${rel}`);
+        }
+        current = path.join(current, part);
+        let st = null;
+        try {
+            st = fs.lstatSync(current);
+        }
+        catch {
+            // Component doesn't exist (yet): keep validating the rest lexically;
+            // the caller reports not-found / creates it under the checked prefix.
+        }
+        if (st?.isSymbolicLink()) {
+            throw new Error(`symlinks are not allowed in the memory workspace: ${rel}`);
+        }
+    }
+    if (current !== root && !current.startsWith(root + path.sep)) {
+        throw new Error(`path escapes memory root: ${rel}`);
+    }
+    return current;
+}