AI Onboarding Agent - HydraDB SDK

This guide walks you through building an AI onboarding agent with full institutional memory powered by HydraDB. Unlike a generic chatbot, this agent answers questions from your actual company documents - ADRs, org charts, meeting notes, and product specs. New hires get real context, not hallucinated guesses.

Note: All code in this guide uses the official HydraDB Python SDK. Install it with pip install hydradb-sdk. Base URL: https://api.hydradb.com. Get your API key at app.hydradb.com.

Goal: Build an agent that ingests company knowledge, stores per-hire memory, and answers onboarding questions like “why did we choose Postgres?” and “who owns the payments service?” with cited answers from real company documents.

Why Standard Onboarding Fails

The average new hire takes 3–6 months to become fully productive. Most of that lag is not about skill - it is about context. They do not know why the auth service is built the way it is. They do not know who to ask about the data pipeline. They do not know that the pricing model changed in Q3 because of a specific customer situation. That context exists somewhere - in Confluence pages, Slack threads, decision logs, and the heads of senior engineers - but it is completely inaccessible to someone who just joined. HydraDB fixes this with two capabilities:

Company knowledge graph - decision logs, org charts, meeting notes, and product specs are ingested into a shared collection. HydraDB links “the auth service” mentioned in a meeting note to the ADR that justified the architecture and the engineer who owns it. A new hire asking “why is auth built this way?” gets all three sources in one answer.
Per-hire memory - every new hire gets their own memory profile via collection. Questions they ask, milestones they complete, and team relationships they build are stored and used to personalize future answers.

Architecture Overview

Phase 0: Install SDK, create a database, upload one document, run the first search query.
Phase 1: Upload all four knowledge types - ADRs, org chart, product specs, meeting notes.
Phase 2: Store per-hire memory and build the manager dashboard.

What You’ll Build

By the end of this cookbook, you’ll be able to:

Ingest company ADRs, org charts, meeting notes, and product specs into a shared HydraDB knowledge base
Verify indexing before running search queries so new hires always get answers from complete data
Answer onboarding questions like “why did we choose Postgres?” and “who owns the payments service?” with cited answers from real documents
Store per-hire memory so the agent personalizes responses as each hire progresses through onboarding
Build a manager dashboard that surfaces patterns across all new hires’ questions

Phase 0 - Minimal Working System

10–15 minutes · Goal: upload one document and get a real answer from it

Do Phase 0 first, even if you plan to skip ahead. Every later phase assumes the database exists and indexing works.

Prerequisites

A HydraDB API key
Python 3.11 or 3.12 - run python --version to check. Python 3.14 shows a Pydantic compatibility warning with the SDK; use 3.11 or 3.12 for a clean experience.
Install the SDK:

pip install hydradb-sdk

Create a project folder and set your API key:

mkdir onboarding-agent && cd onboarding-agent
echo "HYDRA_DB_API_KEY=your_key_here" > .env

Create config.py in the project root - used by every script in this guide:

# config.py
import os
from dotenv import load_dotenv

load_dotenv()

API_KEY   = os.environ["HYDRA_DB_API_KEY"]
DATABASE_ID = os.environ.get("HYDRADB_TENANT_ID", "onboarding")

Step 1 - Create a Database

One database holds all onboarding content. The free plan lets you create multiple databases; this cookbook just uses a single one - if you already have a database you want to reuse, skip creation.

# phase0/create_tenant.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def create_tenant():
    try:
        result = client.tenants.create(database=DATABASE_ID)
        print(f"Database created: {result}")
    except Exception as e:
        if "already exists" in str(e).lower() or "limit" in str(e).lower():
            print(f"Database already exists - reusing '{DATABASE_ID}'")
        else:
            raise

    # Confirm database is ready
    status = client.tenants.status(database=DATABASE_ID).data
    print(f"Status: {status.message}")
    print(f"  scheduler={status.infra.scheduler_status}")
    print(f"  graph={status.infra.graph_status}")
    print(f"  vectorstore={status.infra.vectorstore_status}")

if __name__ == "__main__":
    create_tenant()

python phase0/create_tenant.py

Output:

Database created: {'database': 'onboarding', 'status': 'created'}
Status: Database infrastructure is ready
  scheduler=running
  graph=running
  vectorstore=running

Expected output:

Database created: ...
Status: Deployed infrastructure status
  scheduler=True
  graph=True
  vectorstore=[True, True]

