@hyperspell/openclaw-hyperspell 0.5.0 → 0.7.2

package/index.ts

@@ -1,113 +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 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")
-      },
-    })
-  },
-}
+	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 })
+        }
+      },
+    )
+  })
+}

package/openclaw.plugin.json

@@ -1,88 +1,111 @@
 {
-  "id": "openclaw-hyperspell",
-  "kind": "memory",
-  "uiHints": {
-    "apiKey": {
-      "label": "Hyperspell API Key",
-      "sensitive": true,
-      "placeholder": "hs_...",
-      "help": "Your API key from app.hyperspell.com (or use ${HYPERSPELL_API_KEY})"
-    },
-    "userId": {
-      "label": "User ID",
-      "placeholder": "user_123",
-      "help": "User ID (can be your email)",
-      "advanced": false
-    },
-    "autoContext": {
-      "label": "Auto-Context",
-      "help": "Inject relevant memories before every AI turn",
-      "advanced": true
-    },
-    "sources": {
-      "label": "Sources",
-      "placeholder": "notion,slack,google_drive",
-      "help": "Comma-separated list of sources to search. Leave empty for all sources.",
-      "advanced": true
-    },
-    "maxResults": {
-      "label": "Max Results",
-      "placeholder": "10",
-      "help": "Maximum memories injected into context per turn",
-      "advanced": true
-    },
-    "debug": {
-      "label": "Debug Logging",
-      "help": "Enable verbose debug logs for API calls and responses",
-      "advanced": true
-    },
-    "syncMemories": {
-      "label": "Sync Memory Files",
-      "help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
-      "advanced": true
-    },
-    "knowledgeGraph": {
-      "label": "Memory Network",
-      "help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
-      "advanced": true
-    }
-  },
-  "configSchema": {
-    "type": "object",
-    "additionalProperties": false,
-    "properties": {
-      "apiKey": {
-        "type": "string"
-      },
-      "userId": {
-        "type": "string"
-      },
-      "autoContext": {
-        "type": "boolean"
-      },
-      "sources": {
-        "type": "string"
-      },
-      "maxResults": {
-        "type": "number",
-        "minimum": 1,
-        "maximum": 20
-      },
-      "debug": {
-        "type": "boolean"
-      },
-      "syncMemories": {
-        "type": "boolean"
-      },
-      "knowledgeGraph": {
-        "type": "object",
-        "properties": {
-          "enabled": { "type": "boolean" },
-          "scanIntervalMinutes": { "type": "number", "minimum": 5, "maximum": 1440 },
-          "batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
-        }
-      }
-    },
-    "required": []
-  }
-}
+	"id": "openclaw-hyperspell",
+	"kind": "memory",
+	"uiHints": {
+		"apiKey": {
+			"label": "Hyperspell API Key",
+			"sensitive": true,
+			"placeholder": "hs_...",
+			"help": "Your API key from app.hyperspell.com (or use ${HYPERSPELL_API_KEY})"
+		},
+		"userId": {
+			"label": "User ID",
+			"placeholder": "user_123",
+			"help": "User ID (can be your email)",
+			"advanced": false
+		},
+		"autoContext": {
+			"label": "Auto-Context",
+			"help": "Inject relevant memories before every AI turn",
+			"advanced": true
+		},
+		"autoTrace": {
+			"label": "Auto-Trace",
+			"help": "Automatically send conversation traces to Hyperspell for memory extraction (procedural, mood) at the end of each session",
+			"advanced": true
+		},
+		"sources": {
+			"label": "Sources",
+			"placeholder": "notion,slack,google_drive",
+			"help": "Comma-separated list of sources to search. Leave empty for all sources.",
+			"advanced": true
+		},
+		"maxResults": {
+			"label": "Max Results",
+			"placeholder": "10",
+			"help": "Maximum memories injected into context per turn",
+			"advanced": true
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose debug logs for API calls and responses",
+			"advanced": true
+		},
+		"syncMemories": {
+			"label": "Sync Memory Files",
+			"help": "Automatically sync markdown files in workspace/memory/ to Hyperspell",
+			"advanced": true
+		},
+		"knowledgeGraph": {
+			"label": "Memory Network",
+			"help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
+			"advanced": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"apiKey": {
+				"type": "string"
+			},
+			"userId": {
+				"type": "string"
+			},
+			"autoContext": {
+				"type": "boolean"
+			},
+			"autoTrace": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"extract": {
+						"type": "array",
+						"items": {
+							"type": "string",
+							"enum": ["procedure", "memory", "mood"]
+						}
+					},
+					"metadata": { "type": "object" }
+				}
+			},
+			"sources": {
+				"type": "string"
+			},
+			"maxResults": {
+				"type": "number",
+				"minimum": 1,
+				"maximum": 20
+			},
+			"debug": {
+				"type": "boolean"
+			},
+			"syncMemories": {
+				"type": "boolean"
+			},
+			"knowledgeGraph": {
+				"type": "object",
+				"properties": {
+					"enabled": { "type": "boolean" },
+					"scanIntervalMinutes": {
+						"type": "number",
+						"minimum": 5,
+						"maximum": 1440
+					},
+					"batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
+				}
+			}
+		},
+		"required": []
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.5.0",
+  "version": "0.7.2",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -14,12 +14,13 @@
     "graph/",
     "lib/",
     "types/",
