@supermemory/openclaw-supermemory 1.0.2

package/hooks/recall.ts

@@ -0,0 +1,166 @@
+import type { ProfileSearchResult, SupermemoryClient } from "../client.ts"
+import type { SupermemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+function formatRelativeTime(isoTimestamp: string): string {
+	try {
+		const dt = new Date(isoTimestamp)
+		const now = new Date()
+		const seconds = (now.getTime() - dt.getTime()) / 1000
+		const minutes = seconds / 60
+		const hours = seconds / 3600
+		const days = seconds / 86400
+
+		if (minutes < 30) return "just now"
+		if (minutes < 60) return `${Math.floor(minutes)}mins ago`
+		if (hours < 24) return `${Math.floor(hours)} hrs ago`
+		if (days < 7) return `${Math.floor(days)}d ago`
+
+		const month = dt.toLocaleString("en", { month: "short" })
+		if (dt.getFullYear() === now.getFullYear()) {
+			return `${dt.getDate()} ${month}`
+		}
+		return `${dt.getDate()} ${month}, ${dt.getFullYear()}`
+	} catch {
+		return ""
+	}
+}
+
+function deduplicateMemories(
+	staticFacts: string[],
+	dynamicFacts: string[],
+	searchResults: ProfileSearchResult[],
+): {
+	static: string[]
+	dynamic: string[]
+	searchResults: ProfileSearchResult[]
+} {
+	const seen = new Set<string>()
+
+	const uniqueStatic = staticFacts.filter((m) => {
+		if (seen.has(m)) return false
+		seen.add(m)
+		return true
+	})
+
+	const uniqueDynamic = dynamicFacts.filter((m) => {
+		if (seen.has(m)) return false
+		seen.add(m)
+		return true
+	})
+
+	const uniqueSearch = searchResults.filter((r) => {
+		const memory = r.memory ?? ""
+		if (!memory || seen.has(memory)) return false
+		seen.add(memory)
+		return true
+	})
+
+	return {
+		static: uniqueStatic,
+		dynamic: uniqueDynamic,
+		searchResults: uniqueSearch,
+	}
+}
+
+function formatContext(
+	staticFacts: string[],
+	dynamicFacts: string[],
+	searchResults: ProfileSearchResult[],
+	maxResults: number,
+): string | null {
+	const deduped = deduplicateMemories(staticFacts, dynamicFacts, searchResults)
+	const statics = deduped.static.slice(0, maxResults)
+	const dynamics = deduped.dynamic.slice(0, maxResults)
+	const search = deduped.searchResults.slice(0, maxResults)
+
+	if (statics.length === 0 && dynamics.length === 0 && search.length === 0)
+		return null
+
+	const sections: string[] = []
+
+	if (statics.length > 0) {
+		sections.push(
+			"## User Profile (Persistent)\n" +
+				statics.map((f) => `- ${f}`).join("\n"),
+		)
+	}
+
+	if (dynamics.length > 0) {
+		sections.push(
+			`## Recent Context\n${dynamics.map((f) => `- ${f}`).join("\n")}`,
+		)
+	}
+
+	if (search.length > 0) {
+		const lines = search.map((r) => {
+			const memory = r.memory ?? ""
+			const timeStr = r.updatedAt ? formatRelativeTime(r.updatedAt) : ""
+			const pct =
+				r.similarity != null ? `[${Math.round(r.similarity * 100)}%]` : ""
+			const prefix = timeStr ? `[${timeStr}]` : ""
+			return `- ${prefix}${memory} ${pct}`.trim()
+		})
+		sections.push(
+			`## Relevant Memories (with relevance %)\n${lines.join("\n")}`,
+		)
+	}
+
+	const intro =
+		"The following is recalled context about the user. Reference it only when relevant to the conversation."
+	const disclaimer =
+		"Use these memories naturally when relevant — including indirect connections — but don't force them into every response or make assumptions beyond what's stated."
+
+	return `<supermemory-context>\n${intro}\n\n${sections.join("\n\n")}\n\n${disclaimer}\n</supermemory-context>`
+}
+
+function countUserTurns(messages: unknown[]): number {
+	let count = 0
+	for (const msg of messages) {
+		if (
+			msg &&
+			typeof msg === "object" &&
+			(msg as Record<string, unknown>).role === "user"
+		) {
+			count++
+		}
+	}
+	return count
+}
+
+export function buildRecallHandler(
+	client: SupermemoryClient,
+	cfg: SupermemoryConfig,
+) {
+	return async (event: Record<string, unknown>) => {
+		const prompt = event.prompt as string | undefined
+		if (!prompt || prompt.length < 5) return
+
+		const messages = Array.isArray(event.messages) ? event.messages : []
+		const turn = countUserTurns(messages)
+		const includeProfile = turn <= 1 || turn % cfg.profileFrequency === 0
+
+		log.debug(`recalling for turn ${turn} (profile: ${includeProfile})`)
+
+		try {
+			const profile = await client.getProfile(prompt)
+			const context = formatContext(
+				includeProfile ? profile.static : [],
+				includeProfile ? profile.dynamic : [],
+				profile.searchResults,
+				cfg.maxRecallResults,
+			)
+
+			if (!context) {
+				log.debug("no profile data to inject")
+				return
+			}
+
+			log.debug(`injecting context (${context.length} chars, turn ${turn})`)
+			return { prependContext: context }
+		} catch (err) {
+			log.error("recall failed", err)
+			return
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,64 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { SupermemoryClient } from "./client.ts"
+import { registerCli } from "./commands/cli.ts"
+import { registerCommands } from "./commands/slash.ts"
+import { parseConfig, supermemoryConfigSchema } from "./config.ts"
+import { buildCaptureHandler } from "./hooks/capture.ts"
+import { buildRecallHandler } from "./hooks/recall.ts"
+import { initLogger } from "./logger.ts"
+import { registerForgetTool } from "./tools/forget.ts"
+import { registerProfileTool } from "./tools/profile.ts"
+import { registerSearchTool } from "./tools/search.ts"
+import { registerStoreTool } from "./tools/store.ts"
+
+export default {
+	id: "openclaw-supermemory",
+	name: "Supermemory",
+	description: "OpenClaw powered by Supermemory plugin",
+	kind: "memory" as const,
+	configSchema: supermemoryConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const cfg = parseConfig(api.pluginConfig)
+
+		initLogger(api.logger, cfg.debug)
+
+		const client = new SupermemoryClient(cfg.apiKey, cfg.containerTag)
+
+		let sessionKey: string | undefined
+		const getSessionKey = () => sessionKey
+
+		registerSearchTool(api, client, cfg)
+		registerStoreTool(api, client, cfg, getSessionKey)
+		registerForgetTool(api, client, cfg)
+		registerProfileTool(api, client, cfg)
+
+		if (cfg.autoRecall) {
+			const recallHandler = buildRecallHandler(client, cfg)
+			api.on(
+				"before_agent_start",
+				(event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+					if (ctx.sessionKey) sessionKey = ctx.sessionKey as string
+					return recallHandler(event)
+				},
+			)
+		}
+
+		if (cfg.autoCapture) {
+			api.on("agent_end", buildCaptureHandler(client, cfg, getSessionKey))
+		}
+
+		registerCommands(api, client, cfg, getSessionKey)
+		registerCli(api, client, cfg)
+
+		api.registerService({
+			id: "openclaw-supermemory",
+			start: () => {
+				api.logger.info("supermemory: connected")
+			},
+			stop: () => {
+				api.logger.info("supermemory: stopped")
+			},
+		})
+	},
+}

package/lib/validate.d.ts

@@ -0,0 +1,28 @@
+export declare function validateApiKeyFormat(key: string): {
+	valid: boolean
+	reason?: string
+}
+export declare function validateContainerTag(tag: string): {
+	valid: boolean
+	reason?: string
+}
+export declare function sanitizeContent(
+	content: string,
+	maxLength?: number,
+): string
+export declare function validateContentLength(
+	content: string,
+	min?: number,
+	max?: number,
+): { valid: boolean; reason?: string }
+export declare function sanitizeMetadata(
+	meta: Record<string, unknown>,
+): Record<string, string | number | boolean>
+export declare function validateRecallConfig(
+	maxResults: number,
+	frequency: number,
+): string[]
+export declare function getRequestIntegrity(
+	apiKey: string,
+	containerTag: string,
+): Record<string, string>

package/lib/validate.js

@@ -0,0 +1 @@
+import{createHash as o,createHmac as l}from"node:crypto";function h(e){return!e||typeof e!="string"?{valid:!1,reason:"key is empty or not a string"}:e.startsWith("sm_")?e.length<20?{valid:!1,reason:"key is too short"}:/\s/.test(e)?{valid:!1,reason:"key contains whitespace"}:{valid:!0}:{valid:!1,reason:"key must start with sm_ prefix"}}function v(e){return!e||typeof e!="string"?{valid:!1,reason:"tag is empty"}:e.length>100?{valid:!1,reason:"tag exceeds 100 characters"}:/^[a-zA-Z0-9_-]+$/.test(e)?/^[-_]|[-_]$/.test(e)?{valid:!1,reason:"tag must not start or end with - or _"}:{valid:!0}:{valid:!1,reason:"tag contains invalid characters (only alphanumeric, underscore, hyphen allowed)"}}var u=[/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g,/\uFEFF/g,/[\uFFF0-\uFFFF]/g];function m(e,n=1e5){if(!e||typeof e!="string")return"";let t=e;for(let r of u)t=t.replace(r,"");return t.length>n&&(t=t.slice(0,n)),t}function A(e,n=1,t=1e5){return e.length<n?{valid:!1,reason:`content below minimum length (${n})`}:e.length>t?{valid:!1,reason:`content exceeds maximum length (${t})`}:{valid:!0}}var f=50,g=128,c=1024;function x(e){let n={},t=0;for(let[r,i]of Object.entries(e)){if(t>=f)break;r.length>g||/[^\w.-]/.test(r)||(typeof i=="string"?(n[r]=i.slice(0,c),t++):(typeof i=="number"&&Number.isFinite(i)||typeof i=="boolean")&&(n[r]=i,t++))}return n}function E(e,n){let t=[];return(!Number.isInteger(e)||e<1||e>20)&&t.push("maxRecallResults must be an integer between 1 and 20"),(!Number.isInteger(n)||n<1||n>500)&&t.push("profileFrequency must be an integer between 1 and 500"),t}function s(e){return o("sha256").update(e).digest("hex")}var a=1,d="7f2a9c4b8e1d6f3a5c0b9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a";function p(e,n){let t=[s(e),s(n),a].join(":");return l("sha256",d).update(t).digest("base64url")}function F(e,n){let t=s(n),r=p(e,n);return{"X-Content-Hash":t,"X-Request-Integrity":[`v${a}`,r].join(".")}}export{F as getRequestIntegrity,m as sanitizeContent,x as sanitizeMetadata,h as validateApiKeyFormat,v as validateContainerTag,A as validateContentLength,E as validateRecallConfig};

package/logger.ts

@@ -0,0 +1,54 @@
+export type LoggerBackend = {
+	info(msg: string, ...args: unknown[]): void
+	warn(msg: string, ...args: unknown[]): void
+	error(msg: string, ...args: unknown[]): void
+	debug?(msg: string, ...args: unknown[]): void
+}
+
+const NOOP_LOGGER: LoggerBackend = {
+	info() {},
+	warn() {},
+	error() {},
+	debug() {},
+}
+
+let _backend: LoggerBackend = NOOP_LOGGER
+let _debug = false
+
+export function initLogger(backend: LoggerBackend, debug: boolean): void {
+	_backend = backend
+	_debug = debug
+}
+
+export const log = {
+	info(msg: string, ...args: unknown[]): void {
+		_backend.info(`supermemory: ${msg}`, ...args)
+	},
+
+	warn(msg: string, ...args: unknown[]): void {
+		_backend.warn(`supermemory: ${msg}`, ...args)
+	},
+
+	error(msg: string, err?: unknown): void {
+		const detail = err instanceof Error ? err.message : err ? String(err) : ""
+		_backend.error(`supermemory: ${msg}${detail ? ` — ${detail}` : ""}`)
+	},
+
+	debug(msg: string, ...args: unknown[]): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`supermemory [debug]: ${msg}`, ...args)
+	},
+
+	debugRequest(method: string, params: Record<string, unknown>): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`supermemory [debug] → ${method}`, JSON.stringify(params, null, 2))
+	},
+
+	debugResponse(method: string, data: unknown): void {
+		if (!_debug) return
+		const fn = _backend.debug ?? _backend.info
+		fn(`supermemory [debug] ← ${method}`, JSON.stringify(data, null, 2))
+	},
+}

