opencode-codex-memory 0.5.0 → 0.6.1

package/dist/src/ratelimit.js

@@ -1,23 +1,103 @@
+export class ProviderCapacityError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "ProviderCapacityError";
+    }
+}
 /**
- * Process-local anti-stampede for phase 1 only.
+ * Process-local anti-stampede for phase 1, plus an observed-quota circuit
+ * breaker that stands in for Codex guard.rs.
  *
  * Codex has no wall-clock throttle: it reads live provider quota once per
  * startup (memories/write/src/guard.rs) and fails open when unknown. Opencode
- * does not expose provider rate limits to plugins, so this stub keeps
- * chat.message/idle from hammering discovery + claim when many sessions go
- * idle at once.
+ * does not expose provider rate limits to plugins, so this stub:
+ * - keeps chat.message/idle from hammering discovery + claim (30s, phase 1)
+ * - after a quota/rate-limit API error, skips further claims until the same
+ *   1h window Codex uses for job retry_at — so a quota outage cannot burn
+ *   every eligible session's retry budget
  *
  * Semantics deliberately match "do not start another token-using run too
  * often", not "do not look often":
- * - checkRateLimit only reads the clock (empty/no-claim passes do not stamp)
+ * - checkRateLimit only reads clocks (empty/no-claim passes do not stamp)
  * - markRateLimitUsed stamps after a stage-1 claim actually succeeds
- * - phase 2 has no process timer; the DB claim + 6h cooldown serialize it
- *   (same as codex phase2 job outcomes)
+ * - noteProviderCapacityExhausted stamps after an observed quota error
+ * - phase 2 has no 30s timer; the DB claim + 6h cooldown serialize it.
+ *   The observed-quota stamp still skips phase 2 (Codex start.rs skips both).
  */
 let lastPhase1Work = 0;
+const providerCapacityUntil = new Map();
 const MIN_PHASE1_INTERVAL_MS = 30_000;