+    "sommeliagent/",
     "openclaw.plugin.json",
     "README.md"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hyperspell/openclaw-hyperspell.git"
+    "url": "git+https://github.com/hyperspell/hyperspell-openclaw.git"
   },
   "keywords": [
     "openclaw",
@@ -27,7 +28,9 @@
     "memory",
     "rag",
     "ai",
-    "plugin"
+    "plugin",
+    "sommelier",
+    "wine"
   ],
   "dependencies": {
     "@clack/prompts": "^1.0.0",
@@ -45,7 +48,8 @@
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "hooks": []
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/sommeliagent/references/cross-domain-mappings.md

@@ -0,0 +1,63 @@
+# Cross-Domain Mapping: Music → Wine
+
+The core thesis: sensory and aesthetic preferences transfer across domains. Someone who seeks complexity in music seeks complexity in wine. Someone drawn to dark, brooding sounds wants wines with tension and structure, not crowd-pleasers.
+
+## Music → Wine Dimension Map
+
+| Music Signal | Wine Dimension | Logic |
+|---|---|---|
+| Tempo / energy | Body / weight | High energy → bold, full-bodied; ambient → light, delicate |
+| Complexity (jazz, prog, classical) | Complexity (terroir-driven, natural wines) | Listeners who tolerate/seek complexity want wines that challenge |
+| Valence (happy vs dark) | Sweetness / dryness spectrum | Bright pop → approachable, off-dry; minor key → dry, tannic, austere |
+| Acoustic vs electronic | Old World vs New World | Organic, analog sound → traditional winemaking; synthetic → modern, tech-forward wines |
+| Obscurity / niche taste | Obscurity of region/varietal | Niche listeners don't want grocery store Cab Sav |
+| Repetition tolerance | Familiarity preference | Loop-heavy listeners → reliable house pours; variety seekers → discovery |
+| Lyrical depth | Label story / terroir narrative | People who care about lyrics care about provenance |
+
+## Mapping Algorithm
+
+### Step 1: Music Profile Aggregation
+
+From Spotify's audio features API, we aggregate across a user's top 50 tracks:
+- **avgValence** (0-1): musical positiveness
+- **avgEnergy** (0-1): intensity and activity
+- **avgDanceability** (0-1): dance suitability
+- **avgAcousticness** (0-1): acoustic vs electronic
+- **avgTempo** (BPM): normalized to 0-1 range (/200)
+- **avgComplexity** (derived): instrumentalness × 0.3 + time signature variety × 0.3 + (1 - danceability) × 0.4
+- **obscurityScore** (derived): 1 - (average track popularity / 100)
+
+### Step 2: Wine Dimension Translation
+
+Each wine dimension is a weighted average of music features:
+
+**Body** = energy × 0.5 + tempo × 0.3 + (1 - acousticness) × 0.2
+**Sweetness** = valence × 0.6 + danceability × 0.3 + (1 - complexity) × 0.1
+**Tannin** = (1 - valence) × 0.4 + complexity × 0.3 + energy × 0.3
+**Acidity** = complexity × 0.4 + (1 - valence) × 0.3 + obscurity × 0.3
+**Complexity** = complexity × 0.5 + obscurity × 0.3 + (1 - danceability) × 0.2
+**Fruitiness** = valence × 0.5 + energy × 0.3 + (1 - complexity) × 0.2
+**Earthiness** = acousticness × 0.4 + complexity × 0.3 + obscurity × 0.3
+**Spiciness** = energy × 0.4 + (1 - valence) × 0.3 + complexity × 0.3
+
+### Step 3: Wine Scoring
+
+Each wine in the database has a profile with the same 8 dimensions. Match score = weighted cosine similarity between target profile and wine profile.
+
+Weights: body (1.5), sweetness (1.2), complexity (1.5), tannin (1.0), acidity (1.0), fruitiness (0.8), earthiness (0.8), spiciness (0.7).
+
+### Step 4: Connection Generation
+
+For each recommended wine, the system identifies which specific music-wine connections are strongest and generates explanations.
+
+## Expansion Signals (Future)
+
+- **Reading history** → intellectual complexity tolerance
+- **Food delivery** → direct cuisine/region pairing data
+- **Time of day / mood** → contextual recommendations
+- **Weather + location** → seasonal suggestions
+- **Instagram aesthetic** → visual preference → label/winemaking philosophy
+
+## Philosophy
+
+The signal doesn't need to be scientifically rigorous. This is entertainment that gets smarter. The delight is in the explanation, not the accuracy. The feedback loop (ratings) quietly builds a genuine cross-domain taste database over time.