@hydra_db/openclaw 0.1.1

package/config.ts

@@ -0,0 +1,128 @@
+export type HydraPluginConfig = {
+	apiKey: string
+	tenantId: string
+	subTenantId: string
+	autoRecall: boolean
+	autoCapture: boolean
+	maxRecallResults: number
+	recallMode: "fast" | "thinking"
+	graphContext: boolean
+	ignoreTerm: string
+	debug: boolean
+}
+
+const KNOWN_KEYS = new Set([
+	"apiKey",
+	"tenantId",
+	"subTenantId",
+	"autoRecall",
+	"autoCapture",
+	"maxRecallResults",
+	"recallMode",
+	"graphContext",
+	"ignoreTerm",
+	"debug",
+])
+
+const DEFAULT_SUB_TENANT = "hydra-openclaw-plugin"
+const DEFAULT_IGNORE_TERM = "hydra-ignore"
+
+function envOrNull(name: string): string | undefined {
+	return typeof process !== "undefined" ? process.env[name] : undefined
+}
+
+function resolveEnvVars(value: string): string {
+	return value.replace(/\$\{([^}]+)\}/g, (_, name: string) => {
+		const val = envOrNull(name)
+		if (!val) throw new Error(`Environment variable ${name} is not set`)
+		return val
+	})
+}
+
+export function parseConfig(raw: unknown): HydraPluginConfig {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	const unknown = Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
+	if (unknown.length > 0) {
+		throw new Error(`hydra-db: unrecognized config keys: ${unknown.join(", ")}`)
+	}
+
+	const apiKey =
+		typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+			? resolveEnvVars(cfg.apiKey)
+			: envOrNull("HYDRA_OPENCLAW_API_KEY")
+
+	if (!apiKey) {
+		throw new Error(
+			"hydra-db: apiKey is required — set it in plugin config or via HYDRA_OPENCLAW_API_KEY env var",
+		)
+	}
+
+	const tenantId =
+		typeof cfg.tenantId === "string" && cfg.tenantId.length > 0
+			? resolveEnvVars(cfg.tenantId)
+			: envOrNull("HYDRA_OPENCLAW_TENANT_ID")
+
+	if (!tenantId) {
+		throw new Error(
+			"hydra-db: tenantId is required — set it in plugin config or via HYDRA_OPENCLAW_TENANT_ID env var",
+		)
+	}
+
+	const subTenantId =
+		typeof cfg.subTenantId === "string" && cfg.subTenantId.length > 0
+			? cfg.subTenantId
+			: DEFAULT_SUB_TENANT
+
+	return {
+		apiKey,
+		tenantId,
+		subTenantId,
+		autoRecall: (cfg.autoRecall as boolean) ?? true,
+		autoCapture: (cfg.autoCapture as boolean) ?? true,
+		maxRecallResults: (cfg.maxRecallResults as number) ?? 10,
+		recallMode:
+			cfg.recallMode === "thinking"
+				? ("thinking" as const)
+				: ("fast" as const),
+		graphContext: (cfg.graphContext as boolean) ?? true,
+		ignoreTerm:
+			typeof cfg.ignoreTerm === "string" && cfg.ignoreTerm.length > 0
+				? cfg.ignoreTerm
+				: DEFAULT_IGNORE_TERM,
+		debug: (cfg.debug as boolean) ?? false,
+	}
+}
+
+export function tryParseConfig(raw: unknown): HydraPluginConfig | null {
+	try {
+		return parseConfig(raw)
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Permissive schema parse — validates key names but does NOT require credentials.
+ * This lets the plugin load so the onboarding wizard can run.
+ */
+function parseConfigSoft(raw: unknown): Record<string, unknown> {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	const unknown = Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
+	if (unknown.length > 0) {
+		throw new Error(`hydra-db: unrecognized config keys: ${unknown.join(", ")}`)
+	}
+
+	return cfg
+}
+
+export const hydraConfigSchema = {
+	parse: parseConfigSoft,
+}

package/context.ts

@@ -0,0 +1,191 @@
+import type {
+	PathTriplet,
+	RecallResponse,
+	ScoredPath,
+	VectorChunk,
+} from "./types/hydra.ts"
+
+function formatTriplet(triplet: PathTriplet): string {
+	const src = triplet.source?.name ?? "?"
+	const rel = triplet.relation
+	const predicate =
+		rel?.raw_predicate ?? rel?.canonical_predicate ?? "related to"
+	const tgt = triplet.target?.name ?? "?"
+	const ctx = rel?.context ? ` [${rel.context}]` : ""
+	return `  (${src}) —[${predicate}]→ (${tgt})${ctx}`
+}
+
+export function buildRecalledContext(
+	response: RecallResponse,
+	opts?: {
+		maxGroupOccurrences?: number
+		minEvidenceScore?: number
+	},
+): string {
+	const minScore = opts?.minEvidenceScore ?? 0.4
+
+	const chunks = response.chunks ?? []
+	const graphCtx = response.graph_context ?? {
+		query_paths: [],
+		chunk_relations: [],
+		chunk_id_to_group_ids: {},
+	}
+	const extraContextMap = response.additional_context ?? {}
+
+	const rawRelations: ScoredPath[] = graphCtx.chunk_relations ?? []
+	const relationIndex: Record<string, ScoredPath> = {}
+
+	for (let idx = 0; idx < rawRelations.length; idx++) {
+		const relation = rawRelations[idx]!
+		if ((relation.relevancy_score ?? 0) < minScore) continue
+		const groupId = relation.group_id ?? `p_${idx}`
+		relationIndex[groupId] = relation
+	}
+
+	const chunkToGroupIds = graphCtx.chunk_id_to_group_ids ?? {}
+	const consumedExtraIds = new Set<string>()
+	const chunkSections: string[] = []
+
+	for (let i = 0; i < chunks.length; i++) {
+		const chunk = chunks[i]!
+		const lines: string[] = []
+
+		lines.push(`Chunk ${i + 1}`)
+
+		const meta = chunk.document_metadata ?? {}
+		const title =
+			chunk.source_title || (meta as Record<string, string>).title
+		if (title) {
+			lines.push(`Source: ${title}`)
+		}
+
+		lines.push(chunk.chunk_content ?? "")
+
+		const chunkUuid = chunk.chunk_uuid
+		const linkedGroupIds = chunkToGroupIds[chunkUuid] ?? []
+
+		const matchedRelations: ScoredPath[] = []
+
+		for (const gid of linkedGroupIds) {
+			if (relationIndex[gid]) {
+				matchedRelations.push(relationIndex[gid]!)
+			}
+		}
+
+		if (matchedRelations.length === 0) {
+			for (const rel of Object.values(relationIndex)) {
+				const triplets = rel.triplets ?? []
+				const hasChunk = triplets.some(
+					(t) => t.relation?.chunk_id === chunkUuid,
+				)
+				if (hasChunk) {
+					matchedRelations.push(rel)
+				}
+			}
+		}
+
+		const relationLines: string[] = []
+		for (const rel of matchedRelations) {
+			const triplets = rel.triplets ?? []
+			if (triplets.length > 0) {
+				for (const triplet of triplets) {
+					relationLines.push(formatTriplet(triplet))
+				}
+			} else if (rel.combined_context) {
+				relationLines.push(`  ${rel.combined_context}`)
+			}
+		}
+
+		if (relationLines.length > 0) {
+			lines.push("Graph Relations:")
+			lines.push(...relationLines)
+		}
+
+		const extraIds = chunk.extra_context_ids ?? []
+		if (extraIds.length > 0 && Object.keys(extraContextMap).length > 0) {
+			const extraLines: string[] = []
+			for (const ctxId of extraIds) {
+				if (consumedExtraIds.has(ctxId)) continue
+				const extraChunk = extraContextMap[ctxId]
+				if (extraChunk) {
+					consumedExtraIds.add(ctxId)
+					const extraContent = extraChunk.chunk_content ?? ""
+					const extraTitle = extraChunk.source_title ?? ""
+					if (extraTitle) {
+						extraLines.push(
+							`  Related Context (${extraTitle}): ${extraContent}`,
+						)
+					} else {
+						extraLines.push(`  Related Context: ${extraContent}`)
+					}
+				}
+			}
+			if (extraLines.length > 0) {
+				lines.push("Extra Context:")
+				lines.push(...extraLines)
+			}
+		}
+
+		chunkSections.push(lines.join("\n"))
+	}
+
+	const entityPathLines: string[] = []
+	const rawPaths: ScoredPath[] = graphCtx.query_paths ?? []
+	for (const path of rawPaths) {
+		if (path.combined_context) {
+			entityPathLines.push(path.combined_context)
+		} else {
+			const triplets = path.triplets ?? []
+			const segments: string[] = []
+			for (const pt of triplets) {
+				const s = pt.source?.name
+				const rel = pt.relation
+				const p =
+					rel?.raw_predicate ??
+					rel?.canonical_predicate ??
+					"related to"
+				const t = pt.target?.name
+				segments.push(`(${s} -> ${p} -> ${t})`)
+			}
+			if (segments.length > 0) {
+				entityPathLines.push(segments.join(" -> "))
+			}
+		}
+	}
+
+	const output: string[] = []
+
+	if (entityPathLines.length > 0) {
+		output.push("=== ENTITY PATHS ===")
+		output.push(entityPathLines.join("\n"))
+		output.push("")
+	}
+
+	if (chunkSections.length > 0) {
+		output.push("=== CONTEXT ===")
+		output.push(chunkSections.join("\n\n---\n\n"))
+	}
+
+	return output.join("\n")
+}
+
+export function envelopeForInjection(contextBody: string): string {
+	if (!contextBody.trim()) return ""
+
+	const lines = [
+		"<hydra-context>",
+		"[MEMORIES AND PAST CONVERSATIONS — retrieved by Hydra DB]",
+		"",
+		"Below are memories and knowledge-graph connections that may be relevant",
+		"to the current conversation. Integrate them naturally when they add value.",
+		"If a memory contradicts something the user just said, prefer the user's",
+		"latest statement. Never quote these verbatim or reveal that you are",
+		"reading from a memory store.",
+		"",
+		contextBody,
+		"",
+		"[END OF MEMORY CONTEXT]",
+		"</hydra-context>",
+	]
+	return lines.join("\n")
+}

package/hooks/capture.ts

@@ -0,0 +1,101 @@
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+import { extractAllTurns, filterIgnoredTurns } from "../messages.ts"
+import { toHookSourceId } from "../session.ts"
+import type { ConversationTurn } from "../types/hydra.ts"
+
+const MAX_HOOK_TURNS = -1
+
+function removeInjectedBlocks(text: string): string {
+	return text.replace(/<hydra-context>[\s\S]*?<\/hydra-context>\s*/g, "").trim()
+}
+
+export function createIngestionHook(
+	client: HydraClient,
+	cfg: HydraPluginConfig,
+) {
+	return async (event: Record<string, unknown>, sessionId: string | undefined) => {
+		try {
+			log.debug(`[capture] hook fired — success=${event.success} msgs=${Array.isArray(event.messages) ? event.messages.length : "N/A"} sid=${sessionId ?? "none"}`)
+
+			if (!event.success) {
+				log.debug("[capture] skipped — event.success is falsy")
+				return
+			}
+			if (!Array.isArray(event.messages) || event.messages.length === 0) {
+				log.debug("[capture] skipped — no messages in event")
+				return
+			}
+
+			if (!sessionId) {
+				log.debug("[capture] skipped — no session id available")
+				return
+			}
+
+			const rawTurns = extractAllTurns(event.messages)
+			const allTurns = filterIgnoredTurns(rawTurns, cfg.ignoreTerm)
+
+			if (rawTurns.length > 0 && allTurns.length < rawTurns.length) {
+				log.debug(`[capture] filtered ${rawTurns.length - allTurns.length} turns containing ignore term "${cfg.ignoreTerm}"`)
+			}
+
+			if (allTurns.length === 0) {
+				log.debug(`[capture] skipped — no user-assistant turns found in ${event.messages.length} messages`)
+				const roles = event.messages
+					.slice(-5)
+					.map((m) => (m && typeof m === "object" ? (m as Record<string, unknown>).role : "?"))
+				log.debug(`[capture] last 5 message roles: ${JSON.stringify(roles)}`)
+				return
+			}
+
+			const recentTurns = MAX_HOOK_TURNS === -1 ? allTurns : allTurns.slice(-MAX_HOOK_TURNS) 
+			const turns: ConversationTurn[] = recentTurns.map((t) => ({
+				user: removeInjectedBlocks(t.user),
+				assistant: removeInjectedBlocks(t.assistant),
+			})).filter((t) => t.user.length >= 5 && t.assistant.length >= 5)
+
+			if (turns.length === 0) {
+				log.debug("[capture] skipped — all turns too short after cleaning")
+				return
+			}
+
+			const sourceId = toHookSourceId(sessionId)
+
+			const now = new Date()
+			const timestamp = now.toISOString()
+			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(`[capture] ingesting ${annotatedTurns.length} turns (of ${allTurns.length} total) @ ${timestamp} -> ${sourceId}`)
+
+			await client.ingestConversation(
+				annotatedTurns,
+				sourceId,
+				{
+					metadata: {
+						captured_at: timestamp,
+						source: "openclaw_hook",
+						turn_count: annotatedTurns.length,
+					},
+				},
+			)
+
+			log.debug("[capture] ingestion succeeded")
+		} catch (err) {
+			log.error("[capture] hook error", err)
+		}
+	}
+}

package/hooks/recall.ts

@@ -0,0 +1,46 @@
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+import { buildRecalledContext, envelopeForInjection } from "../context.ts"
+import { log } from "../log.ts"
+import { containsIgnoreTerm } from "../messages.ts"
+
+export function createRecallHook(
+	client: HydraClient,
+	cfg: HydraPluginConfig,
+) {
+	return async (event: Record<string, unknown>) => {
+		const prompt = event.prompt as string | undefined
+		if (!prompt || prompt.length < 5) return
+
+		if (containsIgnoreTerm(prompt, cfg.ignoreTerm)) {
+			log.debug(`recall skipped — prompt contains ignore term "${cfg.ignoreTerm}"`)
+			return
+		}
+
+		log.debug(`recall query (${prompt.length} chars)`)
+
+		try {
+			const response = await client.recall(prompt, {
+				maxResults: cfg.maxRecallResults,
+				mode: cfg.recallMode,
+				graphContext: cfg.graphContext,
+			})
+
+			if (!response.chunks || response.chunks.length === 0) {
+				log.debug("no memories matched")
+				return
+			}
+
+			const body = buildRecalledContext(response)
+			if (!body.trim()) return
+
+			const envelope = envelopeForInjection(body)
+
+			log.debug(`injecting ${response.chunks.length} chunks (${envelope.length} chars)`)
+			return { prependContext: envelope }
+		} catch (err) {
+			log.error("recall failed", err)
+			return
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,212 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { HydraClient } from "./client.ts"
+import type { HydraPluginConfig } from "./config.ts"
+import { registerOnboardingCli as createOnboardingCliRegistrar, registerOnboardingSlashCommands } from "./commands/onboarding.ts"
+import { registerSlashCommands } from "./commands/slash.ts"
+import { hydraConfigSchema, tryParseConfig } from "./config.ts"
+import { createIngestionHook } from "./hooks/capture.ts"
+import { createRecallHook } from "./hooks/recall.ts"
+import { log } from "./log.ts"
+import { registerDeleteTool } from "./tools/delete.ts"
+import { registerGetTool } from "./tools/get.ts"
+import { registerListTool } from "./tools/list.ts"
+import { registerSearchTool } from "./tools/search.ts"
+import { registerStoreTool } from "./tools/store.ts"
+
+const NOT_CONFIGURED_MSG =
+	"[hydra-db] Not configured. Run `openclaw hydra onboard` to set up credentials."
+
+export default {
+	id: "openclaw-hydra-db",
+	name: "Hydra DB",
+	description:
+		"State-of-the-art agentic memory for OpenClaw powered by Hydra DB — auto-capture, recall, and graph-enriched context",
+	kind: "memory" as const,
+	configSchema: hydraConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const cfg = tryParseConfig(api.pluginConfig)
+		const cliClient = cfg ? new HydraClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId) : null
+
+		// Always register ALL CLI commands so they appear in help text.
+		// Non-onboard commands guard on credentials at runtime.
+		api.registerCli(
+			({ program }: { program: any }) => {
+				const root = program
+					.command("hydra")
+					.description("Hydra DB memory commands")
+
+				createOnboardingCliRegistrar(cfg ?? undefined)(root)
+				registerHydraCliCommands(root, cliClient, cfg)
+			},
+			{ commands: ["hydra"] },
+		)
+
+		if (!cfg) {
+			api.registerService({
+				id: "openclaw-hydra-db",
+				start: () => console.log(NOT_CONFIGURED_MSG),
+				stop: () => {},
+			})
+			return
+		}
+
+		// Full plugin registration — credentials present
+		log.init(api.logger, cfg.debug)
+
+		const client = new HydraClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId)
+
+		let activeSessionId: string | undefined
+		let conversationMessages: unknown[] = []
+		const getSessionId = () => activeSessionId
+		const getMessages = () => conversationMessages
+
+		registerSearchTool(api, client, cfg)
+		registerStoreTool(api, client, cfg, getSessionId, getMessages)
+		registerListTool(api, client, cfg)
+		registerDeleteTool(api, client, cfg)
+		registerGetTool(api, client, cfg)
+
+		if (cfg.autoRecall) {
+			const onRecall = createRecallHook(client, cfg)
+			api.on(
+				"before_agent_start",
+				(event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+					if (ctx.sessionId) activeSessionId = ctx.sessionId as string
+					if (Array.isArray(event.messages)) conversationMessages = event.messages
+					log.debug(`[session] before_agent_start — sid=${activeSessionId ?? "none"} msgs=${conversationMessages.length}`)
+					return onRecall(event)
+				},
+			)
+		}
+
+		if (cfg.autoCapture) {
+			const captureHandler = createIngestionHook(client, cfg)
+			api.on(
+				"agent_end",
+				(event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+					if (ctx.sessionId) activeSessionId = ctx.sessionId as string
+					if (Array.isArray(event.messages)) conversationMessages = event.messages
+					log.debug(`[session] agent_end — sid=${activeSessionId ?? "none"} msgs=${conversationMessages.length} ctxKeys=${Object.keys(ctx).join(",")}`)
+					return captureHandler(event, activeSessionId)
+				},
+			)
+		}
+
+		registerSlashCommands(api, client, cfg, getSessionId)
+		registerOnboardingSlashCommands(api, client, cfg)
+
+		api.registerService({
+			id: "openclaw-hydra-db",
+			start: () => log.info("plugin started"),
+			stop: () => log.info("plugin stopped"),
+		})
+	},
+}
+
+/**
+ * Register all `hydra *` CLI subcommands.
+ * Commands other than `onboard` guard on valid credentials at runtime.
+ */
+function registerHydraCliCommands(
+	root: any,
+	client: HydraClient | null,
+	cfg: HydraPluginConfig | null,
+): void {
+	const requireCreds = (): { client: HydraClient; cfg: HydraPluginConfig } | null => {
+		if (client && cfg) return { client, cfg }
+		console.error(NOT_CONFIGURED_MSG)
+		return null
+	}
+
+	root
+		.command("search")
+		.argument("<query>", "Search query")
+		.option("--limit <n>", "Max results", "10")
+		.action(async (query: string, opts: { limit: string }) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const limit = Number.parseInt(opts.limit, 10) || 10
+			const res = await ctx.client.recall(query, {
+				maxResults: limit,
+				mode: ctx.cfg.recallMode,
+				graphContext: ctx.cfg.graphContext,
+			})
+
+			if (!res.chunks || res.chunks.length === 0) {
+				console.log("No memories found.")
+				return
+			}
+
+			for (const chunk of res.chunks) {
+				const score = chunk.relevancy_score != null
+					? ` (${(chunk.relevancy_score * 100).toFixed(0)}%)`
+					: ""
+				const title = chunk.source_title ? `[${chunk.source_title}] ` : ""
+				console.log(`- ${title}${chunk.chunk_content.slice(0, 200)}${score}`)
+			}
+		})
+
+	root
+		.command("list")
+		.description("List all user memories")
+		.action(async () => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.listMemories()
+			const memories = res.user_memories ?? []
+			if (memories.length === 0) {
+				console.log("No memories stored.")
+				return
+			}
+			for (const m of memories) {
+				console.log(`[${m.memory_id}] ${m.memory_content.slice(0, 150)}`)
+			}
+			console.log(`\nTotal: ${memories.length}`)
+		})
+
+	root
+		.command("delete")
+		.argument("<memory_id>", "Memory ID to delete")
+		.action(async (memoryId: string) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.deleteMemory(memoryId)
+			console.log(res.user_memory_deleted ? `Deleted: ${memoryId}` : `Not found: ${memoryId}`)
+		})
+
+	root
+		.command("get")
+		.argument("<source_id>", "Source ID to fetch")
+		.action(async (sourceId: string) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.fetchContent(sourceId)
+			if (!res.success || res.error) {
+				console.error(`Error: ${res.error ?? "unknown"}`)
+				return
+			}
+			console.log(res.content ?? res.content_base64 ?? "(no text content)")
+		})
+
+	root
+		.command("status")
+		.description("Show plugin configuration")
+		.action(() => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			console.log(`Tenant:       ${ctx.client.getTenantId()}`)
+			console.log(`Sub-Tenant:   ${ctx.client.getSubTenantId()}`)
+			console.log(`Auto-Recall:  ${ctx.cfg.autoRecall}`)
+			console.log(`Auto-Capture: ${ctx.cfg.autoCapture}`)
+			console.log(`Recall Mode:  ${ctx.cfg.recallMode}`)
+			console.log(`Graph:        ${ctx.cfg.graphContext}`)
+			console.log(`Max Results:  ${ctx.cfg.maxRecallResults}`)
+			console.log(`Ignore Term:  ${ctx.cfg.ignoreTerm}`)
+		})
+}