@hydra_db/openclaw 0.1.1

package/log.ts

@@ -0,0 +1,48 @@
+export type LoggerBackend = {
+	info(msg: string): void
+	warn(msg: string): void
+	error(msg: string): void
+	debug?(msg: string): void
+}
+
+const TAG = "[hydra-db]"
+
+let _backend: LoggerBackend | null = null
+let _debug = false
+
+export const log = {
+	init(backend: LoggerBackend, debug: boolean) {
+		_backend = backend
+		_debug = debug
+	},
+
+	setDebug(enabled: boolean) {
+		_debug = enabled
+	},
+
+	info(...args: unknown[]) {
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.info(msg)
+		else console.log(msg)
+	},
+
+	warn(...args: unknown[]) {
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.warn(msg)
+		else console.warn(msg)
+	},
+
+	error(...args: unknown[]) {
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.error(msg)
+		else console.error(msg)
+	},
+
+	debug(...args: unknown[]) {
+		if (!_debug) return
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend?.debug) _backend.debug(msg)
+		else if (_backend) _backend.info(msg)
+		else console.debug(msg)
+	},
+}

package/messages.ts

@@ -0,0 +1,88 @@
+import type { ConversationTurn } from "./types/hydra.ts"
+
+export function containsIgnoreTerm(text: string, ignoreTerm: string): boolean {
+	return text.toLowerCase().includes(ignoreTerm.toLowerCase())
+}
+
+export function filterIgnoredTurns(
+	turns: ConversationTurn[],
+	ignoreTerm: string,
+): ConversationTurn[] {
+	return turns.filter(
+		(t) =>
+			!containsIgnoreTerm(t.user, ignoreTerm) &&
+			!containsIgnoreTerm(t.assistant, ignoreTerm),
+	)
+}
+
+export function textFromMessage(msg: Record<string, unknown>): string {
+	const content = msg.content
+	if (typeof content === "string") return content
+	if (Array.isArray(content)) {
+		return content
+			.filter(
+				(b) =>
+					b &&
+					typeof b === "object" &&
+					(b as Record<string, unknown>).type === "text",
+			)
+			.map((b) => (b as Record<string, unknown>).text as string)
+			.filter(Boolean)
+			.join("\n")
+	}
+	return ""
+}
+
+export function extractAllTurns(messages: unknown[]): ConversationTurn[] {
+	const turns: ConversationTurn[] = []
+	let currentUserText: string | null = null
+	let currentAssistantText: string | null = null
+
+	for (const msg of messages) {
+		if (!msg || typeof msg !== "object") continue
+		const m = msg as Record<string, unknown>
+		const text = textFromMessage(m)
+
+		if (m.role === "user") {
+			if (!text) continue
+			if (currentUserText && currentAssistantText) {
+				turns.push({ user: currentUserText, assistant: currentAssistantText })
+			}
+			currentUserText = text
+			currentAssistantText = "no-message"
+		} else if (m.role === "assistant") {
+			if (!text) continue
+			currentAssistantText = text
+		}
+	}
+
+	if (currentUserText && currentAssistantText) {
+		turns.push({ user: currentUserText, assistant: currentAssistantText })
+	}
+
+	return turns
+}
+
+export function getLatestTurn(messages: unknown[]): ConversationTurn | null {
+	let userIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i]
+		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "user") {
+			userIdx = i
+			break
+		}
+	}
+	if (userIdx < 0) return null
+
+	const userText = textFromMessage(messages[userIdx] as Record<string, unknown>)
+	if (!userText) return null
+
+	for (let i = userIdx + 1; i < messages.length; i++) {
+		const m = messages[i]
+		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "assistant") {
+			const aText = textFromMessage(m as Record<string, unknown>)
+			if (aText) return { user: userText, assistant: aText }
+		}
+	}
+	return null
+}

package/openclaw.plugin.json

