opencode-codex-memory 0.1.3 → 0.1.6

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;
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,4 @@
+export declare function memoryRoot(): string;
+export declare function memoryDbPath(): string;
+export declare function opencodeDbPath(): string;
+export declare function memorySummaryPath(): string;

package/dist/src/paths.js

@@ -0,0 +1,23 @@
+import path from "path";
+import os from "os";
+const MEMORY_DIR_NAME = "memories";
+const MEMORY_DB_NAME = "memory.db";
+const OVERRIDE_ENV = "OPENCODE_CODEX_MEMORY_TEST_ROOT";
+function dataRoot() {
+    const override = process.env[OVERRIDE_ENV];
+    if (override)
+        return override;
+    return path.join(os.homedir(), ".local", "share", "opencode");
+}
+export function memoryRoot() {
+    return path.join(dataRoot(), MEMORY_DIR_NAME);
+}
+export function memoryDbPath() {
+    return path.join(dataRoot(), MEMORY_DB_NAME);
+}
+export function opencodeDbPath() {
+    return path.join(dataRoot(), "opencode.db");
+}
+export function memorySummaryPath() {
+    return path.join(memoryRoot(), "memory_summary.md");
+}

package/dist/src/phase1.d.ts

@@ -0,0 +1,11 @@
+import { MemoryStore } from "./store.js";
+export interface Phase1Options {
+    maxAgeDays: number;
+    minIdleHours: number;
+    maxClaimed?: number;
+    maxUnusedDays?: number;
+    excludeSession?: string;
+    extractModel?: string;
+}
+export declare const DEFAULT_PHASE1_OPTIONS: Phase1Options;
+export declare function runPhase1(store: MemoryStore, opts?: Phase1Options): Promise<void>;

package/dist/src/phase1.js

@@ -0,0 +1,104 @@
+import { STAGE1_CONCURRENCY } from "./store.js";
+import { loadTranscript, selectEligibleSessions } from "./capture.js";
+import { redact, isMemoryExcludedFragment } from "./redact.js";
+import { stripCitations } from "./citation.js";
+import { extractViaSubagent } from "./llm.js";
+import { checkRateLimit } from "./ratelimit.js";
+export const DEFAULT_PHASE1_OPTIONS = {
+    maxAgeDays: 10,
+    minIdleHours: 6,
+    maxClaimed: 2,
+    maxUnusedDays: 30,
+};
+// codex serializes the full transcript and truncates at 70% of the model
+// context window, falling back to 150k tokens; ~4 chars/token puts the
+// char-estimate equivalent at 600k.
+const TRANSCRIPT_MAX_CHARS = 600_000;
+// When truncating, keep the head and the tail: the start carries the user's
+// framing, the end carries the final outcome and feedback.
+const TRANSCRIPT_HEAD_CHARS = 360_000;
+const TRANSCRIPT_TAIL_CHARS = 240_000;
+export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
+    store.pruneStage1Outputs(opts.maxUnusedDays ?? 30);
+    const rl = await checkRateLimit("phase1");
+    if (!rl.ok) {
+        console.warn("[opencode-codex-memory] skipping phase1 due to rate limit:", rl.reason);
+        return;
+    }
+    const eligible = selectEligibleSessions(store, opts);
+    if (eligible.length === 0)
+        return;
+    const claimed = store.claimStage1Jobs(eligible, opts.excludeSession, opts.maxClaimed);
+    if (claimed.length === 0)
+        return;
+    const sessionById = new Map(eligible.map((s) => [s.id, s]));
+    await runPool(claimed, STAGE1_CONCURRENCY, async (claim) => {
+        const sid = claim.sessionId;
+        try {
+            const session = sessionById.get(sid);
+            const sourceUpdatedAt = session?.updated_at ?? Date.now();
+            const transcript = buildTranscript(sid);
+            if (!transcript.trim()) {
+                store.markStage1SucceededNoOutput(sid, claim.ownershipToken, sourceUpdatedAt);
+                return;
+            }
+            const result = await extractViaSubagent(sid, transcript, {
+                cwd: session?.directory ?? undefined,
+                model: opts.extractModel,
+            });
+            if (!result) {
+                // Extractor judged the session not worth remembering.
+                store.markStage1SucceededNoOutput(sid, claim.ownershipToken, sourceUpdatedAt);
+                return;
+            }
+            store.markStage1Succeeded(sid, claim.ownershipToken, {
+                session_id: sid,
+                source_updated_at: sourceUpdatedAt,
+                raw_memory: redact(result.raw_memory),
+                rollout_summary: redact(result.rollout_summary),
+                // codex redacts the slug too — it becomes a filename.
+                rollout_slug: result.rollout_slug ? redact(result.rollout_slug) : result.rollout_slug,
+                cwd: session?.directory ?? null,
+                generated_at: Date.now(),
+            });
+        }
+        catch (err) {
+            store.markStage1Failed(sid, claim.ownershipToken, err.message);
+        }
+    });
+}
+function buildTranscript(sessionId) {
+    const msgs = loadTranscript(sessionId);
+    if (msgs.length === 0)
+        return "";
+    const lines = [];
+    for (const m of msgs) {
+        if (m.type === "system")
+            continue;
+        const role = m.role ?? m.type;
+        const text = m.text ?? "";
+        if (!text.trim())
+            continue;
+        // Injected AGENTS.md/<skill> blocks in user content are excluded from
+        // extraction (codex is_memory_excluded_contextual_user_fragment).
+        if (role === "user" && isMemoryExcludedFragment(text))
+            continue;
+        lines.push(`### ${role}\n${redact(stripCitations(text))}`);
+    }
+    const full = lines.join("\n\n");
+    if (full.length <= TRANSCRIPT_MAX_CHARS)
+        return full;
+    return (full.slice(0, TRANSCRIPT_HEAD_CHARS) +
+        "\n\n[... transcript truncated ...]\n\n" +
+        full.slice(full.length - TRANSCRIPT_TAIL_CHARS));
+}
+async function runPool(items, concurrency, fn) {
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+        while (cursor < items.length) {
+            const i = cursor++;
+            await fn(items[i]);
+        }
+    });
+    await Promise.all(workers);
+}

