@psiclawops/hypermem 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.8.4 — compaction fence fix, install-path fixes, zod runtime packaging
+
+- **Compaction fence tail preservation fixed.** The recent-tail preservation fix is included so compaction no longer drops the protected recent tail during fence advancement.
+- **`afterTurn` token count persistence fixed.** Token accounting now persists correctly after turn completion, which keeps follow-on pressure and compaction decisions honest.
+- **Registry install docs corrected and hardened.** Installation guidance now fixes the shipped `ocplatform` typo, clarifies older package behavior around missing `install:runtime`, improves `plugins.load.paths` quoting, and removes the dangerous overwrite-style `plugins.allow` example in favor of merge-safe guidance.
+- **Install tracks clarified.** Docs now distinguish source-clone plugin setup from older npm package behavior so first-run operators do not follow the wrong path.
+- **`zod` now ships for plugin runtime use.** The published package now includes the runtime `zod` dependency required by the HyperCompositor plugin, fixing `Cannot find module 'zod'` on package-based installs.
+
 ## 0.8.2 — npm packaging & install path clarity
 
 - **INSTALL.md and CHANGELOG.md now ship in the npm package.** Previously missing from `package.json` `files` array, so `npm pack` / `npm publish` excluded them. Users installing from the registry now get the full install guide without cloning the repo.

package/INSTALL.md

@@ -17,6 +17,8 @@ If `gateway status` shows "disabled" or "not configured", complete OpenClaw onbo
 
 ## Quick Start
 
+> **Release note:** if the npm package you installed does not contain `hypermem-install` or `install:runtime`, you are on an older public release. Use the source-clone path in this guide or wait for `0.8.4+`.
+
 ```bash
 npm install @psiclawops/hypermem
 npx hypermem-install
@@ -55,19 +57,21 @@ Note any existing values. You must include them in the commands below.
 **Step 2: Wire plugins.**
 
 ```bash
-# Wire plugin load paths — merge with any existing paths from Step 1:
-openclaw config set plugins.load.paths "[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Wire plugin load paths — use a variable to avoid shell quoting problems, then merge if needed:
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 
 # Set the context engine and memory slots:
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
 
-# Allow both plugins — merge with any existing allowed plugins from Step 1.
-# Example (if "my-plugin" was already allowed):
-ocplatform config set plugins.allow '["my-plugin","hypercompositor","hypermem"]' --strict-json
+# Only set plugins.allow if your OpenClaw config already uses an allowlist.
+# If `openclaw config get plugins.allow` returns null, empty, or unset, skip this step.
+# If it returns an array, copy that array and append "hypercompositor" and "hypermem".
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
 ```
 
-> **⚠️  Merge, don't replace.** The command above sets `plugins.allow` to whatever you specify. If `plugins.allow` was non-empty in Step 1, include those entries in the array. Replacing it drops existing plugins (including bundled OpenClaw CLI surfaces and channel plugins).
+> **⚠️  Merge, don't replace.** Do not set `plugins.allow` to only `['hypercompositor','hypermem']`. That can disable bundled CLI surfaces and channel plugins. If your system already has a non-empty allowlist, append the HyperMem plugin ids to that existing array.
 
 **Step 3: Restart.**
 
@@ -374,7 +378,7 @@ npm install
 npm run build
 ```
 
-Build both plugins, then install the runtime payload into OCPlatform's durable plugin directory:
+Build both plugins, then install the runtime payload into 's durable plugin directory:
 
 ```bash
 npm --prefix plugin install && npm --prefix plugin run build
@@ -396,21 +400,23 @@ Use the OpenClaw CLI. **Do not edit `openclaw.json` directly.**
 
 ```bash
 # Check existing values first — merge if non-empty:
-ocplatform config get plugins.load.paths
+openclaw config get plugins.load.paths
 openclaw config get plugins.allow
 
-# Wire plugin load paths (merge with any existing paths):
-openclaw config set plugins.load.paths "[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Wire plugin load paths (use a variable to avoid shell quoting problems):
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 
 # Set the context engine and memory slots:
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
 
