instar 1.3.117 → 1.3.118

package/dist/memory/EmbeddingProvider.d.ts

@@ -20,6 +20,23 @@ export interface EmbeddingProviderConfig {
     dimensions?: number;
     /** Maximum text length to embed in characters (default: 8192) */
     maxTextLength?: number;
+    /**
+     * Idle-unload window in ms. After this long with no embed() call, the loaded
+     * ONNX pipeline is disposed to free its thread pool, which busy-spins even
+     * when idle (measured: ~3.6% of a core on a quiet box, up to ~44% on a
+     * contended one — pure waste while an agent isn't doing memory work). The
+     * next embed() lazily reloads (~1-3s, verified-identical output). Default
+     * 300000 (5 min). Set 0 to disable (keep the model resident forever — the
+     * prior behavior).
+     */
+    idleUnloadMs?: number;
+    /**
+     * Test/advanced seam: factory that produces the feature-extraction pipeline.
+     * Defaults to the real `@huggingface/transformers` import. Tests inject a mock
+     * (a callable with a `dispose()`) to exercise the idle-unload lifecycle
+     * without loading the 80MB model.
+     */
+    pipelineFactory?: (modelName: string) => Promise<any>;
 }
 export declare class EmbeddingProvider {
     private pipeline;
@@ -27,7 +44,13 @@ export declare class EmbeddingProvider {
     private readonly modelName;
     readonly dimensions: number;
     private readonly maxTextLength;
+    private readonly idleUnloadMs;
+    private readonly pipelineFactory?;
     private vecExtensionLoaded;
+    /** In-flight embed() calls — the idle-unload timer never disposes while > 0. */
+    private inFlight;
+    /** Rolling idle-unload timer (reset on every embed); unref'd so it can't keep the process alive. */
+    private idleTimer;
     constructor(config?: EmbeddingProviderConfig);
     /**
      * Ensure the model is loaded. Safe to call multiple times — only loads once.
@@ -38,6 +61,24 @@ export declare class EmbeddingProvider {
      * Whether the model is loaded and ready for embedding.
      */
     get isReady(): boolean;
+    /**
+     * Arm (or re-arm) the rolling idle-unload timer. Called after every embed so
+     * the window restarts on each use — an actively-embedding agent keeps the
+     * model resident; one that goes quiet for `idleUnloadMs` unloads it.
+     */
+    private scheduleIdleUnload;
+    /**
+     * Dispose the loaded pipeline if it's idle — frees the ONNX thread pool that
+     * busy-spins even when no embedding is happening. Guarded on inFlight so a
+     * long-running batch that outlasts the window is never disposed mid-flight;
+     * its completion re-arms the timer.
+     */
+    private maybeUnload;
+    /**
+     * Explicitly release the model + cancel the idle timer (shutdown / tests).
+     * Idempotent.
+     */
+    dispose(): Promise<void>;
     /**
      * Generate a normalized embedding for a single text string.
      * Lazy-initializes the model on first call.

package/dist/memory/EmbeddingProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingProvider.d.ts","sourceRoot":"","sources":["../../src/memory/EmbeddingProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,QAAQ,GAAG,OAAO,gBAAgB,EAAE,QAAQ,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,kBAAkB,CAAyB;gBAEvC,MAAM,CAAC,EAAE,uBAAuB;IAQ5C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAWnB,SAAS;IAOvB;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAID;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAahD;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2B1D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO;IAgBvC,OAAO,CAAC,gBAAgB,CAA4C;IAEpE;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAcvC;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM;IAIhD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAO/C;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;CAUlE"}
+{"version":3,"file":"EmbeddingProvider.d.ts","sourceRoot":"","sources":["../../src/memory/EmbeddingProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,QAAQ,GAAG,OAAO,gBAAgB,EAAE,QAAQ,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACtC,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACvD;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAsC;IACvE,OAAO,CAAC,kBAAkB,CAAyB;IAEnD,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAK;IACrB,oGAAoG;IACpG,OAAO,CAAC,SAAS,CAA8C;gBAEnD,MAAM,CAAC,EAAE,uBAAuB;IAU5C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAWnB,SAAS;IAWvB;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;;OAKG;YACW,WAAW;IAazB;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB9B;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBhD;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAmC1D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO;IAgBvC,OAAO,CAAC,gBAAgB,CAA4C;IAEpE;;;;;OAKG;IACG,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC;IAcvC;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM;IAIhD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAO/C;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;CAUlE"}

package/dist/memory/EmbeddingProvider.js

@@ -18,11 +18,19 @@ export class EmbeddingProvider {
     modelName;
     dimensions;
     maxTextLength;
+    idleUnloadMs;
+    pipelineFactory;
     vecExtensionLoaded = new WeakSet();
+    /** In-flight embed() calls — the idle-unload timer never disposes while > 0. */
+    inFlight = 0;
+    /** Rolling idle-unload timer (reset on every embed); unref'd so it can't keep the process alive. */
+    idleTimer = null;
     constructor(config) {
         this.modelName = config?.modelName ?? 'Xenova/all-MiniLM-L6-v2';
         this.dimensions = config?.dimensions ?? 384;
         this.maxTextLength = config?.maxTextLength ?? 8192;
+        this.idleUnloadMs = config?.idleUnloadMs ?? 300_000;
+        this.pipelineFactory = config?.pipelineFactory;
     }
     // ─── Lifecycle ──────────────────────────────────────────────────
     /**
@@ -39,6 +47,10 @@ export class EmbeddingProvider {
         await this.loading;
     }
     async loadModel() {
+        if (this.pipelineFactory) {
+            this.pipeline = await this.pipelineFactory(this.modelName);
+            return;
+        }
         const { pipeline: createPipeline } = await import('@huggingface/transformers');
         this.pipeline = await createPipeline('feature-extraction', this.modelName, {
             dtype: 'fp32',
@@ -50,20 +62,83 @@ export class EmbeddingProvider {
     get isReady() {
         return this.pipeline !== null;
     }
+    /**
+     * Arm (or re-arm) the rolling idle-unload timer. Called after every embed so
+     * the window restarts on each use — an actively-embedding agent keeps the
+     * model resident; one that goes quiet for `idleUnloadMs` unloads it.
+     */
+    scheduleIdleUnload() {
+        if (this.idleUnloadMs <= 0)
+            return; // disabled — keep resident
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = null;
+            void this.maybeUnload();
+        }, this.idleUnloadMs);
+        // Never let the idle timer hold the process open on its own.
+        this.idleTimer.unref?.();
+    }
+    /**
+     * Dispose the loaded pipeline if it's idle — frees the ONNX thread pool that
+     * busy-spins even when no embedding is happening. Guarded on inFlight so a
+     * long-running batch that outlasts the window is never disposed mid-flight;
+     * its completion re-arms the timer.
+     */
+    async maybeUnload() {
+        if (this.inFlight > 0 || !this.pipeline)
+            return;
+        const p = this.pipeline;
+        this.pipeline = null;
+        this.loading = null;
+        try {
+            await p?.dispose?.();
+        }
+        catch {
+            // @silent-fallback-ok — dispose is best-effort cleanup; failing to free
+            // the session is not fatal (the next embed reloads a fresh pipeline).
+        }
+    }
+    /**
+     * Explicitly release the model + cancel the idle timer (shutdown / tests).
+     * Idempotent.
+     */
+    async dispose() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = null;
+        }
+        if (this.pipeline) {
+            const p = this.pipeline;
+            this.pipeline = null;
+            this.loading = null;
+            try {
+                await p?.dispose?.();
+            }
+            catch { /* @silent-fallback-ok — best-effort cleanup */ }
+        }
+    }
     // ─── Embedding ──────────────────────────────────────────────────
     /**
      * Generate a normalized embedding for a single text string.
      * Lazy-initializes the model on first call.
      */
     async embed(text) {
-        await this.initialize();
-        const truncated = text.slice(0, this.maxTextLength);
-        const output = await this.pipeline(truncated, {
-            pooling: 'mean',
-            normalize: true,
-        });
-        // output.data is a Float32Array from the ONNX model
-        return new Float32Array(output.data);
+        this.inFlight++;
+        try {
+            await this.initialize();
+            const truncated = text.slice(0, this.maxTextLength);
+            const output = await this.pipeline(truncated, {
+                pooling: 'mean',
+                normalize: true,
+            });
+            // output.data is a Float32Array from the ONNX model
+            return new Float32Array(output.data);
+        }
+        finally {
+            this.inFlight--;
+            this.scheduleIdleUnload();
+        }
     }
     /**
      * Generate normalized embeddings for multiple texts.
@@ -72,24 +147,33 @@ export class EmbeddingProvider {
     async embedBatch(texts) {
         if (texts.length === 0)
             return [];
+        // Single-text delegates to embed(), which owns its own inFlight + idle-timer
+        // bookkeeping — don't double-count here.
         if (texts.length === 1)
             return [await this.embed(texts[0])];
-        await this.initialize();
-        const truncated = texts.map(t => t.slice(0, this.maxTextLength));
-        const results = [];
-        // Process in batches of 32 to avoid memory pressure
-        const batchSize = 32;
-        for (let i = 0; i < truncated.length; i += batchSize) {
-            const batch = truncated.slice(i, i + batchSize);
-            for (const text of batch) {
-                const output = await this.pipeline(text, {
-                    pooling: 'mean',
-                    normalize: true,
-                });
-                results.push(new Float32Array(output.data));
+        this.inFlight++;
+        try {
+            await this.initialize();
+            const truncated = texts.map(t => t.slice(0, this.maxTextLength));
+            const results = [];
+            // Process in batches of 32 to avoid memory pressure
+            const batchSize = 32;
+            for (let i = 0; i < truncated.length; i += batchSize) {
+                const batch = truncated.slice(i, i + batchSize);
+                for (const text of batch) {
+                    const output = await this.pipeline(text, {
+                        pooling: 'mean',
+                        normalize: true,
+                    });
+                    results.push(new Float32Array(output.data));
+                }
             }
+            return results;
+        }
+        finally {
+            this.inFlight--;
+            this.scheduleIdleUnload();
         }
-        return results;
     }
     // ─── sqlite-vec Extension ───────────────────────────────────────
     /**

package/dist/memory/EmbeddingProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingProvider.js","sourceRoot":"","sources":["../../src/memory/EmbeddingProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EmbeddingProvider.js","sourceRoot":"","sources":["../../src/memory/EmbeddingProvider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.117",
+  "version": "1.3.118",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-30T11:35:40.574Z",
-  "instarVersion": "1.3.117",
+  "generatedAt": "2026-05-30T11:54:17.258Z",
+  "instarVersion": "1.3.118",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.118.md

@@ -0,0 +1,51 @@
+# Instar Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The shared local embedding model now unloads when idle, freeing the CPU its
+ONNX thread pool was busy-spinning on.**
+
+`EmbeddingProvider` (backing SemanticMemory / MemoryIndex / TopicMemory) loaded the
+all-MiniLM-L6-v2 ONNX model lazily and then kept it resident forever. onnxruntime's
+thread pool busy-spins even when idle — measured live via `process.cpuUsage()` at
+~3.6% of a core on a quiet box, and previously ~44% on a contended agent that was
+supposedly paused. With several agents per box each holding an idle, spinning
+model, that's a real multiplied load source.
+
+Fix: after `idleUnloadMs` (default 300000 = 5 min) with no `embed()`, the pipeline
+is disposed (thread pool freed) and lazily reloaded on the next embed. A rolling
+timer resets on every embed (active agents stay resident), an `inFlight` guard
+prevents disposing mid-batch, and the timer is `unref()`'d. Set `idleUnloadMs: 0`
+to keep the prior keep-resident behavior. Verified live: idle CPU 3.6% → 0.0% after
+dispose, and dispose→reload→embed produces an identical vector.
+
+## What to Tell Your User
+
+Each agent keeps a small local AI model loaded to search its own memories, and the
+engine running that model was quietly burning CPU even when the agent was idle —
+its worker threads spin in a tight loop instead of sleeping. On a machine running
+several agents, that added up to real wasted CPU. I changed it so the model unloads
+after a few minutes of not being used and reloads in about a second the next time
+it's needed. Active memory work is unaffected (the timer resets every time it's
+used); only genuinely idle agents stop wasting CPU. I confirmed the model produces
+the exact same results after an unload-and-reload, so nothing is lost.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Idle-unload of the embedding model | Automatic — frees the ONNX thread pool after ~5 min idle, reloads on next use |
+| Keep the model resident | Construct the embedding provider with the idle window set to zero |
+
+## Evidence
+
+- **Live measurement:** loaded-but-idle model used ~3.6% of a core (3s window,
+  `process.cpuUsage()`); ~44% previously observed on a contended agent. After
+  dispose: 0.0%. dispose→reload→embed produced an identical embedding.
+- **Tests:** `tests/unit/EmbeddingProvider-idle-unload.test.ts` (5, mock pipeline +
+  fake timers) — dispose-after-idle + lazy reload, resident-while-active,
+  disable-via-zero, inFlight guard, explicit dispose. `tsc` clean.
+- Spec: `docs/specs/onnx-idle-unload.md`. Side-effects:
+  `upgrades/side-effects/onnx-idle-unload.md`.

package/upgrades/side-effects/onnx-idle-unload.md

@@ -0,0 +1,36 @@
+# Side-effects — EmbeddingProvider idle-unload
+
+**Change:** `EmbeddingProvider` disposes its loaded ONNX pipeline after
+`idleUnloadMs` (default 5 min) of no `embed()` call, lazily reloading on the next
+embed. New `inFlight` guard, rolling idle timer, and a public `dispose()`.
+
+## Behavioral side-effects
+
+- **First embed after a long idle costs ~1-3s more** (a model reload). All
+  subsequent embeds during active use are unaffected — the idle timer resets on
+  every embed, so a busy agent keeps the model resident. Memory search/index are
+  not latency-critical, so the occasional reload is an acceptable trade for
+  eliminating the idle thread-pool spin (~3.6%-44% of a core).
+- **`isReady` is now dynamic.** Previously it returned true forever once loaded;
+  now it returns false while the model is unloaded between idle periods. No caller
+  uses `isReady` to gate embeds (verified) — `embed()` lazily re-initializes
+  regardless — so this is observational only.
+- **Embeddings are unchanged.** Verified live: dispose→reload→embed produces a
+  byte-identical vector. Unloading/reloading never alters output.
+- **Default-ON.** The production singleton constructs with defaults, so all agents
+  get 5-min idle-unload on update. Set `idleUnloadMs: 0` (constructor config) to
+  restore the prior keep-resident behavior.
+
+## Blast radius
+
+- Scoped to `src/memory/EmbeddingProvider.ts`. SemanticMemory / MemoryIndex /
+  TopicMemory consume it transparently (they call `embed()`/`embedBatch()`, which
+  handle reload internally). No call-site changes.
+- The idle timer is `unref()`'d — it can never keep the process alive.
+- No config schema, hook, or HTTP changes. No new dependencies.
+
+## Migration parity
+
+None required — internal runtime logic in `src/`. No agent-installed file
+(`.claude/settings.json`, `.instar/config.json`, CLAUDE.md template, hook, skill)
+changes. Existing agents receive it on their normal version update.