@psiclawops/hypermem 0.8.5 → 0.9.1

package/dist/reranker.js

@@ -1,308 +0,0 @@
-/**
- * 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/retrieval-policy.d.ts

@@ -1,51 +0,0 @@
-/**
- * hypermem Retrieval Policy
- *
- * Single enforced policy layer for scope-based access control during retrieval.
- * Called by the compositor to filter items before they are injected into context.
- *
- * Scope rules:
- *   'agent' (default / null / undefined): allowed if agentId matches OR is null/undefined (global)
- *   'session': allowed if both agentId AND sessionKey match
- *   'user': allowed if agentId matches
- *   'global': always allowed
- *   any other value: denied with reason 'ambiguous_scope'
- */
-export type RetrievalScope = 'agent' | 'session' | 'user' | 'global';
-export interface RetrievalContext {
-    agentId: string;
-    sessionKey: string;
-}
-export interface ScopeCheckResult {
-    allowed: boolean;
-    /** One of: 'allowed' | 'scope_filtered' | 'ambiguous_scope' */
-    reason: string;
-}
-/**
- * Check whether a single item is accessible in the given retrieval context.
- *
- * @param itemScope       The scope stored on the item (null/undefined → defaults to 'agent')
- * @param itemAgentId     The agentId stored on the item (null/undefined → global)
- * @param itemSessionKey  The sessionKey stored on the item (null/undefined → any)
- * @param ctx             The requester's retrieval context
- */
-export declare function checkScope(itemScope: string | null | undefined, itemAgentId: string | null | undefined, itemSessionKey: string | null | undefined, ctx: RetrievalContext): ScopeCheckResult;
-/**
- * Filter an array of items by scope, returning allowed items and a filtered count.
- *
- * Items are expected to have optional `agentId`, `sessionKey`, and `scope` fields.
- * Null/undefined fields are treated as "unset" (permissive for their slot).
- *
- * @param items  Array of items to filter
- * @param ctx    The requester's retrieval context
- * @returns      { allowed: T[], filteredCount: number }
- */
-export declare function filterByScope<T extends {
-    agentId?: string | null;
-    sessionKey?: string | null;
-    scope?: string | null;
-}>(items: T[], ctx: RetrievalContext): {
-    allowed: T[];
-    filteredCount: number;
-};
-//# sourceMappingURL=retrieval-policy.d.ts.map

package/dist/retrieval-policy.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"retrieval-policy.d.ts","sourceRoot":"","sources":["../src/retrieval-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,GAAG,EAAE,gBAAgB,GACpB,gBAAgB,CAqClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,EACC,KAAK,EAAE,CAAC,EAAE,EACV,GAAG,EAAE,gBAAgB,GACpB;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAczC"}

package/dist/retrieval-policy.js

@@ -1,77 +0,0 @@
-/**
- * hypermem Retrieval Policy
- *
- * Single enforced policy layer for scope-based access control during retrieval.
- * Called by the compositor to filter items before they are injected into context.
- *
- * Scope rules:
- *   'agent' (default / null / undefined): allowed if agentId matches OR is null/undefined (global)
- *   'session': allowed if both agentId AND sessionKey match
- *   'user': allowed if agentId matches
- *   'global': always allowed
- *   any other value: denied with reason 'ambiguous_scope'
- */
-/**
- * Check whether a single item is accessible in the given retrieval context.
- *
- * @param itemScope       The scope stored on the item (null/undefined → defaults to 'agent')
- * @param itemAgentId     The agentId stored on the item (null/undefined → global)
- * @param itemSessionKey  The sessionKey stored on the item (null/undefined → any)
- * @param ctx             The requester's retrieval context
- */
-export function checkScope(itemScope, itemAgentId, itemSessionKey, ctx) {
-    const scope = itemScope ?? 'agent';
-    switch (scope) {
-        case 'agent':
-            // Global agent facts (null/undefined agentId) are readable by all agents.
-            // Agent-specific facts are only readable by the owning agent.
-            if (itemAgentId == null || itemAgentId === ctx.agentId) {
-                return { allowed: true, reason: 'allowed' };
-            }
-            return { allowed: false, reason: 'scope_filtered' };
-        case 'session':
-            // Session-scoped: both agentId AND sessionKey must match.
-            if ((itemAgentId == null || itemAgentId === ctx.agentId) &&
-                (itemSessionKey == null || itemSessionKey === ctx.sessionKey)) {
-                return { allowed: true, reason: 'allowed' };
-            }
-            return { allowed: false, reason: 'scope_filtered' };
-        case 'user':
-            // User-scoped: agentId must match (user prefs are keyed by agent).
-            if (itemAgentId == null || itemAgentId === ctx.agentId) {
-                return { allowed: true, reason: 'allowed' };
-            }
-            return { allowed: false, reason: 'scope_filtered' };
-        case 'global':
-            // Global: always accessible.
-            return { allowed: true, reason: 'allowed' };
-        default:
-            // Unknown scope — deny with ambiguous_scope.
-            return { allowed: false, reason: 'ambiguous_scope' };
-    }
-}
-/**
- * Filter an array of items by scope, returning allowed items and a filtered count.
- *
- * Items are expected to have optional `agentId`, `sessionKey`, and `scope` fields.
- * Null/undefined fields are treated as "unset" (permissive for their slot).
- *
- * @param items  Array of items to filter
- * @param ctx    The requester's retrieval context
- * @returns      { allowed: T[], filteredCount: number }
- */
-export function filterByScope(items, ctx) {
-    const allowed = [];
-    let filteredCount = 0;
-    for (const item of items) {
-        const result = checkScope(item.scope, item.agentId, item.sessionKey, ctx);
-        if (result.allowed) {
-            allowed.push(item);
-        }
-        else {
-            filteredCount++;
-        }
-    }
-    return { allowed, filteredCount };
-}
-//# sourceMappingURL=retrieval-policy.js.map

package/dist/schema.d.ts

@@ -1,15 +0,0 @@
-/**
- * hypermem Agent Message Schema
- *
- * Per-agent database: ~/.openclaw/hypermem/agents/{agentId}/messages.db
- * Write-heavy, temporal, rotatable.
- * Contains ONLY conversation data — structured knowledge lives in library.db.
- */
-import type { DatabaseSync } from 'node:sqlite';
-export declare const LATEST_SCHEMA_VERSION = 10;
-/**
- * Run migrations on an agent message database.
- */
-export declare function migrate(db: DatabaseSync): void;
-export { LATEST_SCHEMA_VERSION as SCHEMA_VERSION };
-//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAgJxC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0K9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}