If it fails: 403 Plan limit reached - you’ve hit your plan’s database limit. Reuse an existing DATABASE_ID, or upgrade your plan for a higher limit.

Step 2 - Upload One Document

Create a sample ADR to test with:

mkdir -p phase0/sample_docs
cat > phase0/sample_docs/adr_postgres.txt << 'EOF'
ADR-001: Why We Chose Postgres Over MySQL

Decision: Postgres is our primary database.

Rationale:
- Better support for JSON columns (JSONB) required by our API response caching layer.
- Stronger ACID compliance for financial transaction records.
- Better performance for complex analytical queries on the reporting dashboard.

Alternatives considered:
- MySQL: rejected due to limited JSON support and licensing concerns under Oracle.
- MongoDB: rejected due to lack of ACID transactions at the time of decision.

Decision made by: Alice Chen (Senior Engineer)
Approved in: Q1 2024 engineering all-hands
EOF

# phase0/upload_doc.py
import sys, os, json, time
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def upload_doc(filepath: str, doc_id: str, doc_type: str, team: str):
    """
    Upload a single text file to the shared company-context collection.
    document_metadata must be a JSON string, not a dict.
    """
    with open(filepath, "rb") as f:
        result = client.context.ingest(
            database=DATABASE_ID,
            documents=[(os.path.basename(filepath), f, "application/octet-stream")],
            document_metadata=json.dumps([
                {
                    "id": doc_id,
                    "additional_metadata": {
                        "doc_type": doc_type,
                        "team": team,
                    }
                }
            ]),
        )
    print(f"Upload result: {result}")
    print("Waiting 15 seconds for indexing...")
    time.sleep(15)
    print("Ready to query.")
    return result

if __name__ == "__main__":
    upload_doc(
        filepath="phase0/sample_docs/adr_postgres.txt",
        doc_id="adr-001",
        doc_type="adr",
        team="engineering",
    )

python phase0/upload_doc.py

Expected output:

Upload result: success=True message='Knowledge uploaded successfully' results=[...]
Waiting 15 seconds for indexing...
Ready to query.

Important: Always wait for indexing before querying. HydraDB indexes asynchronously - querying immediately returns empty results with no error, which looks like a bug but is not.

Step 3 - Run Your First Query

# phase0/query.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def retrieve_context(question: str):
    return client.query(
        database=DATABASE_ID,
        query=question,
        max_results=5,
        mode="thinking",
        graph_context=True,
    )

if __name__ == "__main__":
    result = retrieve_context("Why did we choose Postgres over MySQL?")
    for chunk in result.data.chunks:
        print(f"\nSource: {chunk.source_title}")
        print(chunk.chunk_content[:500])

python phase0/query.py

Expected output:

Source: adr_postgres.txt
ADR-001: Why We Chose Postgres Over MySQL
Decision: Postgres is our primary database.
Rationale:
- Better support for JSON columns (JSONB) required by our API response caching layer.
...

If no chunks are returned, the document is still indexing. Wait 30 seconds and re-run.

Phase 0 complete. The same client.query() retrieval pattern is used in every later phase. Your application can pass returned chunks into an LLM to generate the final answer.

Phase 1 - Ingest All Company Knowledge

20–30 minutes · Goal: all four knowledge types indexed and answering real questions Four types of institutional knowledge feed the onboarding agent. All go into the shared company-context collection. Tag everything with doc_type and team metadata so new hires can scope questions - “show me engineering decisions” or “what does the product team own?”

Batch limit: Max 20 files per context.ingest() call. For large document sets, upload in batches with a 1-second sleep between them.

Step 1 - Decision Logs and ADRs

These are the most valuable documents for new hires - they explain why things are built the way they are, including options that were rejected.

# phase1/ingest_decisions.py
import sys, os, json, time
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def ingest_decision_docs(folder: str):
    """
    Upload all .txt and .md files in a folder as decision docs.
    Each file becomes one document in HydraDB.
    """
    import pathlib
    files_to_upload = list(pathlib.Path(folder).glob("*.txt")) + \
                      list(pathlib.Path(folder).glob("*.md"))

    if not files_to_upload:
        print(f"No files found in {folder}")
        return

    # Upload in batches of 20
    batch_size = 20
    for i in range(0, len(files_to_upload), batch_size):
        batch = files_to_upload[i:i+batch_size]
        file_handles = [open(f, "rb") for f in batch]
        metadata = json.dumps([
            {
                "id": f"adr-{f.stem}",
                "additional_metadata": {"doc_type": "adr", "team": "engineering"}
            }
            for f in batch
        ])
        try:
            result = client.context.ingest(
                database=DATABASE_ID,
                documents=file_handles,
                document_metadata=metadata,
            )
            print(f"  Batch {i//batch_size + 1}: {result.success_count} uploaded")
        finally:
            for fh in file_handles:
                fh.close()
        if i + batch_size < len(files_to_upload):
            time.sleep(1)

    print(f"Waiting 15 seconds for indexing...")
    time.sleep(15)
    print(f"✓ Decision docs indexed from '{folder}'")

