@hyperspell/openclaw-hyperspell 0.5.0 → 0.7.2

package/config.ts

@@ -1,206 +1,273 @@
 export type HyperspellSource =
-  | "collections"
-  | "reddit"
-  | "notion"
-  | "slack"
-  | "google_calendar"
-  | "google_mail"
-  | "box"
-  | "google_drive"
-  | "vault"
-  | "web_crawler"
+	| "collections"
+	| "reddit"
+	| "notion"
+	| "slack"
+	| "google_calendar"
+	| "google_mail"
+	| "box"
+	| "google_drive"
+	| "vault"
+	| "web_crawler";
 
 export type KnowledgeGraphConfig = {
-  enabled: boolean
-  scanIntervalMinutes: number
-  batchSize: number
-}
+	enabled: boolean;
+	scanIntervalMinutes: number;
+	batchSize: number;
+};
+
+export type AutoTraceConfig = {
+	enabled: boolean;
+	extract: Array<"procedure" | "memory" | "mood">;
+	metadata?: Record<string, string | number | boolean>;
+};
 
 export type HyperspellConfig = {
-  apiKey: string
-  userId?: string
-  autoContext: boolean
-  syncMemories: boolean
-  sources: HyperspellSource[]
-  maxResults: number
-  debug: boolean
-  knowledgeGraph: KnowledgeGraphConfig
-}
+	apiKey: string;
+	userId?: string;
+	autoContext: boolean;
+	autoTrace: AutoTraceConfig;
+	syncMemories: boolean;
+	sources: HyperspellSource[];
+	maxResults: number;
+	relevanceThreshold: number;
+	debug: boolean;
+	knowledgeGraph: KnowledgeGraphConfig;
+};
 
 const ALLOWED_KEYS = [
-  "apiKey",
-  "userId",
-  "autoContext",
-  "syncMemories",
-  "sources",
-  "maxResults",
-  "debug",
-  "knowledgeGraph",
-]
+	"apiKey",
+	"userId",
+	"autoContext",
+	"autoTrace",
+	"syncMemories",
+	"sources",
+	"maxResults",
+	"relevanceThreshold",
+	"debug",
+	"knowledgeGraph",
+];
 
 const VALID_SOURCES: HyperspellSource[] = [
-  "collections",
-  "reddit",
-  "notion",
-  "slack",
-  "google_calendar",
-  "google_mail",
-  "box",
-  "google_drive",
-  "vault",
-  "web_crawler",
-]
+	"collections",
+	"reddit",
+	"notion",
+	"slack",
+	"google_calendar",
+	"google_mail",
+	"box",
+	"google_drive",
+	"vault",
+	"web_crawler",
+];
 
 function assertAllowedKeys(
-  value: Record<string, unknown>,
-  allowed: string[],
-  label: string,
+	value: Record<string, unknown>,
+	allowed: string[],
+	label: string,
 ): void {
-  const unknown = Object.keys(value).filter((k) => !allowed.includes(k))
-  if (unknown.length > 0) {
-    throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`)
-  }
+	const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+	if (unknown.length > 0) {
+		throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`);
+	}
 }
 
 function resolveEnvVars(value: string): string {
-  return value.replace(/\$\{([^}]+)\}/g, (_, envVar: string) => {
-    const envValue = process.env[envVar]
-    if (!envValue) {
-      throw new Error(`Environment variable ${envVar} is not set`)
-    }
-    return envValue
-  })
+	return value.replace(/\$\{([^}]+)\}/g, (_, envVar: string) => {
+		const envValue = process.env[envVar];
+		if (!envValue) {
+			throw new Error(`Environment variable ${envVar} is not set`);
+		}
+		return envValue;
+	});
 }
 
 function parseSources(raw: string | string[] | undefined): HyperspellSource[] {
-  if (!raw) {
-    return []
-  }
-
-  // Handle array input
-  if (Array.isArray(raw)) {
-    const sources = raw
-      .map((s) => String(s).trim().toLowerCase())
-      .filter((s) => s.length > 0) as HyperspellSource[]
-
-    for (const source of sources) {
-      if (!VALID_SOURCES.includes(source)) {
-        throw new Error(
-          `Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`,
-        )
-      }
-    }
-
-    return sources
-  }
-
-  // Handle string input (comma-separated)
-  if (typeof raw === "string" && raw.trim() === "") {
-    return []
-  }
-
-  const sources = raw
-    .split(",")
-    .map((s) => s.trim().toLowerCase())
-    .filter((s) => s.length > 0) as HyperspellSource[]
-
-  for (const source of sources) {
-    if (!VALID_SOURCES.includes(source)) {
-      throw new Error(
-        `Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`,
-      )
-    }
-  }
-
-  return sources
+	if (!raw) {
+		return [];
+	}
+
+	// Handle array input
+	if (Array.isArray(raw)) {
+		const sources = raw
+			.map((s) => String(s).trim().toLowerCase())
+			.filter((s) => s.length > 0) as HyperspellSource[];
+
+		for (const source of sources) {
+			if (!VALID_SOURCES.includes(source)) {
+				throw new Error(
+					`Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`,
+				);
+			}
+		}
+
+		return sources;
+	}
+
+	// Handle string input (comma-separated)
+	if (typeof raw === "string" && raw.trim() === "") {
+		return [];
+	}
+
+	const sources = raw
+		.split(",")
+		.map((s) => s.trim().toLowerCase())
+		.filter((s) => s.length > 0) as HyperspellSource[];
+
+	for (const source of sources) {
+		if (!VALID_SOURCES.includes(source)) {
+			throw new Error(
+				`Invalid source "${source}". Valid sources: ${VALID_SOURCES.join(", ")}`,
+			);
+		}
+	}
+
+	return sources;
 }
 
 export function parseConfig(raw: unknown): HyperspellConfig {
-  const cfg =
-    raw && typeof raw === "object" && !Array.isArray(raw)
-      ? (raw as Record<string, unknown>)
-      : {}
-
-  if (Object.keys(cfg).length > 0) {
-    assertAllowedKeys(cfg, ALLOWED_KEYS, "hyperspell config")
-  }
-
-  const apiKey =
-    typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
-      ? resolveEnvVars(cfg.apiKey)
-      : process.env.HYPERSPELL_API_KEY
-
-  if (!apiKey) {
-    throw new Error(
-      "hyperspell: apiKey is required (set in plugin config or HYPERSPELL_API_KEY env var)",
-    )
-  }
-
-  const kgRaw = (cfg.knowledgeGraph ?? {}) as Record<string, unknown>
-
-  return {
-    apiKey,
-    userId: cfg.userId as string | undefined,
-    autoContext: (cfg.autoContext as boolean) ?? true,
-    syncMemories: (cfg.syncMemories as boolean) ?? false,
-    sources: parseSources(cfg.sources as string | string[] | undefined),
-    maxResults: (cfg.maxResults as number) ?? 10,
-    debug: (cfg.debug as boolean) ?? false,
-    knowledgeGraph: {
-      enabled: (kgRaw.enabled as boolean) ?? false,
-      scanIntervalMinutes: (kgRaw.scanIntervalMinutes as number) ?? 60,
-      batchSize: (kgRaw.batchSize as number) ?? 20,
-    },
-  }
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {};
+
+	if (Object.keys(cfg).length > 0) {
+		assertAllowedKeys(cfg, ALLOWED_KEYS, "hyperspell config");
+	}
+
+	const apiKey =
+		typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+			? resolveEnvVars(cfg.apiKey)
+			: process.env.HYPERSPELL_API_KEY;
+
+	if (!apiKey) {
+		throw new Error(
+			"hyperspell: apiKey is required (set in plugin config or HYPERSPELL_API_KEY env var)",
+		);
+	}
+
+	const kgRaw = (cfg.knowledgeGraph ?? {}) as Record<string, unknown>;
+	const atRaw = (cfg.autoTrace ?? {}) as Record<string, unknown>;
+
+	return {
+		apiKey,
+		userId: cfg.userId as string | undefined,
+		autoContext: (cfg.autoContext as boolean) ?? true,
+		autoTrace: {
+			enabled: (atRaw.enabled as boolean) ?? false,
+			extract: (atRaw.extract as Array<"procedure" | "memory" | "mood">) ?? [
+				"procedure",
+			],
+			metadata: atRaw.metadata as
+				| Record<string, string | number | boolean>
+				| undefined,
+		},
+		syncMemories: (cfg.syncMemories as boolean) ?? false,
+		sources: parseSources(cfg.sources as string | string[] | undefined),
+		maxResults: (cfg.maxResults as number) ?? 10,
+		relevanceThreshold: (cfg.relevanceThreshold as number) ?? 0.6,
+		debug: (cfg.debug as boolean) ?? false,
+		knowledgeGraph: {
+			enabled: (kgRaw.enabled as boolean) ?? false,
+			scanIntervalMinutes: (kgRaw.scanIntervalMinutes as number) ?? 60,
+			batchSize: (kgRaw.batchSize as number) ?? 20,
+		},
+	};
 }
 
 export const hyperspellConfigSchema = {
-  parse: parseConfig,
+	parse: parseConfig,
+};
+
+/**
+ * Resolve OpenClaw state directory (matches OpenClaw's own logic).
+ */
+export function resolveStateDir(): string {
+	const { homedir } = require("node:os");
+	const path = require("node:path");
+
+	const override =
+		process.env.OPENCLAW_STATE_DIR?.trim() ||
+		process.env.CLAWDBOT_STATE_DIR?.trim();
+	if (override) {
+		return override.startsWith("~")
+			? override.replace(/^~(?=$|[\\/])/, homedir())
+			: path.resolve(override);
+	}
+	return path.join(homedir(), ".openclaw");
+}
+
+/**
+ * Resolve OpenClaw config file path (matches OpenClaw's own logic).
+ */
+export function resolveConfigPath(): string {
+	const path = require("node:path");
+
+	const override =
+		process.env.OPENCLAW_CONFIG_PATH?.trim() ||
+		process.env.CLAWDBOT_CONFIG_PATH?.trim();
+	if (override) {
+		const { homedir } = require("node:os");
+		return override.startsWith("~")
+			? override.replace(/^~(?=$|[\\/])/, homedir())
+			: path.resolve(override);
+	}
+	return path.join(resolveStateDir(), "openclaw.json");
 }
 
 /**
  * Get the workspace directory from OpenClaw config
  */
 export function getWorkspaceDir(): string {
-  const { homedir } = require("node:os")
-  const fs = require("node:fs")
-  const path = require("node:path")
-
-  // Resolve config path
-  const override = process.env.OPENCLAW_CONFIG_PATH?.trim() || process.env.CLAWDBOT_CONFIG_PATH?.trim()
-  let configPath: string
-  if (override) {
-    configPath = override.startsWith("~")
-      ? override.replace(/^~(?=$|[\\/])/, homedir())
-      : path.resolve(override)
-  } else {
-    const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
-    const resolvedStateDir = stateDir
-      ? (stateDir.startsWith("~") ? stateDir.replace(/^~(?=$|[\\/])/, homedir()) : path.resolve(stateDir))
-      : path.join(homedir(), ".openclaw")
-    configPath = path.join(resolvedStateDir, "openclaw.json")
-  }
-
-  // Read workspace from config
-  if (fs.existsSync(configPath)) {
-    try {
-      const content = fs.readFileSync(configPath, "utf-8")
-      const config = JSON.parse(content)
-      const workspace = config?.agents?.defaults?.workspace
-      if (workspace) {
-        return workspace.startsWith("~")
-          ? workspace.replace(/^~(?=$|[\\/])/, homedir())
-          : workspace
-      }
-    } catch (_e) {
-      // Fall back to default
-    }
-  }
-
-  // Default workspace
-  const stateDir = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim()
-  const resolvedStateDir = stateDir
-    ? (stateDir.startsWith("~") ? stateDir.replace(/^~(?=$|[\\/])/, homedir()) : path.resolve(stateDir))
-    : path.join(homedir(), ".openclaw")
-  return path.join(resolvedStateDir, "workspace")
+	const { homedir } = require("node:os");
+	const fs = require("node:fs");
+	const path = require("node:path");
+
+	// Resolve config path
+	const override =
+		process.env.OPENCLAW_CONFIG_PATH?.trim() ||
+		process.env.CLAWDBOT_CONFIG_PATH?.trim();
+	let configPath: string;
+	if (override) {
+		configPath = override.startsWith("~")
+			? override.replace(/^~(?=$|[\\/])/, homedir())
+			: path.resolve(override);
+	} else {
+		const stateDir =
+			process.env.OPENCLAW_STATE_DIR?.trim() ||
+			process.env.CLAWDBOT_STATE_DIR?.trim();
+		const resolvedStateDir = stateDir
+			? stateDir.startsWith("~")
+				? stateDir.replace(/^~(?=$|[\\/])/, homedir())
+				: path.resolve(stateDir)
+			: path.join(homedir(), ".openclaw");
+		configPath = path.join(resolvedStateDir, "openclaw.json");
+	}
+
+	// Read workspace from config
+	if (fs.existsSync(configPath)) {
+		try {
+			const content = fs.readFileSync(configPath, "utf-8");
+			const config = JSON.parse(content);
+			const workspace = config?.agents?.defaults?.workspace;
+			if (workspace) {
+				return workspace.startsWith("~")
+					? workspace.replace(/^~(?=$|[\\/])/, homedir())
+					: workspace;
+			}
+		} catch (_e) {
+			// Fall back to default
+		}
+	}
+
+	// Default workspace
+	const stateDir =
+		process.env.OPENCLAW_STATE_DIR?.trim() ||
+		process.env.CLAWDBOT_STATE_DIR?.trim();
+	const resolvedStateDir = stateDir
+		? stateDir.startsWith("~")
+			? stateDir.replace(/^~(?=$|[\\/])/, homedir())
+			: path.resolve(stateDir)
+		: path.join(homedir(), ".openclaw");
+	return path.join(resolvedStateDir, "workspace");
 }

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);
+		}
+	};
+}