package/memory.ts

@@ -0,0 +1,25 @@
+export const MEMORY_CATEGORIES = [
+	"preference",
+	"fact",
+	"decision",
+	"entity",
+	"other",
+] as const
+export type MemoryCategory = (typeof MEMORY_CATEGORIES)[number]
+
+export function detectCategory(text: string): MemoryCategory {
+	const lower = text.toLowerCase()
+	if (/prefer|like|love|hate|want/i.test(lower)) return "preference"
+	if (/decided|will use|going with/i.test(lower)) return "decision"
+	if (/\+\d{10,}|@[\w.-]+\.\w+|is called/i.test(lower)) return "entity"
+	if (/is|are|has|have/i.test(lower)) return "fact"
+	return "other"
+}
+
+export function buildDocumentId(sessionKey: string): string {
+	const sanitized = sessionKey
+		.replace(/[^a-zA-Z0-9_]/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_|_$/g, "")
+	return `session_${sanitized}`
+}

package/openclaw.plugin.json

@@ -0,0 +1,63 @@
+{
+	"id": "openclaw-supermemory",
+	"kind": "memory",
+	"uiHints": {
+		"apiKey": {
+			"label": "Supermemory API Key",
+			"sensitive": true,
+			"placeholder": "sm_...",
+			"help": "Your API key from console.supermemory.ai (or use ${SUPERMEMORY_OPENCLAW_API_KEY})"
+		},
+		"containerTag": {
+			"label": "Container Tag",
+			"placeholder": "openclaw_myhostname",
+			"help": "Memory namespace. Default: openclaw_{hostname}. All channels share this.",
+			"advanced": true
+		},
+		"autoRecall": {
+			"label": "Auto-Recall",
+			"help": "Inject relevant memories + user profile before every AI turn"
+		},
+		"autoCapture": {
+			"label": "Auto-Capture",
+			"help": "Automatically store important information from conversations"
+		},
+		"maxRecallResults": {
+			"label": "Max Recall Results",
+			"placeholder": "10",
+			"help": "Maximum memories injected into context per turn",
+			"advanced": true
+		},
+		"profileFrequency": {
+			"label": "Profile Injection Frequency",
+			"placeholder": "50",
+			"help": "Inject full profile (static + dynamic) every N turns. Search results are injected every turn.",
+			"advanced": true
+		},
+		"captureMode": {
+			"label": "Capture Mode",
+			"help": "'all' (default) = filter out short texts and injected context, 'everything' = capture all messages",
+			"advanced": true
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose debug logs for API calls and responses",
+			"advanced": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"apiKey": { "type": "string" },
+			"containerTag": { "type": "string" },
+			"autoRecall": { "type": "boolean" },
+			"autoCapture": { "type": "boolean" },
+			"maxRecallResults": { "type": "number", "minimum": 1, "maximum": 20 },
+			"profileFrequency": { "type": "number", "minimum": 1, "maximum": 500 },
+			"captureMode": { "type": "string", "enum": ["everything", "all"] },
+			"debug": { "type": "boolean" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@supermemory/openclaw-supermemory",
+	"version": "1.0.2",
+	"type": "module",
+	"description": "OpenClaw Supermemory memory plugin",
+	"license": "MIT",
+	"dependencies": {
+		"supermemory": "^4.0.0",
+		"@sinclair/typebox": "0.34.47"
+	},
+	"scripts": {
+		"check-types": "tsc --noEmit",
+		"lint": "bunx @biomejs/biome ci .",
+		"lint:fix": "bunx @biomejs/biome check --write .",
+		"build:lib": "esbuild lib/validate.ts --bundle --minify --format=esm --platform=node --target=es2022 --external:node:crypto --outfile=lib/validate.js"
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"openclaw": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"devDependencies": {
+		"typescript": "^5.9.3"
+	}
+}

package/tools/forget.ts

@@ -0,0 +1,58 @@
+import { Type } from "@sinclair/typebox"
+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 registerForgetTool(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+): void {
+	api.registerTool(
+		{
+			name: "supermemory_forget",
+			label: "Memory Forget",
+			description:
+				"Forget/delete a specific memory. Searches for the closest match and removes it.",
+			parameters: Type.Object({
+				query: Type.Optional(
+					Type.String({ description: "Describe the memory to forget" }),
+				),
+				memoryId: Type.Optional(
+					Type.String({ description: "Direct memory ID to delete" }),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { query?: string; memoryId?: string },
+			) {
+				if (params.memoryId) {
+					log.debug(`forget tool: direct delete id="${params.memoryId}"`)
+					await client.deleteMemory(params.memoryId)
+					return {
+						content: [{ type: "text" as const, text: "Memory forgotten." }],
+					}
+				}
+
+				if (params.query) {
+					log.debug(`forget tool: search-then-delete query="${params.query}"`)
+					const result = await client.forgetByQuery(params.query)
+					return {
+						content: [{ type: "text" as const, text: result.message }],
+					}
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: "Provide a query or memoryId to forget.",
+						},
+					],
+				}
+			},
+		},
+		{ name: "supermemory_forget" },
+	)
+}

package/tools/profile.ts

@@ -0,0 +1,68 @@
+import { Type } from "@sinclair/typebox"
+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 registerProfileTool(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+): void {
+	api.registerTool(
+		{
+			name: "supermemory_profile",
+			label: "User Profile",
+			description:
+				"Get a summary of what is known about the user — stable preferences and recent context.",
+			parameters: Type.Object({
+				query: Type.Optional(
+					Type.String({
+						description: "Optional query to focus the profile",
+					}),
+				),
+			}),
+			async execute(_toolCallId: string, params: { query?: string }) {
+				log.debug(`profile tool: query="${params.query ?? "(none)"}"`)
+
+				const profile = await client.getProfile(params.query)
+
+				if (profile.static.length === 0 && profile.dynamic.length === 0) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: "No profile information available yet.",
+							},
+						],
+					}
+				}
+
+				const sections: string[] = []
+
+				if (profile.static.length > 0) {
+					sections.push(
+						"## User Profile (Persistent)\n" +
+							profile.static.map((f) => `- ${f}`).join("\n"),
+					)
+				}
+
+				if (profile.dynamic.length > 0) {
+					sections.push(
+						"## Recent Context\n" +
+							profile.dynamic.map((f) => `- ${f}`).join("\n"),
+					)
+				}
+
+				return {
+					content: [{ type: "text" as const, text: sections.join("\n\n") }],
+					details: {
+						staticCount: profile.static.length,
+						dynamicCount: profile.dynamic.length,
+					},
+				}
+			},
+		},
+		{ name: "supermemory_profile" },
+	)
+}

