@hyperspell/openclaw-hyperspell 0.4.2 → 0.7.1

package/graph/tools.ts

@@ -0,0 +1,117 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HyperspellClient } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { getWorkspaceDir } from "../config.ts"
+import { log } from "../logger.ts"
+import { NetworkStateManager } from "./state.ts"
+import { scanMemories, formatScanResults, writeEntity, completeMemories } from "./ops.ts"
+import type { EntityType, SourceMemories } from "./ops.ts"
+
+const ENTITY_TYPES = ["people", "projects", "organizations", "topics"] as const
+
+export function registerNetworkTools(
+  api: OpenClawPluginApi,
+  client: HyperspellClient,
+  cfg: HyperspellConfig,
+): void {
+  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: string, params: { batchSize?: number }) {
+        const batchSize = params.batchSize ?? cfg.knowledgeGraph.batchSize
+        try {
+          const memories = await scanMemories(client, stateManager, batchSize)
+          const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt())
+          return {
+            content: [{ type: "text" as const, text }],
+            details: { count: memories.length, memories },
+          }
+        } catch (err) {
+          log.error("network scan failed", err)
+          return {
+            content: [{ type: "text" as const, 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: string,
+        params: { type: EntityType; slug: string; name: string; description: string; relationships?: string[]; sourceMemories?: SourceMemories; email?: string; phone?: string; domain?: string },
+      ) {
+        try {
+          const result = writeEntity(workspaceDir, params)
+          return { content: [{ type: "text" as const, text: `Wrote ${result} (${params.name})` }] }
+        } catch (err) {
+          log.error(`network write failed: ${params.type}/${params.slug}`, err)
+          return { content: [{ type: "text" as const, 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: string, params: { memoryIds: string[] }) {
+        try {
+          const { newCount, totalCount } = completeMemories(stateManager, params.memoryIds)
+          return {
+            content: [{ type: "text" as const, 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" as const, text: `Complete failed: ${err instanceof Error ? err.message : String(err)}` }] }
+        }
+      },
+    },
+    { name: "hyperspell_network_complete" },
+  )
+}

package/hooks/auto-context.ts

@@ -26,25 +26,31 @@ function formatRelativeTime(isoTimestamp: string): string {
   }
 }
 
-function formatContext(results: SearchResult[], maxResults: number): string | null {
-  const limited = results.slice(0, maxResults)
+function formatContext(results: SearchResult[], maxResults: number, threshold: number): string | null {
+  const sections: string[] = []
 
-  if (limited.length === 0) return null
+  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 lines = limited.map((r) => {
     const title = r.title ?? `[${r.source}]`
-    const timeStr = r.createdAt ? formatRelativeTime(r.createdAt) : ""
-    const pct = r.score != null ? `[${Math.round(r.score * 100)}%]` : ""
-    const prefix = timeStr ? `[${timeStr}]` : ""
-    return `- ${prefix} ${title} ${pct}`.trim()
-  })
+    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
 
   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."
 
-  return `<hyperspell-context>\n${intro}\n\n## Relevant Memories (with relevance %)\n${lines.join("\n")}\n\n${disclaimer}\n</hyperspell-context>`
+  return `<hyperspell-context>\n${intro}\n\n${sections.join("\n\n")}\n\n${disclaimer}\n</hyperspell-context>`
 }
 
 export function buildAutoContextHandler(
@@ -59,7 +65,7 @@ export function buildAutoContextHandler(
 
     try {
       const results = await client.search(prompt, { limit: cfg.maxResults })
-      const context = formatContext(results, cfg.maxResults)
+      const context = formatContext(results, cfg.maxResults, cfg.relevanceThreshold)
 
       if (!context) {
         log.debug("auto-context: no relevant memories found")

package/hooks/auto-trace.ts

@@ -0,0 +1,127 @@
+import type { HyperspellClient } from "../client.ts";
+import type { HyperspellConfig } from "../config.ts";
+import { log } from "../logger.ts";
+
+type Message = { role?: string; content?: string | unknown };
+
+const MIN_MESSAGES = 3;
+const MIN_CONVERSATION_LENGTH = 100;
+
+/**
+ * Convert event.messages into OpenClaw JSONL format for the trace API.
+ */
+function messagesToJSONL(messages: unknown[], sessionId: string): string {
+	const lines: string[] = [];
+
+	// Session header
+	lines.push(
+		JSON.stringify({
+			type: "session",
+			version: 3,
+			id: sessionId,
+			timestamp: new Date().toISOString(),
+		}),
+	);
+
+	// Message entries
+	for (const raw of messages as Message[]) {
+		if (!raw.role || !raw.content) continue;
+
+		const content =
+			typeof raw.content === "string"
+				? [{ type: "text", text: raw.content }]
+				: Array.isArray(raw.content)
+					? raw.content
+					: [{ type: "text", text: JSON.stringify(raw.content) }];
+
+		const id = crypto.randomUUID().slice(0, 8);
+
+		if (raw.role === "tool" || raw.role === "toolResult") {
+			// Tool results use a different structure
+			lines.push(
+				JSON.stringify({
+					type: "message",
+					id,
+					timestamp: new Date().toISOString(),
+					message: {
+						role: "toolResult",
+						toolCallId: (raw as Record<string, unknown>).toolCallId ?? id,
+						toolName: (raw as Record<string, unknown>).toolName ?? "unknown",
+						content,
+						isError: (raw as Record<string, unknown>).isError ?? false,
+					},
+				}),
+			);
+		} else {
+			lines.push(
+				JSON.stringify({
+					type: "message",
+					id,
+					timestamp: new Date().toISOString(),
+					message: { role: raw.role, content },
+				}),
+			);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Extract and store conversation trace at session end.
+ * Runs on `agent_end` — fire-and-forget.
+ */
+export function buildAutoTraceHandler(
+	client: HyperspellClient,
+	cfg: HyperspellConfig,
+) {
+	return async (event: Record<string, unknown>) => {
+		if (event.success === false) {
+			log.debug("auto-trace: skipping — agent ended with error");
+			return;
+		}
+
+		const messages = event.messages as unknown[] | undefined;
+		if (!messages || messages.length < MIN_MESSAGES) {
+			log.debug(
+				`auto-trace: skipping — too few messages (${messages?.length ?? 0})`,
+			);
+			return;
+		}
+
+		// Quick content length check
+		const estimate = (messages as Message[])
+			.filter((m) => m.content)
+			.reduce((acc, m) => acc + String(m.content).length, 0);
+		if (estimate < MIN_CONVERSATION_LENGTH) {
+			log.debug(
+				`auto-trace: skipping — conversation too short (${estimate} chars)`,
+			);
+			return;
+		}
+
+		const sessionId = (event.sessionId as string) ?? crypto.randomUUID();
+		const history = messagesToJSONL(messages, sessionId);
+
+		// Title from first user message
+		const firstUser = (messages as Message[]).find((m) => m.role === "user");
+		const title = firstUser?.content
+			? String(firstUser.content).slice(0, 80).replace(/\n/g, " ")
+			: undefined;
+
+		try {
+			const result = await client.sendTrace(history, {
+				sessionId,
+				title,
+				extract: cfg.autoTrace.extract,
+				metadata: cfg.autoTrace.metadata,
+			});
+			log.info(
+				`auto-trace: sent ${result.resourceId} (${messages.length} messages)`,
+			);
+		} catch (err) {
+			// Fire-and-forget — never break the session
+			log.error("auto-trace failed", err);
+		}
+	};
+}

package/index.ts

@@ -1,107 +1,135 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { HyperspellClient } from "./client.ts"
 import { registerCommands } from "./commands/slash.ts"
+import { registerWineCommands } from "./commands/wine.ts"
 import { registerCliCommands } from "./commands/setup.ts"
 import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.ts"
 import { buildAutoContextHandler } from "./hooks/auto-context.ts"
+import { buildAutoTraceHandler } from "./hooks/auto-trace.ts"
 import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.ts"
 import { initLogger } from "./logger.ts"
 import { registerRememberTool } from "./tools/remember.ts"
 import { registerSearchTool } from "./tools/search.ts"
+import { registerSommelierTool, registerSommelierRateTool } from "./tools/sommelier.ts"
+import { registerNetworkTools } from "./graph/index.ts"
 
 export default {
-  id: "openclaw-hyperspell",
-  name: "Hyperspell",
-  description: "Hyperspell gives your Molty context and memory from all your existing data",
-  kind: "memory" as const,
-  configSchema: hyperspellConfigSchema,
-
-  register(api: OpenClawPluginApi) {
-    // 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 as Record<string, unknown> | undefined
-    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
-    registerSearchTool(api, client, cfg)
-    registerRememberTool(api, client, cfg)
-
-    // Register auto-context hook
-    if (cfg.autoContext) {
-      const autoContextHandler = buildAutoContextHandler(client, cfg)
-      api.on("before_agent_start", autoContextHandler)
-    }
-
-    // Register memory sync hook
-    if (cfg.syncMemories) {
-      const fileSyncHandler = buildFileSyncHandler(client, cfg)
-      api.on("file_changed", fileSyncHandler)
-    }
-
-    // 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)
-        }
-      },
-      stop: () => {
-        api.logger.info("hyperspell: stopped")
-      },
-    })
-  },
-}
+	id: "openclaw-hyperspell",
+	name: "Hyperspell",
+	description:
+		"Hyperspell gives your Molty context and memory from all your existing data",
+	kind: "memory" as const,
+	configSchema: hyperspellConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		// 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 as Record<string, unknown> | undefined;
+		const hasConfig = rawConfig?.apiKey || process.env.HYPERSPELL_API_KEY;
+
+		// SommeliAgent works independently of Hyperspell config — it just needs uv + Spotify
+		registerSommelierTool(api)
+		registerSommelierRateTool(api)
+		registerWineCommands(api)
+
+		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
+		registerSearchTool(api, client, cfg);
+		registerRememberTool(api, client, cfg);
+
+		// Register auto-context hook
+		if (cfg.autoContext) {
+			const autoContextHandler = buildAutoContextHandler(client, cfg);
+			api.on("before_agent_start", autoContextHandler);
+		}
+
+		// 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);
+				}
+			},
+			stop: () => {
+				api.logger.info("hyperspell: stopped");
+			},
+		});
+	},
+};

package/lib/browser.ts

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

package/lib/run-script.ts

@@ -0,0 +1,32 @@
+import { execFile } from "node:child_process"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const SCRIPTS_DIR = join(__dirname, "..", "sommeliagent", "scripts")
+
+const ALLOWED_SCRIPTS = new Set(["recommend.py", "rate.py", "auth.py", "history.py"])
+
+export function runScript(
+  scriptName: string,
+  args: string[],
+  timeout: number = 30_000,
+): Promise<{ stdout: string; stderr: string }> {
+  if (!ALLOWED_SCRIPTS.has(scriptName)) {
+    return Promise.reject(new Error(`Unknown script: ${scriptName}`))
+  }
+  return new Promise((resolve, reject) => {
+    execFile(
+      "uv",
+      ["run", join(SCRIPTS_DIR, scriptName), ...args],
+      { timeout, maxBuffer: 1024 * 512 },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(`${scriptName} failed: ${stderr || error.message}`))
+        } else {
+          resolve({ stdout, stderr })
+        }
+      },
+    )
+  })
+}