@supermemory/openclaw-supermemory 1.0.2

package/client.ts

@@ -0,0 +1,205 @@
+import Supermemory from "supermemory"
+import {
+	getRequestIntegrity,
+	sanitizeContent,
+	validateApiKeyFormat,
+	validateContainerTag,
+} from "./lib/validate.js"
+import { log } from "./logger.ts"
+
+export type SearchResult = {
+	id: string
+	content: string
+	memory?: string
+	similarity?: number
+	metadata?: Record<string, unknown>
+}
+
+export type ProfileSearchResult = {
+	memory?: string
+	updatedAt?: string
+	similarity?: number
+	[key: string]: unknown
+}
+
+export type ProfileResult = {
+	static: string[]
+	dynamic: string[]
+	searchResults: ProfileSearchResult[]
+}
+
+function limitText(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, max)}…` : text
+}
+
+export class SupermemoryClient {
+	private client: Supermemory
+	private containerTag: string
+
+	constructor(apiKey: string, containerTag: string) {
+		const keyCheck = validateApiKeyFormat(apiKey)
+		if (!keyCheck.valid) {
+			throw new Error(`invalid API key: ${keyCheck.reason}`)
+		}
+
+		const tagCheck = validateContainerTag(containerTag)
+		if (!tagCheck.valid) {
+			log.warn(`container tag warning: ${tagCheck.reason}`)
+		}
+
+		const integrityHeaders = getRequestIntegrity(apiKey, containerTag)
+
+		this.client = new Supermemory({
+			apiKey,
+			defaultHeaders: integrityHeaders,
+		})
+		this.containerTag = containerTag
+		log.info(`initialized (container: ${containerTag})`)
+	}
+
+	async addMemory(
+		content: string,
+		metadata?: Record<string, string | number | boolean>,
+		customId?: string,
+	): Promise<{ id: string }> {
+		const cleaned = sanitizeContent(content)
+
+		log.debugRequest("add", {
+			contentLength: cleaned.length,
+			customId,
+			metadata,
+		})
+
+		const result = await this.client.add({
+			content: cleaned,
+			containerTag: this.containerTag,
+			...(metadata && { metadata }),
+			...(customId && { customId }),
+		})
+
+		log.debugResponse("add", { id: result.id })
+		return { id: result.id }
+	}
+
+	async search(query: string, limit = 5): Promise<SearchResult[]> {
+		log.debugRequest("search.memories", {
+			query,
+			limit,
+			containerTag: this.containerTag,
+		})
+
+		const response = await this.client.search.memories({
+			q: query,
+			containerTag: this.containerTag,
+			limit,
+		})
+
+		const results: SearchResult[] = (response.results ?? []).map((r) => ({
+			id: r.id,
+			content: r.memory ?? "",
+			memory: r.memory,
+			similarity: r.similarity,
+			metadata: r.metadata ?? undefined,
+		}))
+
+		log.debugResponse("search.memories", { count: results.length })
+		return results
+	}
+
+	async getProfile(query?: string): Promise<ProfileResult> {
+		log.debugRequest("profile", { containerTag: this.containerTag, query })
+
+		const response = await this.client.profile({
+			containerTag: this.containerTag,
+			...(query && { q: query }),
+		})
+
+		log.debugResponse("profile.raw", response)
+
+		const result: ProfileResult = {
+			static: response.profile?.static ?? [],
+			dynamic: response.profile?.dynamic ?? [],
+			searchResults: (response.searchResults?.results ??
+				[]) as ProfileSearchResult[],
+		}
+
+		log.debugResponse("profile", {
+			staticCount: result.static.length,
+			dynamicCount: result.dynamic.length,
+			searchCount: result.searchResults.length,
+		})
+		return result
+	}
+
+	async deleteMemory(id: string): Promise<void> {
+		log.debugRequest("memories.delete", { id })
+		await this.client.memories.delete(id)
+		log.debugResponse("memories.delete", { success: true })
+	}
+
+	async forgetByQuery(
+		query: string,
+	): Promise<{ success: boolean; message: string }> {
+		log.debugRequest("forgetByQuery", { query })
+
+		const results = await this.search(query, 5)
+		if (results.length === 0) {
+			return { success: false, message: "No matching memory found to forget." }
+		}
+
+		const target = results[0]
+		await this.deleteMemory(target.id)
+
+		const preview = limitText(target.content || target.memory || "", 100)
+		return { success: true, message: `Forgot: "${preview}"` }
+	}
+
+	async wipeAllMemories(): Promise<{ deletedCount: number }> {
+		log.debugRequest("wipe", { containerTag: this.containerTag })
+
+		const allIds: string[] = []
+		let page = 1
+
+		while (true) {
+			const response = await this.client.documents.list({
+				containerTags: [this.containerTag],
+				limit: 100,
+				page,
+			})
+
+			if (!response.memories || response.memories.length === 0) break
+
+			for (const doc of response.memories) {
+				if (doc.id) allIds.push(doc.id)
+			}
+
+			if (
+				!response.pagination?.totalPages ||
+				page >= response.pagination.totalPages
+			)
+				break
+			page++
+		}
+
+		if (allIds.length === 0) {
+			log.debug("wipe: no documents found")
+			return { deletedCount: 0 }
+		}
+
+		log.debug(`wipe: found ${allIds.length} documents, deleting in batches`)
+
+		let deletedCount = 0
+		for (let i = 0; i < allIds.length; i += 100) {
+			const batch = allIds.slice(i, i + 100)
+			await this.client.documents.deleteBulk({ ids: batch })
+			deletedCount += batch.length
+		}
+
+		log.debugResponse("wipe", { deletedCount })
+		return { deletedCount }
+	}
+
+	getContainerTag(): string {
+		return this.containerTag
+	}
+}

package/commands/cli.ts

@@ -0,0 +1,96 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { SupermemoryClient } from "../client.ts"
+import type { SupermemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+export function registerCli(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+): void {
+	api.registerCli(
+		// biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+		({ program }: { program: any }) => {
+			const cmd = program
+				.command("supermemory")
+				.description("Supermemory long-term memory commands")
+
+			cmd
+				.command("search")
+				.argument("<query>", "Search query")
+				.option("--limit <n>", "Max results", "5")
+				.action(async (query: string, opts: { limit: string }) => {
+					const limit = Number.parseInt(opts.limit, 10) || 5
+					log.debug(`cli search: query="${query}" limit=${limit}`)
+
+					const results = await client.search(query, limit)
+
+					if (results.length === 0) {
+						console.log("No memories found.")
+						return
+					}
+
+					for (const r of results) {
+						const score = r.similarity
+							? ` (${(r.similarity * 100).toFixed(0)}%)`
+							: ""
+						console.log(`- ${r.content || r.memory || ""}${score}`)
+					}
+				})
+
+			cmd
+				.command("profile")
+				.option("--query <q>", "Optional query to focus the profile")
+				.action(async (opts: { query?: string }) => {
+					log.debug(`cli profile: query="${opts.query ?? "(none)"}"`)
+
+					const profile = await client.getProfile(opts.query)
+
+					if (profile.static.length === 0 && profile.dynamic.length === 0) {
+						console.log("No profile information available yet.")
+						return
+					}
+
+					if (profile.static.length > 0) {
+						console.log("Stable Preferences:")
+						for (const f of profile.static) console.log(`  - ${f}`)
+					}
+
+					if (profile.dynamic.length > 0) {
+						console.log("Recent Context:")
+						for (const f of profile.dynamic) console.log(`  - ${f}`)
+					}
+				})
+
+			cmd
+				.command("wipe")
+				.description("Delete ALL memories for this container tag")
+				.action(async () => {
+					const tag = client.getContainerTag()
+					const readline = await import("node:readline")
+					const rl = readline.createInterface({
+						input: process.stdin,
+						output: process.stdout,
+					})
+
+					const answer = await new Promise<string>((resolve) => {
+						rl.question(
+							`This will permanently delete all memories in "${tag}". Type "yes" to confirm: `,
+							resolve,
+						)
+					})
+					rl.close()
+
+					if (answer.trim().toLowerCase() !== "yes") {
+						console.log("Aborted.")
+						return
+					}
+
+					log.debug(`cli wipe: container="${tag}"`)
+					const result = await client.wipeAllMemories()
+					console.log(`Wiped ${result.deletedCount} memories from "${tag}".`)
+				})
+		},
+		{ commands: ["supermemory"] },
+	)
+}

package/commands/slash.ts

@@ -0,0 +1,80 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { SupermemoryClient } from "../client.ts"
+import type { SupermemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+import { buildDocumentId, detectCategory } from "../memory.ts"
+
+export function registerCommands(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+	getSessionKey: () => string | undefined,
+): void {
+	api.registerCommand({
+		name: "remember",
+		description: "Save something to memory",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const text = ctx.args?.trim()
+			if (!text) {
+				return { text: "Usage: /remember <text to remember>" }
+			}
+
+			log.debug(`/remember command: "${text.slice(0, 50)}"`)
+
+			try {
+				const category = detectCategory(text)
+				const sk = getSessionKey()
+				await client.addMemory(
+					text,
+					{ type: category, source: "openclaw_command" },
+					sk ? buildDocumentId(sk) : undefined,
+				)
+
+				const preview = text.length > 60 ? `${text.slice(0, 60)}…` : text
+				return { text: `Remembered: "${preview}"` }
+			} catch (err) {
+				log.error("/remember failed", err)
+				return { text: "Failed to save memory. Check logs for details." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "recall",
+		description: "Search your memories",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const query = ctx.args?.trim()
+			if (!query) {
+				return { text: "Usage: /recall <search query>" }
+			}
+
+			log.debug(`/recall command: "${query}"`)
+
+			try {
+				const results = await client.search(query, 5)
+
+				if (results.length === 0) {
+					return { text: `No memories found for: "${query}"` }
+				}
+
+				const lines = results.map((r, i) => {
+					const score = r.similarity
+						? ` (${(r.similarity * 100).toFixed(0)}%)`
+						: ""
+					return `${i + 1}. ${r.content || r.memory || ""}${score}`
+				})
+
+				return {
+					text: `Found ${results.length} memories:\n\n${lines.join("\n")}`,
+				}
+			} catch (err) {
+				log.error("/recall failed", err)
+				return { text: "Failed to search memories. Check logs for details." }
+			}
+		},
+	})
+}

package/config.ts

@@ -0,0 +1,99 @@
+import { hostname } from "node:os"
+
+export type CaptureMode = "everything" | "all"
+
+export type SupermemoryConfig = {
+	apiKey: string
+	containerTag: string
+	autoRecall: boolean
+	autoCapture: boolean
+	maxRecallResults: number
+	profileFrequency: number
+	captureMode: CaptureMode
+	debug: boolean
+}
+
+const ALLOWED_KEYS = [
+	"apiKey",
+	"containerTag",
+	"autoRecall",
+	"autoCapture",
+	"maxRecallResults",
+	"profileFrequency",
+	"captureMode",
+	"debug",
+]
+
+function assertAllowedKeys(
+	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(", ")}`)
+	}
+}
+
+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
+	})
+}
+
+function sanitizeTag(raw: string): string {
+	return raw
+		.replace(/[^a-zA-Z0-9_]/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_|_$/g, "")
+}
+
+function defaultContainerTag(): string {
+	return sanitizeTag(`openclaw_${hostname()}`)
+}
+
+export function parseConfig(raw: unknown): SupermemoryConfig {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	if (Object.keys(cfg).length > 0) {
+		assertAllowedKeys(cfg, ALLOWED_KEYS, "supermemory config")
+	}
+
+	const apiKey =
+		typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+			? resolveEnvVars(cfg.apiKey)
+			: process.env.SUPERMEMORY_OPENCLAW_API_KEY
+
+	if (!apiKey) {
+		throw new Error(
+			"supermemory: apiKey is required (set in plugin config or SUPERMEMORY_OPENCLAW_API_KEY env var)",
+		)
+	}
+
+	return {
+		apiKey,
+		containerTag: cfg.containerTag
+			? sanitizeTag(cfg.containerTag as string)
+			: defaultContainerTag(),
+		autoRecall: (cfg.autoRecall as boolean) ?? true,
+		autoCapture: (cfg.autoCapture as boolean) ?? true,
+		maxRecallResults: (cfg.maxRecallResults as number) ?? 10,
+		profileFrequency: (cfg.profileFrequency as number) ?? 50,
+		captureMode:
+			cfg.captureMode === "everything"
+				? ("everything" as const)
+				: ("all" as const),
+		debug: (cfg.debug as boolean) ?? false,
+	}
+}
+
+export const supermemoryConfigSchema = {
+	parse: parseConfig,
+}

