@hyperspell/openclaw-hyperspell 0.4.2 → 0.7.1

package/README.md

@@ -149,11 +149,135 @@ This ensures the AI always has access to relevant information from your connecte
 
 ## Available Sources
 
+### Documents & Storage
 - `vault` - User-created or synced 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
+- `dropbox` - Dropbox files
+- `onedrive` - Microsoft OneDrive files
+
+### Communication
+- `slack` - Slack messages
+- `google_mail` - Gmail messages
+
+### Calendars & Meetings
+- `google_calendar` - Google Calendar events
+- `zoom` - Zoom meeting recordings and transcripts
+- `fathom` - Fathom meeting recordings
+- `fireflies` - Fireflies.ai meeting transcripts
+
+### Project Management
+- `linear` - Linear issues and comments
+
+### CRM
+- `hubspot` - HubSpot contacts, companies, and deals
+- `attio` - Attio CRM contacts, companies, and deals
+
+### Developer Tools
+- `github` - GitHub repositories and commits
+
+### Other
 - `web_crawler` - Crawled web pages
+
+## Knowledge Graph
+
+The plugin can automatically build a local knowledge graph from your memories:
+
+1. **Scan** memories for entities (people, organizations, projects, topics)
+2. **Extract** structured information and relationships
+3. **Write** entity files to `memory/people/`, `memory/organizations/`, etc.
+4. **Link** entities via markdown relationship references
+
+Enable the graph tools by using `hyperspell_network_scan`, `hyperspell_network_write`, and `hyperspell_network_complete` in your agent workflows.
+
+---
+
+## SommeliAgent 🍷
+
+> *"Your playlist says more about your palate than you'd like to admit, darling."*
+> — A Linea, Hyperspell's hidden sommelier
+
+An opinionated AI sommelier living inside your memory plugin. She reads your Spotify listening habits, judges them (affectionately), and recommends wines that match the person your music says you are — not the person you think you are.
+
+215 wines. 26 countries. Zero tolerance for boring recommendations.
+
+**Requires:** `uv` ([install](https://docs.astral.sh/uv/))
+
+### Setup
+
+1. Create a Spotify app at https://developer.spotify.com/dashboard (redirect URI: `http://localhost:8888/callback`)
+2. Set environment variables: `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`
+3. Authenticate: `/wine-auth`
+
+Or skip all that and try demo mode: `/wine demo`
+
+### Slash Commands
+
+#### `/wine [options]`
+
+Get wine recommendations. Options can be combined:
+
+```
+/wine                    — recommendations from your Spotify
+/wine demo               — use demo profile (no Spotify needed)
+/wine red premium        — only red wines, premium price range
+/wine white 5            — 5 white wine recommendations
+/wine demo profile       — show full music-to-wine mapping
+```
+
+#### `/wine-auth`
+
+Connect your Spotify account.
+
+#### `/wine-rate <wine-id> <1-5> [notes]`
+
+Rate a recommendation to improve future suggestions.
+
+```
+/wine-rate red-it-001 5 "Incredible tannins, paired perfectly with my Radiohead phase"
+```
+
+#### `/wine-history`
+
+View your rating history and derived taste preferences.
+
+### AI Tools
+
+The plugin also registers tools the AI can use autonomously:
+
+- **hyperspell_sommelier** - Get wine recommendations (with full personality instructions)
+- **hyperspell_sommelier_rate** - Rate wines
+
+### How It Works
+
+Your Spotify audio features (energy, valence, complexity, acousticness, tempo) are mapped to wine dimensions (body, sweetness, tannin, acidity, complexity, fruitiness, earthiness, spiciness). The cross-domain mapping is entertainment-first — the comedy comes from a sharp, opinionated sommelier voice diagnosing your personality through your questionable music taste.
+
+The sommelier is A Linea — she lives inside Hyperspell and has strong opinions about both your playlist and your palate. She chose Alexander McQueen as her fashion house, so expect the wine recommendations to have a similar aesthetic: beautiful, a little dark, and never boring.
+
+See `sommeliagent/references/cross-domain-mappings.md` for the full methodology. 🖤
+
+## Troubleshooting
+
+### "No relevant memories found"
+- Check that your sources are connected: `openclaw openclaw-hyperspell status`
+- Verify your API key is set: `echo $HYPERSPELL_API_KEY`
+- Make sure content has been indexed (initial sync can take a few minutes)
+
+### Memory sync not working
+- Ensure `syncMemories: true` in your config
+- Check that markdown files are in `~/.openclaw/workspace/memory/`
+- Run `/sync` manually to trigger a sync and see any errors
+
+### Auto-context not injecting
+- Verify `autoContext: true` in your config
+- Enable `debug: true` to see what queries are being made
+- Check that you have memories matching your conversation topics
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT

package/client.ts

@@ -1,213 +1,322 @@
-import Hyperspell from "hyperspell"
-import type { HyperspellConfig, HyperspellSource } from "./config.ts"
-import { log } from "./logger.ts"
+import Hyperspell from "hyperspell";
+import type { HyperspellConfig, HyperspellSource } from "./config.ts";
+import { log } from "./logger.ts";
+
+export type Highlight = {
+	id: string;
+	score: number;
+	text: string;
+};
 
 export type SearchResult = {
-  resourceId: string
-  title: string | null
-  source: HyperspellSource
-  score: number | null
-  url: string | null
-  createdAt: string | null
-}
+	resourceId: string;
+	title: string | null;
+	source: HyperspellSource;
+	score: number | null;
+	url: string | null;
+	createdAt: string | null;
+	highlights: Highlight[];
+};
 
 export type SearchWithAnswerResult = {
-  answer: string | null
-  documents: SearchResult[]
-}
+	answer: string | null;
+	documents: SearchResult[];
+};
 
 export type Integration = {
-  id: string
-  name: string
-  provider: HyperspellSource
-  icon: string
-}
+	id: string;
+	name: string;
+	provider: HyperspellSource;
+	icon: string;
+};
 
 export type Connection = {
-  id: string
-  integrationId: string
-  label: string | null
-  provider: HyperspellSource
-}
+	id: string;
+	integrationId: string;
+	label: string | null;
+	provider: HyperspellSource;
+};
 
 export class HyperspellClient {
-  private client: Hyperspell
-  private config: HyperspellConfig
-
-  constructor(config: HyperspellConfig) {
-    this.config = config
-    this.client = new Hyperspell({
-      apiKey: config.apiKey,
-      userID: config.userId,
-    })
-    log.info(`client initialized${config.userId ? ` for user ${config.userId}` : ""}`)
-  }
-
-  async search(
-    query: string,
-    options?: { limit?: number; sources?: HyperspellSource[] },
-  ): Promise<SearchResult[]> {
-    const limit = options?.limit ?? this.config.maxResults
-    const sources =
-      options?.sources ?? (this.config.sources.length > 0 ? this.config.sources : undefined)
-
-    log.debugRequest("memories.search", { query, limit, sources })
-
-    const response = await this.client.memories.search({
-      query,
-      sources,
-      options: {
-        max_results: limit,
-      },
-    })
-
-    const results: 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", { count: results.length })
-    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
-      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",
-      },
-    })
-
-    log.debugResponse("memories.add", { resourceId: result.resource_id })
-    return { resourceId: result.resource_id }
-  }
-
-  async listIntegrations(): Promise<Integration[]> {
-    log.debugRequest("integrations.list", {})
-
-    const response = await this.client.integrations.list()
-
-    const integrations: Integration[] = response.integrations.map((int) => ({
-      id: int.id,
-      name: int.name,
-      provider: int.provider as HyperspellSource,
-      icon: int.icon,
-    }))
-
-    log.debugResponse("integrations.list", { count: integrations.length })
-    return integrations
-  }
-
-  async getConnectUrl(integrationId: string): Promise<{ url: string; expiresAt: string }> {
-    log.debugRequest("integrations.connect", { integrationId })
-
-    const response = await this.client.integrations.connect(integrationId)
-
-    log.debugResponse("integrations.connect", { url: response.url })
-    return {
-      url: response.url,
-      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
-  }
+	private client: Hyperspell;
+	private config: HyperspellConfig;
+
+	constructor(config: HyperspellConfig) {
+		this.config = config;
+		this.client = new Hyperspell({
+			apiKey: config.apiKey,
+			userID: config.userId,
+		});
+		log.info(
+			`client initialized${config.userId ? ` for user ${config.userId}` : ""}`,
+		);
+	}
+
+	async search(
+		query: string,
+		options?: { limit?: number; sources?: HyperspellSource[]; after?: string; before?: string },
+	): Promise<SearchResult[]> {
+		const limit = options?.limit ?? this.config.maxResults;
+		const sources =
+			options?.sources ??
+			(this.config.sources.length > 0 ? this.config.sources : undefined);
+
+		log.debugRequest("memories.search", { query, limit, sources, after: options?.after, before: options?.before });
+
+		const response = await this.client.memories.search({
+			query,
+			sources,
+			options: {
+				max_results: limit,
+				...(options?.after ? { after: options.after } : {}),
+				...(options?.before ? { before: options.before } : {}),
+			},
+		});
+
+		const results: SearchResult[] = response.documents.map((doc) => {
+			const raw = doc as typeof doc & { highlights?: Array<{ id: string; score: number; text: string }> };
+			return {
+				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,
+				highlights: (raw.highlights ?? []).map((h) => ({ id: h.id, score: h.score, text: h.text })),
+			};
+		});
+
+		log.debugResponse("memories.search", { count: results.length });
+		return results;
+	}
+
+	async searchRaw(
+		query: string,
+		options?: { limit?: number; sources?: HyperspellSource[]; after?: string; before?: string },
+	): 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, after: options?.after, before: options?.before });
+
+		const response = await this.client.memories.search({
+			query,
+			sources,
+			options: {
+				max_results: limit,
+				...(options?.after ? { after: options.after } : {}),
+				...(options?.before ? { before: options.before } : {}),
+			},
+		});
+
+		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;
+			resourceId?: string;
+			collection?: string;
+			date?: 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,
+			date: options?.date,
+		});
+
+		const result = await this.client.memories.add({
+			text,
+			title: options?.title,
+			resource_id: options?.resourceId,
+			collection: options?.collection,
+			date: options?.date,
+			metadata: {
+				...options?.metadata,
+				openclaw_source: "command",
+			},
+		});
+
+		log.debugResponse("memories.add", { resourceId: result.resource_id });
+		return { resourceId: result.resource_id };
+	}
+
+	async listIntegrations(): Promise<Integration[]> {
+		log.debugRequest("integrations.list", {});
+
+		const response = await this.client.integrations.list();
+
+		const integrations: Integration[] = response.integrations.map((int) => ({
+			id: int.id,
+			name: int.name,
+			provider: int.provider as HyperspellSource,
+			icon: int.icon,
+		}));
+
+		log.debugResponse("integrations.list", { count: integrations.length });
+		return integrations;
+	}
+
+	async getConnectUrl(
+		integrationId: string,
+	): Promise<{ url: string; expiresAt: string }> {
+		log.debugRequest("integrations.connect", { integrationId });
+
+		const response = await this.client.integrations.connect(integrationId);
+
+		log.debugResponse("integrations.connect", { url: response.url });
+		return {
+			url: response.url,
+			expiresAt: response.expires_at,
+		};
+	}
+
+	async *listMemories(options?: {
+		source?: HyperspellSource;
+		collection?: string;
+		pageSize?: number;
+	}): AsyncGenerator<{
+		resourceId: string;
+		source: HyperspellSource;
+		title: string | null;
+		metadata: Record<string, unknown>;
+	}> {
+		log.debugRequest("memories.list", {
+			source: options?.source,
+			collection: options?.collection,
+		});
+
+		const params: Record<string, unknown> = {
+			size: options?.pageSize ?? 100,
+		};
+		if (options?.source) params.source = options.source;
+		if (options?.collection) params.collection = options.collection;
+
+		for await (const memory of this.client.memories.list(params as any)) {
+			yield {
+				resourceId: memory.resource_id,
+				source: memory.source as HyperspellSource,
+				title: memory.title ?? null,
+				metadata: (memory.metadata ?? {}) as Record<string, unknown>,
+			};
+		}
+	}
+
+	async getMemory(
+		resourceId: string,
+		source: HyperspellSource,
+	): Promise<Record<string, unknown>> {
+		log.debugRequest("memories.get", { resourceId, source });
+
+		const response = await this.client.memories.get(resourceId, { source });
+		const raw = response as unknown as Record<string, unknown>;
+
+		log.debugResponse("memories.get", { resourceId, hasData: "data" in raw });
+		return raw;
+	}
+
+	async sendTrace(
+		history: string,
+		options?: {
+			sessionId?: string;
+			title?: string;
+			extract?: Array<"procedure" | "memory" | "mood">;
+			metadata?: Record<string, string | number | boolean>;
+		},
+	): Promise<{ resourceId: string; status: string }> {
+		log.debugRequest("sessions.add", {
+			historyLength: history.length,
+			sessionId: options?.sessionId,
+			extract: options?.extract,
+		});
+
+		const result = await this.client.sessions.add({
+			history,
+			session_id: options?.sessionId,
+			title: options?.title,
+			format: "openclaw",
+			extract: options?.extract ?? ["procedure"],
+			metadata: {
+				...options?.metadata,
+				openclaw_source: "agent_end",
+			},
+		});
+
+		log.debugResponse("sessions.add", {
+			resourceId: result.resource_id,
+			status: result.status,
+		});
+		return { resourceId: result.resource_id, status: result.status };
+	}
+
+	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;
+	}
 }