@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/README.md

@@ -35,6 +35,9 @@ Add to your `openclaw.json`:
 ```json
 {
   "plugins": {
+    "slots": {
+      "memory": "openclaw-hyperspell"
+    },
     "entries": {
       "openclaw-hyperspell": {
         "enabled": true,
@@ -43,8 +46,14 @@ Add to your `openclaw.json`:
           "userId": "your-email",
           "autoContext": true,
           "syncMemories": true,
-          "sources": "vault,notion,slack"
+          "sources": "vault,notion,slack",
+          "dreaming": {
+            "enabled": true
+          }
         }
+      },
+      "memory-core": {
+        "enabled": true
       }
     }
   }
@@ -57,6 +66,28 @@ Set the environment variable in `~/.openclaw/.env`:
 HYPERSPELL_API_KEY=hs_...
 ```
 
+### Running alongside Dreaming
+
+OpenClaw's memory slot (`plugins.slots.memory`) is exclusive, but the `memory-core` dreaming engine is an explicit exception: it can sidecar-load alongside the slot owner so Dreaming keeps running while Hyperspell handles remote search and storage.
+
+To enable this, all four settings must be true at once:
+
+| Setting | Value |
+|---|---|
+| `plugins.slots.memory` | `openclaw-hyperspell` |
+| `plugins.entries.openclaw-hyperspell.enabled` | `true` |
+| `plugins.entries.openclaw-hyperspell.config.dreaming.enabled` | `true` |
+| `plugins.entries.memory-core.enabled` | `true` |
+
+The `dreaming.enabled: true` flag on the Hyperspell plugin's config is what tells OpenClaw to load `memory-core` as a sidecar (see `resolveDreamingSidecarEngineId` in OpenClaw's plugin loader). Without it, `memory-core` is treated as a normal memory plugin and the slot policy disables it.
+
+**Two distinct memory tracks:**
+
+- **Hyperspell** — remote, cross-source (Slack, Notion, Drive, Gmail, vault, ...). Runs on every agent turn via `autoContext` and `autoTrace`. Owns the memory slot.
+- **Dreaming** — local, consolidates daily notes and session transcripts into `workspace/MEMORY.md` on cron (light every 6h, deep nightly, REM weekly). Does not read Hyperspell's remote memories. Reads only local files the agent runner writes.
+
+The two systems don't share state at runtime. They can be enabled independently.
+
 ## CLI Commands
 
 ### `openclaw openclaw-hyperspell setup`