package/dist/src/phase2.d.ts

@@ -0,0 +1,11 @@
+import { MemoryStore } from "./store.js";
+export interface Phase2Options {
+    maxRaw: number;
+    maxUnusedDays: number;
+    extensionRetentionDays: number;
+    consolidationModel?: string;
+}
+export declare const DEFAULT_PHASE2_OPTIONS: Phase2Options;
+export declare function runPhase2(store: MemoryStore, opts?: Phase2Options): Promise<{
+    status: string;
+}>;

package/dist/src/phase2.js

@@ -0,0 +1,83 @@
+import { ensureLayout, rebuildRawMemories, writeRolloutSummaries, pruneExtensionResources, writeWorkspaceDiff } from "./workspace.js";
+import { ensureBaseline, captureWorkspaceDiff, resetBaseline, DIFF_ARTIFACT } from "./git-baseline.js";
+import { consolidateViaSubagent } from "./llm.js";
+import { invalidateCache } from "./source.js";
+import { memoryRoot } from "./paths.js";
+import { checkRateLimit } from "./ratelimit.js";
+export const DEFAULT_PHASE2_OPTIONS = {
+    maxRaw: 256,
+    maxUnusedDays: 30,
+    extensionRetentionDays: 7,
+};
+let phase2InFlight = false;
+export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
+    if (phase2InFlight)
+        return { status: "already_running" };
+    phase2InFlight = true;
+    try {
+        const rl = await checkRateLimit("phase2");
+        if (!rl.ok)
+            return { status: "skipped_rate_limit" };
+        const claim = store.claimGlobalPhase2Job();
+        if (claim.type !== "claimed")
+            return { status: claim.type };
+        try {
+            ensureLayout();
+            // Preserves an existing baseline (only initializes a missing one): the
+            // diff below must span last-successful-run -> now so user edits and
+            // ad-hoc notes added since then reach consolidation. Stale stage-1
+            // output pruning happens in phase 1, before the rate gate (codex
+            // start.rs ordering).
+            if (!await ensureBaseline()) {
+                store.markPhase2Failed(claim.ownershipToken, "git baseline failed");
+                return { status: "baseline_failed" };
+            }
+            const outputs = store.getPhase2InputSelection(opts.maxRaw, opts.maxUnusedDays);
+            rebuildRawMemories(outputs);
+            writeRolloutSummaries(outputs);
+            pruneExtensionResources(opts.extensionRetentionDays);
+            const diff = await captureWorkspaceDiff();
+            if (diff.changes.length === 0) {
+                store.markPhase2Succeeded(claim.ownershipToken, outputs);
+                return { status: "no_workspace_changes" };
+            }
+            writeWorkspaceDiff(diff);
+            let heartbeatLost = false;
+            const heartbeat = setInterval(() => {
+                if (!store.heartbeatPhase2Job(claim.ownershipToken)) {
+                    heartbeatLost = true;
+                }
+            }, 90_000);
+            try {
+                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel);
+            }
+            finally {
+                clearInterval(heartbeat);
+            }
+            // Final synchronous ownership confirmation before the destructive
+            // baseline reset (codex phase2.rs does the same): the periodic flag can
+            // be up to 90s stale, and a stale worker resetting the baseline would
+            // swallow the diff a re-claiming worker is about to consume. The
+            // heartbeat is token+status guarded, so it fails once ownership is lost;
+            // markPhase2Failed is equally guarded and becomes a no-op then.
+            if (heartbeatLost || !store.heartbeatPhase2Job(claim.ownershipToken)) {
+                store.markPhase2Failed(claim.ownershipToken, "ownership lost");
+                return { status: "heartbeat_lost" };
+            }
+            if (!await resetBaseline()) {
+                store.markPhase2Failed(claim.ownershipToken, "baseline reset failed");
+                return { status: "baseline_reset_failed" };
+            }
+            store.markPhase2Succeeded(claim.ownershipToken, outputs);
+            invalidateCache();
+            return { status: "succeeded" };
+        }
+        catch (err) {
+            store.markPhase2Failed(claim.ownershipToken, err.message);
+            return { status: "failed" };
+        }
+    }
+    finally {
+        phase2InFlight = false;
+    }
+}

