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 are stored 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

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

Only .md (Markdown) files are supported as valid context files.
Maia enforces a strict 12,000-character limit across all Markdown context files stored in the .matillion/maia/rules/ directory. Additional context files stored in different folders are ignored unless you tell Maia to reference them as described in Accessing additional context files. These files do not count toward the character limit.
It's important to keep context files updated. Maia won't automatically prompt you to make updates unless you ask it to, so make sure you regularly review and update them as your project evolves.

Use cases

Context files can help you to:

Contextualize the project: Give Maia context about your work so it is better able to understand your needs.
Enforce naming conventions: Define how pipelines and resources should be named, in order to ensure consistency.
Build awareness: Provide Maia with business-specific definitions, glossary terms, or standards so it can understand your data.
Simplify reuse: Store connection information, such as usernames, for systems that you will frequently use to build data pipelines.

Where are context files stored?

Context files must be stored in a folder with the following path: .matillion/maia/rules/. This folder is created automatically if you add a context file in the Maia interface. If you create a context file from scratch, you need to create this folder structure first. The rules folder can be accessed in the Files panel in Designer.

Note

You can add additional context files, such as naming-conventions.md, connections.md, standards.md, or context.md to your root folder, as described in Accessing additional context files.

We do not recommend storing additional context files in the .matillion/... folder, as this folder is a reserved location in your project. Storing additional files in this folder may cause issues in the future.

Add or edit context files in the Maia interface

You can work with context files directly in the Maia chat interface by clicking the corresponding option in the top right of the Maia chat interface:

Add context: This button appears at the top of the chat panel when no context file exists. Clicking this option automatically creates the .matillion/maia/rules/ folder and a Markdown file called context.md.
Edit context: After a context file has been created, this button allows you to open and edit the file without switching views. If you have more than one context file in the .matillion/maia/rules/ folder, this button will open the context file that was created first.

Add or edit context files in the Files panel

To add a new context file if no context file exists, follow these steps. If you have already created at least one context file, skip steps 1 and 2.

Create a top-level folder called .matillion.
In the .matillion folder, create a folder called maia.
In the maia folder, create a folder called rules.
Click the three dots ... next to the rules folder, then Add, then Markdown file.
Write your context content in plain Markdown. Maia supports headings, lists, and tables.

Accessing additional context files

Maia can also access additional context, such as complex logic, detailed documentation, or full business process guides. Unlike your static context files, which Maia always reads, Maia will dynamically choose when to refer to your additional files. This allows Maia to use situational information and use-case-specific context to respond to your prompts. For example, if you tell Maia "When building a transformation pipeline, always refer to the comprehensive standards in additional-context/transformation_standards.md", Maia will always refer to this additional context file when building transformation pipelines, but not orchestration pipelines.

To allow Maia to access additional context files:

Store this content in a directory other than the .matillion/... directory. Any other directory in your project is suitable. For example, you could create a new folder called additional-context at the root level and add a new Markdown file called naming-conventions.
Click Edit context in the Maia chat interface to edit your context file.
In your context file, reference the location of your additional context. For example, you could tell Maia "Follow all the rules listed in the naming-conventions file stored in the additional-context folder."

This ensures that the context file containing essential information remains within the character limit, while still allowing Maia users and teammates to access more detailed information.

Using context files from the Matillion Exchange

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. Example context files are available from the 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.

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.

Merging context files to your main branch

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!