@psiclawops/hypermem 0.9.1 → 0.9.3

package/memory-plugin/dist/index.js

@@ -0,0 +1,378 @@
+/**
+ * HyperMem Memory Plugin
+ *
+ * Thin adapter that bridges HyperMem's retrieval capabilities into
+ * OpenClaw's memory slot contract (`kind: "memory"`).
+ *
+ * The context engine plugin (hypercompositor) owns the full lifecycle:
+ * ingest, assemble, compact, afterTurn, bootstrap, dispose.
+ *
+ * This plugin owns the memory slot contract:
+ * - registerMemoryCapability() with runtime + publicArtifacts
+ * - memory_search tool backing via MemorySearchManager
+ * - Public artifacts for memory-wiki bridge
+ *
+ * Both plugins share the same HyperMem singleton (loaded from repo dist).
+ */
+import { definePluginEntry, emptyPluginConfigSchema } from 'openclaw/plugin-sdk/plugin-entry';
+import { matchTriggers, TRIGGER_REGISTRY } from '@psiclawops/hypermem';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+import { fileURLToPath } from 'url';
+// ─── HyperMem singleton ────────────────────────────────────────
+// HyperMem.create() in the core package now dedupes per absolute dataDir, so
+// whichever of the two plugins (context-engine, memory) calls create() first
+// owns the instance. To avoid a race where this plugin would otherwise win
+// boot with no embedding config and force defaults onto the shared instance,
+// we load the same user config file the context-engine plugin loads and pass
+// the full embedding/reranker config through to create().
+const __pluginDir = path.dirname(fileURLToPath(import.meta.url));
+async function resolveHyperMemPath() {
+    try {
+        const resolvedUrl = await import.meta.resolve('@psiclawops/hypermem');
+        return resolvedUrl.startsWith('file:') ? fileURLToPath(resolvedUrl) : resolvedUrl;
+    }
+    catch {
+        return path.resolve(__pluginDir, '../../dist/index.js');
+    }
+}
+async function loadFileConfig(dataDir) {
+    const configPath = path.join(dataDir, 'config.json');
+    try {
+        const raw = await fs.readFile(configPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            console.warn(`[hypermem-memory] Failed to parse config.json (using defaults):`, err.message);
+        }
+        return {};
+    }
+}
+let _hm = null;
+let _hmInitPromise = null;
+async function getHyperMem() {
+    if (_hm)
+        return _hm;
+    if (_hmInitPromise)
+        return _hmInitPromise;
+    _hmInitPromise = (async () => {
+        const hypermemPath = await resolveHyperMemPath();
+        const mod = await import(hypermemPath);
+        const HyperMem = mod.HyperMem;
+        const dataDir = path.join(os.homedir(), '.openclaw/hypermem');
+        const fileConfig = await loadFileConfig(dataDir);
+        const createConfig = {
+            dataDir,
+            cache: {
+                keyPrefix: 'hm:',
+                sessionTTL: 14400,
+                historyTTL: 86400,
+            },
+        };
+        // Forward embedding + reranker so this plugin's create() call produces
+        // an equivalent instance to the context-engine plugin's. Other config
+        // sections (compositor, indexer, dreaming, etc.) are owned by the
+        // context-engine plugin and only matter when it wins the singleton race.
+        if (fileConfig.embedding)
+            createConfig.embedding = fileConfig.embedding;
+        if (fileConfig.reranker)
+            createConfig.reranker = fileConfig.reranker;
+        const instance = await HyperMem.create(createConfig);
+        _hm = instance;
+        return instance;
+    })();
+    return _hmInitPromise;
+}
+const DOCTRINE_COLLECTIONS = new Set([
+    'governance/policy',
+    'governance/charter',
+    'governance/comms',
+    'operations/agents',
+]);
+function doctrineScore(chunk, rank) {
+    const collectionBoost = chunk.collection.startsWith('governance/') ? 1.25 : 1.1;
+    return collectionBoost - Math.min(rank, 9) * 0.03;
+}
+function docChunkToMemoryResult(chunk, rank) {
+    return {
+        path: chunk.sourcePath,
+        startLine: 0,
+        endLine: 0,
+        score: doctrineScore(chunk, rank),
+        snippet: chunk.content.slice(0, 500),
+        source: 'memory',
+        citation: `[doc:${chunk.collection}:${chunk.sectionPath}]`,
+    };
+}
+/**
+ * Create a MemorySearchManager backed by HyperMem's retrieval pipeline.
+ *
+ * Uses HyperMem's:
+ * - library.db fact search (FTS5 + BM25)
+ * - vector store semantic search (when available)
+ * - message search (full-text across conversations)
+ */
+function createMemorySearchManager(hm, agentId, workspaceDir) {
+    return {
+        async search(query, opts) {
+            const maxResults = opts?.maxResults ?? 10;
+            const minScore = opts?.minScore ?? 0;
+            const results = [];
+            const seenDocChunks = new Set();
+            // 0. Canonical doctrine search. Explicit governance queries should surface
+            // policy, charter, comms, and AGENTS chunks before stale daily-memory folklore.
+            try {
+                const triggers = matchTriggers(query, TRIGGER_REGISTRY)
+                    .filter(trigger => DOCTRINE_COLLECTIONS.has(trigger.collection))
+                    .slice(0, 4);
+                for (const trigger of triggers) {
+                    const chunks = hm.queryDocChunks({
+                        collection: trigger.collection,
+                        agentId,
+                        keyword: query,
+                        limit: Math.max(3, Math.ceil(maxResults / Math.max(1, triggers.length))),
+                    });
+                    chunks.forEach((chunk, rank) => {
+                        const key = `${chunk.sourcePath}:${chunk.sectionPath}:${chunk.sourceHash}`;
+                        if (seenDocChunks.has(key))
+                            return;
+                        seenDocChunks.add(key);
+                        const result = docChunkToMemoryResult(chunk, rank);
+                        if (result.score >= minScore)
+                            results.push(result);
+                    });
+                }
+            }
+            catch {
+                // Doctrine search is a precision boost, not a hard dependency.
+            }
+            // 1. Fact search (FTS5 + BM25 from library.db)
+            try {
+                const facts = hm.getActiveFacts(agentId, { limit: maxResults * 2 });
+                // Simple keyword matching for facts (FTS5 handles this in the DB layer)
+                const queryLower = query.toLowerCase();
+                const queryTerms = queryLower.split(/\s+/).filter(t => t.length > 2);
+                for (const fact of facts) {
+                    const contentLower = fact.content.toLowerCase();
+                    const matchCount = queryTerms.filter(t => contentLower.includes(t)).length;
+                    if (matchCount === 0)
+                        continue;
+                    const score = matchCount / queryTerms.length;
+                    if (score < minScore)
+                        continue;
+                    results.push({
+                        path: `library://facts/${fact.id}`,
+                        startLine: 0,
+                        endLine: 0,
+                        score,
+                        snippet: fact.content.slice(0, 300),
+                        source: 'memory',
+                        citation: fact.domain ? `[fact:${fact.domain}]` : '[fact]',
+                    });
+                }
+            }
+            catch {
+                // Fact search non-fatal
+            }
+            // 2. Vector/semantic search (when available)
+            try {
+                const vectorStore = hm.getVectorStore();
+                if (vectorStore) {
+                    const vectorResults = await hm.semanticSearch(agentId, query, {
+                        limit: maxResults,
+                        maxDistance: 1.5,
+                    });
+                    for (const vr of vectorResults) {
+                        const score = 1.0 - (vr.distance / 2.0); // normalize distance to 0-1 score
+                        if (score < minScore)
+                            continue;
+                        results.push({
+                            path: `vector://${vr.sourceTable}/${vr.sourceId}`,
+                            startLine: 0,
+                            endLine: 0,
+                            score,
+                            snippet: vr.content.slice(0, 300),
+                            source: 'memory',
+                            citation: `[${vr.sourceTable}:${vr.sourceId}]`,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Vector search non-fatal
+            }
+            // 3. Message search (FTS5 across conversations)
+            try {
+                const messageResults = hm.search(agentId, query, maxResults);
+                for (const msg of messageResults) {
+                    const content = msg.textContent ?? '';
+                    results.push({
+                        path: `messages://${msg.conversationId ?? 'unknown'}/${msg.id}`,
+                        startLine: 0,
+                        endLine: 0,
+                        score: 0.5, // message search doesn't return scores, use mid-range
+                        snippet: content.slice(0, 300),
+                        source: 'sessions',
+                        citation: `[message:${msg.id}]`,
+                    });
+                }
+            }
+            catch {
+                // Message search non-fatal
+            }
+            // Deduplicate by content similarity, sort by score, limit
+            results.sort((a, b) => b.score - a.score);
+            return results.slice(0, maxResults);
+        },
+        async readFile(params) {
+            const absPath = path.resolve(workspaceDir, params.relPath);
+            try {
+                const content = await fs.readFile(absPath, 'utf-8');
+                const lines = content.split('\n');
+                const from = params.from ?? 0;
+                const count = params.lines ?? lines.length;
+                const slice = lines.slice(from, from + count);
+                return { text: slice.join('\n'), path: absPath };
+            }
+            catch (err) {
+                return { text: `Error reading ${absPath}: ${err.message}`, path: absPath };
+            }
+        },
+        status() {
+            const vectorStore = hm.getVectorStore();
+            const vectorStats = vectorStore ? hm.getVectorStats(agentId) : null;
+            return {
+                backend: 'builtin',
+                provider: 'hypermem',
+                model: 'hypermem-fts5+vector',
+                workspaceDir,
+                dbPath: path.join(os.homedir(), '.openclaw/hypermem'),
+                sources: ['memory', 'sessions'],
+                fts: {
+                    enabled: true,
+                    available: true,
+                },
+                vector: {
+                    enabled: !!vectorStore,
+                    available: !!vectorStore,
+                    dims: vectorStats?.dimensions
+                        ?? vectorStats?.dims
+                        ?? undefined,
+                },
+                custom: {
+                    vectorStats: vectorStats ?? undefined,
+                    factCount: hm.getActiveFacts(agentId, { limit: 1 }).length > 0 ? 'available' : 'empty',
+                },
+            };
+        },
+        async probeEmbeddingAvailability() {
+            try {
+                const vectorStore = hm.getVectorStore();
+                if (!vectorStore)
+                    return { ok: false, error: 'Vector store not initialized' };
+                return { ok: true };
+            }
+            catch (err) {
+                return { ok: false, error: err.message };
+            }
+        },
+        async probeVectorAvailability() {
+            return !!hm.getVectorStore();
+        },
+    };
+}
+// ─── Manager cache ──────────────────────────────────────────────
+// One manager per agentId; closed on plugin dispose.
+const _managers = new Map();
+// ─── Plugin Entry ───────────────────────────────────────────────
+export default definePluginEntry({
+    id: 'hypermem',
+    name: 'HyperMem Memory',
+    description: 'Bridges HyperMem retrieval (facts, vectors, messages) into the OpenClaw memory slot for memory_search and memory-wiki.',
+    kind: 'memory',
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        api.registerMemoryCapability({
+            runtime: {
+                async getMemorySearchManager(params) {
+                    try {
+                        const hm = await getHyperMem();
+                        const agentId = params.agentId || 'main';
+                        // Cache managers per agent
+                        if (!_managers.has(agentId)) {
+                            // Resolve workspace dir from agent config
+                            const agents = params.cfg?.agents?.list ?? [];
+                            const agentCfg = agents.find((a) => a.id === agentId);
+                            const workspaceDir = agentCfg?.workspace
+                                ?? path.join(os.homedir(), '.openclaw/workspace');
+                            _managers.set(agentId, createMemorySearchManager(hm, agentId, workspaceDir));
+                        }
+                        return { manager: _managers.get(agentId) };
+                    }
+                    catch (err) {
+                        return { manager: null, error: err.message };
+                    }
+                },
+                resolveMemoryBackendConfig(_params) {
+                    return { backend: 'builtin' };
+                },
+                async closeAllMemorySearchManagers() {
+                    _managers.clear();
+                },
+            },
+            publicArtifacts: {
+                async listArtifacts(params) {
+                    const artifacts = [];
+                    // List memory files for each agent
+                    const agents = params.cfg?.agents?.list ?? [];
+                    for (const agent of agents) {
+                        const agentId = agent.id;
+                        if (!agentId)
+                            continue;
+                        const workspace = agent.workspace;
+                        if (!workspace)
+                            continue;
+                        const memoryDir = path.join(workspace, 'memory');
+                        try {
+                            const files = await fs.readdir(memoryDir);
+                            for (const file of files) {
+                                if (!file.endsWith('.md'))
+                                    continue;
+                                artifacts.push({
+                                    kind: 'memory-daily',
+                                    workspaceDir: workspace,
+                                    relativePath: `memory/${file}`,
+                                    absolutePath: path.join(memoryDir, file),
+                                    agentIds: [agentId],
+                                    contentType: 'markdown',
+                                });
+                            }
+                        }
+                        catch {
+                            // No memory dir for this agent — skip
+                        }
+                        // Also expose MEMORY.md index
+                        const memoryIndex = path.join(workspace, 'MEMORY.md');
+                        try {
+                            await fs.access(memoryIndex);
+                            artifacts.push({
+                                kind: 'memory-index',
+                                workspaceDir: workspace,
+                                relativePath: 'MEMORY.md',
+                                absolutePath: memoryIndex,
+                                agentIds: [agentId],
+                                contentType: 'markdown',
+                            });
+                        }
+                        catch {
+                            // No MEMORY.md — skip
+                        }
+                    }
+                    return artifacts;
+                },
+            },
+        });
+    },
+});

package/memory-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@psiclawops/hypermem-memory",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "HyperMem memory plugin for OpenClaw \u2014 bridges HyperMem retrieval into the memory slot",
   "type": "module",
   "main": "dist/index.js",
@@ -35,10 +35,12 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "0.9.1"
+    "@psiclawops/hypermem": "0.9.2"
   },
   "devDependencies": {
     "openclaw": "*",

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.