@psiclawops/hypermem 0.1.0

package/dist/rate-limiter.js

@@ -0,0 +1,179 @@
+/**
+ * HyperMem Rate Limiter
+ *
+ * Token-bucket rate limiter for embedding API calls.
+ * Prevents hammering Ollama during bulk indexing.
+ *
+ * Strategy:
+ *   - Burst: allow immediate calls up to bucket capacity
+ *   - Sustained: refill tokens at a steady rate
+ *   - Backpressure: when tokens exhausted, delay until available
+ *   - Priority: high-priority requests (user-facing recall) get reserved tokens
+ *
+ * Usage:
+ *   const limiter = new RateLimiter({ tokensPerSecond: 5, burstSize: 10 });
+ *   await limiter.acquire();  // Waits if necessary
+ *   const embeddings = await generateEmbeddings(texts);
+ */
+const DEFAULT_CONFIG = {
+    tokensPerSecond: 5,
+    burstSize: 10,
+    reservedHigh: 2,
+    maxWaitMs: 30000,
+};
+export class RateLimiter {
+    tokens;
+    lastRefill;
+    config;
+    waitQueue = [];
+    refillTimer = null;
+    _totalAcquired = 0;
+    _totalWaited = 0;
+    _totalRejected = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.tokens = this.config.burstSize;
+        this.lastRefill = Date.now();
+        // Refill tokens periodically
+        this.refillTimer = setInterval(() => this.refill(), 200); // 5x per second
+    }
+    /**
+     * Acquire tokens. Blocks until tokens are available or maxWaitMs expires.
+     *
+     * @param count - Number of tokens to acquire (default 1)
+     * @param priority - Request priority (high gets reserved tokens)
+     * @throws Error if wait exceeds maxWaitMs
+     */
+    async acquire(count = 1, priority = 'normal') {
+        this.refill();
+        // High priority can use reserved tokens
+        const available = priority === 'high'
+            ? this.tokens
+            : Math.max(0, this.tokens - this.config.reservedHigh);
+        if (available >= count) {
+            this.tokens -= count;
+            this._totalAcquired += count;
+            return;
+        }
+        // Need to wait
+        this._totalWaited++;
+        const deadline = Date.now() + this.config.maxWaitMs;
+        return new Promise((resolve, reject) => {
+            this.waitQueue.push({
+                resolve,
+                reject,
+                priority,
+                tokensNeeded: count,
+                deadline,
+            });
+            // Sort by priority (high first) then by deadline (earliest first)
+            this.waitQueue.sort((a, b) => {
+                const priOrder = { high: 0, normal: 1, low: 2 };
+                const priDiff = priOrder[a.priority] - priOrder[b.priority];
+                if (priDiff !== 0)
+                    return priDiff;
+                return a.deadline - b.deadline;
+            });
+        });
+    }
+    /**
+     * Try to acquire tokens without waiting.
+     * Returns true if tokens were acquired, false if not.
+     */
+    tryAcquire(count = 1, priority = 'normal') {
+        this.refill();
+        const available = priority === 'high'
+            ? this.tokens
+            : Math.max(0, this.tokens - this.config.reservedHigh);
+        if (available >= count) {
+            this.tokens -= count;
+            this._totalAcquired += count;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get current limiter state.
+     */
+    get state() {
+        this.refill();
+        return {
+            availableTokens: Math.floor(this.tokens),
+            pendingRequests: this.waitQueue.length,
+            stats: {
+                acquired: this._totalAcquired,
+                waited: this._totalWaited,
+                rejected: this._totalRejected,
+            },
+        };
+    }
+    /**
+     * Stop the refill timer.
+     */
+    destroy() {
+        if (this.refillTimer) {
+            clearInterval(this.refillTimer);
+            this.refillTimer = null;
+        }
+        // Reject all pending
+        for (const waiter of this.waitQueue) {
+            waiter.reject(new Error('Rate limiter destroyed'));
+        }
+        this.waitQueue = [];
+    }
+    // ─── Internal ──────────────────────────────────────────────
+    refill() {
+        const now = Date.now();
+        const elapsed = (now - this.lastRefill) / 1000; // seconds
+        const newTokens = elapsed * this.config.tokensPerSecond;
+        if (newTokens > 0) {
+            this.tokens = Math.min(this.config.burstSize, this.tokens + newTokens);
+            this.lastRefill = now;
+        }
+        // Process wait queue
+        this.processQueue();
+    }
+    processQueue() {
+        const now = Date.now();
+        const toRemove = [];
+        for (let i = 0; i < this.waitQueue.length; i++) {
+            const waiter = this.waitQueue[i];
+            // Check deadline
+            if (now > waiter.deadline) {
+                waiter.reject(new Error(`Rate limit wait exceeded ${this.config.maxWaitMs}ms`));
+                this._totalRejected++;
+                toRemove.push(i);
+                continue;
+            }
+            // Check if tokens available
+            const available = waiter.priority === 'high'
+                ? this.tokens
+                : Math.max(0, this.tokens - this.config.reservedHigh);
+            if (available >= waiter.tokensNeeded) {
+                this.tokens -= waiter.tokensNeeded;
+                this._totalAcquired += waiter.tokensNeeded;
+                waiter.resolve();
+                toRemove.push(i);
+            }
+        }
+        // Remove processed entries (reverse order to maintain indices)
+        for (let i = toRemove.length - 1; i >= 0; i--) {
+            this.waitQueue.splice(toRemove[i], 1);
+        }
+    }
+}
+/**
+ * Rate-limited embedding generator.
+ * Wraps generateEmbeddings with rate limiting.
+ */
+export function createRateLimitedEmbedder(embedFn, limiter) {
+    return async (texts, priority = 'normal') => {
+        if (texts.length === 0)
+            return [];
+        // Each batch counts as 1 token regardless of batch size
+        // This limits the number of API calls, not the number of texts
+        await limiter.acquire(1, priority);
+        return embedFn(texts);
+    };
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/redis.d.ts

@@ -0,0 +1,188 @@
+/**
+ * HyperMem Redis Layer
+ *
+ * Manages the hot-state compositor cache.
+ * Per-agent, per-session keyspace with TTL management.
+ * Falls back gracefully when Redis is unavailable.
+ */
+import type { RedisConfig, SessionMeta, SessionCursor, StoredMessage, NeutralMessage } from './types.js';
+export declare class RedisLayer {
+    private client;
+    private readonly config;
+    private connected;
+    constructor(config?: Partial<RedisConfig>);
+    /**
+     * Connect to Redis. Non-blocking — operations degrade gracefully if connection fails.
+     */
+    connect(): Promise<boolean>;
+    get isConnected(): boolean;
+    private agentKey;
+    private sessionKey;
+    /**
+     * Set the agent's profile in Redis.
+     */
+    setProfile(agentId: string, profile: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the agent's profile.
+     */
+    getProfile(agentId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Track active sessions for an agent.
+     */
+    addActiveSession(agentId: string, sessionKey: string): Promise<void>;
+    removeActiveSession(agentId: string, sessionKey: string): Promise<void>;
+    getActiveSessions(agentId: string): Promise<string[]>;
+    /**
+     * Set a session slot value.
+     */
+    setSlot(agentId: string, sessionKey: string, slot: string, value: string): Promise<void>;
+    /**
+     * Get a session slot value.
+     */
+    getSlot(agentId: string, sessionKey: string, slot: string): Promise<string | null>;
+    /**
+     * Set session metadata.
+     */
+    setSessionMeta(agentId: string, sessionKey: string, meta: SessionMeta): Promise<void>;
+    /**
+     * Get session metadata.
+     */
+    getSessionMeta(agentId: string, sessionKey: string): Promise<SessionMeta | null>;
+    /**
+     * Push messages to the session history list.
+     *
+     * History retention strategy:
+     *   - No aggressive LTRIM. Cap at maxMessages (default 250) to prevent
+     *     unbounded growth, but the real budget enforcement happens in the
+     *     compositor at compose time.
+     *   - TTL is historyTTL (default 24h), not sessionTTL. History outlives
+     *     other session slots because it's the primary context source.
+     *   - System/identity slots are refreshed on every warmSession() call,
+     *     so they effectively never expire during an active session.
+     */
+    pushHistory(agentId: string, sessionKey: string, messages: StoredMessage[], maxMessages?: number): Promise<void>;
+    /**
+     * Get session history from Redis.
+     *
+     * @param limit - When provided, return only the last N messages using
+     *   negative indexing (LRANGE -limit -1). This is the correct enforcement
+     *   point for historyDepth — previously the limit param was ignored on the
+     *   Redis path and only applied to the SQLite fallback.
+     */
+    getHistory(agentId: string, sessionKey: string, limit?: number): Promise<StoredMessage[]>;
+    /**
+     * Check whether a session already has history in Redis.
+     * Used by the bootstrap idempotency guard to avoid re-warming hot sessions.
+     *
+     * Single EXISTS call — sub-millisecond, no data transferred.
+     */
+    sessionExists(agentId: string, sessionKey: string): Promise<boolean>;
+    /**
+     * Trim Redis history to fit within a token budget.
+     *
+     * Walks the history newest→oldest, accumulating estimated tokens.
+     * When the budget is exceeded, trims everything older via LTRIM.
+     * This is the guardrail against model switches: if an agent ran on a
+     * 1M-context model and accumulated a huge history, then switched to a
+     * 120K model, the first assemble() call trims the excess.
+     *
+     * Token estimation: text at length/4, tool JSON at length/2 (dense).
+     *
+     * @returns Number of messages trimmed, or 0 if already within budget.
+     */
+    trimHistoryToTokenBudget(agentId: string, sessionKey: string, tokenBudget: number): Promise<number>;
+    /**
+     * Cache the compositor's assembled submission window.
+     *
+     * The window is the token-budgeted, deduplicated output of compose() —
+     * what actually gets sent to the provider. Separate from history (the
+     * append-only archive). Short TTL: 120s default, refreshed each compose.
+     */
+    setWindow(agentId: string, sessionKey: string, messages: NeutralMessage[], ttlSeconds?: number): Promise<void>;
+    /**
+     * Get the cached submission window.
+     * Returns null on cache miss — caller should run full compose().
+     */
+    getWindow(agentId: string, sessionKey: string): Promise<NeutralMessage[] | null>;
+    /**
+     * Invalidate the submission window cache.
+     * Called after afterTurn ingest writes new messages — ensures the next
+     * compose() runs fresh instead of serving a stale cached window.
+     */
+    invalidateWindow(agentId: string, sessionKey: string): Promise<void>;
+    /**
+     * Write the session cursor after compose().
+     * Tracks the boundary between "LLM has seen this" and "new since last compose."
+     * TTL matches history (24h) so the cursor outlives the window cache.
+     */
+    setCursor(agentId: string, sessionKey: string, cursor: SessionCursor): Promise<void>;
+    /**
+     * Get the session cursor.
+     * Returns null if no cursor exists (first compose, or Redis eviction).
+     */
+    getCursor(agentId: string, sessionKey: string): Promise<SessionCursor | null>;
+    /**
+     * Warm all slots for a session at once.
+     */
+    warmSession(agentId: string, sessionKey: string, slots: {
+        system?: string;
+        identity?: string;
+        context?: string;
+        facts?: string;
+        tools?: string;
+        meta?: SessionMeta;
+        history?: StoredMessage[];
+    }): Promise<void>;
+    /**
+     * Evict all keys for a session.
+     */
+    evictSession(agentId: string, sessionKey: string): Promise<void>;
+    /**
+     * Refresh TTL on all session keys.
+     * Uses historyTTL for the history slot, sessionTTL for everything else.
+     */
+    touchSession(agentId: string, sessionKey: string): Promise<void>;
+    /**
+     * Flush all keys matching this instance's prefix. For testing only.
+     */
+    flushPrefix(): Promise<number>;
+    /**
+     * Cache a fleet-level value. Used for library data that's read frequently.
+     * TTL defaults to 10 minutes — short enough to pick up changes, long enough
+     * to avoid hammering SQLite on every heartbeat.
+     */
+    setFleetCache(key: string, value: string, ttl?: number): Promise<void>;
+    /**
+     * Get a fleet-level cached value.
+     */
+    getFleetCache(key: string): Promise<string | null>;
+    /**
+     * Delete a fleet-level cached value.
+     */
+    delFleetCache(key: string): Promise<void>;
+    /**
+     * Cache a fleet agent's full profile (fleet registry + capabilities + desired state).
+     * Structured so a single key read gives the dashboard everything it needs.
+     */
+    cacheFleetAgent(agentId: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get a cached fleet agent profile.
+     */
+    getCachedFleetAgent(agentId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Cache the fleet summary (agent count, drift count, etc.).
+     * Short TTL — recalculated frequently.
+     */
+    cacheFleetSummary(summary: Record<string, unknown>): Promise<void>;
+    /**
+     * Get the cached fleet summary.
+     */
+    getCachedFleetSummary(): Promise<Record<string, unknown> | null>;
+    /**
+     * Invalidate all fleet cache entries for a specific agent.
+     * Call after mutations to fleet registry / desired state.
+     */
+    invalidateFleetAgent(agentId: string): Promise<void>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../src/redis.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAWzG,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC;IAIzC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IA2CjC,IAAI,WAAW,IAAI,OAAO,CAEzB;IAID,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,UAAU;IAMlB;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlF;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAO1E;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMvE,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ3D;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9F;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMxF;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB3F;;OAEG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAkBtF;;;;;;;;;;;OAWG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,aAAa,EAAE,EACzB,WAAW,GAAE,MAAY,GACxB,OAAO,CAAC,IAAI,CAAC;IAmChB;;;;;;;OAOG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAU/F;;;;;OAKG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO1E;;;;;;;;;;;;OAYG;IACG,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IA8ClB;;;;;;OAMG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,cAAc,EAAE,EAC1B,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC,IAAI,CAAC;IAMhB;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;IAOtF;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ1E;;;;OAIG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,IAAI,CAAC;IAMhB;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IASnF;;OAEG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,WAAW,CAAC;QACnB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;KAC3B,GACA,OAAO,CAAC,IAAI,CAAC;IAuChB;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtE;;;OAGG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBtE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAWpC;;;;OAIG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjF;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAMxD;;OAEG;IACG,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C;;;OAGG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAKnF;;;OAGG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxE;;OAEG;IACG,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAKtE;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAOlC"}