Context files

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. For editing and testing a rule in the app, use Add and improve context.

Context root

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

[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 ..

Paths below the context root

<slug> is an existing datasource slug. A context directory or catalog does not create a connection or grant query access. See Datasources and credentials.

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:

{
  "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"
    }
  ]
}

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. Users, roles and 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.

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.

Markdown

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

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

Group daily metrics by UTC calendar date.

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:

-- 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.md is workspace-wide Markdown. Querio includes the whole file in agent context, so reserve it for durable rules that apply across datasources:

# 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

Put a reusable procedure in skills/<name>/SKILL.md. For example, skills/review-metrics/SKILL.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

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 Use Git and CI 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.

files/ holds analysis data, not automatically loaded instructions; Upload files for analysis covers its use. automations/*.yaml defines scheduled work and is not injected as knowledge, memory, or skills; see Automations.

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.

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 for that editing and verification workflow.