Quickstart

What you’ll build

Step 3 is async - HydraDB parses, chunks, embeds, and graphs your content in the background. Steps 1, 2, 4, and 5 run in real time.

Prerequisites

An API key from app.hydradb.com
A backend that can make HTTP calls, or one of the HydraDB SDKs

Base URL: https://api.hydradb.com
Authentication: Authorization: Bearer $HYDRA_DB_API_KEY on every request (substitute the actual key value)

Install the SDK (optional)

# No install needed - use curl directly

npm install @hydradb/sdk

pip install hydradb-sdk

Initialize a client:

# Set your key as an environment variable
export HYDRA_DB_API_KEY="your_api_key"

import { HydraDBClient } from "@hydradb/sdk";

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

import os
from hydra_db import HydraDB

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

Step 1 - Create a Tenant

A tenant is your fully isolated workspace. Everything you ingest and recall lives inside it.

curl -X POST 'https://api.hydradb.com/tenants/create' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "my_first_tenant"}'

const response = await client.tenant.create({
  tenant_id: "my_first_tenant",
});

response = client.tenant.create(tenant_id="my_first_tenant")

Response:

{
  "status": "accepted",
  "tenant_id": "my_first_tenant",
  "message": "Tenant creation started in the background. Use GET /tenants/infra/status?tenant_id=... to check progress."
}

Receiving a "status": "accepted" response indicates that the creation process has successfully started, but it does not imply that the tenant is fully provisioned.

Tenant creation is asynchronous. Poll until provisioning completes before ingesting:

curl 'https://api.hydradb.com/tenants/infra/status?tenant_id=my_first_tenant' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY"

const status = await client.tenant.getInfraStatus({
  tenant_id: "my_first_tenant"
});

status = client.tenant.get_infra_status(tenant_id="my_first_tenant")

Response:

{
  "tenant_id": "my_first_tenant",
  "org_id": "free",
  "infra": {
    "scheduler_status": true,
    "graph_status": true,
    "vectorstore_status": [true, true]
  },
  "message": "Deployed infrastructure status"
}

Wait until infra.scheduler_status, infra.graph_status, and both values in infra.vectorstore_status are true before ingesting.

Typical provisioning time depends on plan: 1–2 minutes for Free and Ship plans, 4–5 minutes for Enterprise plans (which provision physically-isolated infrastructure). Allow up to ~5 minutes in any polling loop you write.

Step 2 - Ingest Data

HydraDB has two distinct data primitives. Pick the one that matches what you’re ingesting.

Knowledge - documents and app sources

Knowledge is shared, tenant-wide content that all users can recall: PDFs, DOCX files, Slack threads, Notion pages, CSVs.

curl -X POST 'https://api.hydradb.com/ingestion/upload_knowledge' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -F "tenant_id=my_first_tenant" \
  -F "files=@/path/to/contract.pdf"

const result = await client.upload.knowledge({
  tenant_id: "my_first_tenant",
  files: [{ path: "/path/to/contract.pdf", filename: "contract.pdf", contentType: "application/pdf" }]
});

with open("/path/to/contract.pdf", "rb") as f:
    result = client.upload.knowledge(
        tenant_id="my_first_tenant",
        files=[("contract.pdf", f, "application/pdf")]
    )

Response:

{
  "success": true,
  "results": [
    { "source_id": "ef3ea754019855e2b39e9ab5c2d26096", "filename": "contract.pdf", "status": "queued" }
  ],
  "success_count": 1,
  "failed_count": 0
}

Memories - user preferences and conversation history

Memories are user-specific, dynamic context: preferences, chat history, behavioral signals, inferred traits. Each memory is scoped to a sub_tenant_id and is fully isolated from other users.

curl -X POST 'https://api.hydradb.com/memories/add_memory' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "sub_tenant_id": "user_alex_123",
    "memories": [
      {
        "text": "User prefers detailed technical explanations and dark mode",
        "infer": true,
        "user_name": "Alex"
      }
    ]
  }'

const result = await client.upload.addMemory({
  tenant_id: "my_first_tenant",
  sub_tenant_id: "user_alex_123",
  memories: [
    {
      text: "User prefers detailed technical explanations and dark mode",
      infer: true,
      user_name: "Alex",
    },
  ],
});

result = client.upload.add_memory(
    tenant_id="my_first_tenant",
    sub_tenant_id="user_alex_123",
    memories=[
        {
            "text": "User prefers detailed technical explanations and dark mode",
            "infer": True,
            "user_name": "Alex",
        }
    ],
)

Response:

{
  "success": true,
  "results": [
    { "source_id": "1d50e5cd7c196a2bbcc1a59b037b3a44", "status": "queued", "infer": true }
  ],
  "success_count": 1,
  "failed_count": 0
}

Both paths return a source_id you can use to track processing in the next step.

Step 3 - Verify Processing

Ingestion is asynchronous. Content passes through a pipeline before it is searchable:

curl -X POST \
  'https://api.hydradb.com/ingestion/verify_processing?file_ids=<source_id>&tenant_id=my_first_tenant' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY"

const status = await client.upload.verifyProcessing({
  tenant_id: "my_first_tenant",
  sub_tenant_id: "my_first_tenant",
  file_ids: ["<source_id>"],
});

status = client.upload.verify_processing(
    tenant_id="my_first_tenant",
    sub_tenant_id="my_first_tenant",
    file_ids=["<source_id>"],
)

Response:

{
  "statuses": [
    {
      "file_id": "<source_id>",
      "indexing_status": "completed",
      "success": true
    }
  ]
}

