Skip to main content
A coding assistant is only as good as what it can find in the repository. This cookbook ingests a repository into HydraDB, which builds a context graph of its files, types, and functions, then gives a model one tool: search the code.

Prerequisites

  • A HydraDB API key from dashboard.hydradb.com, set as HYDRADB_API_KEY.
  • An OpenAI API key, set as OPENAI_API_KEY. HydraDB returns context, not answers, so any model works; swap the answer function below for your own.
  • Python 3.10 or later, with the SDKs: pip install "hydradb-sdk>=2.1.7,<3" openai.
Save this as hydra.py. Every cookbook imports it. It holds what every HydraDB application does around its own logic: wait for the database, check what an ingest accepted, wait for indexing, and pass query results to a model.
hydra.py

1. Create a database with one collection per repository

A collection per repository keeps a query inside one codebase.
cursor.py

2. Upload the files

Upload source files as documents. HydraDB reads .txt files as plain text and rejects code extensions such as .py, so add .txt to each filename. Derive each id from the file’s path, so that uploading a changed file again replaces the old version (upsert defaults to true). Keep the path in additional_metadata to cite it later. HydraDB extracts entities and relations itself; you supply no parsing rules.
cursor.py

3. Write the search tool

These are the query settings from the CodeWikiBench run: hybrid matching, thinking mode, graph context on, and eight chunks. thinking mode expands the query and reranks, which helps when an answer spans several files. Graph context returns the relations HydraDB extracted, such as which function calls which. Return the chunks, graph relationships, and linked-source context together as JSON. Keep each chunk’s repository path so the model can cite the file.
cursor.py

4. Let the model call it

Give the model the tool and loop until it stops calling it. The model decides what to search for and how many times, which is how it follows a question across files.
cursor.py

Run it

Indexing a few hundred files takes a few minutes. The answer should name specific files and cite a path for each claim.

Common mistakes

  • Uploading code with its own extension: a .py or .ts file is rejected with E1002 in the upload response. Upload it as .txt.
  • Querying before indexing finishes: files that are still queued or processing are not searchable. Wait for completed.
  • Random source IDs: without a stable id, uploading a changed file adds a second copy instead of replacing the first.
  • Using fast mode for cross-file questions: fast is one retrieval pass. Use thinking when the answer spans files.
  • Running it without setting REPO: the cookbook ships no sample code. Point REPO at a real checkout first.

Next steps

  • Query: API Reference: the fields of graph_context.
  • Context: add pull requests and Slack threads, so the assistant can answer why code was written the way it was.
  • Claude Code and Cursor plugins: give an existing coding agent HydraDB memory without building your own.