Quickstart

Build your first context layer end to end:

Install the SDK and set your API key
Create a database
Ingest a document and a memory
Query them in one call

Working with a coding agent such as Claude Code, Cursor, or Codex? Copy this prompt instead, and it builds the integration from the Agent Integration Guide.

Integrate HydraDB into this project with your coding agent.

1. Install and initialize

Get an API key from dashboard.hydradb.com, then set it in the terminal where you run the examples:

export HYDRA_DB_API_KEY="your_api_key"

Install the SDK and create a client:

# Install: pip install "hydradb-sdk>=2,<3"
import os
from hydra_db import HydraDB
from hydra_db.helpers import build_string

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])

// Install: npm install @hydradb/sdk@^2
// Needs a Node.js project with top-level await (ESM).
import { HydraDBClient } from "@hydradb/sdk";
import { buildString } from "@hydradb/sdk/helpers";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY!,
});

# Confirm your key works by listing databases. The later steps use jq to read responses.
curl 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

2. Create a database, ingest context, and query it

Create a database, ingest a refund policy and a customer memory, wait until both are indexed, then query them together. Ingestion runs in the background, which is why the code waits before querying. If you already created a database, set database to its name and skip the create call.

import json, time

database = "my_first_database"

# 1. Create a database and wait until it can accept data.
client.databases.create(database=database)
while not client.databases.status(database=database).data.infra.ready_for_ingestion:
    time.sleep(5)

# 2. Ingest a knowledge document into the shared collection.
with open("refund-policy.md", "w") as f:
    f.write("# Refund policy\n\nRefunds are available within 30 days of purchase. Annual plans are refunded pro rata.\n")

with open("refund-policy.md", "rb") as f:
    doc = client.context.ingest(
        type="knowledge",
        database=database,
        collection="company_docs",
        documents=[("refund-policy.md", f, "text/markdown")],
        document_metadata=json.dumps([{"id": "refund_policy"}]),
    )

# 3. Save one customer's memory in that customer's collection.
mem = client.context.ingest(
    type="memory",
    database=database,
    collection="user_123",
    memories=json.dumps([
        {"text": "Customer asked for a refund on 2026-09-30 and was told to wait for the billing cycle to close."}
    ]),
)

# 4. Wait until both are indexed.
def wait_for(collection, id):
    while True:
        status = client.context.status(
            database=database, collection=collection, ids=[id]
        ).data.statuses[0]
        if status.indexing_status == "completed":
            return
        if status.indexing_status == "errored":
            raise RuntimeError(status.error_message)
        time.sleep(2)

wait_for("company_docs", doc.data.results[0].id)
wait_for("user_123", mem.data.results[0].id)

# 5. Query knowledge and the customer's memory together.
results = client.query(
    database=database,
    collections=["company_docs", "user_123"],
    type="all",
    query="Can this customer get a refund, and what have we told them so far?",
)

print(build_string(results))

import { writeFileSync } from "node:fs";

const database = "my_first_database";

// 1. Create a database and wait until it can accept data.
await client.databases.create({ database });
while (true) {
  const { data } = await client.databases.status({ database });
  if (data?.infra?.readyForIngestion) break;
  await new Promise((resolve) => setTimeout(resolve, 5_000));
}

// 2. Ingest a knowledge document into the shared collection.
writeFileSync(
  "refund-policy.md",
  "# Refund policy\n\nRefunds are available within 30 days of purchase. Annual plans are refunded pro rata.\n",
);

const doc = await client.context.ingest({
  type: "knowledge",
  database,
  collection: "company_docs",
  documents: [{ path: "refund-policy.md", filename: "refund-policy.md", contentType: "text/markdown" }],
  documentMetadata: JSON.stringify([{ id: "refund_policy" }]),
});

// 3. Save one customer's memory in that customer's collection.
const mem = await client.context.ingest({
  type: "memory",
  database,
  collection: "user_123",
  memories: JSON.stringify([
    { text: "Customer asked for a refund on 2026-09-30 and was told to wait for the billing cycle to close." },
  ]),
});