-# Allow both plugins — merge with any existing allowed plugins (example includes "my-plugin"):
-ocplatform config set plugins.allow '["my-plugin","hypercompositor","hypermem"]' --strict-json
+# Only set plugins.allow if your OpenClaw config already uses an allowlist.
+# If it returns an array, append the HyperMem plugin ids to that existing array.
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
 ```
 
-> **⚠️  Merge, don't replace.** Check `openclaw config get plugins.allow` before running this command and include all existing entries in the array.
+> **⚠️  Merge, don't replace.** Never replace a working `plugins.allow` list with only HyperMem entries. If `plugins.allow` is unset or empty, leave it alone.
 
 ### Step 3 — Choose embedding provider
 
@@ -603,7 +609,7 @@ This gives agents 4 days of working memory at startup (~12k chars total). Still
 Controls the maximum size of bootstrap files (AGENTS.md, SOUL.md, etc.) injected on session start. The default (12000) is tight for agents with governance rules, tool references, and identity docs:
 
 ```bash
-ocplatform config set agents.defaults.bootstrapMaxChars 20000 --strict-json
+openclaw config set agents.defaults.bootstrapMaxChars 20000 --strict-json
 ```
 
 ### Compaction safety net
@@ -611,10 +617,10 @@ ocplatform config set agents.defaults.bootstrapMaxChars 20000 --strict-json
 OpenClaw's built-in compaction (`safeguard` mode) serves as a last-resort safety net. Keep it enabled but tuned so it only fires when HyperMem's own pressure management is insufficient:
 
 ```bash
-ocplatform config set agents.defaults.compaction.mode safeguard
+openclaw config set agents.defaults.compaction.mode safeguard
 openclaw config set agents.defaults.compaction.reserveTokens 16384 --strict-json
-ocplatform config set agents.defaults.compaction.keepRecentTokens 6000 --strict-json
-ocplatform config set agents.defaults.compaction.reserveTokensFloor 15000 --strict-json
+openclaw config set agents.defaults.compaction.keepRecentTokens 6000 --strict-json
+openclaw config set agents.defaults.compaction.reserveTokensFloor 15000 --strict-json
 openclaw config set agents.defaults.compaction.maxHistoryShare 0.65 --strict-json
 ```
 
@@ -811,7 +817,7 @@ Expected on fresh installs. Facts and episodes accumulate over real conversation
 
 **Lost bundled plugins after setting `plugins.allow`**
 
-If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw will stop loading everything else (including built-in CLI surfaces and bundled channel plugins). Fix: re-read your OpenClaw defaults (`openclaw config get plugins.allow`), merge hypermem entries back into the full list, and `openclaw gateway restart`.
+If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw can stop loading bundled CLI surfaces and channel plugins. Fix: restore the prior allowlist, append `hypercompositor` and `hypermem`, then `openclaw gateway restart`. If `plugins.allow` was previously unset or empty, remove the HyperMem-only allowlist instead of keeping it.
 
 **Plugin not found**
 

package/README.md

@@ -449,6 +449,8 @@ That's it. No gateway, no plugins, no config files. See [API](#api) for the full
 
 ### OpenClaw plugin install (from source)
 
+> **Release note:** if the npm package you installed does not contain `install:runtime`, you are on an older public release. Use the source-clone path below or wait for `0.8.4+`.
+
 ```bash
 git clone https://github.com/PsiClawOps/hypermem.git
 cd hypermem
@@ -458,7 +460,7 @@ npm --prefix memory-plugin install && npm --prefix memory-plugin run build
 npm run install:runtime
 ```
 
-`install:runtime` stages the runtime payload into `~/.openclaw/plugins/hypermem` and prints the exact config commands to wire the plugins. Before running them, create the data directory and config:
+`install:runtime` stages the runtime payload into `~/.openclaw/plugins/hypermem` and prints the exact config commands to wire the plugins. It does not finish wiring automatically. Before running them, create the data directory and config:
 
 ```bash
 mkdir -p ~/.openclaw/hypermem
@@ -491,13 +493,16 @@ openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
 
