@gamaze/hicortex 0.16.5 → 0.16.7

package/dist/config-read.d.ts

@@ -23,3 +23,9 @@ export declare function readPositiveConfig(config: Record<string, unknown>, key:
  * treated as truthy.
  */
 export declare function readStrictBoolean(config: Record<string, unknown>, key: string): boolean | undefined;
+/**
+ * Read a non-negative finite number (allows 0, unlike readPositiveConfig).
+ * Returns `def` when absent OR invalid. Used for keys where 0 is a valid "off"
+ * value (e.g. ollamaFlushEvery).
+ */
+export declare function readNonNegativeConfig(config: Record<string, unknown>, key: string, def: number): number;

package/dist/config-read.js

@@ -15,6 +15,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readPositiveConfig = readPositiveConfig;
 exports.readStrictBoolean = readStrictBoolean;
+exports.readNonNegativeConfig = readNonNegativeConfig;
 /**
  * Read a positive finite number from a config object. Returns `def` when the
  * key is absent OR present-but-invalid (with a warn in the latter case).
@@ -43,3 +44,17 @@ function readStrictBoolean(config, key) {
     console.warn(`[hicortex] config "${key}" = ${String(v)} is not a boolean — ignored.`);
     return undefined;
 }
+/**
+ * Read a non-negative finite number (allows 0, unlike readPositiveConfig).
+ * Returns `def` when absent OR invalid. Used for keys where 0 is a valid "off"
+ * value (e.g. ollamaFlushEvery).
+ */
+function readNonNegativeConfig(config, key, def) {
+    const v = config[key];
+    if (v === undefined)
+        return def;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+        return v;
+    console.warn(`[hicortex] config "${key}" = ${String(v)} is not a non-negative finite number — using default ${def}.`);
+    return def;
+}

package/dist/llm.d.ts

@@ -31,6 +31,10 @@ export interface LlmConfig {
     enableThinking?: boolean;
     /** Context window for the ollama fast tier (completeOllama). Falls back to 2048. */
     numCtx?: number;
+    /** Flush ollama memory every N ollama calls (0 = off). See HicortexConfig.ollamaFlushEvery. */
+    ollamaFlushEvery?: number;
+    /** Ms to wait after an ollama flush for the runner to release. */
+    ollamaFlushWaitMs?: number;
     /** Optional separate endpoint for reflect-tier LLM (e.g. remote Ollama with larger model). */
     reflectBaseUrl?: string;
     reflectApiKey?: string;
@@ -212,6 +216,7 @@ export declare class RateLimitError extends Error {
 }
 export declare class LlmClient {
     private config;
+    private ollamaCallCount;
     constructor(config: LlmConfig);
     /** Endpoint identity for shared rate-limit state (provider + base URL). */
     private get endpointKey();
@@ -261,6 +266,16 @@ export declare class LlmClient {
      * Ollama: use /api/generate with think:false (important for qwen3.5 models).
      */
     private completeOllama;
+    /**
+     * Flush ollama's accumulated memory: unload the model (keep_alive:0) so the
+     * runner exits + releases its per-request RSS growth, then wait for the release
+     * before the next call reloads fresh. The runner takes >90 s to exit after
+     * keep_alive:0 (measured), so the wait is generous (ollamaFlushWaitMs, default
+     * 180 s). Logs the flush so the wait is distinguishable from a hang. If the
+     * unload request fails (ollama down), the wait is skipped — no dead time for a
+     * release that can't have happened. See #229 review.
+     */
+    private flushOllama;
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.

package/dist/llm.js

@@ -211,6 +211,12 @@ function applyTierTuningOverlay(llmConfig, savedConfig) {
     if (savedConfig.numCtx !== undefined) {
         llmConfig.numCtx = (0, config_read_js_1.readPositiveConfig)(savedConfig, "numCtx", 2048);
     }
+    if (savedConfig.ollamaFlushEvery !== undefined) {
+        llmConfig.ollamaFlushEvery = (0, config_read_js_1.readNonNegativeConfig)(savedConfig, "ollamaFlushEvery", 0);
+    }
+    if (savedConfig.ollamaFlushWaitMs !== undefined) {
+        llmConfig.ollamaFlushWaitMs = (0, config_read_js_1.readPositiveConfig)(savedConfig, "ollamaFlushWaitMs", 180000);
+    }
 }
 /**
  * Resolve an LlmConfig from a saved ~/.hicortex/config.json object.
@@ -511,6 +517,7 @@ exports.RateLimitError = RateLimitError;
 const rateLimitedUntilByEndpoint = new Map();
 class LlmClient {
     config;
+    ollamaCallCount = 0;
     constructor(config) {
         this.config = config;
     }
@@ -546,7 +553,20 @@ class LlmClient {
         // so ONLY this tier gets the smaller context window — the heavy tiers keep 32768
         // (preserves detectChunkSize's chunk-sizing). thinking is not threaded (scoring is
         // excluded from the thinking toggle; ollama is think:false regardless).
-        return this.complete(this.config.model, prompt, tokens, 600_000, undefined, this.config.numCtx ?? 2048);
+        const result = await this.complete(this.config.model, prompt, tokens, 600_000, undefined, this.config.numCtx ?? 2048);
+        // Periodic flush: scoped to scoring (the fast tier) only — heavy tiers
+        // (distill/reflect/classify) don't flush, avoiding a multi-minute pause
+        // mid-distillation + unloading the wrong model. Override-routed tiers never
+        // reach here (completeWithOverride builds a fresh client). See #229 review.
+        const flushEvery = this.config.ollamaFlushEvery ?? 0;
+        if (this.config.provider === "ollama" && flushEvery > 0) {
+            this.ollamaCallCount++;
+            if (this.ollamaCallCount >= flushEvery) {
+                await this.flushOllama(this.config.model);
+                this.ollamaCallCount = 0;
+            }
+        }
+        return result;
     }
     /**
      * Reflect-tier completion (nightly reflection, needs reasoning).
@@ -741,6 +761,33 @@ class LlmClient {
         }
         return result.trim();
     }
+    /**
+     * Flush ollama's accumulated memory: unload the model (keep_alive:0) so the
+     * runner exits + releases its per-request RSS growth, then wait for the release
+     * before the next call reloads fresh. The runner takes >90 s to exit after
+     * keep_alive:0 (measured), so the wait is generous (ollamaFlushWaitMs, default
+     * 180 s). Logs the flush so the wait is distinguishable from a hang. If the
+     * unload request fails (ollama down), the wait is skipped — no dead time for a
+     * release that can't have happened. See #229 review.
+     */
+    async flushOllama(model) {
+        const url = `${this.config.baseUrl.replace(/\/$/, "")}/api/generate`;
+        const waitMs = this.config.ollamaFlushWaitMs ?? 180_000;
+        console.log(`[hicortex] ollama flush: unloading ${model} after ${this.ollamaCallCount} scoring calls, waiting ${waitMs / 1000}s for memory release…`);
+        try {
+            await fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ model, keep_alive: 0 }),
+                signal: AbortSignal.timeout(60_000),
+            });
+            await new Promise((r) => setTimeout(r, waitMs));
+            console.log(`[hicortex] ollama flush: complete`);
+        }
+        catch {
+            console.warn(`[hicortex] ollama flush: unload request failed (ollama unreachable?) — skipping wait`);
+        }
+    }
     /**
      * Anthropic Messages API (/v1/messages).
      * Auth via x-api-key header.

package/dist/types.d.ts

@@ -313,6 +313,27 @@ export interface HicortexConfig {
      * scoring prompt actually needs more.
      */
     numCtx?: number;
