Core Concepts

Suppose you are building a support assistant. It needs your refund policy to answer questions and a customer’s previous support history to avoid suggesting a fix they already tried. HydraDB stores both; your application retrieves them and gives them to the model answering the customer.

Term	What it means in this example	Guide
Database	A separate workspace for one customer’s data, such as `acme_corp`. A query cannot search another database.	Databases and collections
Collection	A named group inside a database, such as `company_docs` or `user_123`. You choose the collection on writes and reads.	Databases and collections
Knowledge	Documents and app content, such as the refund policy.	Knowledge
Memory	A fact or conversation to remember, such as “this customer already restarted the app.”	Memories
Query	A search request, such as “What should this customer try next?”	Query
Metadata	Fields attached to content, such as `status: "approved"`, that you can use to filter results.	Metadata

Knowledge or memories?

Use knowledge for source material your agent should consult: files, wiki pages, tickets, or messages from apps. Use memories for information you want to carry between conversations: preferences, decisions, or what happened previously. These are content categories, not permissions. A private document is still knowledge. A memory belongs to one user only when your application stores and searches it in that user’s collection. For memories, infer: false (the default) stores what you send. With infer: true, HydraDB extracts useful facts or preferences from text or dialogue. Your application chooses what to save; HydraDB does not record interactions you have not sent it.

Where does the data go?

Create a database before adding content. Collections are created when you first write to them, so you do not need a separate collection-creation call. For the support assistant, store the refund policy in company_docs and the customer’s history in user_123. Keep using those same names when you search or check indexing status. If you omit collection, HydraDB uses the database’s default collection, not every collection. Collections organize data. Your backend must choose the collections the caller may search; use Access Control for document-level permissions.

What does a query return?

POST /query returns relevant passages, called chunks, with their source details. A source is one stored item, such as the refund-policy PDF or a memory. Your application puts the passages into a model’s prompt; the model writes the answer. The type field chooses the content category:

"knowledge": documents and app content.
"memory": saved facts and conversations.
"all": both categories from the collections you select.

For the support assistant, this request searches the shared policies and one customer’s history together:

{
  "database": "acme_corp",
  "collections": ["company_docs", "user_123"],
  "acl": ["customer@example.com"],
  "type": "all",
  "query": "What should this customer try next?"
}

Both collections must already exist. type: "all" includes both categories; it does not automatically include other collections or identify the user. The example uses customer@example.com as the caller. Your backend must derive acl from the signed-in user, not trust identities supplied by the client. Queries without acl do not enforce document permissions; documents without an ACL remain unrestricted. Search combines matching by meaning with keyword matching by default. It can also return a context graph: relationships extracted from the content, such as “the Payments team owns the billing service.” Start with the defaults; use Query to tune search and Context Graphs to work with relationships.

When do I need metadata?

Use metadata when a result must meet a rule: for example, only policies whose status is approved. Declare fields you use often in the database’s metadata schema (the field names and types you allow). Use additional_metadata for free-form fields such as a document’s author or external URL. The Metadata guide shows both storage and filter examples.

Next steps

Quickstart: save a memory, search it, and prepare the result for your model.
How to Use API Results: format results and build the model prompt.

Get Started

Usage

Concepts

Plugins

For Agents

Knowledge or memories?

Where does the data go?

What does a query return?

When do I need metadata?

Next steps

​Knowledge or memories?

​Where does the data go?

​What does a query return?

​When do I need metadata?

​Next steps

Knowledge or memories?

Where does the data go?

What does a query return?

When do I need metadata?

Next steps