Skip to main content
Memories is the system for sharing and persisting context across conversations. There are two mechanisms for this in Cascade: Memories, which can be automatically generated by Cascade, and rules, which are manually defined by the user at both the local and global levels.

​
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. 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 that they were created in and Cascade will retrieve them when it believes that they are relevant. Memories generated in one workspace will not be available in another.
Creating and using auto-generated memories do NOT consume credits

​
Rules

Users can explicitly define their own rules for Cascade to follow. Rules can be defined at either the global level or the workspace level. global_rules.md - rules applied across all workspaces .windsurf/rules - workspace level directory containing rules that are tied to globs or natural language descriptions.

​
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.
Rules files are limited to 12000 characters each.

​
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 Cascade 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.