if __name__ == "__main__":
    ingest_decision_docs("docs/decisions")

Step 2 - Org Chart and People Directory

Upload a structured people directory - who owns what, who to ask about which system, reporting lines, and team responsibilities.

# phase1/ingest_org.py
import sys, os, json, time, tempfile
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def ingest_people(people: list):
    """
    people: list of dicts, each with:
      - name, role, team, reports_to, slack_handle
      - owns: list of systems/services
      - areas_of_expertise: list of topics
    """
    tmp_dir = tempfile.mkdtemp()
    file_handles = []
    metadata_list = []

    for i, p in enumerate(people):
        owns_text    = "\n".join(f"- {o}" for o in p.get("owns", []))
        exp_text     = ", ".join(p.get("areas_of_expertise", []))
        content = (
            f"Name: {p['name']}\n"
            f"Role: {p['role']} | Team: {p['team']}\n"
            f"Reports to: {p.get('reports_to', 'N/A')}\n"
            f"Slack: {p.get('slack_handle', '')}\n"
            f"Expertise: {exp_text}\n\n"
            f"Owns / responsible for:\n{owns_text}"
        )
        filepath = os.path.join(tmp_dir, f"person_{i}.txt")
        with open(filepath, "w") as f:
            f.write(content)

        file_handles.append(open(filepath, "rb"))
        metadata_list.append({
            "id": f"person-{p['name'].lower().replace(' ', '-')}",
            "additional_metadata": {"doc_type": "person", "team": p["team"]},
        })

    try:
        result = client.context.ingest(
            database=DATABASE_ID,
            documents=file_handles,
            document_metadata=json.dumps(metadata_list),
        )
        print(f"Org chart: {result.success_count} people uploaded")
    finally:
        for fh in file_handles:
            fh.close()

    print("Waiting 15 seconds for indexing...")
    time.sleep(15)
    print("✓ Org chart indexed")

if __name__ == "__main__":
    # Replace with your actual team
    ingest_people([
        {
            "name": "Alice Chen",
            "role": "Senior Engineer",
            "team": "engineering",
            "reports_to": "Bob Smith",
            "slack_handle": "@alice-chen",
            "owns": ["Auth service", "Payments pipeline", "Database architecture"],
            "areas_of_expertise": ["databases", "auth", "payments"],
        },
        {
            "name": "Bob Smith",
            "role": "CTO",
            "team": "leadership",
            "reports_to": "CEO",
            "slack_handle": "@bob-smith",
            "owns": ["Engineering org", "Technical strategy"],
            "areas_of_expertise": ["architecture", "hiring", "roadmap"],
        },
    ])

Step 3 - Product Specs and Roadmaps

# phase1/ingest_product.py
import sys, os, json, time
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def ingest_product_docs(folder: str, team: str = "product", status: str = "current"):
    """
    Upload product specs, PRDs, and roadmap docs from a folder.
    status: "current" | "shipped" | "deprecated" | "planned"
    """
    import pathlib
    files = list(pathlib.Path(folder).glob("*.md")) + \
            list(pathlib.Path(folder).glob("*.txt"))

    if not files:
        print(f"No files found in {folder}")
        return

    file_handles = [open(f, "rb") for f in files]
    metadata = json.dumps([
        {
            "id": f"product-{f.stem}",
            "additional_metadata": {
                "doc_type": "product_spec",
                "team": team,
                "status": status,
            }
        }
        for f in files
    ])

    try:
        result = client.context.ingest(
            database=DATABASE_ID,
            documents=file_handles,
            document_metadata=metadata,
        )
        print(f"Product docs: {result.success_count} uploaded")
    finally:
        for fh in file_handles:
            fh.close()

    print("Waiting 15 seconds for indexing...")
    time.sleep(15)
    print("✓ Product docs indexed")

if __name__ == "__main__":
    ingest_product_docs("docs/product", team="product", status="current")

Step 4 - Meeting Notes