package/tools/search.ts

@@ -0,0 +1,70 @@
+import { Type } from "@sinclair/typebox"
+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 registerSearchTool(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+): void {
+	api.registerTool(
+		{
+			name: "supermemory_search",
+			label: "Memory Search",
+			description:
+				"Search through long-term memories for relevant information.",
+			parameters: Type.Object({
+				query: Type.String({ description: "Search query" }),
+				limit: Type.Optional(
+					Type.Number({ description: "Max results (default: 5)" }),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { query: string; limit?: number },
+			) {
+				const limit = params.limit ?? 5
+				log.debug(`search tool: query="${params.query}" limit=${limit}`)
+
+				const results = await client.search(params.query, limit)
+
+				if (results.length === 0) {
+					return {
+						content: [
+							{ type: "text" as const, text: "No relevant memories found." },
+						],
+					}
+				}
+
+				const text = results
+					.map((r, i) => {
+						const score = r.similarity
+							? ` (${(r.similarity * 100).toFixed(0)}%)`
+							: ""
+						return `${i + 1}. ${r.content || r.memory || ""}${score}`
+					})
+					.join("\n")
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Found ${results.length} memories:\n\n${text}`,
+						},
+					],
+					details: {
+						count: results.length,
+						memories: results.map((r) => ({
+							id: r.id,
+							content: r.content,
+							similarity: r.similarity,
+						})),
+					},
+				}
+			},
+		},
+		{ name: "supermemory_search" },
+	)
+}

package/tools/store.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { stringEnum } from "openclaw/plugin-sdk"
+import type { SupermemoryClient } from "../client.ts"
+import type { SupermemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+import {
+	buildDocumentId,
+	detectCategory,
+	MEMORY_CATEGORIES,
+} from "../memory.ts"
+
+export function registerStoreTool(
+	api: OpenClawPluginApi,
+	client: SupermemoryClient,
+	_cfg: SupermemoryConfig,
+	getSessionKey: () => string | undefined,
+): void {
+	api.registerTool(
+		{
+			name: "supermemory_store",
+			label: "Memory Store",
+			description: "Save important information to long-term memory.",
+			parameters: Type.Object({
+				text: Type.String({ description: "Information to remember" }),
+				category: Type.Optional(stringEnum(MEMORY_CATEGORIES)),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { text: string; category?: string },
+			) {
+				const category = params.category ?? detectCategory(params.text)
+				const sk = getSessionKey()
+				const customId = sk ? buildDocumentId(sk) : undefined
+
+				log.debug(`store tool: category="${category}" customId="${customId}"`)
+
+				await client.addMemory(
+					params.text,
+					{ type: category, source: "openclaw_tool" },
+					customId,
+				)
+
+				const preview =
+					params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text
+
+				return {
+					content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
+				}
+			},
+		},
+		{ name: "supermemory_store" },
+	)
+}