@@ -82,6 +113,7 @@ Open the Hyperspell connect page to link your accounts (Notion, Slack, Google Dr
 | `sources` | string | - | Comma-separated sources to search (e.g., `vault,notion,slack`) |
 | `maxResults` | number | `10` | Maximum memories per context injection |
 | `debug` | boolean | `false` | Enable verbose logging |
+| `dreaming.enabled` | boolean | `false` | Allow `memory-core` to sidecar-load so Dreaming can consolidate local session transcripts into `workspace/MEMORY.md`. See [Running alongside Dreaming](#running-alongside-dreaming). |
 
 ## Slash Commands
 
@@ -212,6 +244,10 @@ Enable the graph tools by using `hyperspell_network_scan`, `hyperspell_network_w
 - Enable `debug: true` to see what queries are being made
 - Check that you have memories matching your conversation topics
 
+### Enabling `memory-core` disabled Hyperspell
+- This means `memory-core` was placed in `plugins.slots.memory`. The slot should stay on `openclaw-hyperspell`; `memory-core` rides alongside as a sidecar.
+- Restore: set `plugins.slots.memory = "openclaw-hyperspell"`, set both plugins `enabled: true`, and add `dreaming: { enabled: true }` to the Hyperspell config. See [Running alongside Dreaming](#running-alongside-dreaming).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.

package/dist/client.js

@@ -0,0 +1,341 @@
+import Hyperspell from "hyperspell";
+import { normalizeScope } from "./config.js";
+import { log } from "./logger.js";
+const API_BASE_URL = "https://api.hyperspell.com";
+export class HyperspellClient {
+    client;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.client = new Hyperspell({
+            apiKey: config.apiKey,
+            userID: config.userId,
+        });
+        log.info(`client initialized${config.userId ? ` for user ${config.userId}` : ""}`);
+    }
+    rawHeaders() {
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`,
+        };
+        if (this.config.userId) {
+            headers["X-As-User"] = this.config.userId;
+        }
+        return headers;
+    }
+    requestOptions(userId) {
+        if (!userId)
+            return undefined;
+        return { headers: { "X-As-User": userId } };
+    }
+    async search(query, options) {
+        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,
+            userId: options?.userId,
+            filter: options?.filter,
+        });
+        const response = await this.client.memories.search({
+            query,
+            sources,
+            options: {
+                max_results: limit,
+                ...(options?.after ? { after: options.after } : {}),
+                ...(options?.before ? { before: options.before } : {}),
+                ...(options?.filter ? { filter: options.filter } : {}),
+            },
+        }, this.requestOptions(options?.userId));
+        const results = response.documents.map((doc) => {
+            const raw = doc;
+            return {
+                resourceId: doc.resource_id,
+                title: doc.title ?? null,
+                source: doc.source,
+                score: doc.score ?? null,
+                url: doc.metadata?.url ?? null,
+                createdAt: doc.metadata?.created_at ?? 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, options) {
+        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,
+            userId: options?.userId,
+            filter: options?.filter,
+        });
+        const response = await this.client.memories.search({
+            query,
+            sources,
+            options: {
+                max_results: limit,
+                ...(options?.after ? { after: options.after } : {}),
+                ...(options?.before ? { before: options.before } : {}),
+                ...(options?.filter ? { filter: options.filter } : {}),
+            },
+        }, this.requestOptions(options?.userId));
+        log.debugResponse("memories.search (raw)", {
+            count: response.documents.length,
+        });
+        return response;
+    }
+    async searchWithAnswer(query, options) {
+        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,
+            userId: options?.userId,
+            filter: options?.filter,
+        });
+        const response = await this.client.memories.search({
+            query,
+            sources,
+            answer: true,
+            options: {
+                max_results: limit,
+                ...(options?.filter ? { filter: options.filter } : {}),
+            },
+        }, this.requestOptions(options?.userId));
+        const documents = response.documents.map((doc) => ({
+            resourceId: doc.resource_id,
+            title: doc.title ?? null,
+            source: doc.source,
+            score: doc.score ?? null,
+            url: doc.metadata?.url ?? null,
+            createdAt: doc.metadata?.created_at ?? null,
+            highlights: [],
+        }));
+        log.debugResponse("memories.search (with answer)", {
+            count: documents.length,
+            hasAnswer: !!response.answer,
+        });
+        return {
+            answer: response.answer ?? null,
+            documents,
+        };
+    }
+    async addMemory(text, options) {
+        log.debugRequest("memories.add", {
+            textLength: text.length,
+            title: options?.title,
+            resourceId: options?.resourceId,
+            collection: options?.collection,
+            date: options?.date,
+            userId: options?.userId,
+            scope: options?.scope,
+        });
+        const result = await this.client.memories.add({
+            text,
+            title: options?.title,
+            resource_id: options?.resourceId,
+            collection: options?.collection,
+            date: options?.date,
+            metadata: {
+                openclaw_source: "command",
+                ...options?.metadata,
+                ...(options?.userId ? { openclaw_user: options.userId } : {}),
+                ...(options?.scope
+                    ? { openclaw_scope: normalizeScope(options.scope) }
+                    : {}),
+            },
+        }, this.requestOptions(options?.userId));
+        log.debugResponse("memories.add", { resourceId: result.resource_id });
+        return { resourceId: result.resource_id };
+    }
+    async listIntegrations() {
+        log.debugRequest("integrations.list", {});
+        const response = await this.client.integrations.list();
+        const integrations = response.integrations.map((int) => ({
+            id: int.id,
+            name: int.name,
+            provider: int.provider,
+            icon: int.icon,
+        }));
+        log.debugResponse("integrations.list", { count: integrations.length });
+        return integrations;
+    }
+    async getConnectUrl(integrationId, options) {
+        log.debugRequest("integrations.connect", { integrationId });
+        const response = await this.client.integrations.connect(integrationId, undefined, this.requestOptions(options?.userId));
+        log.debugResponse("integrations.connect", { url: response.url });
+        return {
+            url: response.url,
+            expiresAt: response.expires_at,
+        };
+    }
+    async *listMemories(options) {
+        log.debugRequest("memories.list", {
+            source: options?.source,
+            collection: options?.collection,
+            userId: options?.userId,
+        });
+        const params = {
+            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, this.requestOptions(options?.userId))) {
+            yield {
+                resourceId: memory.resource_id,
+                source: memory.source,
+                title: memory.title ?? null,
+                metadata: (memory.metadata ?? {}),
+            };
+        }
+    }
+    async getMemory(resourceId, source, options) {
+        log.debugRequest("memories.get", { resourceId, source });
+        const response = await this.client.memories.get(resourceId, { source }, this.requestOptions(options?.userId));
+        const raw = response;
+        log.debugResponse("memories.get", { resourceId, hasData: "data" in raw });
+        return raw;
+    }
+    async sendTrace(history, options) {
+        log.debugRequest("sessions.add", {
+            historyLength: history.length,
+            sessionId: options?.sessionId,
+            extract: options?.extract,
+            userId: options?.userId,
+            scope: options?.scope,
+        });
+        const result = await this.client.sessions.add({
+            history,
+            session_id: options?.sessionId,
+            title: options?.title,
+            format: "openclaw",
+            // Cast: SDK 0.35 typing accepts only ["procedure" | "memory"], but the
+            // backend's mood extractor (hyperspell/hyperspell#581) accepts "mood".
+            // Remove this cast once the OpenAPI spec is updated.
+            extract: (options?.extract ?? ["procedure"]),
+            metadata: {
+                openclaw_source: "agent_end",
+                ...options?.metadata,
+                ...(options?.userId ? { openclaw_user: options.userId } : {}),
+                ...(options?.scope
+                    ? { openclaw_scope: normalizeScope(options.scope) }
+                    : {}),
+            },
+        }, this.requestOptions(options?.userId));
+        log.debugResponse("sessions.add", {
+            resourceId: result.resource_id,
+            status: result.status,
+        });
+        return { resourceId: result.resource_id, status: result.status };
+    }
+    async listConnections(options) {
+        log.debugRequest("connections.list", { userId: options?.userId });
+        const response = await this.client.connections.list(this.requestOptions(options?.userId));
+        const connections = response.connections.map((conn) => ({
+            id: conn.id,
+            integrationId: conn.integration_id,
+            label: conn.label,
+            provider: conn.provider,
+        }));
+        log.debugResponse("connections.list", { count: connections.length });
+        return connections;
+    }
+    // -- Emotional State (raw fetch -- not in public SDK) -----------------------
+    async storeEmotionalState(conversation, options) {
+        log.debugRequest("emotional-state.store", {
+            conversationLength: conversation.length,
+            relationshipId: options?.relationshipId,
+        });
+        const body = { conversation };
+        if (options?.sessionId)
+            body.session_id = options.sessionId;
+        if (options?.relationshipId)
+            body.relationship_id = options.relationshipId;
+        if (options?.metadata)
+            body.metadata = options.metadata;
+        const res = await fetch(`${API_BASE_URL}/emotional-state`, {
+            method: "POST",
+            headers: this.rawHeaders(),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`POST /emotional-state failed (${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        const result = {
+            resourceId: data.resource_id,
+            summary: data.summary,
+            extractedAt: data.extracted_at,
+            sessionId: data.session_id ?? null,
+            relationshipId: data.relationship_id ?? null,
+            status: data.status,
+        };
+        log.debugResponse("emotional-state.store", { resourceId: result.resourceId });
+        return result;
+    }
+    async getEmotionalState(relationshipId) {
+        log.debugRequest("emotional-state.get", { relationshipId });
+        const url = new URL(`${API_BASE_URL}/emotional-state`);
+        if (relationshipId)
+            url.searchParams.set("relationship_id", relationshipId);
+        const res = await fetch(url.toString(), {
+            method: "GET",
+            headers: this.rawHeaders(),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`GET /emotional-state failed (${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        if (data === null) {
+            log.debugResponse("emotional-state.get", { found: false });
+            return null;
+        }
+        const result = {
+            resourceId: data.resource_id,
+            summary: data.summary,
+            extractedAt: data.extracted_at,
+            sessionId: data.session_id ?? null,
+            relationshipId: data.relationship_id ?? null,
+        };
+        log.debugResponse("emotional-state.get", { found: true, resourceId: result.resourceId });
+        return result;
+    }
+    async deleteEmotionalState(relationshipId) {
+        log.debugRequest("emotional-state.delete", { relationshipId });
+        const url = new URL(`${API_BASE_URL}/emotional-state`);
+        if (relationshipId)
+            url.searchParams.set("relationship_id", relationshipId);
+        const res = await fetch(url.toString(), {
+            method: "DELETE",
+            headers: this.rawHeaders(),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`DELETE /emotional-state failed (${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        const result = { deletedCount: data.deleted_count };
+        log.debugResponse("emotional-state.delete", result);
+        return result;
+    }
+}