@psiclawops/hypermem 0.7.0 → 0.8.0

package/dist/proactive-pass.js

@@ -44,6 +44,44 @@ function getMaxMessageIndex(db, conversationId) {
         .get(conversationId);
     return typeof row.max_index === 'number' ? row.max_index : -1;
 }
+/**
+ * Filter candidate message ids down to rows that are safe to delete without
+ * violating HyperMem's FK edges.
+ *
+ * Current blockers:
+ *   - summary_messages.message_id -> messages.id
+ *   - messages.parent_id -> messages.id (child rows point at parent rows)
+ */
+function getDeletableMessageIds(db, candidateIds) {
+    if (candidateIds.length === 0)
+        return { deletableIds: [], blockedIds: [] };
+    const placeholders = candidateIds.map(() => '?').join(', ');
+    const blocked = db
+        .prepare(`
+      SELECT DISTINCT id
+      FROM (
+        SELECT sm.message_id AS id
+        FROM summary_messages sm
+        WHERE sm.message_id IN (${placeholders})
+
+        UNION
+
+        SELECT parent.id AS id
+        FROM messages child
+        JOIN messages parent ON parent.id = child.parent_id
+        WHERE child.parent_id IN (${placeholders})
+      ) blocked
+    `)
+        .all(...candidateIds, ...candidateIds);
+    if (blocked.length === 0)
+        return { deletableIds: candidateIds, blockedIds: [] };
+    const blockedIds = blocked.map(row => row.id);
+    const blockedSet = new Set(blockedIds);
+    return {
+        deletableIds: candidateIds.filter(id => !blockedSet.has(id)),
+        blockedIds,
+    };
+}
 /**
  * Decide if a message is noise based on content + is_heartbeat flag.
  *
@@ -73,7 +111,7 @@ function isNoiseMessage(textContent, isHeartbeat) {
  * Deletions are wrapped in a single transaction. The FTS5 trigger handles
  * index cleanup automatically (msg_fts_ad fires on DELETE).
  */
