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 theanswerfunction below for your own. - Python 3.10 or later, with the SDKs:
pip install "hydradb-sdk>=2.1.7,<3" openai.
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
Common mistakes
- Uploading code with its own extension: a
.pyor.tsfile is rejected withE1002in the upload response. Upload it as.txt. - Querying before indexing finishes: files that are still
queuedorprocessingare not searchable. Wait forcompleted. - Random source IDs: without a stable
id, uploading a changed file adds a second copy instead of replacing the first. - Using
fastmode for cross-file questions:fastis one retrieval pass. Usethinkingwhen the answer spans files. - Running it without setting
REPO: the cookbook ships no sample code. PointREPOat 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.
