Rules and MEL.md

Rules are instructions Mel reads on every turn: how to run your tests, the style you want, the folders to leave alone. Write them once in a MEL.md file and every conversation in that project follows them. Mel also reads the AGENTS.md and CLAUDE.md files you may already keep for other agents, and rules you keep for yourself in Mel Drive.

Where Mel looks

Mel walks from the repository's root down to the folder you're working in and reads each file it finds. The global file comes first, then the outer folders, then the inner ones, so a subfolder's file reads as a refinement of its parent's. Inside one folder, AGENTS.md and CLAUDE.md come first and MEL.md, the most specific, comes last.

Settings ▸ Knowledge

The Knowledge page (in the Agents group of Settings) shows what the agent follows with every message. It has two tabs, Global and Project based.

Global holds your rules, which apply in every project:

• Search rules narrows the list as you type, by rule name or first line. If nothing matches, the page says so.
• + Add creates a new rules file (New rule.rules.md, with a short starter to replace) in your Drive folder and opens it in Mel's editor. A name that is already taken is skipped, never overwritten.
• Each rule is a card with its name and first line, the most recently changed first. Click a card to open the rule in the editor. A rule you move to the Drive's Trash leaves the list and no longer reaches the agent.
• Instructions in MEL.md, everywhere shows the path of your own MEL.md (~/.mel/MEL.md). Create makes it with a short starter and opens it; Open edits it once it exists.
• Use rules is the switch for your rules. Turning it off applies to new conversations.

Project based holds what belongs to one project:

• MEL.md in a project says where to put the file: at the project's root, or in a folder for that folder alone. The agent reads every MEL.md from the repository's root down to the folder you're working in.
• Pinned for this project lists what is pinned for the project in the active pane, each with Unpin.

What to put in it

Short, concrete lines work best:

# Rules for this repo
- Run tests with `pnpm test`. Fix what fails before you say you're done.
- Use TypeScript strict mode. No `any`.
- Never edit files under `vendor/`.

If AGENTS.md names a test command ("before you finish, run pnpm vitest run --changed"), Mel picks it up as the check to run.

Pinned files and notes

For something that isn't a rule, pin it for the project:

• /pin <path> pins a file from the project — or right-click it in the project explorer and choose Pin to agent context.
• /pin note <text> pins a short note.
• /pins lists what is pinned, and /unpin <n|path> removes one.

Pins are stored in Mel's own settings folder, outside your repository. They're read on every turn, after your rules, and a pin you make now is seen by the next turn.

Limitations

• MEL.md, AGENTS.md and CLAUDE.md share a budget of 12 KB per turn. When they're longer, the outer files are cut first, so the file closest to where you work loses nothing. Drive rules have their own 8 KB.
• A pinned file shows at most 16 KB, a note 2,000 characters, and a project up to 20 pins. Anything cut says so.
• A credential file, like an .env, can't be pinned. A path outside the project can't be pinned either.

Troubleshooting

Mel isn't following a rule. Check the file is in the folder you're working in or one above it, inside the same repository. Rules in a sibling folder aren't read. For Drive rules, check the Use rules switch on the Global tab of Settings ▸ Knowledge.

A pin says "missing". The file was moved or deleted. Pin it again at its new path.

FAQ

Do I need MEL.md if I already have AGENTS.md? No. Mel reads AGENTS.md and CLAUDE.md as they are. Add MEL.md only for rules meant for Mel.

Does a repository I clone get to pin things for me? No. Pins live in your own settings, never in the repository.