-export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
+export function runNoiseSweep(db, conversationId, recentWindowSize = 20, maxCandidates = Infinity) {
     const ZERO = { messagesDeleted: 0, passType: 'noise_sweep' };
     try {
         const safeWindow = resolveSafeWindow(recentWindowSize);
@@ -101,11 +139,16 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
             .all(conversationId, cutoff);
         if (candidates.length === 0)
             return ZERO;
-        // Filter to noise messages
-        const toDelete = candidates.filter(row => isNoiseMessage(row.text_content, row.is_heartbeat));
-        if (toDelete.length === 0)
+        // Filter to noise messages, respecting per-pass candidate cap
+        const toDelete = candidates.filter(row => isNoiseMessage(row.text_content, row.is_heartbeat)).slice(0, Number.isFinite(maxCandidates) ? maxCandidates : undefined);
+        if (toDelete.length === 0) {
             return ZERO;
-        const ids = toDelete.map(r => r.id);
+        }
+        const candidateIds = toDelete.map(r => r.id);
+        const { deletableIds: ids, blockedIds } = getDeletableMessageIds(db, candidateIds);
+        if (ids.length === 0) {
+            return ZERO;
+        }
         // Delete in a transaction; use chunked IN clauses to avoid
         // SQLite's SQLITE_LIMIT_VARIABLE_NUMBER (default 999).
         let totalDeleted = 0;
@@ -126,6 +169,9 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
             db.prepare('ROLLBACK').run();
             throw innerErr;
         }
+        if (totalDeleted > 0) {
+            console.log(`[proactive-pass] Noise sweep conversation=${conversationId} candidates=${candidates.length} noise=${candidateIds.length} deleted=${totalDeleted} skippedReferenced=${blockedIds.length} cutoff=${cutoff}`);
+        }
         return { messagesDeleted: totalDeleted, passType: 'noise_sweep' };
     }
     catch (err) {
@@ -150,16 +196,18 @@ export function runNoiseSweep(db, conversationId, recentWindowSize = 20) {
  *
  * Mutations are committed in a single transaction.
  */
-export function runToolDecay(db, conversationId, recentWindowSize = 40) {
+export function runToolDecay(db, conversationId, recentWindowSize = 40, maxCandidates = Infinity) {
     const ZERO = { messagesUpdated: 0, bytesFreed: 0, passType: 'tool_decay' };
     try {
         const safeWindow = resolveSafeWindow(recentWindowSize);
         const maxIndex = getMaxMessageIndex(db, conversationId);
-        if (maxIndex < 0)
+        if (maxIndex < 0) {
             return ZERO;
+        }
         const cutoff = maxIndex - safeWindow;
-        if (cutoff <= 0)
+        if (cutoff <= 0) {
             return ZERO;
+        }
         // Fetch messages with large tool_results outside the recent window.
         const candidates = db
             .prepare(`
@@ -171,11 +219,13 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
           AND length(tool_results) > 2000
       `)
             .all(conversationId, cutoff);
-        if (candidates.length === 0)
+        if (candidates.length === 0) {
             return ZERO;
-        // Build the update list by processing each candidate.
+        }
+        // Build the update list by processing each candidate, respecting per-pass cap.
+        const cappedCandidates = Number.isFinite(maxCandidates) ? candidates.slice(0, maxCandidates) : candidates;
         const updates = [];
-        for (const row of candidates) {
+        for (const row of cappedCandidates) {
             let parsed;
             try {
                 parsed = JSON.parse(row.tool_results);
@@ -207,8 +257,9 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
                 updates.push({ id: row.id, newJson, savedBytes });
             }
         }
-        if (updates.length === 0)
+        if (updates.length === 0) {
             return ZERO;
+        }
         let totalUpdated = 0;
         let totalBytesFreed = 0;
         db.prepare('BEGIN').run();
@@ -225,6 +276,9 @@ export function runToolDecay(db, conversationId, recentWindowSize = 40) {
             db.prepare('ROLLBACK').run();
             throw innerErr;
         }
+        if (totalUpdated > 0) {
+            console.log(`[proactive-pass] Tool decay conversation=${conversationId} candidates=${candidates.length} updated=${totalUpdated} bytesFreed=${totalBytesFreed} cutoff=${cutoff}`);
+        }
         return {
             messagesUpdated: totalUpdated,
             bytesFreed: totalBytesFreed,

package/dist/replay-recovery.d.ts

@@ -0,0 +1,29 @@
+import { type ReplayMarker, type ReplayState } from './degradation.js';
+export interface ReplayRecoveryInputs {
+    currentState?: ReplayState | '' | null;
+    runtimeTokens: number;
+    redisTokens: number;
+    effectiveBudget: number;
+}
+export interface ReplayRecoveryDecision {
+    active: boolean;
+    shouldSkipCacheReplay: boolean;
+    trimTargetOverride?: number;
+    historyDepthCap?: number;
+    emittedMarker?: ReplayMarker;
+    emittedText?: string;
+    nextState: ReplayState | null;
+}
+export declare const REPLAY_RECOVERY_POLICY: {
+    readonly enterPressure: 0.8;
+    readonly exitPressure: 0.65;
+    readonly redisColdFraction: 0.2;
+    readonly enterTrimTarget: 0.2;
+    readonly stabilizingTrimTarget: 0.35;
+    readonly historyDepthCap: 60;
+    readonly redisFloorTokens: 500;
+};
+export declare function isColdRedisReplay(inputs: ReplayRecoveryInputs): boolean;
+export declare function isReplayRecovered(inputs: ReplayRecoveryInputs): boolean;
+export declare function decideReplayRecovery(inputs: ReplayRecoveryInputs): ReplayRecoveryDecision;
+//# sourceMappingURL=replay-recovery.d.ts.map

package/dist/replay-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-recovery.d.ts","sourceRoot":"","sources":["../src/replay-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B;AAED,eAAO,MAAM,sBAAsB;;;;;;;;CAQzB,CAAC;AAgBX,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CA+DzF"}

package/dist/replay-recovery.js

@@ -0,0 +1,82 @@
+import { formatReplayMarker, } from './degradation.js';
+export const REPLAY_RECOVERY_POLICY = {
+    enterPressure: 0.80,
+    exitPressure: 0.65,
+    redisColdFraction: 0.20,
+    enterTrimTarget: 0.20,
+    stabilizingTrimTarget: 0.35,
+    historyDepthCap: 60,
+    redisFloorTokens: 500,
+};
+function coldRedisThreshold(runtimeTokens) {
+    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(runtimeTokens * REPLAY_RECOVERY_POLICY.redisColdFraction));
+}
+function recoveredRedisThreshold(effectiveBudget) {
+    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(effectiveBudget * REPLAY_RECOVERY_POLICY.redisColdFraction));
+}
+export function isColdRedisReplay(inputs) {
+    return (inputs.runtimeTokens > inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.enterPressure &&
+        inputs.redisTokens < coldRedisThreshold(inputs.runtimeTokens));
+}
+export function isReplayRecovered(inputs) {
+    return (inputs.runtimeTokens <= inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.exitPressure &&
+        inputs.redisTokens >= recoveredRedisThreshold(inputs.effectiveBudget));
+}
+export function decideReplayRecovery(inputs) {
+    const currentState = inputs.currentState ?? null;
+    if (!currentState) {
+        if (!isColdRedisReplay(inputs)) {
+            return {
+                active: false,
+                shouldSkipCacheReplay: false,
+                nextState: null,
+            };
+        }
+        const emittedMarker = {
+            state: 'entering',
+            status: 'bounded',
+            reason: 'replay_cold_redis',
+            summary: 'cold restart, keep the window bounded',
+        };
+        return {
+            active: true,
+            shouldSkipCacheReplay: true,
+            trimTargetOverride: REPLAY_RECOVERY_POLICY.enterTrimTarget,
+            historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
+            emittedMarker,
+            emittedText: formatReplayMarker(emittedMarker),
+            nextState: 'stabilizing',
+        };
+    }
+    if (isReplayRecovered(inputs)) {
+        const emittedMarker = {
+            state: 'exited',
+            status: 'bounded',
+            reason: 'replay_exited',
+            summary: 'stable window restored',
+        };
+        return {
+            active: false,
+            shouldSkipCacheReplay: false,
+            emittedMarker,
+            emittedText: formatReplayMarker(emittedMarker),
+            nextState: null,
+        };
+    }
+    const emittedMarker = {
+        state: 'stabilizing',
+        status: 'bounded',
+        reason: 'replay_stabilizing',
+        summary: 'replay window stabilizing, keep it bounded',
+    };
+    return {
+        active: true,
+        shouldSkipCacheReplay: true,
+        trimTargetOverride: REPLAY_RECOVERY_POLICY.stabilizingTrimTarget,
+        historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
+        emittedMarker,
+        emittedText: formatReplayMarker(emittedMarker),
+        nextState: 'stabilizing',
+    };
+}
+//# sourceMappingURL=replay-recovery.js.map

package/dist/reranker.d.ts

@@ -0,0 +1,95 @@
+/**
+ * hypermem Reranker
+ *
+ * Pluggable reranking interface with circuit-breaker protection and graceful
+ * degradation. Callers that receive null fall back to the original document
+ * order without disruption.
+ *
+ * Providers:
+ *   - ZeroEntropyReranker — https://api.zeroentropy.dev/v1/rerank (zerank-2)
+ *   - OpenRouterReranker  — https://openrouter.ai/api/v1/rerank (cohere/rerank-4-pro)
+ *   - OllamaReranker      — http://localhost:11434/api/chat (yes/no classification)
+ *
+ * API key resolution order (per provider):
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ */
+export interface RerankResult {
+    index: number;
+    score: number;
+    content: string;
+}
+export interface RerankerProvider {
+    readonly name: string;
+    /**
+     * Reranks `documents` by relevance to `query`.
+     * Returns null on any failure — callers MUST fall back to original order.
+     */
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export interface RerankerConfig {
+    provider: 'zeroentropy' | 'openrouter' | 'local' | 'none';
+    minCandidates: number;
+    maxDocuments: number;
+    topK: number;
+    timeoutMs: number;
+    zeroEntropyApiKey?: string;
+    zeroEntropyModel?: string;
+    openrouterApiKey?: string;
+    openrouterModel?: string;
+    ollamaUrl?: string;
+    ollamaModel?: string;
+}
+export declare class ZeroEntropyReranker implements RerankerProvider {
+    readonly name = "zeroentropy";
+    private readonly circuit;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(apiKey: string, model?: string, timeoutMs?: number);
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export declare class OpenRouterReranker implements RerankerProvider {
+    readonly name = "openrouter";
+    private readonly circuit;
+    private readonly apiKey;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(apiKey: string, model?: string, timeoutMs?: number);
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+export declare class OllamaReranker implements RerankerProvider {
+    readonly name = "ollama";
+    private readonly circuit;
+    private readonly baseUrl;
+    private readonly model;
+    private readonly timeoutMs;
+    constructor(baseUrl?: string, model?: string, timeoutMs?: number);
+    /**
+     * Scores documents sequentially — one chat call per document.
+     * The Qwen3-Reranker-0.6B model responds with "yes" (relevant) or "no".
+     * Score: yes → 1.0, anything else → 0.0.
+     *
+     * Sequential iteration is required because Ollama's /api/chat is stateless
+     * per-request and running calls in parallel would overload a local GPU.
+     * Returns null on the first failure to preserve circuit breaker semantics.
+     */
+    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
+}
+/**
+ * Creates a RerankerProvider from the supplied config.
+ *
+ * API key resolution order:
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ *
+ * Returns null when:
+ *   - provider is 'none'
+ *   - provider is 'zeroentropy' and no key found in config or env
+ *   - provider is 'openrouter' and no key found in config or env
+ *
+ * 'local' (Ollama) never returns null from the factory — it has no required
+ * API key. The provider itself returns null on runtime failure.
+ */
+export declare function createReranker(config: RerankerConfig): RerankerProvider | null;
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgFH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAa,EAAE,SAAS,SAAO;IAM1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAID,qBAAa,kBAAmB,YAAW,gBAAgB;IACzD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwB,EAAE,SAAS,SAAO;IAMrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAQD,qBAAa,cAAe,YAAW,gBAAgB;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,SAA2B,EAClC,KAAK,SAAuC,EAC5C,SAAS,SAAS;IAOpB;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CA4C5F;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAyB9E"}

package/dist/reranker.js

@@ -0,0 +1,308 @@
+/**
+ * hypermem Reranker
+ *
+ * Pluggable reranking interface with circuit-breaker protection and graceful
+ * degradation. Callers that receive null fall back to the original document
+ * order without disruption.
+ *
+ * Providers:
+ *   - ZeroEntropyReranker — https://api.zeroentropy.dev/v1/rerank (zerank-2)
+ *   - OpenRouterReranker  — https://openrouter.ai/api/v1/rerank (cohere/rerank-4-pro)
+ *   - OllamaReranker      — http://localhost:11434/api/chat (yes/no classification)
+ *
+ * API key resolution order (per provider):
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ */
+// ── Circuit Breaker ───────────────────────────────────────────────────────────
+/** Number of consecutive failures before the circuit opens. */
+const CIRCUIT_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open after tripping (ms). */
+const CIRCUIT_DISABLE_DURATION_MS = 60_000;
+/**
+ * CircuitBreaker protects a provider from repeated calls during sustained
+ * failures.
+ *
+ * State machine:
+ *   CLOSED  — normal operation; failures increment the counter.
+ *   OPEN    — provider disabled; isOpen() returns true for DISABLE_DURATION.
+ *   HALF-OPEN — one probe allowed after the disable window expires;
+ *               success resets the counter, failure re-opens the circuit.
+ *
+ * Transition: CLOSED → OPEN when consecutiveFailures >= FAILURE_THRESHOLD.
+ * Transition: OPEN → HALF-OPEN when Date.now() >= disabledUntil.
+ * Transition: HALF-OPEN → CLOSED on recordSuccess().
+ * Transition: HALF-OPEN → OPEN on recordFailure() (reset window starts fresh).
+ */
+class CircuitBreaker {
+    /** Consecutive failures since last success. Reset to 0 on any success. */
+    consecutiveFailures = 0;
+    /**
+     * Epoch ms after which the circuit allows a probe.
+     * 0 means the circuit is CLOSED (not disabled).
+     */
+    disabledUntil = 0;
+    /** Returns true when the provider should be skipped. */
+    isOpen() {
+        if (this.disabledUntil === 0)
+            return false; // CLOSED
+        if (Date.now() >= this.disabledUntil) {
+            // Disable window expired — transition to HALF-OPEN: allow one probe.
+            // We clear disabledUntil here so the next call goes through.
+            // If it fails, recordFailure() re-opens the circuit with a fresh window.
+            this.disabledUntil = 0;
+            return false;
+        }
+        return true; // OPEN
+    }
+    /** Call on a successful provider response. Resets all failure state. */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.disabledUntil = 0;
+    }
+    /**
+     * Call on any provider failure (non-2xx, timeout, parse error, etc.).
+     * After CIRCUIT_FAILURE_THRESHOLD consecutive failures, opens the circuit
+     * for CIRCUIT_DISABLE_DURATION_MS milliseconds.
+     */
+    recordFailure() {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= CIRCUIT_FAILURE_THRESHOLD) {
+            // Trip the circuit — disable for the configured window.
+            // Reset consecutiveFailures so the probe after the window isn't
+            // pre-tripped by the old count.
+            this.disabledUntil = Date.now() + CIRCUIT_DISABLE_DURATION_MS;
+            this.consecutiveFailures = 0;
+        }
+    }
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Returns an AbortController that fires after `ms` and a cleanup handle. */
+function withTimeout(ms) {
+    const controller = new AbortController();
+    const id = setTimeout(() => controller.abort(), ms);
+    return { controller, clear: () => clearTimeout(id) };
+}
+// ── ZeroEntropyReranker ───────────────────────────────────────────────────────
+export class ZeroEntropyReranker {
+    name = 'zeroentropy';
+    circuit = new CircuitBreaker();
+    apiKey;
+    model;
+    timeoutMs;
+    constructor(apiKey, model = 'zerank-2', timeoutMs = 2000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const { controller, clear } = withTimeout(this.timeoutMs);
+        try {
+            const response = await fetch('https://api.zeroentropy.dev/v1/rerank', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ query, documents, model: this.model, top_n: topK }),
+                signal: controller.signal,
+            });
+            clear();
+            if (!response.ok) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            const data = (await response.json());
+            if (!Array.isArray(data.results)) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            this.circuit.recordSuccess();
+            return data.results.map((r) => {
+                const score = r.score ?? r.relevance_score ?? 0;
+                const content = resolveDocumentText(r.content, r.document, documents[r.index]);
+                return { index: r.index, score, content };
+            });
+        }
+        catch {
+            clear();
+            this.circuit.recordFailure();
+            return null;
+        }
+    }
+}
+// ── OpenRouterReranker ────────────────────────────────────────────────────────
+export class OpenRouterReranker {
+    name = 'openrouter';
+    circuit = new CircuitBreaker();
+    apiKey;
+    model;
+    timeoutMs;
+    constructor(apiKey, model = 'cohere/rerank-4-pro', timeoutMs = 2000) {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const { controller, clear } = withTimeout(this.timeoutMs);
+        try {
+            const response = await fetch('https://openrouter.ai/api/v1/rerank', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify({ query, documents, model: this.model, top_n: topK }),
+                signal: controller.signal,
+            });
+            clear();
+            if (!response.ok) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            const data = (await response.json());
+            if (!Array.isArray(data.results)) {
+                this.circuit.recordFailure();
+                return null;
+            }
+            this.circuit.recordSuccess();
+            return data.results.map((r) => {
+                const score = r.relevance_score ?? r.score ?? 0;
+                const content = resolveDocumentText(undefined, r.document, documents[r.index]);
+                return { index: r.index, score, content };
+            });
+        }
+        catch {
+            clear();
+            this.circuit.recordFailure();
+            return null;
+        }
+    }
+}
+// ── OllamaReranker ────────────────────────────────────────────────────────────
+const OLLAMA_SYSTEM_PROMPT = 'Judge whether the Document meets the requirements based on the Query and the Instruct provided. ' +
+    'Note that the answer can only be "yes" or "no".';
+export class OllamaReranker {
+    name = 'ollama';
+    circuit = new CircuitBreaker();
+    baseUrl;
+    model;
+    timeoutMs;
+    constructor(baseUrl = 'http://localhost:11434', model = 'dengcao/Qwen3-Reranker-0.6B:Q5_K_M', timeoutMs = 10_000) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.model = model;
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Scores documents sequentially — one chat call per document.
+     * The Qwen3-Reranker-0.6B model responds with "yes" (relevant) or "no".
+     * Score: yes → 1.0, anything else → 0.0.
+     *
+     * Sequential iteration is required because Ollama's /api/chat is stateless
+     * per-request and running calls in parallel would overload a local GPU.
+     * Returns null on the first failure to preserve circuit breaker semantics.
+     */
+    async rerank(query, documents, topK = 10) {
+        if (this.circuit.isOpen())
+            return null;
+        const scored = [];
+        for (let i = 0; i < documents.length; i++) {
+            const doc = documents[i];
+            const userContent = `Instruct: Given a query, retrieve relevant passages that answer the query\n\n` +
+                `Query: ${query}\n\nDocument: ${doc}`;
+            const { controller, clear } = withTimeout(this.timeoutMs);
+            try {
+                const response = await fetch(`${this.baseUrl}/api/chat`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model: this.model,
+                        messages: [
+                            { role: 'system', content: OLLAMA_SYSTEM_PROMPT },
+                            { role: 'user', content: userContent },
+                        ],
+                        stream: false,
+                    }),
+                    signal: controller.signal,
+                });
+                clear();
+                if (!response.ok) {
+                    this.circuit.recordFailure();
+                    return null;
+                }
+                const data = (await response.json());
+                const answer = (data.message?.content ?? '').trim().toLowerCase();
+                // "yes" prefix → relevant; anything else (including "no") → not relevant
+                const score = answer.startsWith('yes') ? 1.0 : 0.0;
+                scored.push({ index: i, score, content: doc });
+            }
+            catch {
+                clear();
+                this.circuit.recordFailure();
+                return null;
+            }
+        }
+        this.circuit.recordSuccess();
+        // Sort by score descending and return top-K
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, topK);
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Creates a RerankerProvider from the supplied config.
+ *
+ * API key resolution order:
+ *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
+ *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
+ *
+ * Returns null when:
+ *   - provider is 'none'
+ *   - provider is 'zeroentropy' and no key found in config or env
+ *   - provider is 'openrouter' and no key found in config or env
+ *
+ * 'local' (Ollama) never returns null from the factory — it has no required
+ * API key. The provider itself returns null on runtime failure.
+ */
+export function createReranker(config) {
+    switch (config.provider) {
+        case 'none':
+            return null;
+        case 'zeroentropy': {
+            const apiKey = config.zeroEntropyApiKey ?? process.env['ZEROENTROPY_API_KEY'];
+            if (!apiKey)
+                return null;
+            return new ZeroEntropyReranker(apiKey, config.zeroEntropyModel ?? 'zerank-2', config.timeoutMs);
+        }
+        case 'openrouter': {
+            const apiKey = config.openrouterApiKey ?? process.env['OPENROUTER_API_KEY'];
+            if (!apiKey)
+                return null;
+            return new OpenRouterReranker(apiKey, config.openrouterModel ?? 'cohere/rerank-4-pro', config.timeoutMs);
+        }
+        case 'local': {
+            return new OllamaReranker(config.ollamaUrl ?? 'http://localhost:11434', config.ollamaModel ?? 'dengcao/Qwen3-Reranker-0.6B:Q5_K_M', config.timeoutMs);
+        }
+    }
+}
+// ── Private Helpers ───────────────────────────────────────────────────────────
+/**
+ * Resolves the document text from a reranking API response.
+ * Preference order: explicit `content` string → `document` string →
+ * `document.text` string → original document from the input array.
+ */
+function resolveDocumentText(content, document, fallback) {
+    if (typeof content === 'string')
+        return content;
+    if (typeof document === 'string')
+        return document;
+    if (document !== null && typeof document === 'object' && typeof document.text === 'string') {
+        return document.text;
+    }
+    return fallback ?? '';
+}
+//# sourceMappingURL=reranker.js.map

package/dist/schema.d.ts

@@ -6,7 +6,7 @@
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LATEST_SCHEMA_VERSION = 8;
+export declare const LATEST_SCHEMA_VERSION = 10;
 /**
  * Run migrations on an agent message database.
  */