@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/dist/index.js

@@ -0,0 +1,132 @@
+import { HyperspellClient } from "./client.js";
+import { registerCommands } from "./commands/slash.js";
+import { registerCliCommands } from "./commands/setup.js";
+import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.js";
+import { buildAutoContextHandler } from "./hooks/auto-context.js";
+import { buildAutoTraceHandler } from "./hooks/auto-trace.js";
+import { buildEmotionalStateCompactionHandler, buildEmotionalStateFetchHandler, buildEmotionalStateSessionCleanupHandler, buildEmotionalStateStoreHandler, } from "./hooks/emotional-state.js";
+import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.js";
+import { buildStartupOrientationCompactionHandler, buildStartupOrientationHandler, buildStartupOrientationSessionCleanupHandler, } from "./hooks/startup-orientation.js";
+import { initLogger } from "./logger.js";
+import { createRememberToolFactory } from "./tools/remember.js";
+import { createSearchToolFactory } from "./tools/search.js";
+import { registerNetworkTools } from "./graph/index.js";
+export default {
+    id: "openclaw-hyperspell",
+    name: "Hyperspell",
+    description: "Hyperspell gives your Molty context and memory from all your existing data",
+    kind: "memory",
+    configSchema: hyperspellConfigSchema,
+    register(api) {
+        // Register CLI commands (openclaw openclaw-hyperspell setup|status|connect)
+        api.registerCli((ctx) => {
+            registerCliCommands(ctx.program, api.pluginConfig);
+        }, { commands: ["openclaw-hyperspell"] });
+        // Check if configured
+        const rawConfig = api.pluginConfig;
+        const hasConfig = rawConfig?.apiKey || process.env.HYPERSPELL_API_KEY;
+        if (!hasConfig) {
+            api.logger.info("hyperspell: not configured - run 'openclaw openclaw-hyperspell setup'");
+            // Still register slash commands so they show up, but they'll return an error
+            api.registerCommand({
+                name: "getcontext",
+                description: "Search your memories for relevant context",
+                acceptsArgs: true,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
+            api.registerCommand({
+                name: "remember",
+                description: "Save something to memory",
+                acceptsArgs: true,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
+            api.registerCommand({
+                name: "sync",
+                description: "Sync memory/*.md files with Hyperspell",
+                acceptsArgs: false,
+                requireAuth: false,
+                handler: async () => {
+                    return {
+                        text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
+                    };
+                },
+            });
+            return;
+        }
+        const cfg = parseConfig(api.pluginConfig);
+        initLogger(api.logger, cfg.debug);
+        const client = new HyperspellClient(cfg);
+        // Register AI tools (factory pattern for sender context)
+        api.registerTool(createSearchToolFactory(client, cfg), {
+            name: "hyperspell_search",
+        });
+        api.registerTool(createRememberToolFactory(client, cfg), {
+            name: "hyperspell_remember",
+        });
+        // Register emotional context hooks.
+        // - fetch: inject once per session on first turn (cached thereafter)
+        // - compaction: clear cache so the next turn re-injects after trim
+        // - session cleanup: drop Set entry on session end
+        // - store: extract new emotional state from the finished session
+        if (cfg.emotionalContext) {
+            api.on("before_agent_start", buildEmotionalStateFetchHandler(client, cfg));
+            api.on("after_compaction", buildEmotionalStateCompactionHandler());
+            api.on("session_end", buildEmotionalStateSessionCleanupHandler());
+            api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
+        }
+        // Register auto-context hook
+        if (cfg.autoContext) {
+            const autoContextHandler = buildAutoContextHandler(client, cfg);
+            api.on("before_agent_start", autoContextHandler);
+        }
+        // Register startup-orientation hooks: recent-interactions + unfinished-loops
+        // injected once per session on first turn. Lifecycle mirrors emotional-context.
+        if (cfg.startupOrientation.enabled) {
+            api.on("before_agent_start", buildStartupOrientationHandler(client, cfg));
+            api.on("after_compaction", buildStartupOrientationCompactionHandler());
+            api.on("session_end", buildStartupOrientationSessionCleanupHandler());
+        }
+        // Register auto-trace hook (send conversations to Hyperspell on session end)
+        if (cfg.autoTrace.enabled) {
+            api.on("agent_end", buildAutoTraceHandler(client, cfg));
+        }
+        // Register memory sync hook
+        if (cfg.syncMemories) {
+            const fileSyncHandler = buildFileSyncHandler(client, cfg);
+            api.on("file_changed", fileSyncHandler);
+        }
+        // Register memory network tools
+        if (cfg.knowledgeGraph.enabled) {
+            registerNetworkTools(api, client, cfg);
+        }
+        // Register slash commands
+        registerCommands(api, client, cfg);
+        // Register service for lifecycle management
+        api.registerService({
+            id: "openclaw-hyperspell",
+            start: async () => {
+                api.logger.info("hyperspell: connected");
+                // Sync memories on startup if enabled
+                if (cfg.syncMemories) {
+                    const workspaceDir = getWorkspaceDir();
+                    await syncMemoriesOnStartup(client, workspaceDir, {
+                        userId: cfg.multiUser?.sharedUserId,
+                    });
+                }
+            },
+            stop: () => {
+                api.logger.info("hyperspell: stopped");
+            },
+        });
+    },
+};

package/dist/lib/browser.js

@@ -0,0 +1,29 @@
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+export function openInBrowser(url) {
+    return new Promise((resolve, reject) => {
+        let file;
+        let args;
+        switch (platform()) {
+            case "darwin":
+                file = "open";
+                args = [url];
+                break;
+            case "win32":
+                file = "cmd";
+                args = ["/c", "start", "", url];
+                break;
+            default:
+                file = "xdg-open";
+                args = [url];
+        }
+        execFile(file, args, (error) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+}

package/dist/lib/sender.js

@@ -0,0 +1,173 @@
+import { normalizeScope } from "../config.js";
+import { log } from "../logger.js";
+import { getVoiceIdentifier } from "./voice-id.js";
+function matchFromSenderMap(ctx, cfg) {
+    const multiUser = cfg.multiUser;
+    if (!multiUser) {
+        return cfg.userId
+            ? { userId: cfg.userId, name: cfg.userId, resolved: true }
+            : undefined;
+    }
+    // Try direct senderId lookup (slash command contexts)
+    const senderId = ctx?.senderId ??
+        ctx?.requesterSenderId ??
+        undefined;
+    if (senderId && multiUser.senderMap[senderId]) {
+        const profile = multiUser.senderMap[senderId];
+        log.debug(`sender resolved via senderId: ${senderId} -> ${profile.userId}`);
+        return { ...profile, resolved: true };
+    }
+    // Try sessionKey substring matching (longest-first to avoid partial matches)
+    const sessionKey = ctx?.sessionKey;
+    if (sessionKey) {
+        const sortedEntries = Object.entries(multiUser.senderMap).sort(([a], [b]) => b.length - a.length);
+        for (const [handle, profile] of sortedEntries) {
+            if (sessionKey.includes(handle)) {
+                log.debug(`sender resolved via sessionKey: ${handle} -> ${profile.userId}`);
+                return { ...profile, resolved: true };
+            }
+        }
+    }
+    // Fallback: use sharedUserId for unknown senders
+    log.debug("sender unresolved, falling back to sharedUserId");
+    return {
+        userId: multiUser.sharedUserId,
+        name: multiUser.sharedUserId,
+        resolved: false,
+    };
+}
+/**
+ * Synchronous sender resolution from sessionKey + senderMap. Use this for
+ * hooks and tools that don't receive audio — the voice-ID path is skipped.
+ */
+export function resolveUser(ctx, cfg) {
+    return matchFromSenderMap(ctx, cfg);
+}
+/**
+ * Asynchronous sender resolution. Checks voice-ID first (if enabled and
+ * audio is in ctx), then falls back to the synchronous path. Callers that
+ * never receive audio should use `resolveUser` to avoid unnecessary async
+ * overhead.
+ */
+export async function resolveUserAsync(ctx, cfg) {
+    const voiceCfg = cfg.multiUser?.scoping?.voiceId;
+    const audio = ctx?.audio;
+    if (voiceCfg?.enabled && audio && cfg.multiUser) {
+        try {
+            const identifier = getVoiceIdentifier(cfg);
+            const result = await identifier.identify(audio);
+            const threshold = voiceCfg.confidenceThreshold ?? 0.7;
+            if (result && result.confidence >= threshold) {
+                // Find profile for the voice-identified userId
+                for (const profile of Object.values(cfg.multiUser.senderMap)) {
+                    if (profile.userId === result.userId) {
+                        log.debug(`sender resolved via voice: ${result.userId} (conf=${result.confidence.toFixed(2)})`);
+                        return { ...profile, resolved: true };
+                    }
+                }
+            }
+        }
+        catch (err) {
+            log.error("voice-id identification failed", err);
+        }
+    }
+    return matchFromSenderMap(ctx, cfg);
+}
+/**
+ * Get all unique userIds from the multiUser config (for knowledge graph scanning).
+ */
+export function getAllUserIds(cfg) {
+    if (!cfg.multiUser) {
+        return cfg.userId ? [cfg.userId] : [];
+    }
+    const userIds = new Set();
+    for (const profile of Object.values(cfg.multiUser.senderMap)) {
+        userIds.add(profile.userId);
+    }
+    userIds.add(cfg.multiUser.sharedUserId);
+    return [...userIds];
+}
+/**
+ * Resolve the Role for a user. Looks first at the profile-level `role`
+ * override, then at `scoping.users[userId].role`. Returns undefined if
+ * scoping is disabled or the user has no role assignment.
+ */
+export function resolveRole(user, cfg) {
+    const scoping = cfg.multiUser?.scoping;
+    if (!scoping || !user)
+        return undefined;
+    const roleName = user.role ?? scoping.users[user.userId]?.role;
+    if (!roleName)
+        return undefined;
+    return scoping.roles[roleName];
+}
+/**
+ * Readable scopes for this user. If scoping is disabled, returns ["*"] so
+ * `buildScopeFilter` produces no filter and PR #6 behavior is preserved.
+ */
+export function getCanReadScopes(user, cfg) {
+    if (!cfg.multiUser?.scoping)
+        return ["*"];
+    const role = resolveRole(user, cfg);
+    return role?.canRead ?? [];
+}
+/**
+ * Default write scope for this user — explicit param > role default > global default.
+ */
+export function getDefaultWriteScope(user, cfg) {
+    const role = resolveRole(user, cfg);
+    return (role?.defaultWriteScope ??
+        cfg.multiUser?.scoping?.defaultScope ??
+        "private");
+}
+/**
+ * Build a MongoDB-style metadata filter for Hyperspell's `options.filter`.
+ *
+ * Contract:
+ * - `["*"]` (wildcard) → returns `undefined` (no filter).
+ * - `[]` (empty) → returns a **match-nothing** filter, NOT `undefined`. An
+ *   empty `canRead` is a deliberate "no access" signal and must not silently
+ *   return all results.
+ * - Otherwise: `$or` of named-scope clause and (if "self" present) an
+ *   own-user clause keyed by `openclaw_user`.
+ */
+export function buildScopeFilter(canRead, userId) {
+    if (canRead.includes("*"))
+        return undefined;
+    if (canRead.length === 0) {
+        // Deliberate "no access" — match nothing.
+        return { openclaw_scope: "__never__" };
+    }
+    const namedScopes = canRead.filter((s) => s !== "self" && s !== "*");
+    const includeSelf = canRead.includes("self");
+    const clauses = [];
+    if (namedScopes.length > 0) {
+        clauses.push({
+            openclaw_scope: { $in: namedScopes.map((s) => normalizeScope(s)) },
+        });
+    }
+    if (includeSelf && userId) {
+        clauses.push({ openclaw_user: userId });
+    }
+    if (clauses.length === 0) {
+        return { openclaw_scope: "__never__" };
+    }
+    if (clauses.length === 1) {
+        return clauses[0];
+    }
+    return { $or: clauses };
+}
+/**
+ * Route a write: private scope stays in the user's own Hyperspell space
+ * (defense-in-depth); shared scopes go to `sharedUserId` with optional
+ * per-scope collection.
+ */
+export function routeWrite(user, scope, cfg) {
+    const scoping = cfg.multiUser?.scoping;
+    if (scope === "private") {
+        return { userId: user?.userId, collection: undefined };
+    }
+    const sharedUserId = cfg.multiUser?.sharedUserId ?? user?.userId;
+    const collection = scoping?.collections?.[scope];
+    return { userId: sharedUserId, collection };
+}

package/dist/lib/voice-id.js

@@ -0,0 +1,22 @@
+const NO_OP = {
+    async identify() {
+        return null;
+    },
+};
+const registry = new Map();
+/**
+ * Register a voice-ID adapter implementation under a name that can be
+ * referenced from `cfg.multiUser.scoping.voiceId.adapter`. Call this from
+ * downstream code that wants to plug in a real speaker diarization model;
+ * Phase 1 ships with no adapters registered — the no-op is used.
+ */
+export function registerVoiceIdentifier(name, impl) {
+    registry.set(name, impl);
+}
+export function getVoiceIdentifier(cfg) {
+    const name = cfg.multiUser?.scoping?.voiceId?.adapter;
+    if (name && registry.has(name)) {
+        return registry.get(name);
+    }
+    return NO_OP;
+}

package/dist/logger.js

@@ -0,0 +1,32 @@
+let _logger = console;
+let _debug = false;
+export function initLogger(logger, debug) {
+    _logger = logger;
+    _debug = debug;
+}
+export const log = {
+    info: (message, ...args) => {
+        _logger.info(`hyperspell: ${message}`, ...args);
+    },
+    warn: (message, ...args) => {
+        _logger.warn(`hyperspell: ${message}`, ...args);
+    },
+    error: (message, ...args) => {
+        _logger.error(`hyperspell: ${message}`, ...args);
+    },
+    debug: (message, ...args) => {
+        if (_debug) {
+            _logger.debug(`hyperspell: ${message}`, ...args);
+        }
+    },
+    debugRequest: (method, params) => {
+        if (_debug) {
+            _logger.debug(`hyperspell: [${method}] request`, params);
+        }
+    },
+    debugResponse: (method, result) => {
+        if (_debug) {
+            _logger.debug(`hyperspell: [${method}] response`, result);
+        }
+    },
+};

package/dist/sync/markdown.js

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { log } from "../logger.js";
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?/;
+/**
+ * Parse frontmatter from markdown content
+ */
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontmatterText = match[1];
+    const body = content.slice(match[0].length);
+    const frontmatter = {};
+    for (const line of frontmatterText.split("\n")) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex > 0) {
+            const key = line.slice(0, colonIndex).trim();
+            const value = line.slice(colonIndex + 1).trim();
+            frontmatter[key] = value;
+        }
+    }
+    return { frontmatter, body };
+}
+/**
+ * Serialize frontmatter back to string
+ */
+function serializeFrontmatter(frontmatter) {
+    const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${value}`);
+    return `---\n${lines.join("\n")}\n---\n`;
+}
+/**
+ * Read a markdown file and parse its content
+ */
+function readMarkdownFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { frontmatter, body } = parseFrontmatter(content);
+        const title = frontmatter.title || path.basename(filePath, ".md");
+        return {
+            filePath,
+            title,
+            content: body.trim(),
+            hyperspellId: frontmatter.hyperspell_id || null,
+        };
+    }
+    catch (err) {
+        log.error(`Failed to read markdown file: ${filePath}`, err);
+        return null;
+    }
+}
+/**
+ * Update the hyperspell_id in the frontmatter of a markdown file
+ */
+function updateFrontmatterId(filePath, hyperspellId) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const { frontmatter, body } = parseFrontmatter(content);
+        frontmatter.hyperspell_id = hyperspellId;
+        const newContent = serializeFrontmatter(frontmatter) + body;
+        fs.writeFileSync(filePath, newContent);
+        log.debug(`Updated frontmatter in ${filePath} with hyperspell_id: ${hyperspellId}`);
+    }
+    catch (err) {
+        log.error(`Failed to update frontmatter in ${filePath}`, err);
+    }
+}
+/**
+ * Get all markdown files from the memory directory, including subdirectories
+ */
+export function getMemoryFiles(workspaceDir) {
+    const memoryDir = path.join(workspaceDir, "memory");
+    if (!fs.existsSync(memoryDir)) {
+        return [];
+    }
+    const results = [];
+    function walk(dir) {
+        try {
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    walk(fullPath);
+                }
+                else if (entry.name.endsWith(".md")) {
+                    results.push(fullPath);
+                }
+            }
+        }
+        catch (err) {
+            log.error(`Failed to read directory: ${dir}`, err);
+        }
+    }
+    walk(memoryDir);
+    return results;
+}
+/**
+ * Sync a single markdown file to Hyperspell
+ */
+export async function syncMarkdownFile(client, filePath, options) {
+    const file = readMarkdownFile(filePath);
+    if (!file) {
+        return { success: false, error: "Failed to read file" };
+    }
+    if (!file.content) {
+        return { success: false, error: "File has no content" };
+    }
+    try {
+        const result = await client.addMemory(file.content, {
+            title: file.title,
+            resourceId: file.hyperspellId || undefined,
+            collection: "openclaw",
+            metadata: {
+                openclaw_source: "memory_sync",
+                file_path: filePath,
+            },
+            userId: options?.userId,
+        });
+        // Update frontmatter with new resource ID if it changed or was newly created
+        if (result.resourceId !== file.hyperspellId) {
+            updateFrontmatterId(filePath, result.resourceId);
+        }
+        return { success: true, resourceId: result.resourceId };
+    }
+    catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        log.error(`Failed to sync ${filePath}`, err);
+        return { success: false, error: errorMsg };
+    }
+}
+/**
+ * Sync all markdown files in the memory directory
+ */
+export async function syncAllMemoryFiles(client, workspaceDir, options) {
+    const files = getMemoryFiles(workspaceDir);
+    let synced = 0;
+    let failed = 0;
+    const errors = [];
+    for (const filePath of files) {
+        const result = await syncMarkdownFile(client, filePath, { userId: options?.userId });
+        if (result.success) {
+            synced++;
+            log.info(`Synced: ${path.basename(filePath)} -> ${result.resourceId}`);
+        }
+        else {
+            failed++;
+            errors.push(`${path.basename(filePath)}: ${result.error}`);
+        }
+    }
+    return { synced, failed, errors };
+}

package/dist/tools/remember.js

@@ -0,0 +1,97 @@
+import { Type } from "@sinclair/typebox";
+import { getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
+import { log } from "../logger.js";
+export function createRememberToolFactory(client, cfg) {
+    const scopingEnabled = !!cfg.multiUser?.scoping;
+    const availableScopes = cfg.multiUser?.scoping?.scopes ?? [];
+    const scopeDescription = scopingEnabled
+        ? `Privacy scope for this memory. Available: ${availableScopes.join(", ")}. Defaults to the user's role default.`
+        : "Privacy scope (only used when scoping is enabled in config).";
+    return (ctx) => ({
+        name: "hyperspell_remember",
+        label: "Memory Store",
+        description: "Save important information to the user's memory.",
+        parameters: Type.Object({
+            text: Type.String({ description: "Information to remember" }),
+            title: Type.Optional(Type.String({ description: "Optional title for the memory" })),
+            date: Type.Optional(Type.String({ description: "Date of the memory (ISO 8601 or YYYY-MM-DD). Helps ranking and enables date-range filtering. Defaults to now if omitted." })),
+            userId: Type.Optional(Type.String({
+                description: "Store for a specific user or 'shared' for everyone. Omit to store for current sender.",
+            })),
+            scope: Type.Optional(Type.String({ description: scopeDescription })),
+        }),
+        async execute(_toolCallId, params) {
+            const resolved = resolveUser(ctx, cfg);
+            // Scope resolution: explicit param > role default > global default > "private"
+            const scope = params.scope ??
+                (scopingEnabled ? getDefaultWriteScope(resolved, cfg) : "private");
+            // Validate scope is in declared vocabulary (if scoping is enabled)
+            if (scopingEnabled &&
+                availableScopes.length > 0 &&
+                !availableScopes.includes(scope)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
+                        },
+                    ],
+                };
+            }
+            // canWriteScopes enforcement (role-level deny list)
+            if (scopingEnabled) {
+                const role = resolveRole(resolved, cfg);
+                if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `You cannot write to scope "${scope}".`,
+                            },
+                        ],
+                    };
+                }
+            }
+            // Route: explicit userId override takes precedence; otherwise derive from scope
+            let userId;
+            let collection;
+            if (params.userId) {
+                userId = params.userId;
+            }
+            else if (scopingEnabled) {
+                const routed = routeWrite(resolved, scope, cfg);
+                userId = routed.userId;
+                collection = routed.collection;
+            }
+            else {
+                userId = resolved?.userId;
+            }
+            log.debug(`remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId} scope=${scope}`);
+            try {
+                await client.addMemory(params.text, {
+                    title: params.title,
+                    date: params.date,
+                    collection,
+                    metadata: { source: "openclaw_tool" },
+                    userId,
+                    scope: scopingEnabled ? scope : undefined,
+                });
+                const preview = params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text;
+                return {
+                    content: [{ type: "text", text: `Stored: "${preview}"` }],
+                };
+            }
+            catch (err) {
+                log.error("remember tool failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Failed to store memory: ${err instanceof Error ? err.message : String(err)}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}