Skip to main content
Memories is the system for sharing and persisting context across conversations. There are two mechanisms for this in Windsurf: Memories, which are automatically generated by Cascade, and Rules, which are manually defined by the user at the global, workspace, or system level.

​
Memories, Rules, Workflows, or Skills?

Windsurf offers several ways to customize Cascade. Use this table to pick the right one:
FeatureWhat it doesHow it’s activatedWhen to use it
RulesTell Cascade how to behave (e.g. “use bun, not npm”)always_on, glob, model_decision, or manual (see below)Coding conventions, style guides, project constraints
AGENTS.mdLocation-scoped rules with zero configAutomatic — root = always-on, subdirectory = globDirectory-specific conventions without frontmatter
WorkflowsPrompt templates for repeatable multi-step tasksManual only via /[workflow-name] slash commandDeployments, PR reviews, release checklists
SkillsMulti-step procedures bundled with supporting files (scripts, templates)Dynamically invoked by the model, or @mentionComplex tasks where Cascade needs reference files — invest here
MemoriesContext Cascade auto-generates during conversationsAutomatic retrieval when relevantLet Cascade remember one-off facts; for durable knowledge, prefer Rules or AGENTS.md
Recommendation: For knowledge you want Cascade to reliably reuse, write it as a Rule or add it to AGENTS.md in your repo rather than relying on auto-generated Memories. Rules are version-controlled, shareable with your team, and give you explicit control over activation.

​
How to Manage Memories

Memories and Rules can be accessed and configured at any time by clicking on the Customizations icon in the top right slider menu in Cascade, or via “Windsurf - Settings” in the bottom-right hand corner. To edit an existing memory, simply click into it and then click the Edit button.

​
Memories

During conversation, Cascade can automatically generate and store memories if it encounters context that it believes is useful to remember. Additionally, you can ask Cascade to create a memory at any time. Just prompt Cascade to “create a memory of …”. Cascade’s autogenerated memories are associated with the workspace they were created in and are stored locally in ~/.codeium/windsurf/memories/. Cascade retrieves them when it believes they’re relevant. Memories generated in one workspace are not available in another, and they are not committed to your repository.
Creating and using auto-generated memories do NOT consume credits.
Auto-generated memories live only on your machine. If you want Cascade to remember something durably — and share it with your team — ask Cascade to write it to a Rule in .windsurf/rules/ or to your repo’s AGENTS.md instead.

​
Rules

Users can explicitly define their own rules for Cascade to follow. Rules can be defined at the global, workspace, or system level, and can also be inferred from AGENTS.md files.
ScopeLocationNotes
Global~/.codeium/windsurf/memories/global_rules.mdSingle file, applied across all workspaces. Always on. Limited to 6,000 characters.
Workspace.windsurf/rules/*.mdOne file per rule, each with its own activation mode. Limited to 12,000 characters per file.
AGENTS.mdAny directory in your workspaceProcessed by the same Rules engine — root-level = always-on, subdirectory = auto-glob for that directory.
System (Enterprise)OS-specific (e.g. /etc/windsurf/rules/)Deployed by IT, read-only for end users.

​
Rules Discovery

Windsurf automatically discovers rules from multiple locations to provide flexible organization:
  • Current workspace and sub-directories: All .windsurf/rules directories within your current workspace and its sub-directories
  • Git repository structure: For git repositories, Windsurf also searches up to the git root directory to find rules in parent directories
  • Multiple workspace support: When multiple folders are open in the same workspace, rules are deduplicated and displayed with the shortest relative path

​
Rules Storage Locations

Rules can be stored in any of these locations:
  • .windsurf/rules in your current workspace directory
  • .windsurf/rules in any sub-directory of your workspace
  • .windsurf/rules in parent directories up to the git root (for git repositories)
When you create a new rule, it will be saved in the .windsurf/rules directory of your current workspace, not necessarily at the git root. To get started with Rules, click on the Customizations icon in the top right slider menu in Cascade, then navigate to the Rules panel. Here, you can click on the + Global or + Workspace button to create new rules at either the global or workspace level, respectively.
You can find example rule templates curated by the Windsurf team at https://windsurf.com/editor/directory to help you get started.
Workspace rule files are limited to 12,000 characters each. The global rules file is limited to 6,000 characters.

​
Activation Modes

Each workspace rule declares an activation mode in its frontmatter via the trigger field. This controls when the rule’s content is given to Cascade and how much context window it consumes:
Modetrigger: valueHow it reaches CascadeContext cost
Always Onalways_onFull rule content is included in the system prompt on every message.Every message
Model Decisionmodel_decisionOnly the description is shown in the system prompt. Cascade reads the full rule file when it decides the description is relevant.Description always; full content on demand
GlobglobRule is applied when Cascade reads or edits a file matching the globs pattern (e.g. *.js, src/**/*.ts).Only when matching files are touched
ManualmanualRule is not in the system prompt. You activate it by typing @rule-name in the Cascade input box.Only when @mentioned
The global rules file (global_rules.md) and root-level AGENTS.md files don’t use frontmatter — they are always on.
Example workspace rule with frontmatter: 
---
trigger: glob
globs: **/*.test.ts
---

All test files must use `describe`/`it` blocks and mock external API calls.

​
Best Practices

To help Cascade follow your rules effectively, follow these best practices:
  • Keep rules simple, concise, and specific. Rules that are too long or vague may confuse Cascade.
  • There’s no need to add generic rules (e.g. “write good code”), as these are already baked into Cascade’s training data.
  • Format your rules using bullet points, numbered lists, and markdown. These are easier for Cascade to follow compared to a long paragraph. For example:
# Coding Guidelines 
- My project's programming language is python
- Use early returns when possible
- Always add documentation when creating new functions and classes
  • XML tags can be an effective way to communicate and group similar rules together. For example:
<coding_guidelines>
- My project's programming language is python
- Use early returns when possible
- Always add documentation when creating new functions and classes
</coding_guidelines>

​
System-Level Rules (Enterprise)

Enterprise organizations can deploy system-level rules that apply globally across all workspaces and cannot be modified by end users without administrator permissions. This is ideal for enforcing organization-wide coding standards, security policies, and compliance requirements. System-level rules are loaded from OS-specific directories: macOS: 
/Library/Application Support/Windsurf/rules/*.md
Linux/WSL: 
/etc/windsurf/rules/*.md
Windows: 
C:\ProgramData\Windsurf\rules\*.md
Place your rule files (as .md files) in the appropriate directory for your operating system. The system will automatically load all .md files from these directories.

​
How System Rules Work

System-level rules are merged with workspace and global rules, providing additional context to Cascade without overriding user-defined rules. This allows organizations to establish baseline standards while still permitting teams to add project-specific customizations. In the Windsurf UI, system-level rules are displayed with a “System” label and cannot be deleted by end users.
Important: System-level rules should be managed by your IT or security team. Ensure your internal teams handle deployment, updates, and compliance according to your organization’s policies. You can use standard tools and workflows such as Mobile Device Management (MDM) or Configuration Management to do so.