-# ⚠️  Add to your existing plugins.allow — do not replace your current list.
-# Edit the array below to include any plugins you already have allowed:
-openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+# Only set plugins.allow if your OpenClaw config already uses an allowlist.
+# If `openclaw config get plugins.allow` returns null, empty, or unset, skip this step.
+# If it returns an array, copy that array and append "hypercompositor" and "hypermem".
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
 
 openclaw gateway restart
 ```
 
+Do **not** replace a working `plugins.allow` list with only `['hypercompositor','hypermem']`. That can disable bundled CLI surfaces and channel plugins.
+
 Verify (run these commands from the repo clone directory — `bin/` is a relative path):
 
 ```bash

package/dist/compaction-fence.d.ts

@@ -41,6 +41,14 @@ export interface CompactionEligibility {
     /** The fence itself */
     fence: CompactionFence | null;
 }
+export interface UpdateCompactionFenceOptions {
+    /**
+     * Minimum number of most-recent non-system messages that must remain above
+     * the fence. Prevents compaction from fencing off the live conversational
+     * tail under pressure.
+     */
+    minTailMessages?: number;
+}
 /**
  * Add the compaction_fences table to an existing messages.db.
  * Idempotent — safe to call on every startup.
@@ -57,7 +65,7 @@ export declare function ensureCompactionFenceSchema(db: DatabaseSync): void;
  * This prevents a short compose window from accidentally exposing
  * already-compacted messages.
  */
-export declare function updateCompactionFence(db: DatabaseSync, conversationId: number, oldestVisibleMessageId: number): void;
+export declare function updateCompactionFence(db: DatabaseSync, conversationId: number, oldestVisibleMessageId: number, opts?: UpdateCompactionFenceOptions): void;
 /**
  * Get the current compaction fence for a conversation.
  * Returns null if no fence has been set (meaning: no compaction allowed).

package/dist/compaction-fence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-fence.d.ts","sourceRoot":"","sources":["../src/compaction-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAQlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,sBAAsB,EAAE,MAAM,GAC7B,IAAI,CAqBN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B7E"}
+{"version":3,"file":"compaction-fence.d.ts","sourceRoot":"","sources":["../src/compaction-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAQlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,sBAAsB,EAAE,MAAM,EAC9B,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAgDN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B7E"}

package/dist/compaction-fence.js

@@ -48,17 +48,38 @@ export function ensureCompactionFenceSchema(db) {
  * This prevents a short compose window from accidentally exposing
  * already-compacted messages.
  */