@@ -0,0 +1,74 @@
+{
+	"id": "openclaw-hydra-db",
+	"kind": "memory",
+	"uiHints": {
+		"apiKey": {
+			"label": "Hydra API Key",
+			"sensitive": true,
+			"placeholder": "your-hydra-api-key",
+			"help": "Your API key from Hydra (or use ${HYDRA_OPENCLAW_API_KEY})"
+		},
+		"tenantId": {
+			"label": "Tenant ID",
+			"placeholder": "tenant-01",
+			"help": "Your Hydra tenant identifier (or use ${HYDRA_OPENCLAW_TENANT_ID})"
+		},
+		"subTenantId": {
+			"label": "Sub-Tenant ID",
+			"placeholder": "hydra-openclaw",
+			"help": "Sub-tenant for data partitioning (default: hydra-openclaw)",
+			"advanced": true
+		},
+		"autoRecall": {
+			"label": "Auto-Recall",
+			"help": "Inject relevant memories before every AI turn (default: true)"
+		},
+		"autoCapture": {
+			"label": "Auto-Capture",
+			"help": "Automatically store conversation exchanges after every AI turn (default: true)"
+		},
+		"maxRecallResults": {
+			"label": "Max Recall Results",
+			"placeholder": "10",
+			"help": "Maximum memory chunks injected into context per turn",
+			"advanced": true
+		},
+		"recallMode": {
+			"label": "Recall Mode",
+			"help": "'fast' (default) or 'thinking' (personalised recall with deeper graph traversal)",
+			"advanced": true
+		},
+		"graphContext": {
+			"label": "Graph Context",
+			"help": "Include knowledge graph relations in recalled context (default: true)",
+			"advanced": true
+		},
+		"ignoreTerm": {
+			"label": "Ignore Term",
+			"placeholder": "hydra-ignore",
+			"help": "Messages containing this term will be excluded from recall and capture (default: hydra-ignore)"
+		},
+		"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" },
+			"tenantId": { "type": "string" },
+			"subTenantId": { "type": "string" },
+			"autoRecall": { "type": "boolean" },
+			"autoCapture": { "type": "boolean" },
+			"maxRecallResults": { "type": "number", "minimum": 1, "maximum": 50 },
+			"recallMode": { "type": "string", "enum": ["fast", "thinking"] },
+			"graphContext": { "type": "boolean" },
+			"ignoreTerm": { "type": "string" },
+			"debug": { "type": "boolean" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hydra_db/openclaw",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "OpenClaw plugin for Hydra DB — the State-of-the-art agentic memory system with auto-capture, recall, and knowledge graph context for open-claw",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.47"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/session.ts

@@ -0,0 +1,11 @@
+export function toSourceId(sessionId: string): string {
+	return `sess_${sessionId}`
+}
+
+export function toHookSourceId(sessionId: string): string {
+	return `hook_${sessionId}`
+}
+
+export function toToolSourceId(sessionId: string): string {
+	return `tool_${sessionId}`
+}

package/tools/delete.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerDeleteTool(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	_cfg: HydraPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "hydra_delete_memory",
+			label: "Hydra Delete Memory",
+			description:
+				"Delete a specific memory from Hydra by its memory ID. Use this when the user explicitly asks you to forget something or remove a specific piece of stored information. Always confirm the memory ID before deleting.",
+			parameters: Type.Object({
+				memory_id: Type.String({
+					description: "The unique ID of the memory to delete",
+				}),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { memory_id: string },
+			) {
+				log.debug(`delete tool: memory_id=${params.memory_id}`)
+
+				const res = await client.deleteMemory(params.memory_id)
+
+				if (res.user_memory_deleted) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Successfully deleted memory: ${params.memory_id}`,
+							},
+						],
+					}
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Memory ${params.memory_id} was not found or has already been deleted.`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "hydra_delete_memory" },
+	)
+}

package/tools/get.ts

@@ -0,0 +1,57 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerGetTool(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	_cfg: HydraPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "hydra_get_content",
+			label: "Hydra Get Content",
+			description:
+				"Fetch the full content of a specific source from Hydra by its source ID. Use this to retrieve the complete text of a memory source when you need more details than what's shown in search results.",
+			parameters: Type.Object({
+				source_id: Type.String({
+					description: "The unique source ID to fetch content for",
+				}),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { source_id: string },
+			) {
+				log.debug(`get tool: source_id=${params.source_id}`)
+
+				const res = await client.fetchContent(params.source_id)
+
+				if (!res.success || res.error) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Failed to fetch source ${params.source_id}: ${res.error ?? "unknown error"}`,
+							},
+						],
+					}
+				}
+
+				const content = res.content ?? res.content_base64 ?? "(no text content available)"
+				const preview = content.length > 3000 ? `${content.slice(0, 3000)}…\n\n[Content truncated, showing first 3000 characters]` : content
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Source: ${params.source_id}\n\n${preview}`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "hydra_get_content" },
+	)
+}

package/tools/list.ts

@@ -0,0 +1,56 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerListTool(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	_cfg: HydraPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "hydra_list_memories",
+			label: "Hydra List Memories",
+			description:
+				"List all user memories stored in Hydra. Returns memory IDs and content summaries. Use this when the user asks what you remember about them or wants to see their stored information.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, never>) {
+				log.debug("list tool: fetching all memories")
+
+				const res = await client.listMemories()
+				const memories = res.user_memories ?? []
+
+				if (memories.length === 0) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: "No memories stored yet.",
+							},
+						],
+					}
+				}
+
+				const lines = memories.map((m, i) => {
+					const preview =
+						m.memory_content.length > 100
+							? `${m.memory_content.slice(0, 100)}…`
+							: m.memory_content
+					return `${i + 1}. [ID: ${m.memory_id}]\n   ${preview}`
+				})
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Found ${memories.length} memories:\n\n${lines.join("\n\n")}`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "hydra_list_memories" },
+	)
+}

package/tools/search.ts

@@ -0,0 +1,64 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { buildRecalledContext } from "../context.ts"
+import { log } from "../log.ts"
+import type { VectorChunk } from "../types/hydra.ts"
+
+
+export function registerSearchTool(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	cfg: HydraPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "hydra_search",
+			label: "Hydra Search",
+			description:
+				"Search through Hydra DB memories. Returns relevant chunks with graph-enriched context.",
+			parameters: Type.Object({
+				query: Type.String({ description: "Search query" }),
+				limit: Type.Optional(
+					Type.Number({ description: "Max results (default: 10)" }),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { query: string; limit?: number },
+			) {
+				const limit = params.limit ?? cfg.maxRecallResults
+				log.debug(`search tool: "${params.query}" limit=${limit}`)
+
+				const res = await client.recall(params.query, {
+					maxResults: limit,
+					mode: cfg.recallMode,
+					graphContext: cfg.graphContext,
+				})
+
+				if (!res.chunks || res.chunks.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No relevant memories found." }],
+					}
+				}
+
+				const contextStr = buildRecalledContext(res)
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Found ${res.chunks.length} \n\n---\nFull context:\n${contextStr}`,
+						},
+					],
+					details: {
+						count: res.chunks.length,
+						hasGraphContext: !!res.graph_context,
+					},
+				}
+			},
+		},
+		{ name: "hydra_search" },
+	)
+}