-export async function checkRateLimit(kind = "phase1") {
-    // Phase 2: no process-local gate (codex relies on DB claim/cooldown only).
+export const PROVIDER_CAPACITY_BACKOFF_MS = 3_600_000;
+const PROVIDER_CAPACITY_RE = /usage limit|free usage exceeded|provider capacity exhausted|rate[\s_-]?limit|quota(?:\s+(?:exceeded|exhausted|reached))?|too many requests|\b429\b|resource_exhausted|insufficient_quota|billing.?hard.?limit/i;
+function errorRecord(error) {
+    return error && typeof error === "object" ? error : null;
+}
+function providerCapacityStatusCode(error) {
+    const record = errorRecord(error);
+    const data = errorRecord(record?.data);
+    const value = record?.statusCode ?? data?.statusCode;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+export function providerCapacityMessage(error) {
+    try {
+        if (typeof error === "string")
+            return error;
+        if (error instanceof Error)
+            return String(error.message ?? "unknown error");
+        const record = errorRecord(error);
+        const data = errorRecord(record?.data);
+        const message = record?.message ?? data?.message;
+        if (typeof message === "string")
+            return message;
+        return String(error ?? "unknown error");
+    }
+    catch {
+        return "unknown error";
+    }
+}
+export function isProviderCapacityError(error) {
+    if (error instanceof ProviderCapacityError)
+        return true;
+    if (providerCapacityStatusCode(error) === 429)
+        return true;
+    return PROVIDER_CAPACITY_RE.test(providerCapacityMessage(error));
+}
+function providerCapacityScope(phase, model) {
+    return model ? `model:${model}` : `phase:${phase}:default`;
+}
+export function activeProviderCapacityBackoffs(now = Date.now()) {
+    const active = [];
+    for (const [scope, until] of providerCapacityUntil) {
+        if (until <= now) {
+            providerCapacityUntil.delete(scope);
+            continue;
+        }
+        active.push({ scope, retry_at: Math.floor(until / 1000) });
+    }
+    return active.sort((a, b) => a.scope.localeCompare(b.scope));
+}
+export function isProviderCapacityBlocked(phase, model, now = Date.now()) {
+    const until = providerCapacityUntil.get(providerCapacityScope(phase, model));
+    return until !== undefined && until > now;
+}
+/** Call after a quota/rate-limit failure so later passes skip claiming. */
+export function noteProviderCapacityExhausted(phase, model, now = Date.now()) {
+    providerCapacityUntil.set(providerCapacityScope(phase, model), now + PROVIDER_CAPACITY_BACKOFF_MS);
+}
+export async function checkRateLimit(kind = "phase1", model) {
+    if (isProviderCapacityBlocked(kind, model)) {
+        return {
+            ok: false,
+            reason: `provider capacity exhausted for ${providerCapacityScope(kind, model)} (observed quota/rate-limit)`,
+        };
+    }
+    // Phase 2: no 30s gate (codex relies on DB claim/cooldown only).
     if (kind === "phase2")
         return { ok: true };
     const now = Date.now();
@@ -31,7 +111,8 @@ export function markRateLimitUsed(kind = "phase1") {
     if (kind === "phase1")
         lastPhase1Work = Date.now();
 }
-/** Test seam: reset the process-local stamp. */
+/** Test seam: reset the process-local stamps. */
 export function resetRateLimitForTest() {
     lastPhase1Work = 0;
+    providerCapacityUntil.clear();
 }

package/dist/src/store.d.ts

@@ -57,6 +57,13 @@ export declare class MemoryStore {
     /** Extraction succeeded but produced nothing worth keeping: finish the job and drop any stale output. */
     markStage1SucceededNoOutput(sessionId: string, ownershipToken: string, sourceUpdatedAt: number): void;
     markStage1Failed(sessionId: string, ownershipToken: string, error: unknown): void;
+    /**
+     * Re-open stage-1 jobs that exhausted their retry budget solely because of
+     * a quota/rate-limit error. Historical completed sessions never get a newer
+     * watermark, so without this they stay failed forever after a quota outage.
+     * Leaves retry_at alone so an active backoff still holds.
+     */
+    requeueExhaustedProviderCapacityJobs(): number;
     /**
      * Plugin dispose/reload: release a claimed stage-1 job without burning a retry
      * or imposing the 1h backoff. Leaves status=pending so the next process can
@@ -146,11 +153,20 @@ export declare class MemoryStore {
      */
     stage1JobSnapshot(): {
         by_status: Record<string, number>;
-        recent_errors: {
-            session_id: string;
-            last_error: string;
-            retry_at: number | null;
-            status: string;
-        }[];
+        by_failure_class: {
+            backoff: number;
+            provider_capacity: number;
+            other_exhausted: number;
+        };
+        recent_errors: Stage1RecentError[];
     };
 }
+export type Stage1FailureClass = "backoff" | "provider_capacity" | "other_exhausted";
+export interface Stage1RecentError {
+    session_id: string;
+    last_error: string;
+    retry_at: number | null;
+    status: string;
+    retry_remaining: number;
+    failure_class: Stage1FailureClass | null;
+}

package/dist/src/store.js

@@ -1,4 +1,5 @@
 import { openDb } from "./db.js";
+import { isProviderCapacityError } from "./ratelimit.js";
 export const DEFAULT_RETRY_REMAINING = 3;
 export const STAGE1_LEASE_SECONDS = 3600;
 export const PHASE2_LEASE_SECONDS = 3600;
@@ -191,6 +192,24 @@ export class MemoryStore {
     }
     markStage1Failed(sessionId, ownershipToken, error) {
         const message = failureMessage(error);
+        const tNow = nowSec();
+        const retryAt = tNow + STAGE1_RETRY_DELAY_SECONDS;
+        // Quota/rate-limit is transient provider capacity, not a bad transcript.
+        // Codex avoids claiming in that state via guard.rs; we cannot read quota,
+        // so keep the job pending and do not burn retry_remaining. Claim still
+        // honors retry_at, so this cannot tight-loop while quota is down.
+        if (isProviderCapacityError(error)) {
+            this.db
+                .prepare(`UPDATE memory_jobs SET
+             status = 'pending',
+             last_error = ?,
+             retry_at = ?,
+             finished_at = ?,
+             lease_until = NULL
+           WHERE kind='memory_stage1' AND job_key=? AND status='running' AND ownership_token=?`)
+                .run(message.slice(0, 4000), retryAt, tNow, sessionId, ownershipToken);
+            return;
+        }
         this.db
             .prepare(`UPDATE memory_jobs SET
            status = CASE WHEN retry_remaining > 1 THEN 'pending' ELSE 'failed' END,
@@ -200,7 +219,30 @@ export class MemoryStore {
            finished_at = ?,
            lease_until = NULL
          WHERE kind='memory_stage1' AND job_key=? AND status='running' AND ownership_token=?`)
-            .run(message.slice(0, 4000), nowSec() + STAGE1_RETRY_DELAY_SECONDS, nowSec(), sessionId, ownershipToken);
+            .run(message.slice(0, 4000), retryAt, tNow, sessionId, ownershipToken);
+    }
+    /**
+     * Re-open stage-1 jobs that exhausted their retry budget solely because of
+     * a quota/rate-limit error. Historical completed sessions never get a newer
+     * watermark, so without this they stay failed forever after a quota outage.
+     * Leaves retry_at alone so an active backoff still holds.
+     */
+    requeueExhaustedProviderCapacityJobs() {
+        const rows = this.db
+            .prepare(`SELECT job_key, last_error FROM memory_jobs
+         WHERE kind='memory_stage1' AND status='failed' AND last_error IS NOT NULL`)
+            .all();
+        let n = 0;
+        const stmt = this.db.prepare(`UPDATE memory_jobs SET status='pending', retry_remaining=?
+       WHERE kind='memory_stage1' AND job_key=? AND status='failed'`);
+        this.db.transaction(() => {
+            for (const row of rows) {
+                if (!isProviderCapacityError(row.last_error))
+                    continue;
+                n += stmt.run(DEFAULT_RETRY_REMAINING, row.job_key).changes;
+            }
+        }).immediate();
+        return n;
     }
     /**
      * Plugin dispose/reload: release a claimed stage-1 job without burning a retry
@@ -529,12 +571,39 @@ export class MemoryStore {
         const by_status = {};
         for (const r of rows)
             by_status[r.status] = r.c;
-        const recent_errors = this.db
-            .prepare(`SELECT job_key AS session_id, last_error, retry_at, status FROM memory_jobs
+        const tNow = nowSec();
+        const errorRows = this.db
+            .prepare(`SELECT job_key AS session_id, last_error, retry_at, status, retry_remaining FROM memory_jobs
          WHERE kind='memory_stage1' AND last_error IS NOT NULL
-         ORDER BY COALESCE(finished_at, started_at, 0) DESC
-         LIMIT 5`)
+         ORDER BY COALESCE(finished_at, started_at, 0) DESC`)
             .all();
-        return { by_status, recent_errors };
+        const by_failure_class = { backoff: 0, provider_capacity: 0, other_exhausted: 0 };
+        const recent_errors = [];
+        for (const row of errorRows) {
+            const failure_class = classifyStage1Failure(row, tNow);
+            if (failure_class)
+                by_failure_class[failure_class]++;
+            if (recent_errors.length < 5) {
+                recent_errors.push({
+                    session_id: row.session_id,
+                    last_error: row.last_error,
+                    retry_at: row.retry_at,
+                    status: row.status,
+                    retry_remaining: row.retry_remaining,
+                    failure_class,
+                });
+            }
+        }
+        return { by_status, by_failure_class, recent_errors };
+    }
+}
+function classifyStage1Failure(row, nowSec) {
+    if (row.status === "failed" || row.retry_remaining <= 0) {
+        return isProviderCapacityError(row.last_error) ? "provider_capacity" : "other_exhausted";
     }
+    if (row.retry_at != null && row.retry_at > nowSec)
+        return "backoff";
+    if (isProviderCapacityError(row.last_error))
+        return "provider_capacity";
+    return null;
 }

package/dist/tools/control.js

@@ -12,6 +12,8 @@ import { codexInteropMtimes, resolveCodexInterop } from "../src/codex-interop.js
 import { claudeImportStatus, resolveClaudeHome } from "../src/claude-import.js";
 import { formatDiagnosticLine, getDiscoveryStatus, getRecentDiagnostics, } from "../src/diagnostics.js";
 import { isPluginShuttingDown } from "../src/lifecycle.js";
+import { getAgentHealth } from "../src/agent-health.js";
+import { activeProviderCapacityBackoffs } from "../src/ratelimit.js";
 function isSymlinkedRoot() {
     try {
         assertMemoryRootSafe();
@@ -137,6 +139,18 @@ function listMemoriesDir() {
     walk(root, "");
     return out;
 }
+function renderAgentHealth() {
+    const health = getAgentHealth();
+    const lines = [
+        `agent_config: ${health.observed ? "observed" : "not observed (config hook has not run)"}`,
+        `agent_generation_enabled: ${health.generationEnabled ?? "unknown"}`,
+    ];
+    for (const name of ["memorize", "memorize-extract"]) {
+        const entry = health.agents[name];
+        lines.push(`  agent_${name}: source=${entry.source} status=${entry.healthy ? "healthy" : "degraded"}`, ...entry.issues.map((issue) => `    issue: ${issue}`));
+    }
+    return lines;
+}
 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, " +
@@ -187,7 +201,8 @@ function fmtWatermarkMs(ms) {
 }
 export const memory_inspect = tool({
     description: "Inspect the current memory state. Returns: stage1_outputs count, stage-1 job status " +
-        "breakdown and recent errors, Phase 2 job status (including last error / retry time), " +
+        "breakdown, failure classes (backoff / provider_capacity / other_exhausted), recent errors, " +
+        "Phase 2 job status (including last error / retry time), " +
         "last discovery outcome, pipeline diagnostics, memory_summary token estimate " +
         "(on-disk; injection caps at ~2500), a listing of the memories directory, the " +
         "effective plugin options, and any configuration warnings. Use it to verify " +
@@ -231,9 +246,20 @@ export const memory_inspect = tool({
             const stage1StatusParts = Object.entries(stage1Jobs.by_status)
                 .sort(([a], [b]) => a.localeCompare(b))
                 .map(([s, c]) => `${s}=${c}`);
+            const fc = stage1Jobs.by_failure_class;
+            const failureParts = [
+                fc.backoff > 0 ? `backoff=${fc.backoff}` : "",
+                fc.provider_capacity > 0 ? `provider_capacity=${fc.provider_capacity}` : "",
+                fc.other_exhausted > 0 ? `other_exhausted=${fc.other_exhausted}` : "",
+            ].filter(Boolean);
             const stage1Lines = [
                 `stage1_jobs: ${stage1StatusParts.length > 0 ? stage1StatusParts.join(" ") : "none"}`,
-                ...stage1Jobs.recent_errors.map((e) => `  stage1_error ${e.session_id} (${e.status}): ${e.last_error.slice(0, 200)}${e.retry_at ? ` retry_at=${fmtUnixSec(e.retry_at)}` : ""}`),
+                `stage1_failures: ${failureParts.length > 0 ? failureParts.join(" ") : "none"}`,
+                ...stage1Jobs.recent_errors.map((e) => {
+                    const klass = e.failure_class ? `, ${e.failure_class}` : "";
+                    const retry = e.retry_at ? ` retry_at=${fmtUnixSec(e.retry_at)}` : "";
+                    return `  stage1_error ${e.session_id} (${e.status}${klass}): ${e.last_error.slice(0, 200)}${retry}`;
+                }),
             ];
             const discovery = getDiscoveryStatus();
             const discoveryLine = discovery
@@ -247,6 +273,10 @@ export const memory_inspect = tool({
                 `phase2_in_flight: ${isPhase2InFlight()}`,
                 `plugin_shutting_down: ${isPluginShuttingDown()}`,
             ];
+            const capacityBackoffs = activeProviderCapacityBackoffs();
+            const capacityLines = capacityBackoffs.length > 0
+                ? capacityBackoffs.map((b) => `provider_capacity_backoff ${b.scope}: retry_at=${fmtUnixSec(b.retry_at)}`)
+                : ["provider_capacity_backoff: none"];
             const diagnostics = getRecentDiagnostics(12);
             const diagnosticLines = diagnostics.length > 0
                 ? ["recent_events:", ...diagnostics.map((e) => `  ${formatDiagnosticLine(e)}`)]
@@ -258,12 +288,15 @@ export const memory_inspect = tool({
                 discoveryLine,
                 eligibilityHint,
                 ...processLines,
+                ...capacityLines,
                 `memory_summary_chars: ${summaryChars}`,
                 `memory_summary_tokens_est: ${summaryTokens} (on disk; injection caps at ~2500)`,
                 `memories_dir_entries: ${listing.length}`,
                 "",
                 ...renderEffectiveConfig(),
                 "",
+                ...renderAgentHealth(),
+                "",
                 ...diagnosticLines,
                 "",
                 "Files:",
@@ -274,6 +307,7 @@ export const memory_inspect = tool({
                 metadata: {
                     stage1_count: outputs.length,
                     stage1_jobs: stage1Jobs.by_status,
+                    stage1_failures: stage1Jobs.by_failure_class,
                     stage1_recent_errors: stage1Jobs.recent_errors,
                     phase2_status: phase2?.status ?? null,
                     phase2_last_error: phase2?.last_error ?? null,
@@ -281,6 +315,7 @@ export const memory_inspect = tool({
                     phase2_last_attempt_finished_at: phase2?.finished_at ?? null,
                     phase2_last_success_watermark: phase2?.last_success_watermark ?? null,
                     phase2_last_success_finished_at: phase2?.success_finished_at ?? null,
+                    provider_capacity_backoffs: capacityBackoffs,
                     // Back-compat aliases used by earlier inspect consumers.
                     phase2_last_finished_at: phase2?.success_finished_at ?? null,
                     discovery,
@@ -298,6 +333,7 @@ export const memory_inspect = tool({
                         },
                     },
                     config_warnings: [...getConfigWarnings()],
+                    agent_health: getAgentHealth(),
                     recent_events: diagnostics,
                 },
             };

package/dist/tools/memory.d.ts

@@ -15,11 +15,13 @@ export declare const memory_list: {
     description: string;
     args: {
         path: import("zod").ZodDefault<import("zod").ZodString>;
+        cursor: import("zod").ZodOptional<import("zod").ZodString>;
         max_results: import("zod").ZodDefault<import("zod").ZodNumber>;
     };
     execute(args: {
         path: string;
         max_results: number;
+        cursor?: string | undefined;
     }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
 };
 export declare const memory_search: {

package/dist/tools/memory.js

@@ -20,7 +20,9 @@ export const memory_read = tool({
             }
             const stat = fs.lstatSync(fullPath);
             if (stat.isDirectory()) {
-                const entries = fs.readdirSync(fullPath);
+                const entries = visibleEntries(fullPath)
+                    .sort((a, b) => comparePathNames(a.name, b.name))
+                    .map((e) => e.name);
                 return {
                     output: `Directory ${args.path}/\n` + entries.map((e) => `- ${e}`).join("\n") + "\n(use memory_list for sorted, typed listings)",
                     metadata: { kind: "directory", entries },
@@ -92,15 +94,23 @@ function visibleEntries(dir) {
     return out;
 }
 const LIST_MAX_RESULTS = 2000;
+// Codex sorts paths lexically (`Path` ordering), not with locale collation.
+// Keep ordering stable across hosts and match ASCII path ordering.
+function comparePathNames(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
 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.",
+        "with entry types. Hidden files and symlinks are skipped. Supports cursor pagination and listing " +
+        "a single file. Use path '' (empty) for the memory root.",
     args: {
         path: tool.schema.string().default("").describe("Relative directory path inside the memory workspace ('' for the root)."),
+        cursor: tool.schema.string().optional().describe("Pagination cursor from a previous response's next_cursor."),
         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 root = assertMemoryRootSafe();
             const fullPath = safeResolveMemoryPath(args.path || ".");
             if (!fs.existsSync(fullPath))
                 return { output: `Not found: ${args.path}` };
@@ -111,19 +121,49 @@ export const memory_list = tool({
             if (st.isSymbolicLink()) {
                 return { output: `memory_list error: symlinks are not allowed in the memory workspace: ${args.path}` };
             }
-            if (!st.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.` };
+            const entries = st.isFile()
+                ? [{ path: path.relative(root, fullPath).split(path.sep).join("/"), entry_type: "file" }]
+                : st.isDirectory()
+                    ? visibleEntries(fullPath)
+                        .sort((a, b) => comparePathNames(a.name, b.name))
+                        .map((e) => ({
+                        path: path.relative(root, path.join(fullPath, e.name)).split(path.sep).join("/"),
+                        entry_type: e.isDir ? "directory" : "file",
+                    }))
+                    : [];
+            let startIndex = 0;
+            if (args.cursor !== undefined) {
+                if (!/^\d+$/.test(args.cursor)) {
+                    return { output: `memory_list error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                }
+                startIndex = Number(args.cursor);
+                if (!Number.isSafeInteger(startIndex)) {
+                    return { output: `memory_list error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                }
+            }
+            if (startIndex > entries.length) {
+                return { output: `memory_list error: cursor ${args.cursor} exceeds result count ${entries.length}.` };
+            }
+            const maxResults = args.max_results ?? LIST_MAX_RESULTS;
+            const endIndex = Math.min(startIndex + maxResults, entries.length);
+            const nextCursor = endIndex < entries.length ? String(endIndex) : null;
+            const truncated = nextCursor !== null;
+            const listing = entries.slice(startIndex, endIndex);
+            if (listing.length === 0) {
+                const output = st.isDirectory()
+                    ? entries.length === 0
+                        ? `Directory ${args.path || "."} is empty.`
+                        : `No entries at cursor ${startIndex} for directory ${args.path || "."}.`
+                    : "";
+                return {
+                    output,
+                    metadata: { path: args.path, entries: [], next_cursor: nextCursor, truncated },
+                };
+            }
             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 },
+                    (truncated ? `\n[truncated: ${entries.length - endIndex} more entries; pass cursor=${nextCursor}]` : ""),
+                metadata: { path: args.path, entries: listing, next_cursor: nextCursor, truncated },
             };
         }
         catch (err) {
@@ -156,7 +196,7 @@ function parseDateArg(value, endOfDay) {
 function collectSearchFiles(start, prefix) {
     const files = [];
     const walk = (dir, rel) => {
-        const entries = visibleEntries(dir).sort((a, b) => a.name.localeCompare(b.name));
+        const entries = visibleEntries(dir).sort((a, b) => comparePathNames(a.name, b.name));
         for (const { name, isDir } of entries) {
             const abs = path.join(dir, name);
             const relPath = rel ? `${rel}/${name}` : name;
@@ -328,7 +368,21 @@ export const memory_search = tool({
             }
             const rangeLabel = timeFiltered ? ` in ${args.since ?? "..."}..${args.until ?? "..."}` : "";
             if (queries.length === 0) {
-                const listing = files.slice(0, args.max_results).map((f) => {
+                let startIndex = 0;
+                if (args.cursor !== undefined) {
+                    startIndex = Number.parseInt(args.cursor, 10);
+                    if (!Number.isInteger(startIndex) || startIndex < 0 || String(startIndex) !== args.cursor.trim()) {
+                        return { output: `memory_search error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                    }
+                    if (startIndex > files.length) {
+                        return { output: `memory_search error: cursor ${startIndex} exceeds result count ${files.length}.` };
+                    }
+                }
+                const endIndex = Math.min(startIndex + (args.max_results ?? SEARCH_MAX_RESULTS), files.length);
+                const page = files.slice(startIndex, endIndex);
+                const nextCursor = endIndex < files.length ? String(endIndex) : null;
+                const truncated = nextCursor !== null;
+                const listing = page.map((f) => {
                     let content = "";
                     try {
                         content = readRegularFileNoFollow(f.abs).content.toString("utf8");
@@ -337,11 +391,25 @@ export const memory_search = tool({
                     }
                     return `${new Date(f.ts).toISOString()} ${f.rel} — ${firstContentLine(content)}`;
                 });
-                if (listing.length === 0)
+                if (files.length === 0)
                     return { output: `No time-anchored memory files${rangeLabel}.` };
+                if (listing.length === 0) {
+                    return {
+                        output: `No memory files at cursor ${startIndex}${rangeLabel}.`,
+                        metadata: { count: 0, next_cursor: nextCursor, truncated, since: args.since, until: args.until },
+                    };
+                }
                 return {
-                    output: `${listing.length} memory file(s)${rangeLabel}:\n${listing.join("\n")}`,
-                    metadata: { count: listing.length, since: args.since, until: args.until },
+                    output: `${listing.length} of ${files.length} memory file(s)${rangeLabel}` +
+                        `${truncated ? ` (more available; pass cursor=${nextCursor})` : ""}:\n` +
+                        listing.join("\n"),
+                    metadata: {
+                        count: listing.length,
+                        next_cursor: nextCursor,
+                        truncated,
+                        since: args.since,
+                        until: args.until,
+                    },
                 };
             }
             const caseSensitive = args.case_sensitive ?? true;
@@ -364,7 +432,7 @@ export const memory_search = tool({
                     continue; // binary, like codex's InvalidData skip
                 searchFileContent(f, content.split(/\r?\n/), queries, preparedQueries, mode, args.line_count ?? 1, args.context_lines ?? 0, caseSensitive, normalized, all);
             }
-            all.sort((a, b) => a.path.localeCompare(b.path) || a.match_line_number - b.match_line_number);
+            all.sort((a, b) => comparePathNames(a.path, b.path) || a.match_line_number - b.match_line_number);
             let startIndex = 0;
             if (args.cursor !== undefined) {
                 startIndex = Number.parseInt(args.cursor, 10);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Persistent memory plugin for opencode — ports codex's two-phase memory system (extraction → consolidation → injection → citation feedback)",
   "type": "module",
   "main": "./dist/src/index.js",