Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What are Windsurf rules?

Windsurf rules are Markdown instructions the Cascade agent follows in every workspace or in one project. Global rules live in one file under ~/.codeium/windsurf/memories; workspace rules are one file per rule in the project, each with a trigger: always on, glob, model decision or manual. Cascade also writes its own memories, stored locally, not in the repo.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

Always-on and glob rules enter Cascade's system prompt in full; a model-decision rule sends only its description, and Cascade opens it when relevant.global_rules.mdalways onrules/migrations.mdtrigger: globrules/perf.mdmodel_decisionCascadesystem prompt per messageyoufull text, every messagewhen a match is editeddescription onlyreads it if relevant@rule-name for manual
  1. Global rules: one file, ~/.codeium/windsurf/memories/global_rules.md, always on in every workspace, up to 6,000 characters. Edit it under Customizations.

  2. Workspace rules: one Markdown file per rule under .windsurf/rules (the docs now prefer .devin/rules), up to 12,000 characters each, committed with the project.

  3. Front matter sets the trigger: always_on puts the whole file in the system prompt; glob attaches it when matching files are edited; manual waits for @name.

  4. model_decision puts only the description in the system prompt. Cascade reads the full rule when it judges that the description fits the task in hand.

  5. Memories are different: Cascade writes them itself during chats, keeps them in ~/.codeium/windsurf/memories tied to the workspace, and never commits them.

Source: Windsurf docs: Memories and rules

Windsurf rules versus memories

Windsurf's Cascade agent has two kinds of persistent context and they are easy to mix up. Rules are files you write: a global one for yourself and per-rule files in the workspace. Memories are notes Cascade generates on its own when it meets something it considers worth keeping, or when you ask it to "create a memory of" a decision. Both are stored under ~/.codeium/windsurf/memories, but only rules in the workspace are meant to be committed. Memories stay on your machine, are tied to the workspace they came from, and cost no credits.

The docs are direct about which to prefer for durable knowledge: a rule or an AGENTS.md, because those are version-controlled and shareable. Memories also apply only to the legacy Cascade agent; the newer Devin Local agent does not persist them, and the docs point to a migration wizard that turns them into skills.

Example: a glob rule for migrations

---
trigger: glob
globs: db/migrations/**
description: How we write schema migrations
---
- Expand first: add columns and tables now, drop or rename in a later release.
- Every migration needs a down() that actually reverses it.
- Never edit a migration that has shipped; add a new one.

With trigger: glob, this loads only while Cascade reads or edits a file under db/migrations. Change it to model_decision and the behaviour flips: only the description line goes into the system prompt, and Cascade decides from that one sentence whether to open the rest. A vague description is the usual reason such a rule never fires.

Where the files live and how they load

Global rules are a single file, ~/.codeium/windsurf/memories/global_rules.md, always on, limited to 6,000 characters. Workspace rules live in .windsurf/rules/*.md, with .devin/rules/*.md now listed as the preferred location, one rule per file and 12,000 characters per file. The old single .windsurfrules at the workspace root is still read. Each workspace file picks a trigger in its front matter: always_on, glob, model_decision or manual. A manual rule stays out of the system prompt until you type @rule-name in the Cascade input. A root AGENTS.md is treated as an always-on rule without front matter.

You can edit any of this from the Customizations panel in Cascade: click a rule or a memory, then Edit.

Common mistakes

  • Writing generic coding advice. The docs say to skip it; Cascade already knows the basics. Spend the characters on what is specific to this codebase.
  • Long, vague rules. Overly long or unclear rules confuse Cascade, in the docs' own words. Bullets, numbered lists and XML tags to group related rules help.
  • Expecting a model_decision rule to always be present. Only its description is. If the rule must apply every time, use always_on.
  • Relying on memories to onboard a teammate. They never leave your machine. Put shared knowledge in a committed rule.

FAQ

Is the .windsurfrules file still read?
Yes. The legacy single file at the workspace root is still read, but the docs steer you to one file per rule under .windsurf/rules or .devin/rules, because each file then gets its own trigger and its own 12,000-character budget.
What is the difference between Windsurf rules and memories?
Rules are files you write and commit. Memories are notes Cascade generates about a workspace and stores on your machine; they don't ship with the repository and don't use credits. For anything the team must share, the docs recommend a rule or AGENTS.md.
Does Windsurf read AGENTS.md?
Yes, through the same rules engine. A root-level AGENTS.md needs no front matter and is always on; one in a subdirectory applies to that directory automatically, as if it had a glob trigger.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.