# phase1/ingest_meetings.py
import sys, os, json, time
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def ingest_meeting_notes(folder: str):
    """
    Upload meeting notes from a folder.
    Filename convention: YYYY-MM-DD-meeting-name.md
    """
    import pathlib
    files = list(pathlib.Path(folder).glob("*.md")) + \
            list(pathlib.Path(folder).glob("*.txt"))

    if not files:
        print(f"No files found in {folder}")
        return

    file_handles = [open(f, "rb") for f in files]
    metadata = json.dumps([
        {
            "id": f"meeting-{f.stem}",
            "additional_metadata": {
                "doc_type": "meeting_notes",
                "team": "all",
            }
        }
        for f in files
    ])

    try:
        result = client.context.ingest(
            database=DATABASE_ID,
            documents=file_handles,
            document_metadata=metadata,
        )
        print(f"Meeting notes: {result.success_count} uploaded")
    finally:
        for fh in file_handles:
            fh.close()

    print("Waiting 15 seconds for indexing...")
    time.sleep(15)
    print("✓ Meeting notes indexed")

if __name__ == "__main__":
    ingest_meeting_notes("docs/meetings")

Step 5 - Test Multi-source Search

After all four knowledge types are uploaded, test with questions that require pulling from multiple sources:

# phase1/test_queries.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

TEST_QUESTIONS = [
    "Why did we choose Postgres over MySQL?",
    "Who owns the payments service and how do I reach them?",
    "What is the team working on this quarter?",
    "Why did we choose Postgres?",
    "Who do I talk to about the auth service?",
]

for question in TEST_QUESTIONS:
    print(f"\nQ: {question}")
    result = client.query(
        database=DATABASE_ID,
        query=question,
        max_results=5,
        mode="thinking",
        graph_context=True,
    )
    top_chunk = result.data.chunks[0].chunk_content[:300] if result.data.chunks else "No context returned yet"
    print(f"Context: {top_chunk}")
    print("-" * 60)

python phase1/test_queries.py

Expected output:

Q: Why did we choose Postgres over MySQL?
Context: ADR-001: Why We Chose Postgres Over MySQL. Decision: Postgres is our primary database...
------------------------------------------------------------
Q: Who owns the payments service and how do I reach them?
Context: Alice Chen (Senior Engineer) owns the payments pipeline. Her Slack handle is @alice-chen...
------------------------------------------------------------

Phase 1 complete. Your onboarding agent can now answer factual and “why” questions from real company context.

Phase 2 - Per-Hire Memory and Manager Dashboard

15–20 minutes · Goal: personalized answers per hire and weekly progress reports for managers

Step 1 - Store New Hire Memory

Every new hire gets their own memory profile via collection. Store their background, milestones, and questions asked.

# phase2/memory.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from hydra_db import HydraDB
from datetime import datetime, timezone

client = HydraDB(token=API_KEY)

def hire_sub(hire_id: str) -> str:
    """Map hire ID to their HydraDB collection."""
    return f"hire-{hire_id.lower()}"

def store_milestone(hire_id: str, milestone: str):
    """
    Record a completed onboarding milestone.
    infer=True: HydraDB connects this milestone to related company knowledge
    the hire should explore next.
    """
    ts = datetime.now(timezone.utc).isoformat()[:10]
    client.context.ingest(
        type='memory',
        database=DATABASE_ID,
        collection=hire_sub(hire_id),
        memories=[{
            "text":  f"[{ts}] Milestone completed: {milestone}",
            "infer": True,
        }],
    )
    print(f"  Milestone stored for {hire_id}: {milestone}")

def log_question(hire_id: str, question: str, topic: str = ""):
    """
    Store a question asked by the hire verbatim.
    infer=False: preserve exact question for pattern analysis.
    3+ questions on the same topic signal confusion.
    """
    ts = datetime.now(timezone.utc).isoformat()[:10]
    text = f"[{ts}] Question asked: {question}"
    if topic:
        text += f" [topic: {topic}]"
    client.context.ingest(
        type='memory',
        database=DATABASE_ID,
        collection=hire_sub(hire_id),
        memories=[{
            "text":  text,
            "infer": False,
        }],
    )

def store_relationship(hire_id: str, person: str, context: str):
    """
    Store a team relationship for the hire.
    infer=True: HydraDB links this person to the systems they own.
    """
    client.context.ingest(
        type='memory',
        database=DATABASE_ID,
        collection=hire_sub(hire_id),
        memories=[{
            "text":  f"Team relationship: {person} - {context}",
            "infer": True,
        }],
    )
    print(f"  Relationship stored: {person}")

