> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-t3code-rewrite-docs-declutter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand what to store, where to store it, and what a query returns.

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](/essentials/v2/multi-tenant) |
| **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](/essentials/v2/multi-tenant) |
| **Knowledge** | Documents and app content, such as the refund policy. | [Knowledge](/essentials/v2/knowledge) |
| **Memory** | A fact or conversation to remember, such as "this customer already restarted the app." | [Memories](/essentials/v2/memories) |
| **Query** | A search request, such as "What should this customer try next?" | [Query](/essentials/v2/query) |
| **Metadata** | Fields attached to content, such as `status: "approved"`, that you can use to filter results. | [Metadata](/essentials/v2/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](/essentials/v2/access-control) for document-level permissions.

## What does a query return?

[`POST /query`](/api-reference/v2/endpoint/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:

```json theme={"dark"}
{
  "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](/essentials/v2/query) to tune search and [Context Graphs](/essentials/v2/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](/essentials/v2/metadata) shows both storage and filter examples.

## Next steps

* [Quickstart](/get-started/v2/quickstart): save a memory, search it, and prepare the result for your model.
* [How to Use API Results](/essentials/v2/api-results): format results and build the model prompt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.