@hydra_db/openclaw 0.1.1

package/.github/workflows/publish.yaml

@@ -0,0 +1,40 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Publish package to npm
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        # If you have a build step, otherwise remove this
+        run: npm run build
+        continue-on-error: true
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # Only publish if this is not a pre-release and version has changed
+          if [ "$(npm view . version)" != "$(node -p "require('./package.json').version")" ]; then
+            npm publish --access public
+          else
+            echo "Version already published, skipping."
+          fi

package/README.md

@@ -0,0 +1,172 @@
+# Hydra DB — OpenClaw Plugin
+
+State-of-the-art agentic memory for OpenClaw powered by [Hydra DB](https://hydradb.com). Automatically captures conversations, recalls relevant context with knowledge-graph connections, and injects them before every AI turn.
+
+## Install
+
+```bash
+openclaw plugins install @hydra_db/openclaw-hydra-db
+```
+
+Restart OpenClaw after installing.
+
+If you run OpenClaw via the local gateway, restart it too:
+
+```bash
+openclaw gateway restart
+```
+
+## Get Your Credentials
+1. Get your Hydra API Key from [Hydra DB](https://app.hydradb.com)
+2. Get your Tenant ID from the Hydra dashboard
+
+## Interactive Onboarding
+
+Run the interactive CLI wizard (recommended):
+
+```bash
+# Basic onboarding (API key, tenant ID, sub-tenant, ignore term)
+openclaw hydra onboard
+
+# Advanced onboarding (all options including recall mode, graph context, etc.)
+openclaw hydra onboard --advanced
+```
+
+The wizard guides you through configuration with colored prompts and **writes your config to** `plugins.entries.openclaw-hydra-db.config` inside OpenClaw's settings file.
+
+The path is resolved in the same order OpenClaw itself uses:
+
+1. `$OPENCLAW_CONFIG_PATH` — if set, used directly
+2. `$OPENCLAW_STATE_DIR/openclaw.json` — if `OPENCLAW_STATE_DIR` is set
+3. `$OPENCLAW_HOME/.openclaw/openclaw.json` — if `OPENCLAW_HOME` is set
+4. Default: `~/.openclaw/openclaw.json` (macOS/Linux) or `%USERPROFILE%\.openclaw\openclaw.json` (Windows)
+
+No manual adjustment needed — the wizard auto-detects the correct path.
+
+After onboarding, restart the gateway:
+
+```bash
+openclaw gateway restart
+```
+
+## Manual Configuration
+
+If you prefer, you can configure credentials manually.
+
+Two required values:
+
+- **API key**
+- **Tenant ID**
+
+Environment variables (recommended for secrets):
+
+```bash
+export HYDRA_OPENCLAW_API_KEY="your-api-key"
+export HYDRA_OPENCLAW_TENANT_ID="your-tenant-id"
+```
+
+Or configure directly in OpenClaw's settings file:
+
+- **macOS / Linux:** `~/.openclaw/openclaw.json`
+- **Windows:** `%USERPROFILE%\.openclaw\openclaw.json`
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "openclaw-hydra-db": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${HYDRA_OPENCLAW_API_KEY}",
+          "tenantId": "${HYDRA_OPENCLAW_TENANT_ID}"
+        }
+      }
+    }
+  }
+}
+```
+
+After changing config, restart the gateway so the plugin reloads:
+
+```bash
+openclaw gateway restart
+```
+
+### Options
+
+| Key                  | Type        | Default               | Description                                                                    |
+| -------------------- | ----------- | --------------------- | ------------------------------------------------------------------------------ |
+| `subTenantId`      | `string`  | `"hydra-openclaw-plugin"` | Sub-tenant for data partitioning within your tenant                      |
+| `autoRecall`       | `boolean` | `true`              | Inject relevant memories before every AI turn                                  |
+| `autoCapture`      | `boolean` | `true`              | Store conversation exchanges after every AI turn                               |
+| `maxRecallResults` | `number`  | `10`                | Max memory chunks injected into context per turn                               |
+| `recallMode`       | `string`  | `"fast"`            | `"fast"` or `"thinking"` (deeper personalised recall with graph traversal) |
+| `graphContext`     | `boolean` | `true`              | Include knowledge graph relations in recalled context                          |
+| `ignoreTerm`       | `string`  | `"hydra-ignore"`    | Messages containing this term are excluded from recall & capture              |
+| `debug`            | `boolean` | `false`             | Verbose debug logs                                                             |
+
+## How It Works
+
+- **Auto-Recall** — Before every AI turn, queries Hydra (`/recall/recall_preferences`) for relevant memories and injects graph-enriched context (entity paths, chunk relations, extra context).
+- **Auto-Capture** — After every AI turn, the last user/assistant exchange is sent to Hydra (`/memories/add_memory`) as conversation pairs with `infer: true` and `upsert: true`. The session ID is used as `source_id` so Hydra groups exchanges per session and builds a knowledge graph automatically.
+
+## Slash Commands
+
+| Command                     | Description                           |
+| --------------------------- | ------------------------------------- |
+| `/hydra-onboard`          | Show current configuration status     |
+| `/hydra-remember <text>` | Save something to Hydra memory       |
+| `/hydra-recall <query>`  | Search memories with relevance scores |
+| `/hydra-list`            | List all stored user memories         |
+| `/hydra-delete <id>`     | Delete a specific memory by its ID    |
+| `/hydra-get <source_id>` | Fetch the full content of a source    |
+
+## AI Tools
+
+| Tool                   | Description |
+| ---------------------- | ----------- |
+| `hydra_store`         | Save the recent conversation history to Hydra as memory |
+| `hydra_search`        | Search Hydra memories (returns graph-enriched context) |
+| `hydra_list_memories` | List all stored user memories (IDs + summaries) |
+| `hydra_get_content`   | Fetch full content for a specific `source_id` |
+| `hydra_delete_memory` | Delete a memory by `memory_id` (use only when user explicitly asks) |
+
+## CLI
+
+```bash
+openclaw hydra onboard             # Interactive onboarding wizard
+openclaw hydra onboard --advanced  # Advanced onboarding wizard
+openclaw hydra search <query>      # Search memories
+openclaw hydra list                # List all user memories
+openclaw hydra delete <id>         # Delete a memory
+openclaw hydra get <source_id>     # Fetch source content
+openclaw hydra status              # Show plugin configuration
+```
+
+## Troubleshooting
+
+### `Not configured. Run openclaw hydra onboard`
+
+This means the plugin is enabled, but credentials are missing.
+
+Run:
+
+```bash
+openclaw hydra onboard
+openclaw gateway restart
+```
+
+### CLI says a command is unknown
+
+Update/restart the gateway so it reloads the plugin:
+
+```bash
+openclaw gateway restart
+```
+
+## Context Injection
+
+Recalled context is injected inside `<hydra-context>` tags containing:
+
+- **Entity Paths** — Knowledge graph paths connecting entities relevant to the query
+- **Context Chunks** — Retrieved memory chunks with source titles, graph relations, and linked extra context

package/client.ts

@@ -0,0 +1,214 @@
+import { log } from "./log.ts"
+import type {
+	AddMemoryRequest,
+	AddMemoryResponse,
+	ConversationTurn,
+	DeleteMemoryResponse,
+	FetchContentRequest,
+	FetchContentResponse,
+	ListDataRequest,
+	ListMemoriesResponse,
+	ListSourcesResponse,
+	RecallRequest,
+	RecallResponse,
+} from "./types/hydra.ts"
+
+const API_BASE = "https://api.hydradb.com"
+
+const INGEST_INSTRUCTIONS =
+	"Focus on extracting user preferences, habits, opinions, likes, dislikes, " +
+	"goals, and recurring themes. Capture any stated or implied personal context " +
+	"that would help personalise future interactions. Capture important personal details like " +
+	"name, age, email ids, phone numbers, etc. along with the original name and context " +
+	"so that it can be used to personalise future interactions."
+
+export class HydraClient {
+	private apiKey: string
+	private tenantId: string
+	private subTenantId: string
+
+	constructor(apiKey: string, tenantId: string, subTenantId: string) {
+		this.apiKey = apiKey
+		this.tenantId = tenantId
+		this.subTenantId = subTenantId
+		log.info(`connected (tenant=${tenantId}, sub=${subTenantId})`)
+	}
+
+	private headers(): Record<string, string> {
+		return {
+			Authorization: `Bearer ${this.apiKey}`,
+			"Content-Type": "application/json",
+		}
+	}
+
+	private async post<T>(path: string, body: unknown): Promise<T> {
+		const url = `${API_BASE}${path}`
+		log.debug("POST", path, body)
+		const res = await fetch(url, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify(body),
+		})
+		if (!res.ok) {
+			const text = await res.text().catch(() => "")
+			throw new Error(`Hydra ${path} → ${res.status}: ${text}`)
+		}
+		return res.json() as Promise<T>
+	}
+
+	private async del<T>(path: string, params: Record<string, string>): Promise<T> {
+		const qs = new URLSearchParams(params).toString()
+		const url = `${API_BASE}${path}?${qs}`
+		log.debug("DELETE", path, params)
+		const res = await fetch(url, {
+			method: "DELETE",
+			headers: this.headers(),
+		})
+		if (!res.ok) {
+			const text = await res.text().catch(() => "")
+			throw new Error(`Hydra ${path} → ${res.status}: ${text}`)
+		}
+		return res.json() as Promise<T>
+	}
+
+	// --- Ingest ---
+
+	async ingestConversation(
+		turns: ConversationTurn[],
+		sourceId: string,
+		opts?: {
+			userName?: string
+			metadata?: Record<string, unknown>
+		},
+	): Promise<AddMemoryResponse> {
+		const payload: AddMemoryRequest = {
+			memories: [
+				{
+					user_assistant_pairs: turns,
+					infer: true,
+					source_id: sourceId,
+					user_name: opts?.userName ?? "User",
+					custom_instructions: INGEST_INSTRUCTIONS,
+					...(opts?.metadata && {
+						document_metadata: JSON.stringify(opts.metadata),
+					}),
+				},
+			],
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			upsert: true,
+		}
+		return this.post<AddMemoryResponse>("/memories/add_memory", payload)
+	}
+
+	async ingestText(
+		text: string,
+		opts?: {
+			sourceId?: string
+			title?: string
+			infer?: boolean
+			isMarkdown?: boolean
+			customInstructions?: string
+		},
+	): Promise<AddMemoryResponse> {
+		const shouldInfer = opts?.infer ?? true
+		const payload: AddMemoryRequest = {
+			memories: [
+				{
+					text,
+					infer: shouldInfer,
+					is_markdown: opts?.isMarkdown ?? false,
+					...(shouldInfer && {
+						custom_instructions: opts?.customInstructions ?? INGEST_INSTRUCTIONS,
+					}),
+					...(opts?.sourceId && { source_id: opts.sourceId }),
+					...(opts?.title && { title: opts.title }),
+				},
+			],
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			upsert: true,
+		}
+		return this.post<AddMemoryResponse>("/memories/add_memory", payload)
+	}
+
+	// --- Recall ---
+
+	async recall(
+		query: string,
+		opts?: {
+			maxResults?: number
+			mode?: "fast" | "thinking"
+			graphContext?: boolean
+			recencyBias?: number
+		},
+	): Promise<RecallResponse> {
+		const payload: RecallRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			query,
+			max_results: opts?.maxResults ?? 10,
+			mode: opts?.mode ?? "thinking",
+			alpha: 0.8,
+			recency_bias: opts?.recencyBias ?? 0,
+			graph_context: opts?.graphContext ?? true,
+		}
+		return this.post<RecallResponse>("/recall/recall_preferences", payload)
+	}
+
+	// --- List ---
+
+	async listMemories(): Promise<ListMemoriesResponse> {
+		const payload: ListDataRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			kind: "memories",
+		}
+		return this.post<ListMemoriesResponse>("/list/data", payload)
+	}
+
+	async listSources(sourceIds?: string[]): Promise<ListSourcesResponse> {
+		const payload: ListDataRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			kind: "memories",
+			...(sourceIds && { source_ids: sourceIds }),
+		}
+		return this.post<ListSourcesResponse>("/list/data", payload)
+	}
+
+	// --- Delete ---
+
+	async deleteMemory(memoryId: string): Promise<DeleteMemoryResponse> {
+		return this.del<DeleteMemoryResponse>("/memories/delete_memory", {
+			tenant_id: this.tenantId,
+			memory_id: memoryId,
+			sub_tenant_id: this.subTenantId,
+		})
+	}
+
+	// --- Fetch Content ---
+
+	async fetchContent(
+		sourceId: string,
+		mode: "content" | "url" | "both" = "content",
+	): Promise<FetchContentResponse> {
+		const payload: FetchContentRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			source_id: sourceId,
+			mode,
+		}
+		return this.post<FetchContentResponse>("/fetch/content", payload)
+	}
+
+	// --- Accessors ---
+
+	getTenantId(): string {
+		return this.tenantId
+	}
+
+	getSubTenantId(): string {
+		return this.subTenantId
+	}
+}

package/commands/cli.ts

@@ -0,0 +1,97 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { HydraClient } from "../client.ts"
+import type { HydraPluginConfig } from "../config.ts"
+
+export function registerCliCommands(
+	api: OpenClawPluginApi,
+	client: HydraClient,
+	cfg: HydraPluginConfig,
+	onboardingRegistrar?: (root: any) => void,
+): void {
+	api.registerCli(
+		({ program }: { program: any }) => {
+			const root = program
+				.command("hydra")
+				.description("Hydra DB memory commands")
+
+			root
+				.command("search")
+				.argument("<query>", "Search query")
+				.option("--limit <n>", "Max results", "10")
+				.action(async (query: string, opts: { limit: string }) => {
+					const limit = Number.parseInt(opts.limit, 10) || 10
+					const res = await client.recall(query, {
+						maxResults: limit,
+						mode: cfg.recallMode,
+						graphContext: 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 res = await 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 res = await 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 res = await 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(() => {
+					console.log(`Tenant:       ${client.getTenantId()}`)
+					console.log(`Sub-Tenant:   ${client.getSubTenantId()}`)
+					console.log(`Auto-Recall:  ${cfg.autoRecall}`)
+					console.log(`Auto-Capture: ${cfg.autoCapture}`)
+					console.log(`Recall Mode:  ${cfg.recallMode}`)
+					console.log(`Graph:        ${cfg.graphContext}`)
+					console.log(`Max Results:  ${cfg.maxRecallResults}`)
+					console.log(`Ignore Term:  ${cfg.ignoreTerm}`)
+				})
+
+			if (onboardingRegistrar) onboardingRegistrar(root)
+		},
+		{ commands: ["hydra"] },
+	)
+}