@psiclawops/hypermem 0.9.1 → 0.9.2

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/models/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/models/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

@@ -0,0 +1,51 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,77 @@
+/**
+ * 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

@@ -0,0 +1,15 @@
+/**
+ * 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 = 11;
+/**
+ * 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

@@ -0,0 +1 @@
+{"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,CAsM9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}