@hyperspell/openclaw-hyperspell 0.1.1 → 0.3.0

package/README.md

@@ -10,9 +10,23 @@ OpenClaw plugin for [Hyperspell](https://hyperspell.com) - Context and memory fo
 openclaw plugins install @hyperspell/openclaw-hyperspell
 ```
 
-## Configuration
+## Quick Start
 
-Add to your `openclaw.json`:
+Run the interactive setup wizard:
+
+```bash
+openclaw openclaw-hyperspell setup
+```
+
+The setup wizard will guide you through:
+1. Creating a Hyperspell account (if you don't have one)
+2. Configuring your API key
+3. Setting up your User ID for multi-tenant memory
+4. Connecting your apps (Notion, Slack, Google Drive, etc.)
+
+## Manual Configuration
+
+Alternatively, add to your `openclaw.json`:
 
 ```json
 {
@@ -22,6 +36,7 @@ Add to your `openclaw.json`:
         "enabled": true,
         "config": {
           "apiKey": "${HYPERSPELL_API_KEY}",
+          "userId": "your-email",
           "autoContext": true
         }
       }
@@ -37,12 +52,26 @@ Or set the environment variable:
 export HYPERSPELL_API_KEY=hs_...
 ```
 
+## CLI Commands
+
+### `openclaw openclaw-hyperspell setup`
+
+Interactive setup wizard that walks you through configuration.
+
+### `openclaw openclaw-hyperspell status`
+
+Check your current configuration and connection status.
+
+### `openclaw openclaw-hyperspell connect`
+
+Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Drive, etc.)
+
 ### Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `apiKey` | string | `${HYPERSPELL_API_KEY}` | Hyperspell API key |
-| `userId` | string | - | User ID to scope searches (for non-JWT API keys) |
+| `userId` | string | - | User ID (can be your email) |
 | `autoContext` | boolean | `true` | Auto-inject relevant memories before each AI turn |
 | `sources` | string | - | Comma-separated sources to search (e.g., `notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
@@ -58,16 +87,6 @@ Search your memories for relevant context.
 /getcontext Q1 budget planning
 ```
 
-### `/connect <source>`
-
-Connect an account to Hyperspell. Opens the OAuth flow in your browser.
-
-```
-/connect notion
-/connect slack
-/connect google_drive
-```
-
 ### `/remember <text>`
 
 Save something to memory.
@@ -95,12 +114,11 @@ This ensures the AI always has access to relevant information from your connecte
 
 ## Available Sources
 
-- `collections` - User-created collections
+- `vault` - User-created memories
 - `notion` - Notion pages and databases
 - `slack` - Slack messages
 - `google_calendar` - Google Calendar events
 - `google_mail` - Gmail messages
 - `google_drive` - Google Drive files
 - `box` - Box files
-- `vault` - Vault documents
 - `web_crawler` - Crawled web pages

package/client.ts

@@ -11,6 +11,11 @@ export type SearchResult = {
   createdAt: string | null
 }
 
+export type SearchWithAnswerResult = {
+  answer: string | null
+  documents: SearchResult[]
+}
+
 export type Integration = {
   id: string
   name: string
@@ -18,6 +23,13 @@ export type Integration = {
   icon: string
 }
 
+export type Connection = {
+  id: string
+  integrationId: string
+  label: string | null
+  provider: HyperspellSource
+}
+
 export class HyperspellClient {
   private client: Hyperspell
   private config: HyperspellConfig
@@ -26,8 +38,9 @@ export class HyperspellClient {
     this.config = config
     this.client = new Hyperspell({
       apiKey: config.apiKey,
+      userID: config.userId,
     })
-    log.info("client initialized")
+    log.info(`client initialized${config.userId ? ` for user ${config.userId}` : ""}`)
   }
 
   async search(
@@ -61,18 +74,89 @@ export class HyperspellClient {
     return results
   }
 
+  async searchRaw(
+    query: string,
+    options?: { limit?: number; sources?: HyperspellSource[] },
+  ): Promise<Record<string, unknown>> {
+    const limit = options?.limit ?? this.config.maxResults
+    const sources =
+      options?.sources ?? (this.config.sources.length > 0 ? this.config.sources : undefined)
+
+    log.debugRequest("memories.search (raw)", { query, limit, sources })
+
+    const response = await this.client.memories.search({
+      query,
+      sources,
+      options: {
+        max_results: limit,
+      },
+    })
+
+    log.debugResponse("memories.search (raw)", { count: response.documents.length })
+
+    return response as unknown as Record<string, unknown>
+  }
+
+  async searchWithAnswer(
+    query: string,
+    options?: { limit?: number; sources?: HyperspellSource[] },
+  ): Promise<SearchWithAnswerResult> {
+    const limit = options?.limit ?? this.config.maxResults
+    const sources =
+      options?.sources ?? (this.config.sources.length > 0 ? this.config.sources : undefined)
+
+    log.debugRequest("memories.search (with answer)", { query, limit, sources })
+
+    const response = await this.client.memories.search({
+      query,
+      sources,
+      answer: true,
+      options: {
+        max_results: limit,
+      },
+    })
+
+    const documents: SearchResult[] = response.documents.map((doc) => ({
+      resourceId: doc.resource_id,
+      title: doc.title ?? null,
+      source: doc.source as HyperspellSource,
+      score: doc.score ?? null,
+      url: doc.metadata?.url as string | null ?? null,
+      createdAt: doc.metadata?.created_at as string | null ?? null,
+    }))
+
+    log.debugResponse("memories.search (with answer)", {
+      count: documents.length,
+      hasAnswer: !!response.answer,
+    })
+
+    return {
+      answer: response.answer ?? null,
+      documents,
+    }
+  }
+
   async addMemory(
     text: string,
-    options?: { title?: string; metadata?: Record<string, string | number | boolean> },
+    options?: {
+      title?: string
+      resourceId?: string
+      collection?: string
+      metadata?: Record<string, string | number | boolean>
+    },
   ): Promise<{ resourceId: string }> {
     log.debugRequest("memories.add", {
       textLength: text.length,
       title: options?.title,
+      resourceId: options?.resourceId,
+      collection: options?.collection,
     })
 
     const result = await this.client.memories.add({
       text,
       title: options?.title,
+      resource_id: options?.resourceId,
+      collection: options?.collection,
       metadata: {
         ...options?.metadata,
         openclaw_source: "command",
@@ -110,4 +194,20 @@ export class HyperspellClient {
       expiresAt: response.expires_at,
     }
   }
+
+  async listConnections(): Promise<Connection[]> {
+    log.debugRequest("connections.list", {})
+
+    const response = await this.client.connections.list()
+
+    const connections: Connection[] = response.connections.map((conn) => ({
+      id: conn.id,
+      integrationId: conn.integration_id,
+      label: conn.label,
+      provider: conn.provider as HyperspellSource,
+    }))
+
+    log.debugResponse("connections.list", { count: connections.length })
+    return connections
+  }
 }