package/tools/store.ts

@@ -0,0 +1,116 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+import { extractAllTurns, filterIgnoredTurns } from "../messages.ts"
+import { toToolSourceId } from "../session.ts"
+import type { ConversationTurn } from "../types/hydra.ts"
+
+const MAX_STORE_TURNS = 10
+
+function removeInjectedBlocks(text: string): string {
+	return text.replace(/<hydra-context>[\s\S]*?<\/hydra-context>\s*/g, "").trim()
+}
+
+export function registerStoreTool(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	cfg: HydraPluginConfig,
+	getSessionId: () => string | undefined,
+	getMessages: () => unknown[],
+): void {
+	api.registerTool(
+		{
+			name: "hydra_store",
+			label: "Hydra Store",
+			description:
+				"Save the full conversation history to Hydra DB memory. Use this to persist facts, preferences, or decisions the user wants remembered. The complete chat history will be sent for context-rich storage.",
+			parameters: Type.Object({
+				text: Type.String({
+					description: "A brief summary or note about what is being saved",
+				}),
+				title: Type.Optional(
+					Type.String({
+						description: "Optional title for the memory entry",
+					}),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { text: string; title?: string },
+			) {
+				const sid = getSessionId()
+				const sourceId = sid ? toToolSourceId(sid) : undefined
+				const messages = getMessages()
+
+				log.debug(`[store] tool called — sid=${sid ?? "none"} msgs=${messages.length} text="${params.text.slice(0, 50)}"`)
+
+				const rawTurns = extractAllTurns(messages)
+				const filteredTurns = filterIgnoredTurns(rawTurns, cfg.ignoreTerm)
+				const recentTurns = filteredTurns.slice(-MAX_STORE_TURNS)
+				const turns: ConversationTurn[] = recentTurns.map((t) => ({
+					user: removeInjectedBlocks(t.user),
+					assistant: removeInjectedBlocks(t.assistant),
+				}))
+
+				log.debug(`[store] extracted ${rawTurns.length} total turns, ${rawTurns.length - filteredTurns.length} ignored, using last ${turns.length} (MAX_STORE_TURNS=${MAX_STORE_TURNS})`)
+
+				if (turns.length > 0 && sourceId) {
+					const now = new Date()
+					const readableTime = now.toLocaleString("en-US", {
+						weekday: "short",
+						year: "numeric",
+						month: "short",
+						day: "numeric",
+						hour: "2-digit",
+						minute: "2-digit",
+						timeZoneName: "short",
+					})
+
+					const annotatedTurns = turns.map((t, i) => ({
+						user: i === 0 ? `[Temporal details: ${readableTime}]\n\n${t.user}` : t.user,
+						assistant: t.assistant,
+					}))
+
+					log.debug(`[store] ingesting ${annotatedTurns.length} conversation turns -> ${sourceId}`)
+
+					await client.ingestConversation(annotatedTurns, sourceId, {
+						metadata: {
+							captured_at: now.toISOString(),
+							source: "openclaw_tool",
+							note: params.text,
+						},
+					})
+
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Saved ${annotatedTurns.length} conversation turns to Hydra (${sourceId}). Note: "${params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text}"`,
+							},
+						],
+					}
+				}
+
+				log.debug("[store] no conversation turns found, falling back to text ingestion")
+
+				await client.ingestText(params.text, {
+					sourceId,
+					title: params.title ?? "Agent Memory",
+					infer: true,
+				})
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Saved to Hydra: "${params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text}"`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "hydra_store" },
+	)
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts",
+    "tools/*.ts",
+    "hooks/*.ts",
+    "commands/*.ts",
+    "types/*.ts"
+  ],
+  "exclude": ["node_modules", "dist", "ignore"]
+}