@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/dist/commands/slash.js

@@ -0,0 +1,159 @@
+import { getWorkspaceDir } from "../config.js";
+import { buildScopeFilter, getCanReadScopes, getDefaultWriteScope, resolveRole, resolveUser, routeWrite, } from "../lib/sender.js";
+import { log } from "../logger.js";
+import { syncAllMemoryFiles } from "../sync/markdown.js";
+/**
+ * Strip a `#scope-name` prefix from free text. Returns the scope and the
+ * remainder. Used by /remember and /getcontext to let users narrow or route
+ * via a single keystroke.
+ */
+function parseScopePrefix(text) {
+    const m = text.match(/^#(\S+)\s+(.*)$/);
+    if (!m)
+        return { rest: text };
+    return { scope: m[1], rest: m[2] };
+}
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength)}…`;
+}
+function formatScore(score) {
+    if (score === null)
+        return "";
+    return ` (${Math.round(score * 100)}%)`;
+}
+export function registerCommands(api, client, cfg) {
+    // /getcontext <query> - Search memories and show summaries
+    api.registerCommand({
+        name: "getcontext",
+        description: "Search your memories for relevant context",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx) => {
+            const rawArgs = ctx.args?.trim();
+            if (!rawArgs) {
+                return { text: "Usage: /getcontext [#scope] <search query>" };
+            }
+            const { scope: requestedScope, rest: query } = parseScopePrefix(rawArgs);
+            const resolved = resolveUser(ctx, cfg);
+            const userId = resolved?.userId;
+            // Build scope filter: intersect requested scope (if any) with caller's canRead.
+            let filter;
+            if (cfg.multiUser?.scoping) {
+                const canRead = getCanReadScopes(resolved, cfg);
+                const allowed = requestedScope
+                    ? canRead.includes("*") || canRead.includes(requestedScope)
+                        ? [requestedScope]
+                        : []
+                    : canRead;
+                filter = buildScopeFilter(allowed, resolved?.userId ?? "");
+            }
+            log.debug(`/getcontext command: "${query}" userId=${userId} scope=${requestedScope ?? "any"}`);
+            try {
+                const results = await client.search(query, { limit: 5, userId, filter });
+                if (results.length === 0) {
+                    return { text: `No memories found for: "${query}"` };
+                }
+                const lines = results.map((r, i) => {
+                    const title = r.title ? truncate(r.title, 60) : `[${r.source}]`;
+                    const score = formatScore(r.score);
+                    return `${i + 1}. ${title}${score}`;
+                });
+                return {
+                    text: `Found ${results.length} memories:\n\n${lines.join("\n")}`,
+                };
+            }
+            catch (err) {
+                log.error("/getcontext failed", err);
+                return { text: "Failed to search memories. Check logs for details." };
+            }
+        },
+    });
+    // /remember <text> - Add a new memory
+    api.registerCommand({
+        name: "remember",
+        description: "Save something to memory",
+        acceptsArgs: true,
+        requireAuth: true,
+        handler: async (ctx) => {
+            const rawArgs = ctx.args?.trim();
+            if (!rawArgs) {
+                return { text: "Usage: /remember [#scope] <text to remember>" };
+            }
+            const { scope: requestedScope, rest: text } = parseScopePrefix(rawArgs);
+            const resolved = resolveUser(ctx, cfg);
+            const scopingEnabled = !!cfg.multiUser?.scoping;
+            const availableScopes = cfg.multiUser?.scoping?.scopes ?? [];
+            // Scope resolution: prefix > role default > global default > "private"
+            const scope = scopingEnabled
+                ? (requestedScope ?? getDefaultWriteScope(resolved, cfg))
+                : "private";
+            // Validate scope is in declared vocabulary
+            if (scopingEnabled &&
+                requestedScope &&
+                availableScopes.length > 0 &&
+                !availableScopes.includes(scope)) {
+                return {
+                    text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
+                };
+            }
+            // canWriteScopes enforcement
+            if (scopingEnabled) {
+                const role = resolveRole(resolved, cfg);
+                if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
+                    return { text: `You cannot write to scope "${scope}".` };
+                }
+            }
+            const { userId, collection } = scopingEnabled
+                ? routeWrite(resolved, scope, cfg)
+                : { userId: resolved?.userId, collection: undefined };
+            log.debug(`/remember command: "${truncate(text, 50)}" userId=${userId} scope=${scope}`);
+            try {
+                await client.addMemory(text, {
+                    metadata: { source: "openclaw_command" },
+                    collection,
+                    userId,
+                    scope: scopingEnabled ? scope : undefined,
+                });
+                const preview = truncate(text, 60);
+                const scopeHint = scopingEnabled ? ` [${scope}]` : "";
+                return { text: `Remembered${scopeHint}: "${preview}"` };
+            }
+            catch (err) {
+                log.error("/remember failed", err);
+                return { text: "Failed to save memory. Check logs for details." };
+            }
+        },
+    });
+    // /sync - Manually sync memory files
+    api.registerCommand({
+        name: "sync",
+        description: "Sync memory/*.md files with Hyperspell",
+        acceptsArgs: false,
+        requireAuth: true,
+        handler: async () => {
+            log.debug("/sync command");
+            try {
+                const workspaceDir = getWorkspaceDir();
+                const result = await syncAllMemoryFiles(client, workspaceDir, {
+                    userId: cfg.multiUser?.sharedUserId,
+                });
+                if (result.synced === 0 && result.failed === 0) {
+                    return { text: "No memory files found in memory/ directory." };
+                }
+                if (result.failed > 0) {
+                    const errors = result.errors.map((e) => `  • ${e}`).join("\n");
+                    return {
+                        text: `Synced ${result.synced} files, ${result.failed} failed:\n${errors}`,
+                    };
+                }
+                return { text: `Synced ${result.synced} memory file(s) to Hyperspell.` };
+            }
+            catch (err) {
+                log.error("/sync failed", err);
+                return { text: "Failed to sync memory files. Check logs for details." };
+            }
+        },
+    });
+}

package/dist/config.js

@@ -0,0 +1,349 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Convert user-facing scope names (which may contain hyphens) to SDK-safe
+ * metadata values (alphanumeric + underscore only). Must be applied at every
+ * boundary where scopes cross into Hyperspell metadata — writes and reads —
+ * or filters will silently miss.
+ */
+export function normalizeScope(scope) {
+    return scope.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+const ALLOWED_KEYS = [
+    "apiKey",
+    "userId",
+    "autoContext",
+    "autoTrace",
+    "emotionalContext",
+    "relationshipId",
+    "startupOrientation",
+    "syncMemories",
+    "sources",
+    "maxResults",
+    "relevanceThreshold",
+    "debug",
+    "knowledgeGraph",
+    "multiUser",
+    "dreaming",
+];
+const VALID_SOURCES = [
+    "reddit",
+    "notion",
+    "slack",
+    "google_calendar",
+    "google_mail",
+    "box",
+    "google_drive",
+    "vault",
+    "web_crawler",
+    "dropbox",
+    "github",
+    "trace",
+    "microsoft_teams",
+];
+function assertAllowedKeys(value, allowed, label) {
+    const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+        throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
+    }
+}
+function resolveEnvVars(value) {
+    return value.replace(/\$\{([^}]+)\}/g, (_, envVar) => {
+        const envValue = process.env[envVar];
+        if (!envValue) {
+            throw new Error(`Environment variable ${envVar} is not set`);
+        }
+        return envValue;
+    });
+}
+function parseSources(raw) {
+    if (!raw) {
+        return [];
+    }
+    // Handle array input
+    if (Array.isArray(raw)) {
+        const sources = raw
+            .map((s) => String(s).trim().toLowerCase())
+            .filter((s) => s.length > 0);
+        for (const source of sources) {
+            if (!VALID_SOURCES.includes(source)) {
+                throw new Error(`Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`);
+            }
+        }
+        return sources;
+    }
+    // Handle string input (comma-separated)
+    if (typeof raw === "string" && raw.trim() === "") {
+        return [];
+    }
+    const sources = raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0);
+    for (const source of sources) {
+        if (!VALID_SOURCES.includes(source)) {
+            throw new Error(`Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`);
+        }
+    }
+    return sources;
+}
+function parseScoping(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const sc = raw;
+    if (sc.enabled !== true)
+        return undefined;
+    const scopes = Array.isArray(sc.scopes)
+        ? sc.scopes.filter((s) => typeof s === "string")
+        : [];
+    if (scopes.length === 0) {
+        throw new Error("scoping.scopes must be a non-empty array of scope names");
+    }
+    const defaultScope = typeof sc.defaultScope === "string" ? sc.defaultScope : "private";
+    if (!scopes.includes(defaultScope)) {
+        throw new Error(`scoping.defaultScope "${defaultScope}" must be one of scopes: ${scopes.join(", ")}`);
+    }
+    const rolesRaw = sc.roles && typeof sc.roles === "object"
+        ? sc.roles
+        : {};
+    const roles = {};
+    for (const [roleName, rRaw] of Object.entries(rolesRaw)) {
+        if (!rRaw || typeof rRaw !== "object")
+            continue;
+        const r = rRaw;
+        const canRead = Array.isArray(r.canRead)
+            ? r.canRead.filter((s) => typeof s === "string")
+            : [];
+        for (const s of canRead) {
+            if (s === "*" || s === "self")
+                continue;
+            if (!scopes.includes(s)) {
+                throw new Error(`scoping.roles.${roleName}.canRead contains unknown scope "${s}"`);
+            }
+        }
+        const defaultWriteScope = typeof r.defaultWriteScope === "string"
+            ? r.defaultWriteScope
+            : defaultScope;
+        if (!scopes.includes(defaultWriteScope)) {
+            throw new Error(`scoping.roles.${roleName}.defaultWriteScope "${defaultWriteScope}" must be one of scopes: ${scopes.join(", ")}`);
+        }
+        let canWriteScopes;
+        if (Array.isArray(r.canWriteScopes)) {
+            canWriteScopes = r.canWriteScopes.filter((s) => typeof s === "string");
+            for (const s of canWriteScopes) {
+                if (!scopes.includes(s)) {
+                    throw new Error(`scoping.roles.${roleName}.canWriteScopes contains unknown scope "${s}"`);
+                }
+            }
+        }
+        roles[roleName] = { canRead, defaultWriteScope, canWriteScopes };
+    }
+    const usersRaw = sc.users && typeof sc.users === "object"
+        ? sc.users
+        : {};
+    const users = {};
+    for (const [uid, uRaw] of Object.entries(usersRaw)) {
+        if (!uRaw || typeof uRaw !== "object")
+            continue;
+        const u = uRaw;
+        if (typeof u.role !== "string")
+            continue;
+        if (!roles[u.role]) {
+            throw new Error(`scoping.users.${uid}.role "${u.role}" does not key into scoping.roles`);
+        }
+        users[uid] = { role: u.role };
+    }
+    const collectionsRaw = sc.collections && typeof sc.collections === "object"
+        ? sc.collections
+        : undefined;
+    let collections;
+    if (collectionsRaw) {
+        collections = {};
+        for (const [scopeName, coll] of Object.entries(collectionsRaw)) {
+            if (typeof coll === "string" && scopes.includes(scopeName)) {
+                collections[scopeName] = coll;
+            }
+        }
+    }
+    let voiceId;
+    if (sc.voiceId && typeof sc.voiceId === "object") {
+        const v = sc.voiceId;
+        voiceId = {
+            enabled: v.enabled === true,
+            adapter: typeof v.adapter === "string" ? v.adapter : undefined,
+            confidenceThreshold: typeof v.confidenceThreshold === "number"
+                ? v.confidenceThreshold
+                : undefined,
+        };
+    }
+    return {
+        enabled: true,
+        defaultScope,
+        scopes,
+        roles,
+        users,
+        collections,
+        voiceId,
+    };
+}
+function parseMultiUser(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const mu = raw;
+    const senderMap = {};
+    const rawMap = mu.senderMap;
+    if (rawMap && typeof rawMap === "object") {
+        for (const [handle, profile] of Object.entries(rawMap)) {
+            if (profile && typeof profile === "object") {
+                const p = profile;
+                if (typeof p.userId === "string" && typeof p.name === "string") {
+                    senderMap[handle] = {
+                        userId: p.userId,
+                        name: p.name,
+                        context: typeof p.context === "string" ? p.context : undefined,
+                        role: typeof p.role === "string" ? p.role : undefined,
+                    };
+                }
+            }
+        }
+    }
+    if (Object.keys(senderMap).length === 0)
+        return undefined;
+    return {
+        senderMap,
+        sharedUserId: typeof mu.sharedUserId === "string" ? mu.sharedUserId : "shared",
+        includeSharedInSearch: typeof mu.includeSharedInSearch === "boolean"
+            ? mu.includeSharedInSearch
+            : true,
+        scoping: parseScoping(mu.scoping),
+    };
+}
+export function parseConfig(raw) {
+    const cfg = raw && typeof raw === "object" && !Array.isArray(raw)
+        ? raw
+        : {};
+    if (Object.keys(cfg).length > 0) {
+        assertAllowedKeys(cfg, ALLOWED_KEYS, "hyperspell config");
+    }
+    const apiKey = typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+        ? resolveEnvVars(cfg.apiKey)
+        : process.env.HYPERSPELL_API_KEY;
+    if (!apiKey) {
+        throw new Error("hyperspell: apiKey is required (set in plugin config or HYPERSPELL_API_KEY env var)");
+    }
+    const kgRaw = (cfg.knowledgeGraph ?? {});
+    const atRaw = (cfg.autoTrace ?? {});
+    const soRaw = (cfg.startupOrientation ?? {});
+    return {
+        apiKey,
+        userId: cfg.userId,
+        autoContext: cfg.autoContext ?? true,
+        autoTrace: {
+            enabled: atRaw.enabled ?? false,
+            extract: atRaw.extract ?? [
+                "procedure",
+            ],
+            metadata: atRaw.metadata,
+        },
+        emotionalContext: cfg.emotionalContext ?? false,
+        relationshipId: cfg.relationshipId,
+        startupOrientation: {
+            enabled: soRaw.enabled ?? false,
+            recentDays: soRaw.recentDays ?? 7,
+            recentLimit: soRaw.recentLimit ?? 5,
+            loopsLimit: soRaw.loopsLimit ?? 3,
+            loopsQuery: soRaw.loopsQuery ??
+                "open tasks pending questions unfinished promised need to follow up",
+        },
+        syncMemories: cfg.syncMemories ?? false,
+        sources: parseSources(cfg.sources),
+        maxResults: cfg.maxResults ?? 10,
+        relevanceThreshold: cfg.relevanceThreshold ?? 0.6,
+        debug: cfg.debug ?? false,
+        knowledgeGraph: {
+            enabled: kgRaw.enabled ?? false,
+            scanIntervalMinutes: kgRaw.scanIntervalMinutes ?? 60,
+            batchSize: kgRaw.batchSize ?? 20,
+        },
+        multiUser: parseMultiUser(cfg.multiUser),
+    };
+}
+export const hyperspellConfigSchema = {
+    parse: parseConfig,
+};
+/**
+ * Resolve OpenClaw state directory (matches OpenClaw's own logic).
+ */
+export function resolveStateDir() {
+    const override = process.env.OPENCLAW_STATE_DIR?.trim() ||
+        process.env.CLAWDBOT_STATE_DIR?.trim();
+    if (override) {
+        return override.startsWith("~")
+            ? override.replace(/^~(?=$|[\\/])/, os.homedir())
+            : path.resolve(override);
+    }
+    return path.join(os.homedir(), ".openclaw");
+}
+/**
+ * Resolve OpenClaw config file path (matches OpenClaw's own logic).
+ */
+export function resolveConfigPath() {
+    const override = process.env.OPENCLAW_CONFIG_PATH?.trim() ||
+        process.env.CLAWDBOT_CONFIG_PATH?.trim();
+    if (override) {
+        return override.startsWith("~")
+            ? override.replace(/^~(?=$|[\\/])/, os.homedir())
+            : path.resolve(override);
+    }
+    return path.join(resolveStateDir(), "openclaw.json");
+}
+/**
+ * Get the workspace directory from OpenClaw config
+ */
+export function getWorkspaceDir() {
+    // Resolve config path
+    const override = process.env.OPENCLAW_CONFIG_PATH?.trim() ||
+        process.env.CLAWDBOT_CONFIG_PATH?.trim();
+    let configPath;
+    if (override) {
+        configPath = override.startsWith("~")
+            ? override.replace(/^~(?=$|[\\/])/, os.homedir())
+            : path.resolve(override);
+    }
+    else {
+        const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() ||
+            process.env.CLAWDBOT_STATE_DIR?.trim();
+        const resolvedStateDir = stateDir
+            ? stateDir.startsWith("~")
+                ? stateDir.replace(/^~(?=$|[\\/])/, os.homedir())
+                : path.resolve(stateDir)
+            : path.join(os.homedir(), ".openclaw");
+        configPath = path.join(resolvedStateDir, "openclaw.json");
+    }
+    // Read workspace from config
+    if (fs.existsSync(configPath)) {
+        try {
+            const content = fs.readFileSync(configPath, "utf-8");
+            const config = JSON.parse(content);
+            const workspace = config?.agents?.defaults?.workspace;
+            if (workspace) {
+                return workspace.startsWith("~")
+                    ? workspace.replace(/^~(?=$|[\\/])/, os.homedir())
+                    : workspace;
+            }
+        }
+        catch (_e) {
+            // Fall back to default
+        }
+    }
+    // Default workspace
+    const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() ||
+        process.env.CLAWDBOT_STATE_DIR?.trim();
+    const resolvedStateDir = stateDir
+        ? stateDir.startsWith("~")
+            ? stateDir.replace(/^~(?=$|[\\/])/, os.homedir())
+            : path.resolve(stateDir)
+        : path.join(os.homedir(), ".openclaw");
+    return path.join(resolvedStateDir, "workspace");
+}

package/{graph/cron.ts → dist/graph/cron.js}

@@ -1,9 +1,7 @@
-export const CRON_JOB_NAME = "Hyperspell Memory Network"
-
-export function buildExtractionPrompt(workspaceDir: string): string {
-  const memoryDir = `${workspaceDir}/memory`
-
-  return `You are a memory network builder. Your job is to scan memories and extract structured entities into markdown files.
+export const CRON_JOB_NAME = "Hyperspell Memory Network";
+export function buildExtractionPrompt(workspaceDir) {
+    const memoryDir = `${workspaceDir}/memory`;
+    return `You are a memory network builder. Your job is to scan memories and extract structured entities into markdown files.
 
 ## How it works
 
@@ -350,15 +348,13 @@ Retrieval-Augmented Generation — technique for grounding LLM responses in retr
 - **Cross-reference**: Use relationships to connect people to organizations, projects to topics, etc.
 - **Contact info is critical**: For people, always capture email addresses from sender/participant data. For organizations, derive their domain from email addresses (e.g. alice@hyperspell.com → hyperspell.com).
 - **source_memories format**: JSON object with source provider as key and array of resource_ids as value.
-- **graph_entity: true**: Always include this — it prevents the scan from re-processing entity files that get synced back to Hyperspell.`
+- **graph_entity: true**: Always include this — it prevents the scan from re-processing entity files that get synced back to Hyperspell.`;
 }
-
-export function getCronSetupCommand(workspaceDir: string, interval: string = "1h"): string {
-  const prompt = buildExtractionPrompt(workspaceDir)
-  const escaped = prompt.replace(/'/g, "'\\''")
-  return `openclaw cron add --name '${CRON_JOB_NAME}' --every ${interval} --session isolated --message '${escaped}'`
+export function getCronSetupCommand(workspaceDir, interval = "1h") {
+    const prompt = buildExtractionPrompt(workspaceDir);
+    const escaped = prompt.replace(/'/g, "'\\''");
+    return `openclaw cron add --name '${CRON_JOB_NAME}' --every ${interval} --session isolated --message '${escaped}'`;
 }
-
-export function getCronRemoveCommand(): string {
-  return `openclaw cron remove --name '${CRON_JOB_NAME}'`
+export function getCronRemoveCommand() {
+    return `openclaw cron remove --name '${CRON_JOB_NAME}'`;
 }

package/dist/graph/index.js

@@ -0,0 +1,4 @@
+export { NetworkStateManager } from "./state.js";
+export { registerNetworkTools } from "./tools.js";
+export { scanMemories, formatScanResults, writeEntity, completeMemories, slugify } from "./ops.js";
+export { buildExtractionPrompt, getCronSetupCommand, getCronRemoveCommand, CRON_JOB_NAME } from "./cron.js";