package/dist/src/ratelimit.d.ts

@@ -0,0 +1,5 @@
+export interface RateLimitInfo {
+    ok: boolean;
+    reason?: string;
+}
+export declare function checkRateLimit(kind?: "phase1" | "phase2"): Promise<RateLimitInfo>;

package/dist/src/ratelimit.js

@@ -0,0 +1,20 @@
+let lastPhase1 = 0;
+let lastPhase2 = 0;
+const MIN_PHASE1_INTERVAL_MS = 30_000;
+const MIN_PHASE2_INTERVAL_MS = 5 * 60 * 1000;
+export async function checkRateLimit(kind = "phase1") {
+    const now = Date.now();
+    if (kind === "phase1") {
+        if (now - lastPhase1 < MIN_PHASE1_INTERVAL_MS) {
+            return { ok: false, reason: "phase1 rate limit (30s)" };
+        }
+        lastPhase1 = now;
+    }
+    else {
+        if (now - lastPhase2 < MIN_PHASE2_INTERVAL_MS) {
+            return { ok: false, reason: "phase2 rate limit (5min)" };
+        }
+        lastPhase2 = now;
+    }
+    return { ok: true };
+}

package/dist/src/redact.d.ts

@@ -0,0 +1,8 @@
+export declare function redact(text: string): string;
+/**
+ * Mirrors codex is_memory_excluded_contextual_user_fragment (phase1.rs):
+ * injected AGENTS.md instruction blocks and <skill> payloads inside user
+ * content are contextual boilerplate, not conversation — they must not be
+ * mined for memories.
+ */
+export declare function isMemoryExcludedFragment(text: string): boolean;

package/dist/src/redact.js