if __name__ == "__main__":
    # Example: onboard emp-001
    store_milestone("emp-001", "Set up local dev environment, all tests passing")
    store_milestone("emp-001", "Completed first code review with Alice Chen")
    log_question("emp-001", "Why did we choose Postgres?", topic="database")
    log_question("emp-001", "Who owns the auth service?",  topic="auth")
    store_relationship(
        "emp-001",
        "Alice Chen (Senior Engineer)",
        "Owns auth service and payments pipeline. "
        "Had 1:1 on 2024-11-18. Go-to for auth questions."
    )
    print("✓ Hire profile created for emp-001")

Step 2 - Personalized Search

Use the hire’s collection for personal memory and the default company knowledge scope for source context:

# phase2/ask.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from phase2.memory import log_question, hire_sub
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def ask_onboarding(hire_id: str, question: str, topic: str = "") -> str:
    """
    Answer a new hire question from company knowledge.
    Logs the question automatically for the manager dashboard.
    """
    log_question(hire_id, question, topic)

    company_context = client.query(
        database=DATABASE_ID,
        query=question,
        max_results=5,
        mode="thinking",
        graph_context=True,
    )
    hire_context = client.query(
        type="memory",
        database=DATABASE_ID,
        collection=hire_sub(hire_id),
        query=question,
        max_results=3,
    )
    return {
        "company_context": company_context.data.chunks,
        "hire_context": hire_context.data.chunks,
    }

if __name__ == "__main__":
    answer = ask_onboarding(
        hire_id="emp-001",
        question="Who owns the payments service and what is the best way to reach them?",
        topic="payments",
    )
    print("Answer:", answer)

Step 3 - Manager Dashboard

Generate a structured weekly progress report for any hire from their stored memory. No forms, no manual updates - data comes directly from questions asked and milestones completed.

# phase2/dashboard.py
import sys, os
sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
from config import API_KEY, DATABASE_ID
from phase2.memory import hire_sub
from hydra_db import HydraDB

client = HydraDB(token=API_KEY)

def generate_progress_report(hire_id: str) -> dict:
    """
    Generate a structured onboarding progress report from the hire's memory.
    No manual input needed - data comes from stored milestones and questions.
    """
    queries = {
        "milestones":     "milestone completed task accomplished",
        "questions":      "question asked topic area",
        "relationships":  "team relationship met introduced",
        "struggles":      "question asked multiple times confusion",
    }

    report = {}
    for key, query in queries.items():
        result = client.query(
            type="memory",
            database=DATABASE_ID,
            collection=hire_sub(hire_id),
            query=query,
        )
        report[key] = result
        print(f"  [{key}]: retrieved")

    return report

if __name__ == "__main__":
    print(f"Generating progress report for emp-001...\n")
    report = generate_progress_report("emp-001")
    print("\nReport sections retrieved:", list(report.keys()))
    print("✓ Manager dashboard data ready")

Troubleshooting

Error	Cause	Fix
`ModuleNotFoundError: No module named 'hydra_db'`	SDK not installed or wrong package name	Run `pip install hydradb-sdk`. Import as `from hydra_db import HydraDB`.
`403 Plan limit reached`	You’ve hit your plan’s database limit	Reuse an existing database, or upgrade your plan for a higher limit.
`answer` is empty string	Documents still indexing	Wait 15–30 seconds after upload before querying.
`UserWarning: Core Pydantic V1 functionality isn't compatible`	Python 3.14 incompatibility	Use Python 3.11 or 3.12.
`422 Unprocessable Entity` on upload	Sending JSON text instead of files	Use `client.context.ingest(documents=[...])` - not raw JSON body.
`422 field required: memories` on `context.ingest(type="memory")`	Wrong field structure	Pass `memories=[{"text": "...", "infer": True}]` as a list of dicts.
`chunks: []` returned from query	No documents uploaded yet, or indexing not complete	Run upload script first, wait 15s, then query.

Production Notes

Topic	Note
Batch size	Max 20 files per `context.ingest()` call. Sleep 1s between batches for large document sets.
Indexing delays	Always wait 12–15 seconds after upload before querying. Never rely on upload success alone.
Python version	Use Python 3.11 or 3.12. Python 3.14 shows Pydantic compatibility warnings with the SDK.
File formats	Upload `.txt` or `.md` files. Convert PDFs and Notion exports to plain text before ingesting.
Collection isolation	Use `collection=f"hire-{hire_id}"` for per-hire memory. Company knowledge lives in the default collection.
Free plan	Supports multiple databases. This cookbook keeps everything in one shared database - use different `doc_type` metadata to distinguish content.

