# Context files

Paths, formats and loading rules for catalogs, joins, knowledge, memory and skills.



Use this reference to place a rule where Querio can find it, and to check whether the agent will see its contents. Catalogs and knowledge belong to a datasource; memory and skills apply across the workspace. For what each kind of context is for, see [Context and accuracy](https://docs.querio.ai/understand/context). For editing and testing a rule in the app, use [Add and improve context](https://docs.querio.ai/guides/improve-context).

<a id="why-files"></a>



## Context root [#context-root]

`querio.toml` stays at the workspace root. Its `[context].root` points to the directory containing the context files:

```toml
[context]
root = "querio/"
```

Here, memory is at `querio/memory/MEMORY.md`. If `querio.toml`, its `[context]` table, or `root` is absent, the context root is `.` (the workspace root). Changing `root` selects a different directory; it does not move files.

Use a nonempty relative directory with forward slashes. Absolute paths, backslashes, `..`, `.git`, and `.querio` path components are rejected. The resolved path must stay inside the workspace, including through symlinks. Invalid TOML produces an error rather than falling back to `.`.

<a id="common-folders"></a>



<a id="how-querio-saves-context-for-you"></a>



### Paths below the context root [#paths-below-the-context-root]

| Path                                          | What Querio uses it for                                                              |
| --------------------------------------------- | ------------------------------------------------------------------------------------ |
| `datasources/<slug>/catalog.json`             | Tables, columns, descriptions, visibility, and joins for a selected datasource.      |
| `datasources/<slug>/kb/*.md`, `*.sql`, `*.py` | Rules and examples for a selected datasource. Direct files only.                     |
| `memory/MEMORY.md`                            | Workspace-wide instructions included in full.                                        |
| `skills/<name>/SKILL.md`                      | Procedures advertised by name, description, and path. Direct skill directories only. |
| `files/`                                      | Data for the files datasource, not automatically included as agent instructions.     |
| `automations/*.yaml`                          | Automation definitions, loaded separately from agent context.                        |

`<slug>` is an existing datasource slug. A context directory or catalog does not create a connection or grant query access. See [Datasources and credentials](https://docs.querio.ai/reference/datasources).

<a id="catalog"></a>



<a id="adding-tables"></a>



<a id="schemas"></a>



<a id="tables"></a>



<a id="columns"></a>



<a id="joins"></a>



## Catalog and joins [#catalog-and-joins]

Each datasource has one `catalog.json` with `schemas` and `joins` arrays. An empty catalog is `{"schemas": [], "joins": []}`. This example describes two tables and the join between them:

```json
{
  "schemas": [
    {
      "name": "public",
      "tables": [
        {
          "name": "orders",
          "description": "One row per order.",
          "columns": [
            { "name": "customer_id", "type": "integer" }
          ]
        },
        {
          "name": "customers",
          "columns": [
            { "name": "id", "type": "integer", "primary_key": true }
          ]
        }
      ]
    }
  ],
  "joins": [
    {
      "source_table": "public.orders",
      "source_column": "customer_id",
      "target_table": "public.customers",
      "target_column": "id",
      "type": "left",
      "cardinality": "many to one"
    }
  ]
}
```

| Object                | Required fields and defaults                                                                                                                               |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalog               | `schemas` and `joins` default to empty arrays.                                                                                                             |
| Schema                | String `name` required; `tables` defaults to an empty array.                                                                                               |
| Table                 | String `name` required; `columns` defaults to an empty array.                                                                                              |
| Column                | String `name` and `type` required; `primary_key` defaults to `false`; `foreign_key` defaults to an empty array.                                            |
| Schema, table, column | Optional string `description` and `created_at` default to empty strings; `visible` defaults to `true`.                                                     |
| Foreign key           | `references_schema`, `references_table`, and `references_column` are strings defaulting to empty strings.                                                  |
| Join                  | String `source_table`, `source_column`, `target_table`, and `target_column` required; `type` defaults to `inner`; `cardinality` defaults to `many to one`. |

Use schema-qualified table names in joins. Join type and cardinality guide analysis; they do not create database constraints or run a join. The loader accepts strings for these fields without enforcing a fixed list of values.

Descriptions, visibility, and joins are business context. Names, data types, keys, and timestamps describe datasource structure. Introspection can update that structure and rebuild joins from foreign keys, so review custom joins after a refresh.

`visible: false` removes a schema, table, or column from the agent's catalog guidance. Tables with no visible columns and schemas with no visible tables are also omitted. Joins remain listed even when their tables are hidden; update affected joins too. Visibility does not restrict database access. [Groups](https://docs.querio.ai/reference/groups) covers permissions.

A missing catalog gives the agent empty schema guidance. Invalid JSON, unknown fields, and wrong value types cause a loading error. Valid JSON does not prove the described tables or relationships exist in the database.

<a id="knowledge-base"></a>



<a id="frontmatter"></a>



## Knowledge files [#knowledge-files]

Place knowledge directly in `datasources/<slug>/kb/`. Only `.md`, `.sql`, and `.py` files at that level are selected; nested files and other extensions are ignored. They provide guidance and examples. Loading one does not execute its SQL or Python.

Each file can declare `name`, `description`, and `context` using plain `key: value` lines. This parser does not interpret full YAML: avoid quoted values, nested objects, and multiline values. `name` defaults to the filename without its extension; `description` defaults to empty. Use the description to say when the file is useful.

| In Context             | File metadata                         | What the agent receives                                                                                 |
| ---------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Always**             | `context: always`                     | The file body whenever its datasource is selected.                                                      |
| **Only when relevant** | Any other value, or no `context` line | Name, description, and path. The agent is instructed to read a matching file before using its guidance. |

### Markdown [#markdown]

Put metadata first, between `---` delimiters. For `datasources/warehouse/kb/reporting-time.md`:

```md
---
name: Reporting time
description: Time zone used for daily reporting
context: always
---

Group daily metrics by UTC calendar date.
```

### SQL and Python [#sql-and-python]

Start with consecutive metadata comment lines. SQL uses `--`; Python uses `#`. A blank or non-comment line ends the header. For `datasources/warehouse/kb/order-count.sql`:

```sql
-- name: Order count
-- description: Count orders from the orders table
-- context: reference

SELECT COUNT(*) AS order_count FROM public.orders;
```

For Python, the equivalent header starts with `# name: Order count`. Check any analysis using these examples against the actual data and your team's definitions.

## Memory [#memory]

`memory/MEMORY.md` is workspace-wide Markdown. Querio includes the whole file in agent context, so reserve it for durable rules that apply across datasources:

```md
# Memory

State the reporting period and time zone with every time-based result.
```

No metadata header is required. Other files in `memory/` are not automatically loaded as memory. A missing `MEMORY.md` contributes empty memory.

## Skills [#skills]

Put a reusable procedure in `skills/<name>/SKILL.md`. For example, `skills/review-metrics/SKILL.md`:

```md
---
name: review-metrics
description: Review metric definitions before presenting results
---

Check the metric definition, reporting period and aggregation grain.
Compare the result with a known answer before presenting it.
```

Skill metadata uses the same plain, single-line format as Markdown knowledge. Without metadata, the name defaults to the containing directory and the description is empty. A clear description helps the agent select the skill.

Querio advertises each skill's name, description, and path. The agent is instructed to read `SKILL.md` when the request matches it or invokes `/<skill-name>`; skill bodies are not all included in advance. Supporting files can be read when the skill calls for them, but are not separately discovered as skills. Use direct directories under `skills/` and the exact filename `SKILL.md`.

Querio supplies its built-in notebook instructions separately. A workspace copy of `notebook-code-mode/SKILL.md` does not replace them.

## Selection, files and reserved paths [#selection-files-and-reserved-paths]

Agent loading recognizes the paths above. It does not recursively search knowledge directories or discover skills at arbitrary depths. Automatic file discovery skips symlink files and paths reached through symlink directories.

`[context].include` and `[context].exclude` select committed paths for Git upload, not agent loading. They match repository-relative paths; exclusions win. Setting `root = "querio/"` does not prefix those patterns or limit uploads to that directory. See [Sync context with Git](https://docs.querio.ai/guides/git-sync).

Workspace file operations hide `.git` and `.querio` at any depth, `.gitignore` by default, and filenames ending in `.querio-tmp`. Other dotfiles are not automatically hidden. `.querio/` is reserved runtime state at the workspace root. For file permissions, versions, and publication boundaries, see [Files and versions](https://docs.querio.ai/reference/files-versions).

`files/` holds analysis data, not automatically loaded instructions; [Upload files for analysis](https://docs.querio.ai/guides/upload-files) covers its use. `automations/*.yaml` defines scheduled work and is not injected as knowledge, memory, or skills; see [Automations](https://docs.querio.ai/reference/automations).

<a id="refreshing-the-catalog"></a>



<a id="visibility"></a>



## Check what loaded [#check-what-loaded]

In **Context**, select the datasource and inspect its tables, **Joins**, **Catalog file**, and **Knowledge**, alongside workspace **Memory** and **Skills**. Check the displayed path against your configured root. Reading or editing files requires workspace file permissions; datasource access is separate.

Context shows a cached snapshot of recognized files. It includes `querio.toml`, catalogs, direct knowledge files, `MEMORY.md`, `SKILL.md`, and automation YAML, but not data under `files/`. Non-UTF-8 files and files containing null bytes are omitted. The snapshot has a 64 MiB source-content budget and a separate 64 MiB encoded limit. Seeing a file there does not prove a running agent loaded it.

In an analysis conversation, send `/reload` by itself. It rebuilds workspace context and skills from that session's current directory and reports a command count. The count includes built-in commands; it is not a file count. Reload does not switch working copies, publish edits, execute knowledge examples, or rerun notebook cells.

| If you see...                            | Check...                                                                                                                                           |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing knowledge or skill               | Path, filename case, supported extension, directory depth, and symlinks.                                                                           |
| Missing datasource guidance              | The conversation's selected datasource and its slug.                                                                                               |
| Empty memory                             | `memory/MEMORY.md` under the current context root.                                                                                                 |
| An indexed rule without its body         | **Only when relevant** advertises the file; the agent must read it. Use **Always** only for a rule needed on every question about that datasource. |
| A reload error                           | `querio.toml`, catalog JSON and field types, and readable text files.                                                                              |
| Saved edits absent from the conversation | The session's file version or working copy, then `/reload`. See [Files and versions](https://docs.querio.ai/reference/files-versions).             |

Finally, ask a question affected by one specific rule, inspect the generated analysis, and compare its result with a known answer. Follow [Add and improve context](https://docs.querio.ai/guides/improve-context) for that editing and verification workflow.