Cascade Memories
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:
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:
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.