# HydraDB

A `database` + `tool` node for [HydraDB](https://hydradb.com) — a managed graph + memory store. It gives agents four tools to store text into HydraDB (with automatic knowledge-graph extraction), recall graph-enriched context by natural-language query, inspect the extracted relations, and read the database's shape.

## What it does

HydraDB retrieves natively on its own servers — there is **no embedding step, no query language, and no LLM translation** in this node. Agents call the tools on demand; nothing flows through data lanes (`lanes: {}`). The node holds an API key + a target `database`/`collection` and issues HydraDB v2 REST calls.

## Tools

| Tool | Inputs | Returns |
|---|---|---|
| `store_memory` | `text` (required), `metadata` (optional) | ingest status + raw response |
| `recall_memory` | `query` (required), `max_results` (optional, ≤100) | ranked, graph-enriched `results` |
| `query_graph` | `source_id` (optional) | entities + relationship triplets |
| `get_schema` | — | `database`, `collections`, and infra readiness flags |

## Setup

1. Create an API key and a database in the HydraDB dashboard.
2. Configure the node:
   - **API Key** — paste it, or leave blank to use the `HYDRA_DB_API_KEY` environment variable.
   - **Database** — your HydraDB database id (required).
   - **Collection** — optional scope within the database (default `default`).
   - **Max results** — default cap for `recall_memory` (default `10`).

The API key is a secure field (never stored as a default) and is cleared from memory on teardown.

## Limits

- **Not a vector/RAG store:** there is no `embedding → store → retrieve` lane path — retrieval is HydraDB-native and happens via the agent tools.
- **`query_graph` is relation inspection, not a query language** — HydraDB has no Cypher/AQL equivalent; you get extracted entities and triplets, optionally scoped to one `source_id`.
- **`get_schema`** reports collections + infra readiness, not a per-field data schema.
- `recall_memory` caps `max_results` at 100.
- v2 scopes by `database` + `collection` (the older `tenant_id` / `sub_tenant_id` names are accepted as deprecated aliases).

## Examples

Agent tool calls:

```jsonc
// store
{ "tool": "store_memory", "args": { "text": "Alex prefers concise answers and dark mode." } }
// recall
{ "tool": "recall_memory", "args": { "query": "What are Alex's UI preferences?", "max_results": 5 } }
// inspect the graph for one source
{ "tool": "query_graph", "args": { "source_id": "doc_12345" } }
// discover collections + readiness
{ "tool": "get_schema", "args": {} }
```

## Upstream docs

- API reference: <https://docs.hydradb.com/api-reference/v2/sdks.md>
- Query: <https://docs.hydradb.com/api-reference/v2/endpoint/query.md>
- Ingest: <https://docs.hydradb.com/api-reference/v2/endpoint/ingest-context.md>
- Context relations: <https://docs.hydradb.com/api-reference/v2/endpoint/source-relations.md>

## Troubleshooting

- **"API key is required"** — set the API Key field or `HYDRA_DB_API_KEY`.
- **`DATABASE_NOT_FOUND`** — the `database` id is wrong or not yet created.
- **Empty `recall_memory` results** — the database may still be provisioning; call `get_schema` and check `infra.ready_for_ingestion`.
- **Requests fail with 401** — the key is invalid or lacks access to the database.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `hydradb.api_key` | `string` | **API Key**<br/>HydraDB API key. Falls back to the HYDRA_DB_API_KEY environment variable if left blank. |  |
| `hydradb.collection` | `string` | **Collection**<br/>Collection scope within the database (per-user/workspace partition for memories). | `"default"` |
| `hydradb.database` | `string` | **Database**<br/>HydraDB database - the space that stores your context. Create one in the HydraDB dashboard. |  |
| `hydradb.max_results` | `integer` | **Max results**<br/>Default maximum number of results returned by recall_memory. | `10` |
| `hydradb.profile` | `string` |  | `"default"` |

## Dependencies

- `requests`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/db_hydradb)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->