@psiclawops/hypermem 0.9.3 → 0.9.5

package/plugin/openclaw.plugin.json

@@ -3,11 +3,208 @@
   "enabledByDefault": false,
   "kind": "context-engine",
   "activation": {
-    "onCapabilities": ["context-engine"]
+    "onCapabilities": [
+      "context-engine"
+    ]
   },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {}
+    "properties": {
+      "hyperMemPath": {
+        "type": "string"
+      },
+      "dataDir": {
+        "type": "string"
+      },
+      "contextWindowSize": {
+        "type": "integer",
+        "minimum": 1
+      },
+      "contextWindowReserve": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 0.5
+      },
+      "deferToolPruning": {
+        "type": "boolean"
+      },
+      "verboseLogging": {
+        "type": "boolean"
+      },
+      "warmCacheReplayThresholdMs": {
+        "type": "integer",
+        "minimum": 0
+      },
+      "subagentWarming": {
+        "type": "string",
+        "enum": [
+          "full",
+          "light",
+          "off"
+        ]
+      },
+      "contextWindowOverrides": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "contextTokens": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "contextWindow": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        }
+      },
+      "compositor": {
+        "type": "object",
+        "additionalProperties": true
+      },
+      "eviction": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "imageAgeTurns": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "toolResultAgeTurns": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "minTokensToEvict": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "keepPreviewChars": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      },
+      "embedding": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "none",
+              "ollama",
+              "openai",
+              "gemini"
+            ]
+          },
+          "ollamaUrl": {
+            "type": "string"
+          },
+          "openaiApiKey": {
+            "type": "string"
+          },
+          "openaiBaseUrl": {
+            "type": "string"
+          },
+          "geminiApiKey": {
+            "type": "string"
+          },
+          "geminiBaseUrl": {
+            "type": "string"
+          },
+          "geminiIndexTaskType": {
+            "type": "string"
+          },
+          "geminiQueryTaskType": {
+            "type": "string"
+          },
+          "queryInputType": {
+            "type": "string"
+          },
+          "documentInputType": {
+            "type": "string"
+          },
+          "queryPrefix": {
+            "type": "string"
+          },
+          "documentPrefix": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "dimensions": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "timeout": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "batchSize": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      },
+      "reranker": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "provider"
+        ],
+        "properties": {
+          "provider": {
+            "type": "string",
+            "enum": [
+              "zeroentropy",
+              "openrouter",
+              "local",
+              "none"
+            ]
+          },
+          "minCandidates": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "maxDocuments": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "topK": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "timeoutMs": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "zeroEntropyApiKey": {
+            "type": "string"
+          },
+          "zeroEntropyModel": {
+            "type": "string"
+          },
+          "openrouterApiKey": {
+            "type": "string"
+          },
+          "openrouterModel": {
+            "type": "string"
+          },
+          "ollamaUrl": {
+            "type": "string"
+          },
+          "ollamaModel": {
+            "type": "string"
+          }
+        }
+      }
+    }
   }
 }

package/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@psiclawops/hypercompositor",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "HyperCompositor \u2014 context engine plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "0.9.2",
+    "@psiclawops/hypermem": "0.9.5",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/scripts/install-packed-runtime.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdtempSync, rmSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const repoRoot = path.resolve(__dirname, '..');
+
+const argv = process.argv.slice(2);
+let installRoot = path.join(os.homedir(), '.openclaw/plugins/hypermem');
+let inputTarball = null;
+
+for (let i = 0; i < argv.length; i += 1) {
+  const arg = argv[i];
+  if (arg === '--install-root' && argv[i + 1]) {
+    installRoot = path.resolve(argv[++i]);
+  } else if (arg === '--tarball' && argv[i + 1]) {
+    inputTarball = path.resolve(argv[++i]);
+  } else if (arg.endsWith('.tgz')) {
+    inputTarball = path.resolve(arg);
+  } else if (!arg.startsWith('--')) {
+    installRoot = path.resolve(arg);
+  }
+}
+
+function run(command, args, options = {}) {
+  return execFileSync(command, args, {
+    cwd: options.cwd ?? repoRoot,
+    stdio: options.stdio ?? 'pipe',
+    encoding: options.encoding ?? 'utf8',
+    env: process.env,
+  });
+}
+
+function safeRemove(filePath) {
+  try {
+    if (existsSync(filePath) && statSync(filePath).isFile()) rmSync(filePath, { force: true });
+  } catch {
+    // Best-effort cleanup only. Never delete directories here.
+  }
+}
+
+const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+const tempRoot = mkdtempSync(path.join(os.tmpdir(), 'hypermem-packed-runtime-'));
+const tempApp = path.join(tempRoot, 'app');
+let tarballPath = inputTarball;
+let createdTarball = false;
+
+try {
+  if (!tarballPath) {
+    console.log('Packing HyperMem via npm pack...');
+    const packOutput = run('npm', ['pack', '--silent']).trim();
+    const tarballName = packOutput.split('\n').filter(Boolean).pop();
+    if (!tarballName) throw new Error('npm pack did not return a tarball name');
+    tarballPath = path.join(repoRoot, tarballName);
+    createdTarball = true;
+  } else if (!existsSync(tarballPath) || !statSync(tarballPath).isFile()) {
+    throw new Error(`Tarball not found or not a file: ${tarballPath}`);
+  }
+
+  console.log(`Installing packed artifact into temp app: ${tempApp}`);
+  run('npm', ['--prefix', tempApp, 'init', '-y'], { stdio: 'ignore' });
+  run('npm', ['--prefix', tempApp, 'install', '--no-audit', '--no-fund', tarballPath], {
+    stdio: 'inherit',
+  });
+
+  const backupPath = `${installRoot}.backup.${stamp}`;
+  if (existsSync(installRoot)) {
+    console.log(`Backing up current runtime: ${backupPath}`);
+    cpSync(installRoot, backupPath, { recursive: true, force: false, errorOnExist: true });
+  }
+
+  const installer = path.join(
+    tempApp,
+    'node_modules',
+    '@psiclawops',
+    'hypermem',
+    'scripts',
+    'install-runtime.mjs',
+  );
+  console.log(`Installing packed runtime to: ${installRoot}`);
+  run(process.execPath, [installer, installRoot], { stdio: 'inherit' });
+
+  const pkg = JSON.parse(
+    run(process.execPath, [
+      '-e',
+      `console.log(require('fs').readFileSync(${JSON.stringify(path.join(installRoot, 'package.json'))}, 'utf8'))`,
+    ]),
+  );
+  console.log(`Installed ${pkg.name}@${pkg.version} from packed artifact.`);
+  console.log(`Runtime path: ${installRoot}`);
+  console.log('Restart OpenClaw gateway before validating runtime behavior.');
+} finally {
+  if (createdTarball && tarballPath) safeRemove(tarballPath);
+  rmSync(tempRoot, { recursive: true, force: true });
+}