// 4. Wait until both are indexed.
async function waitFor(collection: string, id: string | undefined) {
  if (!id) throw new Error("Ingestion returned no id");
  while (true) {
    const status = (await client.context.status({ database, collection, ids: [id] })).data?.statuses?.[0];
    if (!status) throw new Error("Status is missing");
    if (status.indexingStatus === "completed") return;
    if (status.indexingStatus === "errored") throw new Error(status.errorMessage ?? "Indexing failed");
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
}

await waitFor("company_docs", doc.data?.results?.[0]?.id);
await waitFor("user_123", mem.data?.results?.[0]?.id);

// 5. Query knowledge and the customer's memory together.
const results = await client.query({
  database,
  collections: ["company_docs", "user_123"],
  type: "all",
  query: "Can this customer get a refund, and what have we told them so far?",
});

console.log(buildString(results));

DATABASE="my_first_database"
API="https://api.hydradb.com"
AUTH=(-H "Authorization: Bearer $HYDRA_DB_API_KEY" -H "API-Version: 2")

# 1. Create a database and wait until it can accept data.
curl -s -X POST "$API/databases" "${AUTH[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"database\":\"${DATABASE}\"}"

until curl -s "$API/databases/status?database=${DATABASE}" "${AUTH[@]}" \
  | jq -e '.data.infra.ready_for_ingestion' > /dev/null; do
  sleep 5
done

# 2. Ingest a knowledge document into the shared collection.
cat > refund-policy.md <<'EOF'
# Refund policy

Refunds are available within 30 days of purchase. Annual plans are refunded pro rata.
EOF

DOC_ID=$(curl -s -X POST "$API/context/ingest" "${AUTH[@]}" \
  -F "type=knowledge" \
  -F "database=${DATABASE}" \
  -F "collection=company_docs" \
  -F "[email protected]" \
  -F 'document_metadata=[{"id":"refund_policy"}]' \
  | jq -r '.data.results[0].id')

# 3. Save one customer's memory in that customer's collection.
MEM_ID=$(curl -s -X POST "$API/context/ingest" "${AUTH[@]}" \
  -F "type=memory" \
  -F "database=${DATABASE}" \
  -F "collection=user_123" \
  -F 'memories=[{"text":"Customer asked for a refund on 2026-09-30 and was told to wait for the billing cycle to close."}]' \
  | jq -r '.data.results[0].id')

# 4. Wait until both are indexed.
wait_for() {
  while true; do
    STATUS=$(curl -s -G "$API/context/status" "${AUTH[@]}" \
      --data-urlencode "database=${DATABASE}" \
      --data-urlencode "collection=$1" \
      --data-urlencode "ids=$2")
    STATE=$(echo "$STATUS" | jq -r '.data.statuses[0].indexing_status')
    if [ "$STATE" = "completed" ]; then return; fi
    if [ "$STATE" = "errored" ]; then
      echo "$STATUS" | jq -r '.data.statuses[0].error_message'; exit 1
    fi
    sleep 2
  done
}
wait_for company_docs "$DOC_ID"
wait_for user_123 "$MEM_ID"

# 5. Query knowledge and the customer's memory together.
curl -s -X POST "$API/query" "${AUTH[@]}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF | jq -r '.data.chunks[].chunk_content'
{
  "database": "${DATABASE}",
  "collections": ["company_docs", "user_123"],
  "type": "all",
  "query": "Can this customer get a refund, and what have we told them so far?"
}
EOF

3. Check the result

The query returns passages from your context, not a generated answer. The SDK examples print formatted context; cURL prints the passage text. Both should include the policy and the memory:

Refunds are available within 30 days of purchase. Annual plans are refunded pro rata.
Customer asked for a refund on 2026-09-30 and was told to wait for the billing cycle to close.

Send these passages to your model as context. build_string in Python and buildString in TypeScript format them for a prompt. See How to Use API Results for more.

What you have built

That is the full HydraDB loop: create a database, ingest context, wait for indexing, query it, and pass the result to a model. HydraDB handles parsing, chunking, embedding, graph building, and search. Your application sends the query and gets back the slice of context that fits it. HydraDB is serverless, so there is nothing to provision, shard, or scale. Nothing in the code changes between one document and ten million, or between a Markdown file and a Slack workspace synced by a connector.

Where to go next

If you want to	Read
Understand how context gets stored and retrieved	Architecture
Ingest files or app records	Knowledge, App Sources
Sync 70 apps, including Slack, Gmail, and Notion, automatically	Connectors
Tune query behavior (`alpha`, `mode`, `recency_bias`)	Query
Design a filterable metadata schema	Metadata
Organize data across databases and collections	Multi-tenancy
Turn query results into a model prompt	How to Use API Results
See the full endpoint reference	API Reference
Pick from real-world recipes	Cookbooks

Stuck? Reach out at [email protected].

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Install and initialize

2. Create a database, ingest context, and query it

3. Check the result

What you have built

Where to go next

​1. Install and initialize

​2. Create a database, ingest context, and query it

​3. Check the result

​What you have built

​Where to go next

1. Install and initialize

2. Create a database, ingest context, and query it

3. Check the result

What you have built

Where to go next