-export function updateCompactionFence(db, conversationId, oldestVisibleMessageId) {
+export function updateCompactionFence(db, conversationId, oldestVisibleMessageId, opts = {}) {
     const now = new Date().toISOString();
+    const minTailMessages = typeof opts.minTailMessages === 'number' && Number.isFinite(opts.minTailMessages)
+        ? Math.max(1, Math.floor(opts.minTailMessages))
+        : undefined;
+    const oldestRecentRow = minTailMessages != null
+        ? db.prepare(`
+          SELECT id FROM messages
+          WHERE conversation_id = ?
+            AND role != 'system'
+          ORDER BY message_index DESC
+          LIMIT 1 OFFSET ?
+        `).get(conversationId, minTailMessages - 1) ?? db.prepare(`
+          SELECT id FROM messages
+          WHERE conversation_id = ?
+            AND role != 'system'
+          ORDER BY message_index ASC
+          LIMIT 1
+        `).get(conversationId)
+        : undefined;
+    const clampedMessageId = oldestRecentRow
+        ? Math.min(oldestVisibleMessageId, oldestRecentRow.id)
+        : oldestVisibleMessageId;
     const existing = db.prepare('SELECT fence_message_id FROM compaction_fences WHERE conversation_id = ?').get(conversationId);
     if (!existing) {
         // First fence for this conversation
-        db.prepare('INSERT INTO compaction_fences (conversation_id, fence_message_id, updated_at) VALUES (?, ?, ?)').run(conversationId, oldestVisibleMessageId, now);
+        db.prepare('INSERT INTO compaction_fences (conversation_id, fence_message_id, updated_at) VALUES (?, ?, ?)').run(conversationId, clampedMessageId, now);
         return;
     }
     // Monotone progress: fence only moves forward
-    if (oldestVisibleMessageId > existing.fence_message_id) {
-        db.prepare('UPDATE compaction_fences SET fence_message_id = ?, updated_at = ? WHERE conversation_id = ?').run(oldestVisibleMessageId, now, conversationId);
+    if (clampedMessageId > existing.fence_message_id) {
+        db.prepare('UPDATE compaction_fences SET fence_message_id = ?, updated_at = ? WHERE conversation_id = ?').run(clampedMessageId, now, conversationId);
     }
 }
 /**

package/dist/compositor.js

@@ -2495,7 +2495,7 @@ export class Compositor {
             `).get(conversation.id, historyMsgCount - 1);
                         if (oldestIncluded) {
                             ensureCompactionFenceSchema(db);
-                            updateCompactionFence(db, conversation.id, oldestIncluded.id);
+                            updateCompactionFence(db, conversation.id, oldestIncluded.id, { minTailMessages: 8 });
                         }
                     }
                 }

package/docs/TUNING.md

@@ -577,7 +577,7 @@ Large T0 results (>40k chars) at high context pressure (>80%) get head-and-tail
 
 **When `deferToolPruning: true`**: hypermem skips its own gradient when OpenClaw's native `contextPruning` is active. The native pruner handles tool result trimming on those providers. The gradient remains active as fallback for other providers.
 
-> **Recommended:** disable OpenClaw's context pruning entirely (`openclaw config set agents.defaults.contextPruning.mode off`) and let HyperMem manage all context pressure. The two systems do not coordinate and can fight each other, causing unpredictable context loss. See INSTALL.md "OCPlatform Platform Settings" for the full recommended config.
+> **Recommended:** disable OpenClaw's context pruning entirely (`openclaw config set agents.defaults.contextPruning.mode off`) and let HyperMem manage all context pressure. The two systems do not coordinate and can fight each other, causing unpredictable context loss. See INSTALL.md "OpenClaw Platform Settings" for the full recommended config.
 
 **When `verboseLogging: true`**: HyperMem emits budget-source and trim-decision logs so you can see whether a turn used runtime `tokenBudget`, a manual `contextWindowOverrides` entry, or the `contextWindowSize` fallback.
 

package/memory-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@psiclawops/hypermem-memory",
-  "version": "0.8.3",
-  "description": "HyperMem memory plugin for OpenClaw \u2014 bridges HyperMem retrieval into the memory slot",
+  "version": "0.8.4",
+  "description": "HyperMem memory plugin for OpenClaw — bridges HyperMem retrieval into the memory slot",
   "type": "module",
   "main": "dist/index.js",
   "license": "Apache-2.0",

package/node_modules/sqlite-vec/README.md

@@ -0,0 +1 @@
+TODO

package/node_modules/sqlite-vec/index.cjs

@@ -0,0 +1,46 @@
+
+
+const { arch, platform } = require("node:process");
+
+
+const BASE_PACKAGE_NAME = "sqlite-vec";
+const ENTRYPOINT_BASE_NAME = "vec0";
+const supportedPlatforms = [["darwin","x64"],["linux","x64"],["darwin","arm64"],["win32","x64"],["linux","arm64"]];
+
+const invalidPlatformErrorMessage = `Unsupported platform for ${BASE_PACKAGE_NAME}, on a ${platform}-${arch} machine. Supported platforms are (${supportedPlatforms
+  .map(([p, a]) => `${p}-${a}`)
+  .join(",")}). Consult the ${BASE_PACKAGE_NAME} NPM package README for details.`;
+
+const extensionNotFoundErrorMessage = packageName => `Loadble extension for ${BASE_PACKAGE_NAME} not found. Was the ${packageName} package installed?`;
+
+function validPlatform(platform, arch) {
+  return (
+    supportedPlatforms.find(([p, a]) => platform === p && arch === a) !== undefined
+  );
+}
+function extensionSuffix(platform) {
+  if (platform === "win32") return "dll";
+  if (platform === "darwin") return "dylib";
+  return "so";
+}
+function platformPackageName(platform, arch) {
+  const os = platform === "win32" ? "windows" : platform;
+  return `${BASE_PACKAGE_NAME}-${os}-${arch}`;
+}
+
+function getLoadablePath() {
+  if (!validPlatform(platform, arch)) {
+    throw new Error(
+      invalidPlatformErrorMessage
+    );
+  }
+  const packageName = platformPackageName(platform, arch);
+  const loadablePath = require.resolve(packageName + "/" + ENTRYPOINT_BASE_NAME + "." + extensionSuffix(platform));
+  return loadablePath;
+}
+
+function load(db) {
+  db.loadExtension(getLoadablePath());
+}
+
+module.exports = {getLoadablePath, load};

package/node_modules/sqlite-vec/index.d.ts

@@ -0,0 +1,17 @@
+
+
+/**
+ * TODO JSDoc
+ */
+export declare function getLoadablePath(): string;
+
+
+interface Db {
+    loadExtension(file: string, entrypoint?: string | undefined): void;
+}
+
+/**
+ * TODO JSDoc
+ */
+export declare function load(db: Db): void;
+

package/node_modules/sqlite-vec/index.mjs

@@ -0,0 +1,47 @@
+
+
+import { fileURLToPath } from "node:url";
+import { arch, platform } from "node:process";
+
+
+const BASE_PACKAGE_NAME = "sqlite-vec";
+const ENTRYPOINT_BASE_NAME = "vec0";
+const supportedPlatforms = [["darwin","x64"],["linux","x64"],["darwin","arm64"],["win32","x64"],["linux","arm64"]];
+
+const invalidPlatformErrorMessage = `Unsupported platform for ${BASE_PACKAGE_NAME}, on a ${platform}-${arch} machine. Supported platforms are (${supportedPlatforms
+  .map(([p, a]) => `${p}-${a}`)
+  .join(",")}). Consult the ${BASE_PACKAGE_NAME} NPM package README for details.`;
+
+const extensionNotFoundErrorMessage = packageName => `Loadble extension for ${BASE_PACKAGE_NAME} not found. Was the ${packageName} package installed?`;
+
+function validPlatform(platform, arch) {
+  return (
+    supportedPlatforms.find(([p, a]) => platform === p && arch === a) !== undefined
+  );
+}
+function extensionSuffix(platform) {
+  if (platform === "win32") return "dll";
+  if (platform === "darwin") return "dylib";
+  return "so";
+}
+function platformPackageName(platform, arch) {
+  const os = platform === "win32" ? "windows" : platform;
+  return `${BASE_PACKAGE_NAME}-${os}-${arch}`;
+}
+
+function getLoadablePath() {
+  if (!validPlatform(platform, arch)) {
+    throw new Error(
+      invalidPlatformErrorMessage
+    );
+  }
+  const packageName = platformPackageName(platform, arch);
+  const loadablePath = fileURLToPath(import.meta.resolve(packageName + "/" + ENTRYPOINT_BASE_NAME + "." + extensionSuffix(platform)));
+  return loadablePath;
+}
+
+function load(db) {
+  db.loadExtension(getLoadablePath());
+}
+
+export {getLoadablePath, load};

package/node_modules/sqlite-vec/package.json

@@ -0,0 +1 @@
+{"name":"sqlite-vec","version":"0.1.9","author":"Alex Garcia","license":"MIT OR Apache","description":"A vector search SQLite extension.","repository":{"type":"git","url":"https://github.com/asg017/sqlite-vec","directory":null},"main":"./index.cjs","module":"./index.mjs","types":"./index.d.ts","exports":{".":{"require":"./index.cjs","import":"./index.mjs","types":"./index.d.ts"}},"files":[],"keywords":[],"optionalDependencies":{"sqlite-vec-darwin-x64":"0.1.9","sqlite-vec-linux-x64":"0.1.9","sqlite-vec-darwin-arm64":"0.1.9","sqlite-vec-windows-x64":"0.1.9","sqlite-vec-linux-arm64":"0.1.9"}}

package/node_modules/sqlite-vec-linux-x64/README.md

@@ -0,0 +1 @@
+TODO

package/node_modules/sqlite-vec-linux-x64/package.json

@@ -0,0 +1 @@
+{"name":"sqlite-vec-linux-x64","version":"0.1.9","author":"Alex Garcia","license":"MIT OR Apache","description":"A vector search SQLite extension.","repository":{"type":"git","url":"https://github.com/asg017/sqlite-vec","directory":null},"exports":{"./vec0.so":{"default":"./vec0.so"}},"files":[],"keywords":[],"os":["linux"],"cpu":["x64"]}

package/node_modules/zod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/zod/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
+  <h1 align="center">Zod</h1>
+  <p align="center">
+    TypeScript-first schema validation with static type inference
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://github.com/colinhacks/zod/actions?query=branch%3Amain"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Zod CI status" /></a>
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
+<a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
+<a href="https://discord.gg/KaSRdyX2vc" rel="nofollow"><img src="https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white" alt="discord server"></a>
+<a href="https://github.com/colinhacks/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a>
+</p>
+
+<div align="center">
+  <a href="https://zod.dev/api">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://discord.gg/RcG33DQJdf">Discord</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://twitter.com/colinhacks">𝕏</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
+  <br />
+</div>
+
+<br/>
+<br/>
+
+<h2 align="center">Featured sponsor: Jazz</h2>
+
+<div align="center">
+  <a href="https://jazz.tools/?utm_source=zod">
+    <picture width="85%" >
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png">
+      <img alt="jazz logo" src="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png" width="85%">
+    </picture>
+  </a>
+  <br/>
+  <p><sub>Learn more about <a target="_blank" rel="noopener noreferrer" href="mailto:sponsorship@colinhacks.com">featured sponsorships</a></sub></p>
+</div>
+
+<br/>
+<br/>
+<br/>
+
+### [Read the docs →](https://zod.dev/api)
+
+<br/>
+<br/>
+
+## What is Zod?
+
+Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.
+
+```ts
+import * as z from "zod";
+
+const User = z.object({
+  name: z.string(),
+});
+
+// some untrusted data...
+const input = {
+  /* stuff */
+};
+
+// the parsed result is validated and type safe!
+const data = User.parse(input);
+
+// so you can use it with confidence :)
+console.log(data.name);
+```
+
+<br/>
+
+## Features
+
+- Zero external dependencies
+- Works in Node.js and all modern browsers
+- Tiny: `2kb` core bundle (gzipped)
+- Immutable API: methods return a new instance
+- Concise interface
+- Works with TypeScript and plain JS
+- Built-in JSON Schema conversion
+- Extensive ecosystem
+
+<br/>
+
+## Installation
+
+```sh
+npm install zod
+```
+
+<br/>
+
+## Basic usage
+
+Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.
+
+```ts
+import * as z from "zod";
+
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+```
+
+### Parsing data
+
+Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.
+
+```ts
+Player.parse({ username: "billie", xp: 100 });
+// => returns { username: "billie", xp: 100 }
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.parseAsync("hello");
+// => "hello"
+```
+
+### Handling errors
+
+When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.
+
+```ts
+try {
+  Player.parse({ username: 42, xp: "100" });
+} catch (err) {
+  if (err instanceof z.ZodError) {
+    err.issues;
+    /* [
+      {
+        expected: 'string',
+        code: 'invalid_type',
+        path: [ 'username' ],
+        message: 'Invalid input: expected string'
+      },
+      {
+        expected: 'number',
+        code: 'invalid_type',
+        path: [ 'xp' ],
+        message: 'Invalid input: expected number'
+      }
+    ] */
+  }
+}
+```
+
+To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.
+
+```ts
+const result = Player.safeParse({ username: 42, xp: "100" });
+if (!result.success) {
+  result.error; // ZodError instance
+} else {
+  result.data; // { username: string; xp: number }
+}
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](#refine) or [transforms](#transform), you'll need to use the `.safeParseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.safeParseAsync("hello");
+// => { success: true; data: "hello" }
+```
+
+### Inferring types
+
+Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.
+
+```ts
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+
+// extract the inferred type
+type Player = z.infer<typeof Player>;
+
+// use it in your code
+const player: Player = { username: "billie", xp: 100 };
+```
+
+In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:
+
+```ts
+const mySchema = z.string().transform((val) => val.length);
+
+type MySchemaIn = z.input<typeof mySchema>;
+// => string
+
+type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
+// number
+```