How to use context file in Maia

About this guide
This guide explains how to create, manage, and use context files in Maia to apply consistent project standards across all pipeline prompts.

What are context files?

Context files are plain Markdown documents that embed reusable knowledge such as naming conventions, schema rules, and project goals directly into every interaction with Maia. When you ask Maia to build or modify a pipeline, these files are automatically included in the background to help Maia follow your project’s standards.

Why use context files?

Using context files helps you:

  • Avoid repeating the same instructions in every prompt
  • Standardize how pipelines are created across your team
  • Ensure naming, structure, and logic follow your organization’s best practices
  • Share project-specific knowledge in a scalable way

Where to store context files

Context files must be placed in the following location within your project:

.matillion/maia/rules/

You can create:

  • A single file, like context.md
  • Or multiple files based on topic, such as:
    • naming.md
    • standards.md
    • warehouse_design.md

Maia automatically reads all .md files in this folder and applies them to every prompt.

Important

  • Maia enforces a strict 12,000-character limit across all Markdown context files stored in the .matillion/maia/rules/ directory.
  • Files stored elsewhere (e.g., other folders under .matillion/) are ignored and do not count toward this limit.
  • If you have additional context, such as complex logic, detailed documentation, or full business process guides, we recommend storing that content outside of the rules directory, for example in the main directory of your project.
  • Then, within your context file, simply reference the location or link to that resource. This ensures that the essential guidance remains within the limit, while still pointing Maia users or teammates to deeper information.

How to add or edit context files

You can manage context files in two ways:

1. From the Files panel in the designer

  • Navigate to .matillion/maia/rules/
  • Right-click to add a new Markdown file
  • Use standard Markdown formatting (headings, bullet lists, code blocks)

2. From the Maia chat panel

  • Add Context: Appears when no context file exists yet
  • Edit Context: Appears once context is active, so you can update it without switching views

What to Include in a context file

Typical context file elements:

  • A brief project overview
  • Naming conventions (e.g., for tables, pipelines, or views)
  • Schema design rules (e.g., star schema structure)
  • Data source metadata
  • Business logic constraints

You can use standard Markdown features:

  • Headings (##)
  • Lists (- item)
  • Bold/italic text
  • Code blocks for SQL, YAML, or example config

Example context files

Start with one of these sample files, which you can customize:

These examples show different structures and standards you can reuse across projects.

Best practices

  • Keep each file short and focused
  • Use clear, natural language — Maia doesn’t require technical syntax
  • Update files as your project evolves
  • Use multiple context files to organize guidance by topic

Summary

Context files let you teach Maia your team’s standards once and reuse them automatically in every pipeline prompt. With just a few Markdown files, you can boost accuracy, consistency, and team alignment.