Quickstart

This guide walks you through the full HydraDB loop end-to-end - create a workspace, ingest some content, wait for indexing, and run a query - using the API. By the end you’ll have a working personalized-RAG flow that you can plug into your own LLM prompt. If you’re new to HydraDB, the Core Concepts page is a useful 5-minute primer first. If you want the architecture-level story, see Architecture.

Install and initialize

Grab an API key from app.hydradb.com

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

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

// Install: npm install @hydradb/sdk@^2
import { HydraDBClient } from "@hydradb/sdk";

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

# No SDK needed — set your key once and reuse it.
export HYDRA_DB_API_KEY="your_api_key"

curl 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

Fast path: create, ingest, query

Create a database, add one memory to the default collection, wait for indexing, then query it.

import json, time

database = "my_first_database"

# 1. Create a database.
client.databases.create(database=database)

# 2. Wait until the database can accept data.
while True:
    infra = client.databases.status(database=database).data.infra
    if infra.ready_for_ingestion:
        break
    time.sleep(5)

# 3. Ingest one memory into the default collection.
ingest = client.context.ingest(
    type="memory",
    database=database,
    memories=json.dumps([
        {"text": "User prefers detailed technical explanations and dark mode"}
    ]),
)

id = ingest.data.results[0].id

# 4. Wait until the memory is indexed.
while True:
    status = client.context.status(
        database=database,
        ids=[id],
    ).data.statuses[0]

    if status.indexing_status == "completed":
        break
    if status.indexing_status == "errored":
        raise RuntimeError(status.error_message)

    time.sleep(2)

# 5. Search memories.
results = client.query(
    database=database,
    type="memory",
    query="What does the user prefer?",
)

print(results.data.chunks)

const database = "my_first_database";

// 1. Create a database.
await client.databases.create({ database: database });

// 2. Wait until the database can accept data.
while (true) {
  const { data } = await client.databases.status({ database: database });
  if (data?.infra.readyForIngestion) break;
  await new Promise((resolve) => setTimeout(resolve, 5_000));
}

// 3. Ingest one memory into the default collection.
const ingest = await client.context.ingest({
  type: "memory",
  database: database,
  memories: JSON.stringify([
    { text: "User prefers detailed technical explanations and dark mode" },
  ]),
});

const id = ingest.data.results[0].id;

// 4. Wait until the memory is indexed.
while (true) {
  const status = (await client.context.status({
    database: database,
    ids: [id],
  })).data.statuses[0];

  if (status.indexingStatus === "completed") break;
  if (status.indexingStatus === "errored") {
    throw new Error(status.errorMessage);
  }

  await new Promise((resolve) => setTimeout(resolve, 2_000));
}

// 5. Search memories.
const results = await client.query({
  database: database,
  type: "memory",
  query: "What does the user prefer?",
});

console.log(results.data.chunks);

export HYDRA_DB_API_KEY="your_api_key"
DATABASE="my_first_database"

# 1. Create a database.
curl -s -X POST 'https://api.hydradb.com/databases' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d "{\"database\":\"${DATABASE}\"}"

# 2. Wait until the database can accept data.
until curl -s "https://api.hydradb.com/databases/status?database=${DATABASE}" \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  | jq -e '.data.infra.ready_for_ingestion' > /dev/null; do
  sleep 5
done

# 3. Ingest one memory into the default collection.
ID=$(curl -s -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=memory" \
  -F "database=${DATABASE}" \
  -F 'memories=[{"text":"User prefers detailed technical explanations and dark mode"}]' \
  | jq -r '.data.results[0].id')

# 4. Wait until the memory is indexed.
while true; do
  STATUS=$(curl -s -G 'https://api.hydradb.com/context/status' \
    -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
    -H "API-Version: 2" \
    --data-urlencode "database=${DATABASE}" \
    --data-urlencode "ids=${ID}")

  INDEXING_STATUS=$(echo "$STATUS" | jq -r '.data.statuses[0].indexing_status')

  if [ "$INDEXING_STATUS" = "completed" ]; then break; fi
  if [ "$INDEXING_STATUS" = "errored" ]; then
    echo "$STATUS" | jq -r '.data.statuses[0].error_message'
    exit 1
  fi

  sleep 2
done

# 5. Search memories.
curl -s -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF | jq '.data.chunks'
{
  "database": "${DATABASE}",
  "type": "memory",
  "query": "What does the user prefer?"
}
EOF

What you have built

You have built the full retrieval loop: create an isolated workspace, ingest context, wait for indexing, query it, and pass the returned context to an LLM. HydraDB handles parsing, chunking, embedding, graph construction, and hybrid retrieval; your application sends the query and gets back the right slice of context. Steps 1 and 3 are asynchronous(runs in background) - HydraDB provisions infrastructure and indexes your content in the background, so each one needs a short polling loop. Steps 2, 4, and 5 run in real time. The same loop scales as your corpus grows; nothing in the code changes between 10 documents and 10,000.

You’re done

That’s the full HydraDB v2 loop: create a database, ingest knowledge and memories, verify processing, query, and feed the result to an LLM. Everything else in HydraDB - metadata filters, collections, graph traversal, forceful relations - layers on top of this foundation.

Where to go next

If you want to…	Read…
Understand how content gets stored and retrieved	Architecture
Tune query behavior (`alpha`, `mode`, `recency_bias`)	Query
Design a filterable metadata schema	Metadata
Scope data per user or workspace	Multi-Tenant
Format the LLM prompt from `RetrievalResult`	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

Concepts

Plugins

For Agents

Install and initialize

Fast path: create, ingest, query

What you have built

You’re done

Where to go next

​Install and initialize

​Fast path: create, ingest, query

​What you have built

​You’re done

​Where to go next

Install and initialize

Fast path: create, ingest, query

What you have built

You’re done

Where to go next