@@ -0,0 +1,37 @@
+const REDACTIONS = [
+    { re: /sk-ant-[A-Za-z0-9_\-]{20,}/g, replacement: "[REDACTED:anthropic-key]" },
+    { re: /sk-[A-Za-z0-9]{20,}/g, replacement: "[REDACTED:openai-key]" },
+    { re: /AKIA[0-9A-Z]{16}/g, replacement: "[REDACTED:aws-key]" },
+    { re: /gh[pousr]_[A-Za-z0-9]{36,}/g, replacement: "[REDACTED:github-token]" },
+    { re: /xox[baprs]-[A-Za-z0-9\-]{10,}/g, replacement: "[REDACTED:slack-token]" },
+    // Case-insensitive with a 16-char floor, matching codex's sanitizer.
+    { re: /bearer\s+[A-Za-z0-9\-\._~+\/=]{16,}/gi, replacement: "Bearer [REDACTED]" },
+    {
+        re: /-----BEGIN [A-Z]+ PRIVATE KEY-----[\s\S]*?-----END [A-Z]+ PRIVATE KEY-----/g,
+        replacement: "[REDACTED:private-key]",
+    },
+    { re: /(password|passwd|pwd|secret|api[_-]?key|token|access[_-]?token)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
+    { re: /(?:aws_secret_access_key|aws_access_key_id)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
+];
+export function redact(text) {
+    let out = text;
+    for (const { re, replacement } of REDACTIONS) {
+        out = out.replace(re, replacement);
+    }
+    return out;
+}
+function matchesMarkedFragment(text, startMarker, endMarker) {
+    const trimmed = text.trim();
+    return (trimmed.slice(0, startMarker.length).toLowerCase() === startMarker.toLowerCase() &&
+        trimmed.slice(-endMarker.length).toLowerCase() === endMarker.toLowerCase());
+}
+/**
+ * Mirrors codex is_memory_excluded_contextual_user_fragment (phase1.rs):
+ * injected AGENTS.md instruction blocks and <skill> payloads inside user
+ * content are contextual boilerplate, not conversation — they must not be
+ * mined for memories.
+ */
+export function isMemoryExcludedFragment(text) {
+    return (matchesMarkedFragment(text, "# AGENTS.md instructions", "</INSTRUCTIONS>") ||
+        matchesMarkedFragment(text, "<skill>", "</skill>"));
+}

package/dist/src/source.d.ts

@@ -0,0 +1,3 @@
+export declare function invalidateCache(): void;
+export declare function buildMemorySystemPrompt(): string | null;
+export declare function ensureMemoryLayout(): void;

package/dist/src/source.js

@@ -0,0 +1,46 @@
+import fs from "fs";
+import path from "path";
+import { memorySummaryPath, memoryRoot } from "./paths.js";
+import { truncateToTokens } from "./token.js";
+import { fillTemplate } from "./llm.js";
+const MEMORY_SUMMARY_TOKEN_LIMIT = 2500;
+const READ_PATH_TEMPLATE = "read_path.md";
+let cached = null;
+function readTemplate() {
+    const templatePath = path.join(import.meta.dirname, "templates", READ_PATH_TEMPLATE);
+    return fs.readFileSync(templatePath, "utf8");
+}
+function readMemorySummary() {
+    const summaryPath = memorySummaryPath();
+    if (!fs.existsSync(summaryPath))
+        return null;
+    const stat = fs.statSync(summaryPath);
+    if (cached && cached.mtime === stat.mtimeMs) {
+        return cached.content;
+    }
+    const raw = fs.readFileSync(summaryPath, "utf8").trim();
+    if (!raw)
+        return null;
+    const truncated = truncateToTokens(raw, MEMORY_SUMMARY_TOKEN_LIMIT);
+    cached = {
+        content: truncated,
+        mtime: stat.mtimeMs,
+    };
+    return truncated;
+}
+export function invalidateCache() {
+    cached = null;
+}
+export function buildMemorySystemPrompt() {
+    const summary = readMemorySummary();
+    if (!summary)
+        return null;
+    const template = readTemplate();
+    return fillTemplate(template, {
+        base_path: memoryRoot(),
+        memory_summary: summary,
+    });
+}
+export function ensureMemoryLayout() {
+    fs.mkdirSync(memoryRoot(), { recursive: true });
+}