Customize Maia with Context Files

Maia supports context files. Context files are a powerful way to embed reusable knowledge and best practices directly into every Maia prompt. These Markdown files live in your project and can include project context, business rules that affect pipeline design, data warehousing standards, and naming conventions.

Maia automatically reads all context files stored in your project and uses them to enhance its responses so you don't have to repeat your requirements every time.

What are context files?

Context files are Markdown files stored in the .matillion/maia/rules/ directory of your Git-backed project in the Designer. They provide reusable guidance to Maia in plain language.

Each time you interact with Maia, the content of all context files is included in the background, helping Maia understand your standards and preferences.

Note

If you choose to use context files, it's important to keep them updated. Maia won't prompt you to make updates, so make sure you regularly review and update them as your project evolves. Only .md (Markdown) files are supported as valid context files.

Note

When working with context files, it is important to note:

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—any other directory in the same project is fine.
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.

Add or edit context from the Maia panel

In addition to managing files from the Files panel, you can also work with context files directly in the Maia chat interface.

Add Context: This button appears at the top of the chat panel when no context is yet applied. It lets you create one immediately.
Edit Context: Once a context file is applied, this button allows you to open and edit the file without switching views.

These options let you apply guidance to Maia with minimal effort while you build your pipelines.

Where are context files stored?

To view your context files, navigate to .matillion/maia/rules/ in the Files panel.
Add a new Markdown file (e.g., naming.md, connections.md, standards.md, or context.md).
1. By default the file is named context.md, but you can create multiple files for different purposes and also rename context files.
Write your context content in plain Markdown. Maia supports headings, lists, and tables.

Example use cases

Scenario	How a context file helps
Contextualize the project	Give Maia context about your project.
Enforce naming conventions	Define how pipelines and resources should be named.
Build awareness	Include business-specific definitions, glossary terms, or standards.
Simplify reuse	Store connection information for systems that you will frequently use to build data pipelines

Example: Downloadable context file

Sample context files are available to help teams standardize project documentation, enforce naming conventions, and define best practices. These examples are intended to accelerate setup and ensure consistency across pipeline development.

Download example context files from Matillion Exchange

These files can be used to:

Apply consistent naming and modeling standards across teams.
Embed reusable business logic and glossary terms into Maia's prompts.
Simplify setup by reusing validated patterns and integration rules.

Using context files from the Matillion Exchange

To use a context file from the Matillion Exchange:

Download the files: Matillion Exchange - Maia Context Files.
Save the file in the .matillion/maia/rules/ directory of your project.
Commit your changes.
Once you have committed your changes, Maia will use the context file during future interactions.

Git workflow

To make sure your context file is available in all future branches, we recommend using this Git workflow:

Start from your default branch (for example, main).
Create a feature branch from main (e.g., adding-context-file).
Add the context file, then commit and push your changes.
Switch back to main, merge in the feature branch, and push the updated main branch.
All future branches created from main will automatically include the context file.

Got feedback or spotted something we can improve?

We'd love to hear from you. Join the conversation in the Documentation forum!