package/hooks/capture.ts

@@ -0,0 +1,99 @@
+import type { SupermemoryClient } from "../client.ts"
+import type { SupermemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+import { buildDocumentId } from "../memory.ts"
+
+function getLastTurn(messages: unknown[]): unknown[] {
+	let lastUserIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i]
+		if (
+			msg &&
+			typeof msg === "object" &&
+			(msg as Record<string, unknown>).role === "user"
+		) {
+			lastUserIdx = i
+			break
+		}
+	}
+	return lastUserIdx >= 0 ? messages.slice(lastUserIdx) : messages
+}
+
+export function buildCaptureHandler(
+	client: SupermemoryClient,
+	cfg: SupermemoryConfig,
+	getSessionKey: () => string | undefined,
+) {
+	return async (event: Record<string, unknown>) => {
+		if (
+			!event.success ||
+			!Array.isArray(event.messages) ||
+			event.messages.length === 0
+		)
+			return
+
+		const lastTurn = getLastTurn(event.messages)
+
+		const texts: string[] = []
+		for (const msg of lastTurn) {
+			if (!msg || typeof msg !== "object") continue
+			const msgObj = msg as Record<string, unknown>
+			const role = msgObj.role
+			if (role !== "user" && role !== "assistant") continue
+
+			const content = msgObj.content
+
+			const parts: string[] = []
+
+			if (typeof content === "string") {
+				parts.push(content)
+			} else if (Array.isArray(content)) {
+				for (const block of content) {
+					if (!block || typeof block !== "object") continue
+					const b = block as Record<string, unknown>
+					if (b.type === "text" && typeof b.text === "string") {
+						parts.push(b.text)
+					}
+				}
+			}
+
+			if (parts.length > 0) {
+				texts.push(`[role: ${role}]\n${parts.join("\n")}\n[${role}:end]`)
+			}
+		}
+
+		const captured =
+			cfg.captureMode === "all"
+				? texts
+						.map((t) =>
+							t
+								.replace(
+									/<supermemory-context>[\s\S]*?<\/supermemory-context>\s*/g,
+									"",
+								)
+								.trim(),
+						)
+						.filter((t) => t.length >= 10)
+				: texts
+
+		if (captured.length === 0) return
+
+		const content = captured.join("\n\n")
+		const sk = getSessionKey()
+		const customId = sk ? buildDocumentId(sk) : undefined
+
+		log.debug(
+			`capturing ${captured.length} texts (${content.length} chars) → ${customId ?? "no-session-key"}`,
+		)
+
+		try {
+			await client.addMemory(
+				content,
+				{ source: "openclaw", timestamp: new Date().toISOString() },
+				customId,
+			)
+		} catch (err) {
+			log.error("capture failed", err)
+		}
+	}
+}