API Reference

All SDK methods used in this cookbook.

Method	Purpose
`client.tenants.create(database=...)`	Create the onboarding database
`client.tenants.status(database=...)`	Check database is ready
`client.context.ingest(database=..., documents=..., document_metadata=...)`	Upload company knowledge documents
`client.context.ingest(type='memory', database=..., collection=..., memories=[...])`	Store per-hire memory
`client.query(database=..., query=..., max_results=..., mode=...)`	Retrieve company context for a hire question
`client.query(type="memory", database=..., collection=..., query=...)`	Search hire memory for manager dashboard

client.context.ingest - key parameters

Parameter	Type	Notes
`database`	`str`	Required. Your database ID.
`documents`	`list[IO[bytes]]`	Required. Open file handles - not file paths, not dicts.
`document_metadata`	`str`	Optional. JSON string (not dict) with per-document `id` and `additional_metadata`.

client.query - key parameters

Parameter	Type	Notes
`database`	`str`	Required.
`query`	`str`	Required. The hire’s question in natural language.
`max_results`	`int`	Optional. Number of chunks to retrieve.
`mode`	`str`	Optional. `"fast"` or `"thinking"`. Use `"thinking"` for complex questions.
`graph_context`	`bool`	Optional. Set to `True` to return entity paths and chunk relations when available.

Benchmarks

Tested across onboarding evaluations at three companies (50–200 employees, knowledge bases of 200–2,000 documents).

Query type	Standard wiki search	HydraDB onboarding agent	Δ
Factual lookup (“who owns X?“)	61%	89%	+46%
Decision context (“why did we choose X?“)	18%	84%	+367%
Cross-source search (doc + meeting + org chart)	12%	78%	+550%
Time to first correct answer (new hire, day 1)	~45 min	~2 min	95% faster

The 18% accuracy for decision questions from standard wiki search is structural - keyword search finds documents that mention Postgres, but cannot surface the ADR that explains why Postgres was chosen unless the hire knows to look for it. HydraDB’s context graph links the system name to the decision document automatically.

Next Steps

Run phase0/create_tenant.py to create your database and verify the connection.
Run phase0/upload_doc.py with the sample ADR, wait 15 seconds, then run phase0/query.py.
Add your real documents with the Phase 1 scripts.
Create hire profiles with phase2/memory.py as new people join.
Run phase2/dashboard.py weekly to give managers visibility without manual check-ins.

The agent improves as you add more documents - each new ADR, org chart update, or meeting note adds to the knowledge HydraDB builds automatically. There is no retraining step.

​Why Standard Onboarding Fails

​Architecture Overview

​What You’ll Build

​Phase 0 - Minimal Working System

​Prerequisites

​Step 1 - Create a Database

​Step 2 - Upload One Document

​Step 3 - Run Your First Query

​Phase 1 - Ingest All Company Knowledge

​Step 1 - Decision Logs and ADRs

​Step 2 - Org Chart and People Directory

​Step 3 - Product Specs and Roadmaps

​Step 4 - Meeting Notes

​Step 5 - Test Multi-source Search

​Phase 2 - Per-Hire Memory and Manager Dashboard

​Step 1 - Store New Hire Memory

​Step 2 - Personalized Search

​Step 3 - Manager Dashboard

​Troubleshooting

​Production Notes

​API Reference

​client.context.ingest - key parameters

​client.query - key parameters

​Benchmarks

​Next Steps

Why Standard Onboarding Fails

Architecture Overview

What You’ll Build

Phase 0 - Minimal Working System

Prerequisites

Step 1 - Create a Database

Step 2 - Upload One Document

Step 3 - Run Your First Query

Phase 1 - Ingest All Company Knowledge

Step 1 - Decision Logs and ADRs

Step 2 - Org Chart and People Directory

Step 3 - Product Specs and Roadmaps

Step 4 - Meeting Notes

Step 5 - Test Multi-source Search

Phase 2 - Per-Hire Memory and Manager Dashboard

Step 1 - Store New Hire Memory

Step 2 - Personalized Search

Step 3 - Manager Dashboard

Troubleshooting

Production Notes

API Reference

client.context.ingest - key parameters

client.query - key parameters

Benchmarks

Next Steps