Poll every few seconds until indexing_status is "completed". Most documents index in under 60 seconds; larger documents may take up to 5 minutes.

Step 4 - Recall Context

HydraDB exposes two recall endpoints - one per store. Use the one that matches what you ingested.

For Knowledge - documents

curl -X POST 'https://api.hydradb.com/recall/full_recall' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "query": "What are the pricing tiers?",
    "max_results": 5,
    "mode": "fast",
    "graph_context": true
  }'

const result = await client.recall.fullRecall({
  tenant_id: "my_first_tenant",
  query: "What are the pricing tiers?",
  max_results: 5,
  mode: "fast",
  graph_context: true
});

result = client.recall.full_recall(
    tenant_id="my_first_tenant",
    query="What are the pricing tiers?",
    max_results=5,
    mode="fast",
    graph_context=True
)

For Memories - user preferences

curl -X POST 'https://api.hydradb.com/recall/recall_preferences' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "sub_tenant_id": "user_alex_123",
    "query": "answer style and tone preferences",
    "mode": "fast",
    "max_results": 3
  }'

const memories = await client.recall.recallPreferences({
  tenant_id: "my_first_tenant",
  sub_tenant_id: "user_alex_123",
  query: "answer style and tone preferences",
  mode: "fast",
  max_results: 3,
});

memories = client.recall.recall_preferences(
    tenant_id="my_first_tenant",
    sub_tenant_id="user_alex_123",
    query="answer style and tone preferences",
    mode="fast",
    max_results=3,
)

Key flags:

mode: "thinking" - multi-stage recall with query expansion and reranking. Better results, higher latency. Default is "fast".
graph_context: true - enriches results with entity relationships from the knowledge graph. Only applies to full_recall.

Sample response (full_recall):

{
  "chunks": [
    {
      "chunk_uuid": "a1b2c3d4-...",
      "source_id": "doc_12345",
      "chunk_content": "Tiered pricing: $29/month Starter, $79/month Pro, $199/month Enterprise...",
      "source_title": "Q4 Pricing Strategy",
      "relevancy_score": 0.92
    }
  ],
  "graph_context": {
    "query_paths": [
      {
        "triplets": [
          {
            "source": { "name": "Pricing Strategy" },
            "relation": { "canonical_predicate": "OWNED_BY" },
            "target": { "name": "Product Team" }
          }
        ]
      }
    ],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  }
}

relevancy_score: A metric to evaluate each chunk’s relevance to the query. Ranges from 0.0 to 2.0.

chunks is retrieved content ranked by relevance. graph_context contains entity relationships extracted from your data - useful for reasoning about how things connect, not just what was said.

Step 5 - Pass it to your LLM

For personalized, grounded answers, call both full_recall and recall_preferences in parallel and merge the results into one prompt:

# Run both recall calls, then merge in your application layer

const [knowledge, memories] = await Promise.all([
  client.recall.fullRecall({
    tenant_id: "my_first_tenant",
    query: "What are the pricing tiers?",
    mode: "thinking",
    max_results: 5,
    graph_context: true,
  }),
  client.recall.recallPreferences({
    tenant_id: "my_first_tenant",
    sub_tenant_id: "user_alex_123",
    query: "answer style and tone preferences",
    mode: "thinking",
    max_results: 3,
  }),
]);

const knowledgeCtx = buildContextString(knowledge);
const memoryCtx = buildContextString(memories);

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content: "Answer using only the provided context. Match the user's preferred style.",
    },
    {
      role: "user",
      content: `User preferences:\n${memoryCtx}\n\nRelevant docs:\n${knowledgeCtx}\n\nQuestion: What are the pricing tiers?`,
    },
  ],
});

import asyncio
from hydra_db import AsyncHydraDB

async_client = AsyncHydraDB(token=os.environ["HYDRA_DB_API_KEY"])

async def run():
    knowledge, memories = await asyncio.gather(
        async_client.recall.full_recall(
            tenant_id="my_first_tenant",
            query="What are the pricing tiers?",
            mode="thinking",
            max_results=5,
            graph_context=True,
        ),
        async_client.recall.recall_preferences(
            tenant_id="my_first_tenant",
            sub_tenant_id="user_alex_123",
            query="answer style and tone preferences",
            mode="thinking",
            max_results=3,
        ),
    )
    knowledge_ctx = build_context_string(knowledge)
    memory_ctx = build_context_string(memories)
    return knowledge_ctx, memory_ctx

For the build_context_string() helper, see How to Use API Results.

You’re done

That’s the full loop: create a tenant, ingest Knowledge and Memories, wait for processing, recall context, feed it to an LLM. Everything else in HydraDB - metadata filters, sub-tenants, graph traversal, personalization - builds on this foundation. Where to go next:

Essentials → Memories - how user-scoped memory works
Essentials → Knowledge - how document ingestion works
Essentials → Recall - parameters, modes, and tuning
API Reference - full endpoint documentation
Cookbooks - end-to-end use case guides

Stuck? Reach out at [email protected].

Get Started

Essentials

Plugins

For Agents

What you’ll build

Prerequisites

Install the SDK (optional)

Knowledge - documents and app sources

Memories - user preferences and conversation history

For Knowledge - documents

For Memories - user preferences

You’re done

​What you’ll build

​Prerequisites

​Install the SDK (optional)

​Knowledge - documents and app sources

​Memories - user preferences and conversation history

​For Knowledge - documents

​For Memories - user preferences

​You’re done

What you’ll build

Prerequisites

Install the SDK (optional)

Knowledge - documents and app sources

Memories - user preferences and conversation history

For Knowledge - documents

For Memories - user preferences

You’re done