package/scripts/install-runtime.mjs

@@ -1,23 +1,99 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..');
-const installRoot = process.argv[2]
-  ? path.resolve(process.argv[2])
+
+function usage() {
+  console.log(`
+hypermem-install — stage the HyperMem runtime for OpenClaw
+
+Usage:
+  hypermem-install [install-root] [options]
+  hypermem-install --install-root <path> [options]
+
+Options:
+  --install-root <path>       Runtime install directory
+                              default: ~/.openclaw/plugins/hypermem
+  --skip-embedding-check      Do not require the configured embedding provider
+                              to be reachable during install
+  --skip-openclaw-config      Do not attempt OpenClaw config writes. Current
+                              installer is read-only for OpenClaw config, so
+                              this is accepted for CI/container scripts.
+  -h, --help                  Show this help
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    installRoot: null,
+    skipEmbeddingCheck: false,
+    skipOpenClawConfig: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '--install-root') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('--install-root requires a path');
+      }
+      options.installRoot = value;
+      i += 1;
+    } else if (arg === '--skip-embedding-check') {
+      options.skipEmbeddingCheck = true;
+    } else if (arg === '--skip-openclaw-config') {
+      options.skipOpenClawConfig = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!options.installRoot) {
+      options.installRoot = arg;
+    } else {
+      throw new Error(`Unexpected positional argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+let options;
+try {
+  options = parseArgs(process.argv.slice(2));
+} catch (err) {
+  console.error(`hypermem-install: ${err.message}`);
+  usage();
+  process.exit(2);
+}
+
+if (options.help) {
+  usage();
+  process.exit(0);
+}
+
+const installRoot = options.installRoot
+  ? path.resolve(options.installRoot)
   : path.join(os.homedir(), '.openclaw/plugins/hypermem');
+const hypermemConfigPath = path.join(os.homedir(), '.openclaw', 'hypermem', 'config.json');
+const defaultConfigSource = path.join(REPO_ROOT, 'assets', 'default-config.json');
 
 const requiredEntries = [
   ['dist', 'dist'],
   ['package.json', 'package.json'],
   ['README.md', 'README.md'],
   ['LICENSE', 'LICENSE'],
+  ['assets/default-config.json', 'assets/default-config.json'],
   ['bin/hypermem-status.mjs', 'bin/hypermem-status.mjs'],
   ['bin/hypermem-model-audit.mjs', 'bin/hypermem-model-audit.mjs'],
+  ['bin/hypermem-doctor.mjs', 'bin/hypermem-doctor.mjs'],
+  ['bin/hypermem-bench.mjs', 'bin/hypermem-bench.mjs'],
+  ['bench/data-access-bench.mjs', 'bench/data-access-bench.mjs'],
   ['plugin/dist', 'plugin/dist'],
   ['plugin/package.json', 'plugin/package.json'],
   ['plugin/openclaw.plugin.json', 'plugin/openclaw.plugin.json'],
@@ -57,6 +133,77 @@ const entries = [
   ...sqliteVecNativeEntries.filter(([srcRel]) => existsSync(path.join(REPO_ROOT, srcRel))),
 ];
 
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, 'utf8'));
+}
+
+function writeDefaultConfigIfMissing() {
+  if (!existsSync(defaultConfigSource)) {
+    console.error(`Missing default config artifact: ${defaultConfigSource}`);
+    process.exit(1);
+  }
+  if (existsSync(hypermemConfigPath)) {
+    return { path: hypermemConfigPath, created: false, config: readJson(hypermemConfigPath) };
+  }
+  mkdirSync(path.dirname(hypermemConfigPath), { recursive: true, mode: 0o700 });
+  const content = readFileSync(defaultConfigSource, 'utf8');
+  writeFileSync(hypermemConfigPath, content.endsWith('\n') ? content : `${content}\n`, { mode: 0o600 });
+  return { path: hypermemConfigPath, created: true, config: JSON.parse(content) };
+}
+
+async function probeEmbeddingProvider(config) {
+  const embedding = config?.embedding ?? {};
+  const provider = embedding.provider ?? 'ollama';
+  if (provider === 'none') return { ok: true, skipped: true, reason: 'embedding provider disabled' };
+  if (provider !== 'ollama') return { ok: true, skipped: true, reason: `embedding provider ${provider} is not probed by installer` };
+
+  const baseUrl = String(embedding.ollamaUrl ?? 'http://localhost:11434').replace(/\/$/, '');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 1500);
+  try {
+    const res = await fetch(`${baseUrl}/api/tags`, { signal: controller.signal });
+    if (!res.ok) return { ok: false, provider, baseUrl, reason: `HTTP ${res.status}` };
+    const body = await res.json().catch(() => ({}));
+    const model = embedding.model ?? 'nomic-embed-text';
+    const models = Array.isArray(body.models) ? body.models : [];
+    const hasModel = models.some((entry) => entry?.name === model || entry?.model === model || String(entry?.name ?? '').startsWith(`${model}:`));
+    if (!hasModel) {
+      return { ok: false, provider, baseUrl, reason: `model ${model} is not installed` };
+    }
+    return { ok: true, provider, baseUrl, model };
+  } catch (err) {
+    const detail = err.cause?.code ? `${err.message} (${err.cause.code})` : err.message;
+    return { ok: false, provider, baseUrl, reason: err.name === 'AbortError' ? 'probe timed out' : `cannot reach ${baseUrl}: ${detail}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const configResult = writeDefaultConfigIfMissing();
+
+if (!options.skipEmbeddingCheck) {
+  const probe = await probeEmbeddingProvider(configResult.config);
+  if (!probe.ok) {
+    console.error(`
+Embedding provider check failed: ${probe.reason}
+
+HyperMem default semantic recall uses Ollama with nomic-embed-text.
+Remediation:
+  1. Install and start Ollama: https://ollama.com/download
+  2. Pull the embedding model: ollama pull nomic-embed-text
+  3. Re-run hypermem-install
+
+Advanced/CI override:
+  hypermem-install --skip-embedding-check
+
+Config checked:
+  ${configResult.path}
+`);
+    process.exit(3);
+  }
+}
+
 rmSync(installRoot, { recursive: true, force: true });
 mkdirSync(installRoot, { recursive: true });
 
@@ -75,7 +222,17 @@ symlinkSync(openclawInstallPath, path.join(installRoot, 'memory-plugin/node_modu
 symlinkSync('../../..', path.join(installRoot, 'plugin/node_modules/@psiclawops/hypermem'));
 symlinkSync('../../..', path.join(installRoot, 'memory-plugin/node_modules/@psiclawops/hypermem'));
 
-console.log(`\n  Runtime installed to:\n    ${installRoot}\n`);
+console.log(`
+  Runtime installed to:
+    ${installRoot}
+`);
+console.log(`  HyperMem config:
+    ${configResult.path} ${configResult.created ? '(created)' : '(already existed, unchanged)'}
+`);
+if (options.skipEmbeddingCheck) {
+  console.log(`  Embedding provider check skipped by --skip-embedding-check.
+`);
+}
 console.log(`  Next steps — wire the plugins into OpenClaw:\n`);
 console.log(`    openclaw config set plugins.load.paths '["${installRoot}/plugin","${installRoot}/memory-plugin"]' --strict-json`);
 console.log(`    openclaw config set plugins.slots.contextEngine hypercompositor`);
@@ -85,7 +242,10 @@ console.log(`    openclaw config get plugins.allow`);
 console.log(`    # Example merge (if "my-plugin" was already allowed):`);
 console.log(`    #   openclaw config set plugins.allow '["my-plugin","hypercompositor","hypermem"]' --strict-json`);
 console.log(`    # If plugins.allow is empty or unset, skip that step instead of creating a new allowlist.`);
+console.log(`    openclaw plugins registry --refresh`);
+console.log(`    openclaw doctor --fix --yes`);
 console.log(`    openclaw gateway restart\n`);
 console.log(`  Verify:\n`);
+console.log(`    openclaw plugins registry --refresh`);
 console.log(`    openclaw plugins list`);
 console.log(`    node bin/hypermem-status.mjs --health\n`);