@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/dist/graph/ops.js

@@ -0,0 +1,221 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAllUserIds } from "../lib/sender.js";
+import { log } from "../logger.js";
+const ENTITY_TYPES = ["people", "projects", "organizations", "topics"];
+export function slugify(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+function summarizeMemoryData(data, source) {
+    if (!Array.isArray(data) || data.length === 0)
+        return "";
+    const items = data;
+    if (source === "slack" || source === "google_mail") {
+        const senders = new Map();
+        const messages = [];
+        for (const item of items) {
+            const sender = item.sender;
+            if (sender?.name && sender?.email) {
+                senders.set(String(sender.email), String(sender.name));
+            }
+            if (item.content && messages.length < 5) {
+                messages.push(String(item.content).slice(0, 200));
+            }
+        }
+        const parts = [];
+        if (senders.size > 0) {
+            parts.push(`Participants: ${[...senders.entries()].map(([e, n]) => `${n} <${e}>`).join(", ")}`);
+        }
+        if (messages.length > 0) {
+            parts.push(`Recent messages:\n${messages.join("\n---\n")}`);
+        }
+        return parts.join("\n\n");
+    }
+    if (source === "notion") {
+        const parts = [];
+        for (const item of items.slice(0, 10)) {
+            if (item.__type === "Title" && item.text) {
+                parts.push(`## ${item.text}`);
+            }
+            else if (item.__type === "Markdown" && item.text) {
+                parts.push(String(item.text).slice(0, 300));
+            }
+            else if (item.__type === "Table" && item.table_rows) {
+                const rows = item.table_rows;
+                if (rows[0])
+                    parts.push(`Table: ${rows[0].join(" | ")}`);
+            }
+        }
+        return parts.join("\n");
+    }
+    const parts = [];
+    for (const item of items.slice(0, 10)) {
+        if (item.text) {
+            parts.push(String(item.text).slice(0, 300));
+        }
+    }
+    return parts.join("\n");
+}
+export async function scanMemories(client, stateManager, batchSize, cfg) {
+    const unprocessed = [];
+    const userIds = cfg ? getAllUserIds(cfg) : [undefined];
+    outer: for (const userId of userIds) {
+        for await (const mem of client.listMemories({ userId })) {
+            if (stateManager.isProcessed(mem.resourceId))
+                continue;
+            if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true)
+                continue;
+            if (mem.metadata?.status !== "completed")
+                continue;
+            let summary = "";
+            try {
+                const full = await client.getMemory(mem.resourceId, mem.source, { userId });
+                const data = full.data;
+                const participants = full.participants;
+                const participantLine = participants?.length
+                    ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
+                    : "";
+                const dataSummary = data ? summarizeMemoryData(data, mem.source) : "";
+                summary = [participantLine, dataSummary].filter(Boolean).join("\n\n");
+            }
+            catch {
+                summary = "(content unavailable)";
+            }
+            unprocessed.push({
+                resourceId: mem.resourceId,
+                source: mem.source,
+                title: mem.title,
+                summary: summary.slice(0, 1000),
+            });
+            if (unprocessed.length >= batchSize)
+                break outer;
+        }
+    }
+    return unprocessed;
+}
+export function formatScanResults(memories, processedCount, lastScan) {
+    if (memories.length === 0) {
+        return `No unprocessed memories found. ${processedCount} memories already processed. Last scan: ${lastScan || "never"}`;
+    }
+    const formatted = memories
+        .map((m) => {
+        const lines = [`[${m.source}] ${m.title || "(untitled)"} (id: ${m.resourceId})`];
+        if (m.summary)
+            lines.push(m.summary);
+        return lines.join("\n");
+    })
+        .join("\n\n---\n\n");
+    return `Found ${memories.length} unprocessed memories:\n\n${formatted}`;
+}
+export function writeEntity(workspaceDir, params) {
+    const slug = slugify(params.slug);
+    const dir = path.join(workspaceDir, "memory", params.type);
+    const filePath = path.join(dir, `${slug}.md`);
+    fs.mkdirSync(dir, { recursive: true });
+    // Check for existing file and merge
+    let existingSourceMemories = {};
+    let existingRelationships = [];
+    let hyperspellId = "";
+    if (fs.existsSync(filePath)) {
+        const existing = fs.readFileSync(filePath, "utf-8");
+        const fmMatch = existing.match(/^---\n([\s\S]*?)\n---\n?/);
+        if (fmMatch) {
+            const fmText = fmMatch[1];
+            for (const line of fmText.split("\n")) {
+                const idx = line.indexOf(":");
+                if (idx <= 0)
+                    continue;
+                const key = line.slice(0, idx).trim();
+                const val = line.slice(idx + 1).trim();
+                if (key === "hyperspell_id")
+                    hyperspellId = val;
+                if (key === "source_memories") {
+                    try {
+                        existingSourceMemories = JSON.parse(val);
+                    }
+                    catch { }
+                }
+                if (key === "relationships") {
+                    try {
+                        existingRelationships = JSON.parse(val);
+                    }
+                    catch { }
+                }
+            }
+        }
+    }
+    // Merge source memories
+    const mergedSources = { ...existingSourceMemories };
+    if (params.sourceMemories) {
+        for (const [source, ids] of Object.entries(params.sourceMemories)) {
+            const existing = mergedSources[source] || [];
+            const merged = [...new Set([...existing, ...ids])];
+            mergedSources[source] = merged;
+        }
+    }
+    // Merge relationships
+    const mergedRelationships = [
+        ...new Set([...existingRelationships, ...(params.relationships || [])]),
+    ];
+    // Build frontmatter
+    const fm = {
+        title: params.name,
+        type: params.type.slice(0, -1), // "people" → "person"
+        graph_entity: "true",
+        source_memories: JSON.stringify(mergedSources),
+        last_extracted: new Date().toISOString(),
+    };
+    if (hyperspellId)
+        fm.hyperspell_id = hyperspellId;
+    if (mergedRelationships.length > 0) {
+        fm.relationships = JSON.stringify(mergedRelationships);
+    }
+    if (params.email)
+        fm.email = params.email;
+    if (params.phone)
+        fm.phone = params.phone;
+    if (params.domain)
+        fm.domain = params.domain;
+    // Build body
+    const bodyParts = [`# ${params.name}\n`, params.description];
+    const contactParts = [];
+    if (params.email)
+        contactParts.push(`- Email: ${params.email}`);
+    if (params.phone)
+        contactParts.push(`- Phone: ${params.phone}`);
+    if (params.domain)
+        contactParts.push(`- Domain: ${params.domain}`);
+    if (contactParts.length > 0) {
+        bodyParts.push("\n## Contact\n");
+        bodyParts.push(...contactParts);
+    }
+    if (mergedRelationships.length > 0) {
+        bodyParts.push("\n## Relationships\n");
+        for (const rel of mergedRelationships) {
+            const [relationship, target] = rel.split(":");
+            if (target) {
+                const targetName = target.split("/").pop()?.replace(/-/g, " ") || target;
+                bodyParts.push(`- ${relationship}: [${targetName}](../${target}.md)`);
+            }
+            else {
+                bodyParts.push(`- ${rel}`);
+            }
+        }
+    }
+    // Build file content
+    const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`);
+    const content = `---\n${fmLines.join("\n")}\n---\n${bodyParts.join("\n")}\n`;
+    fs.writeFileSync(filePath, content);
+    log.info(`Wrote entity: ${params.type}/${slug}.md`);
+    return `${params.type}/${slug}.md`;
+}
+export function completeMemories(stateManager, memoryIds) {
+    const newCount = stateManager.markProcessed(memoryIds);
+    stateManager.updateLastScan();
+    stateManager.save();
+    return { newCount, totalCount: stateManager.getProcessedCount() };
+}

package/dist/graph/state.js

@@ -0,0 +1,68 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { log } from "../logger.js";
+const STATE_VERSION = 1;
+const STATE_FILENAME = ".network-state.json";
+export class NetworkStateManager {
+    statePath;
+    state;
+    constructor(workspaceDir) {
+        const memoryDir = path.join(workspaceDir, "memory");
+        fs.mkdirSync(memoryDir, { recursive: true });
+        this.statePath = path.join(memoryDir, STATE_FILENAME);
+        this.state = this.load();
+    }
+    load() {
+        try {
+            if (fs.existsSync(this.statePath)) {
+                const raw = fs.readFileSync(this.statePath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.version === STATE_VERSION) {
+                    return parsed;
+                }
+                log.warn(`Network state version mismatch (got ${parsed.version}, want ${STATE_VERSION}), resetting`);
+            }
+        }
+        catch (err) {
+            log.warn("Failed to load network state, starting fresh", err);
+        }
+        return { processedIds: {}, lastScanAt: null, version: STATE_VERSION };
+    }
+    save() {
+        const tmpPath = this.statePath + ".tmp";
+        try {
+            fs.writeFileSync(tmpPath, JSON.stringify(this.state, null, 2));
+            fs.renameSync(tmpPath, this.statePath);
+        }
+        catch (err) {
+            log.error("Failed to save network state", err);
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { }
+        }
+    }
+    isProcessed(resourceId) {
+        return resourceId in this.state.processedIds;
+    }
+    markProcessed(resourceIds) {
+        let count = 0;
+        const now = new Date().toISOString();
+        for (const id of resourceIds) {
+            if (!(id in this.state.processedIds)) {
+                this.state.processedIds[id] = now;
+                count++;
+            }
+        }
+        return count;
+    }
+    updateLastScan() {
+        this.state.lastScanAt = new Date().toISOString();
+    }
+    getProcessedCount() {
+        return Object.keys(this.state.processedIds).length;
+    }
+    getLastScanAt() {
+        return this.state.lastScanAt;
+    }
+}

package/dist/graph/tools.js

@@ -0,0 +1,87 @@
+import { Type } from "@sinclair/typebox";
+import { getWorkspaceDir } from "../config.js";
+import { log } from "../logger.js";
+import { NetworkStateManager } from "./state.js";
+import { scanMemories, formatScanResults, writeEntity, completeMemories } from "./ops.js";
+const ENTITY_TYPES = ["people", "projects", "organizations", "topics"];
+export function registerNetworkTools(api, client, cfg) {
+    const workspaceDir = getWorkspaceDir();
+    const stateManager = new NetworkStateManager(workspaceDir);
+    api.registerTool({
+        name: "hyperspell_network_scan",
+        label: "Memory Network Scan",
+        description: "Scan Hyperspell memories and return a batch of unprocessed ones with their content summaries. Use this to find new memories that need entity extraction.",
+        parameters: Type.Object({
+            batchSize: Type.Optional(Type.Number({ description: "Max memories to return (default: 20)" })),
+        }),
+        async execute(_toolCallId, params) {
+            const batchSize = params.batchSize ?? cfg.knowledgeGraph.batchSize;
+            try {
+                const memories = await scanMemories(client, stateManager, batchSize, cfg);
+                const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt());
+                return {
+                    content: [{ type: "text", text }],
+                    details: { count: memories.length, memories },
+                };
+            }
+            catch (err) {
+                log.error("network scan failed", err);
+                return {
+                    content: [{ type: "text", text: `Scan failed: ${err instanceof Error ? err.message : String(err)}` }],
+                };
+            }
+        },
+    }, { name: "hyperspell_network_scan" });
+    api.registerTool({
+        name: "hyperspell_network_write",
+        label: "Memory Network Write",
+        description: "Write or update an entity file in the memory network. Creates markdown files in memory/people/, memory/projects/, memory/organizations/, or memory/topics/.",
+        parameters: Type.Object({
+            type: Type.Union(ENTITY_TYPES.map((t) => Type.Literal(t)), {
+                description: "Entity type: people, projects, organizations, or topics",
+            }),
+            slug: Type.String({ description: "URL-safe identifier (lowercase with hyphens, e.g. 'alice-chen')" }),
+            name: Type.String({ description: "Display name of the entity" }),
+            description: Type.String({ description: "Description of the entity" }),
+            relationships: Type.Optional(Type.Array(Type.String(), {
+                description: "Relationships in format 'relationship:type/slug', e.g. 'works-at:organizations/hyperspell'",
+            })),
+            sourceMemories: Type.Optional(Type.Record(Type.String(), Type.Array(Type.String()), {
+                description: "Source memories by provider, e.g. { slack: ['C073WR69EPM'], google_mail: ['19bbe68026553623'] }",
+            })),
+            email: Type.Optional(Type.String({ description: "Email address (for people)" })),
+            phone: Type.Optional(Type.String({ description: "Phone number (for people)" })),
+            domain: Type.Optional(Type.String({ description: "Domain/homepage (for organizations)" })),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const result = writeEntity(workspaceDir, params);
+                return { content: [{ type: "text", text: `Wrote ${result} (${params.name})` }] };
+            }
+            catch (err) {
+                log.error(`network write failed: ${params.type}/${params.slug}`, err);
+                return { content: [{ type: "text", text: `Write failed: ${err instanceof Error ? err.message : String(err)}` }] };
+            }
+        },
+    }, { name: "hyperspell_network_write" });
+    api.registerTool({
+        name: "hyperspell_network_complete",
+        label: "Memory Network Complete",
+        description: "Mark a batch of memory IDs as processed so they won't appear in future scans.",
+        parameters: Type.Object({
+            memoryIds: Type.Array(Type.String(), { description: "List of resource_ids to mark as processed" }),
+        }),
+        async execute(_toolCallId, params) {
+            try {
+                const { newCount, totalCount } = completeMemories(stateManager, params.memoryIds);
+                return {
+                    content: [{ type: "text", text: `Marked ${newCount} new memories as processed (${totalCount} total). Last scan: ${stateManager.getLastScanAt()}` }],
+                };
+            }
+            catch (err) {
+                log.error("network complete failed", err);
+                return { content: [{ type: "text", text: `Complete failed: ${err instanceof Error ? err.message : String(err)}` }] };
+            }
+        },
+    }, { name: "hyperspell_network_complete" });
+}

package/dist/hooks/auto-context.js

@@ -0,0 +1,199 @@
+import { buildScopeFilter, getCanReadScopes, resolveUser, } from "../lib/sender.js";
+import { log } from "../logger.js";
+/**
+ * Memories produced by session-end hooks (auto-trace, emotional-state) are
+ * tagged `source: "openclaw_agent_end"`. The emotional-state hook already has
+ * a dedicated fetch path (`getEmotionalState` + `<hyperspell-emotional-context>`
+ * injection), so those memories should NOT also surface via generic retrieval —
+ * double-injection dilutes results and replays the conversation verbatim.
+ * Exclude them here at the search filter.
+ */
+const EXCLUDE_SESSION_END_FILTER = {
+    source: { $ne: "openclaw_agent_end" },
+};
+function mergeWithExclude(base) {
+    if (!base)
+        return EXCLUDE_SESSION_END_FILTER;
+    return { $and: [base, EXCLUDE_SESSION_END_FILTER] };
+}
+function formatRelativeTime(isoTimestamp) {
+    try {
+        const dt = new Date(isoTimestamp);
+        const now = new Date();
+        const seconds = (now.getTime() - dt.getTime()) / 1000;
+        const minutes = seconds / 60;
+        const hours = seconds / 3600;
+        const days = seconds / 86400;
+        if (minutes < 30)
+            return "just now";
+        if (minutes < 60)
+            return `${Math.floor(minutes)}mins ago`;
+        if (hours < 24)
+            return `${Math.floor(hours)} hrs ago`;
+        if (days < 7)
+            return `${Math.floor(days)}d ago`;
+        const month = dt.toLocaleString("en", { month: "short" });
+        if (dt.getFullYear() === now.getFullYear()) {
+            return `${dt.getDate()} ${month}`;
+        }
+        return `${dt.getDate()} ${month}, ${dt.getFullYear()}`;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Format a list of search results as per-highlight bullets, filtered by relevance threshold.
+ * Returns null if nothing passes the threshold.
+ */
+function formatHighlightBullets(results, maxResults, threshold) {
+    const sections = [];
+    for (const r of results.slice(0, maxResults)) {
+        if ((r.score ?? 0) < threshold)
+            continue;
+        const aboveThreshold = r.highlights.filter((h) => h.score >= threshold);
+        if (aboveThreshold.length === 0)
+            continue;
+        const title = r.title ?? `[${r.source}]`;
+        const bullets = aboveThreshold
+            .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round(h.score * 100)}%]`)
+            .join("\n");
+        sections.push(`### ${title} (resource_id: ${r.resourceId}, source: ${r.source})\n\n${bullets}`);
+    }
+    if (sections.length === 0)
+        return null;
+    return sections.join("\n\n");
+}
+const INTRO = "The following is context from the user's connected sources. Reference it only when relevant to the conversation.";
+const DISCLAIMER = "Use this context naturally when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated.";
+function wrapSingle(body) {
+    return `<hyperspell-context>\n${INTRO}\n\n${body}\n\n${DISCLAIMER}\n</hyperspell-context>`;
+}
+export function buildAutoContextHandler(client, cfg) {
+    return async (event, ctx) => {
+        const prompt = event.prompt;
+        if (!prompt || prompt.length < 5)
+            return;
+        // Multi-user path
+        if (cfg.multiUser) {
+            const resolved = resolveUser(ctx, cfg);
+            return multiUserSearch(client, cfg, prompt, resolved);
+        }
+        // Single-user path — preserves main's highlights + threshold behavior
+        log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`);
+        try {
+            const results = await client.search(prompt, {
+                limit: cfg.maxResults,
+                filter: EXCLUDE_SESSION_END_FILTER,
+            });
+            const formatted = formatHighlightBullets(results, cfg.maxResults, cfg.relevanceThreshold);
+            if (!formatted) {
+                log.debug("auto-context: no relevant memories found");
+                return;
+            }
+            log.debug(`auto-context: injecting ${results.length} memories`);
+            return { prependContext: wrapSingle(formatted) };
+        }
+        catch (err) {
+            log.error("auto-context failed", err);
+            return;
+        }
+    };
+}
+async function multiUserSearch(client, cfg, prompt, resolved) {
+    const multiUser = cfg.multiUser;
+    const isKnownSender = !!resolved?.resolved;
+    const includeShared = multiUser.includeSharedInSearch;
+    // Determine scope filter for the shared-space search based on caller's role.
+    // Unknown senders fall back to least-sensitive scopes; absent scoping config →
+    // filter is undefined → PR #6 behavior preserved.
+    const canRead = multiUser.scoping
+        ? isKnownSender
+            ? getCanReadScopes(resolved, cfg)
+            : ["family", "kid_shared"]
+        : ["*"];
+    const scopeFilter = buildScopeFilter(canRead, resolved?.userId ?? "");
+    log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"} canRead=${JSON.stringify(canRead)}`);
+    // Build parallel searches — personal (known senders only) + shared
+    const personalSearch = isKnownSender
+        ? client.search(prompt, {
+            limit: cfg.maxResults,
+            userId: resolved.userId,
+            filter: EXCLUDE_SESSION_END_FILTER,
+        })
+        : null;
+    // Always search shared for unknown senders, even if includeSharedInSearch is false
+    const sharedLimit = isKnownSender
+        ? Math.ceil(cfg.maxResults / 2)
+        : cfg.maxResults;
+    const sharedSearch = includeShared || !isKnownSender
+        ? client.search(prompt, {
+            limit: sharedLimit,
+            userId: multiUser.sharedUserId,
+            filter: mergeWithExclude(scopeFilter),
+        })
+        : null;
+    const searches = [personalSearch, sharedSearch].filter(Boolean);
+    const settled = await Promise.allSettled(searches);
+    let idx = 0;
+    let personalResults = [];
+    let sharedResults = [];
+    if (personalSearch) {
+        const r = settled[idx++];
+        if (r.status === "fulfilled") {
+            personalResults = r.value;
+        }
+        else {
+            log.error("auto-context: personal search failed", r.reason);
+        }
+    }
+    if (sharedSearch) {
+        const r = settled[idx++];
+        if (r.status === "fulfilled") {
+            sharedResults = r.value;
+        }
+        else {
+            log.error("auto-context: shared search failed", r.reason);
+        }
+    }
+    const sections = [];
+    // User identity preamble
+    if (isKnownSender && resolved) {
+        const contextLine = resolved.context ? ` ${resolved.context}` : "";
+        sections.push(`You are speaking with ${resolved.name}.${contextLine}`);
+    }
+    // Personal section (threshold-filtered per PR #11/#12 format)
+    if (isKnownSender && personalResults.length > 0 && resolved) {
+        const formatted = formatHighlightBullets(personalResults, cfg.maxResults, cfg.relevanceThreshold);
+        if (formatted) {
+            sections.push(`<personal-context>\nMemories from ${resolved.name}'s personal sources and history.\n\n${formatted}\n</personal-context>`);
+        }
+    }
+    // Shared section
+    if (sharedResults.length > 0) {
+        const sharedDisplayLimit = isKnownSender
+            ? Math.ceil(cfg.maxResults / 2)
+            : cfg.maxResults;
+        const formatted = formatHighlightBullets(sharedResults, sharedDisplayLimit, cfg.relevanceThreshold);
+        if (formatted) {
+            sections.push(`<shared-context>\nShared memories available to all users.\n\n${formatted}\n</shared-context>`);
+        }
+    }
+    // If only the identity preamble is present (no memory sections), still inject identity
+    const haveMemorySections = sections.some((s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"));
+    if (!haveMemorySections) {
+        log.debug("auto-context: no relevant memories found");
+        if (isKnownSender && resolved) {
+            const contextLine = resolved.context ? ` ${resolved.context}` : "";
+            return {
+                prependContext: `<hyperspell-context>\nYou are speaking with ${resolved.name}.${contextLine}\n</hyperspell-context>`,
+            };
+        }
+        return;
+    }
+    const totalCount = personalResults.length + sharedResults.length;
+    log.debug(`auto-context: injecting ${totalCount} memories (${personalResults.length} personal, ${sharedResults.length} shared)`);
+    return {
+        prependContext: `<hyperspell-context>\n${sections.join("\n\n")}\n\n${DISCLAIMER}\n</hyperspell-context>`,
+    };
+}