+    /**
+     * Flush ollama's accumulated memory every N scoring calls — workaround for
+     * ollama's per-request memory growth (the runner's RSS climbs ~171 MB/call and
+     * isn't freed between requests), which swap-thrashes RAM-constrained boxes
+     * during long consolidations. Default 0 (off). When >0, every Nth scoring call
+     * (`completeFast`) triggers a `keep_alive:0` unload + an `ollamaFlushWaitMs`
+     * pause for the runner to exit + release, then the next call reloads fresh.
+     * N=15 caps a cycle at ~2.5 GB. Scoped to the fast tier (scoring) only. Note:
+     * N counts **logical** scoring calls, not raw HTTP requests — `complete()`
+     * retries up to 4× on timeout, so under retry pressure the actual accumulation
+     * may be up to 4×N calls' worth. In practice the flush prevents the thrash that
+     * causes retries, keeping the count accurate.
+     */
+    ollamaFlushEvery?: number;
+    /**
+     * Milliseconds to wait after an ollama flush (`keep_alive:0`) for the runner
+     * to exit + release its accumulated memory before the next call reloads.
+     * Default 180000 (3 min — the runner takes >90 s to exit after keep_alive:0;
+     * doubled for margin). Only relevant when `ollamaFlushEvery` > 0.
+     */
+    ollamaFlushWaitMs?: number;
 }
 /** A config-owned life-sphere domain (see HicortexConfig.domains). */
 export interface DomainDef {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "description": "Self-learning memory for AI agents — experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {