Windsurf Memories Feature Guide 2026: How to Make Cascade Remember Your Codebase

Windsurf Memories let Cascade automatically capture and reuse context from your conversations — so you stop re-explaining your stack, naming conventions, and architecture every session. Combined with Rules and AGENTS.md, you get a persistent codebase brain that survives IDE restarts.

Why Cascade Forgets — and the Three Systems That Fix It

Cascade forgets your codebase context for the same reason every LLM-based tool does: each conversation starts with a blank context window. Without explicit persistence, Cascade has no memory of the React component patterns you discussed last Tuesday, the database schema you described two weeks ago, or your team’s prohibition on using any in TypeScript. In 2026, with Windsurf serving 1M+ active developers and writing 70M+ lines of code per day, the memory problem has become the central UX challenge for AI-native IDEs. Windsurf solves this with three complementary systems: Memories (auto-captured conversation context), Rules (developer-authored, version-controlled instructions), and AGENTS.md (zero-config location-scoped context). Each serves a distinct role. Using the wrong one — for example, relying on auto-generated Memories for team-wide coding standards — leads to inconsistency, surprises, and eventually losing trust in Cascade entirely. This guide maps exactly when to use each system, how to set them up, and how to build a context stack that scales from solo developer to 50-person engineering team.

Understanding the 5 Context Systems in Windsurf

Windsurf’s Cascade engine draws on five distinct context mechanisms, each designed for a different persistence and sharing pattern. Understanding all five prevents the common mistake of over-relying on one and under-using the others. The five systems are: Rules (coding conventions with four activation modes — Always On, Glob, Model Decision, Manual), AGENTS.md (location-scoped zero-config instructions), Workflows (prompt templates invoked via slash commands), Skills (multi-step reusable workflows with supporting files), and Memories (auto-captured context from conversations, automatically retrieved). Rules and AGENTS.md are version-controlled, team-shareable, and explicitly authored by developers. Memories are automatically generated by Cascade and stored locally — they’re personal and ephemeral by design. Workflows and Skills power repeatable processes rather than persistent context. For most developers, the highest-leverage investment is getting Rules and AGENTS.md right, then letting Memories handle the long tail of one-off context that isn’t worth documenting explicitly.

Context System Comparison Table

How Cascade Memories Work

Windsurf Memories are automatically generated by Cascade during your conversations — no configuration required. When Cascade detects that you’ve shared a piece of context worth remembering (your preferred state management library, a quirk of your legacy API, the fact that you use pnpm not npm), it creates a memory entry that gets retrieved in future sessions when the topic is relevant. Memories are stored locally in ~/.codeium/windsurf/memories/ and are workspace-specific, meaning each project directory has its own isolated memory store. Crucially, memories don’t consume your Windsurf credits — they’re free to create and retrieve. Automatic retrieval means Cascade pulls relevant memories into context before responding, without you having to reference them. The limitation is that auto-generation is probabilistic: Cascade doesn’t always create a memory for every important piece of information you share, and you can’t guarantee which memories will be retrieved in any given session. For context that absolutely must be present, use Rules instead.

Where Memories Are Stored

Memories live at ~/.codeium/windsurf/memories/ on your local machine, organized by workspace. You can inspect, edit, or delete memory files directly — they’re plain text. The workspace isolation means switching from your frontend repo to your backend repo automatically shifts which memories are active. This is intentional design: you don’t want your Rails-specific database patterns bleeding into your Go microservices context. The local storage also means memories are personal — your teammates don’t share them even if they open the same repo. When you pair program or onboard a new developer, their Cascade starts fresh with no inherited memories from your conversations.

Manual Memory Creation: Teaching Cascade Explicitly

Beyond automatic memory generation, you can manually instruct Cascade to create a memory using natural language: just say “create a memory of…” or “remember that…” during a conversation. This gives you explicit control over what gets persisted without writing a formal Rule. Manual memory creation is useful for one-off context that’s too granular or personal for a shared Rules file but important enough that you don’t want to re-explain it every session. For example: “Remember that the /legacy API endpoints don’t follow REST conventions because they’re 8 years old and we can’t break backwards compatibility.” This kind of contextual nuance would be out of place in a .windsurf/rules/ file but is exactly the kind of thing you want Cascade to remember. Manual memories are created immediately and begin appearing in future relevant conversations. They follow the same storage and retrieval rules as auto-generated memories — local, workspace-specific, non-version-controlled.

Reviewing and Managing Memories

To see what Cascade has remembered, ask it directly: “What do you know about this codebase?” or “Show me your memories for this workspace.” Cascade will surface its stored memories. You can also browse ~/.codeium/windsurf/memories/ in your file system to see raw memory files. Delete any memories that are stale, incorrect, or no longer relevant — Cascade won’t automatically expire memories. A quarterly memory audit (delete outdated entries, promote important ones to Rules) is a useful maintenance practice for developers who use Windsurf heavily.

Rules System: The Version-Controlled Alternative

Windsurf Rules are developer-authored markdown files that give Cascade explicit, persistent instructions — and unlike Memories, they’re version-controlled and team-shareable. Rules are the right tool for anything that should be consistent across your team: coding standards, architecture decisions, framework conventions, testing requirements, and anything you’d put in an onboarding doc. As of Wave 8, the modern Rules format uses a .windsurf/rules/ directory with individual .md files per rule group, each with YAML frontmatter specifying the activation mode. Workspace rules have a 12,000-character limit per file — enough for comprehensive, well-organized instructions. Global rules (personal preferences that apply across all your projects) live at a system path and have a 6,000-character limit. If you’re still using a single .windsurfrules file in your project root, you’re using the legacy format — it still works, but the modern multi-file structure is clearer and more maintainable.

Modern .windsurf/rules/ Directory Structure

The modern Rules format uses a directory of individual .md files, each scoped to a logical concern. A typical project structure looks like:

Each file uses YAML frontmatter to declare its activation mode:

---
trigger: always_on
---

# Coding Standards

<tech_stack>
- TypeScript 5.x with strict mode enabled
- React 19 with Server Components where applicable
- Tailwind CSS for styling — no CSS modules
- pnpm for package management
</tech_stack>

<naming_conventions>
- Components: PascalCase (e.g., UserProfile.tsx)
- Hooks: camelCase with `use` prefix (e.g., useUserData.ts)
- API routes: kebab-case (e.g., /api/user-profile)
</naming_conventions>

XML tags like <tech_stack> and <naming_conventions> help Cascade parse and retrieve the most relevant sections. Commit these files to Git so the entire team shares the same context.

Legacy .windsurfrules vs Modern Multi-File Format

The legacy .windsurfrules file (single file in the project root) still works but has significant limitations compared to the modern format. A single monolithic file is harder to maintain, can’t use activation modes per rule group, and encourages dumping everything into one place. The modern .windsurf/rules/ directory solves this by letting you scope each file to a concern and assign independent activation modes. Migration strategy: open your existing .windsurfrules, identify logical groupings (stack info, conventions, testing rules, prohibitions), and split them into individual files under .windsurf/rules/. Add appropriate YAML frontmatter to each file. Then delete or archive the original .windsurfrules. The split takes 15-20 minutes for a typical project and immediately makes your Rules more maintainable.

Rule Activation Modes: Always On, Manual, Glob, Model Decision

Windsurf Rules support four activation modes that control when Cascade applies a rule. Choosing the right mode for each rule file is as important as writing the rule content. Always On (trigger: always_on) means Cascade includes the rule in every conversation — use this for universal standards that apply regardless of context. Glob (trigger: glob, pattern: "src/**/*.test.ts") activates the rule only when you’re working on files matching the glob pattern — use this for test-specific conventions, component-specific patterns, or infrastructure rules that don’t apply to application code. Model Decision (trigger: model_decision) lets Cascade decide when the rule is relevant — useful for context that’s important in some situations but would be noise in others. Manual (trigger: manual) only activates when you explicitly reference the rule in a conversation — use this for specialized conventions you want available on demand without cluttering every context window.

Activation Mode Decision Guide

AGENTS.md: Zero-Config Location-Scoped Rules

AGENTS.md is the simplest context system Windsurf offers — just drop a file named AGENTS.md into any directory and Cascade automatically applies it as an always-on rule for that directory and its subdirectories. No frontmatter, no configuration, no activation mode to choose. A root-level AGENTS.md acts as a global always-on rule for the entire project. A AGENTS.md in src/components/ applies only when Cascade is working in that directory. This location-scoping makes AGENTS.md ideal for monorepos where different packages have different conventions, for legacy directories with special handling rules, or for directories where specific security or compliance rules apply. AGENTS.md files are committed to Git, so they’re team-shareable and version-controlled. The zero-config approach makes them easier to adopt than the full Rules system — any developer can drop in an AGENTS.md without understanding YAML frontmatter or activation modes.

AGENTS.md vs Rules: When to Use Each

Use AGENTS.md when you want directory-scoped context with no configuration overhead. Use Rules when you need specific activation modes (Glob, Manual), want to organize context into named files, or need the 12,000-character limit per file. For a solo developer or small team adopting Windsurf for the first time, AGENTS.md in the project root is the fastest path to useful persistent context — write it like an onboarding doc for Cascade and commit it to your repo.

Rules vs Memories vs AGENTS.md: Decision Framework

Choosing between Windsurf’s context systems comes down to three questions: Does this context need to be shared with my team? Does it need version control? Can it be auto-captured or does it need to be explicitly authored? Memories are the right tool when context is personal, ephemeral, or too granular for formal documentation — things like “I’m currently mid-refactor on the auth module” or “I prefer verbose error messages during debugging.” Rules are right when context is team-wide, durable, and explicitly important: coding standards, architecture constraints, testing requirements. AGENTS.md sits in between: it’s explicitly authored and version-controlled like Rules, but zero-config and directory-scoped. The official Windsurf recommendation is telling: for durable knowledge, prefer Rules or AGENTS.md over auto-generated Memories. Memories are a convenience layer, not a reliability layer.

Context System Decision Tree

Global Rules: Personal Preferences That Follow You Everywhere

Global Rules are personal Rules that apply across all your Windsurf projects, not just a single workspace. They live at an OS-specific path (on macOS: ~/Library/Application Support/Windsurf/global_rules.md, on Linux: ~/.config/Windsurf/global_rules.md) and have a 6,000-character limit. Global Rules are ideal for developer preferences that transcend any single project: your preferred code style, how you like explanations formatted, your debugging approach, languages you prefer for comments. Unlike workspace Rules, Global Rules are personal — they’re not committed to a repo and don’t affect your teammates’ Cascade behavior. A good Global Rules file might include your preferred verbosity level for Cascade responses, your favorite architectural patterns, and conventions you carry from project to project. Think of Global Rules as Cascade’s understanding of you as a developer, not of any specific codebase.

Enterprise and System-Level Rules: Scaling Team Knowledge

Windsurf’s enterprise context system extends Rules beyond individual workspaces to organization-wide deployment — making it the only AI IDE context mechanism designed to scale from a single developer to a 500-person engineering org. System admins can deploy Rules to OS-specific paths (/etc/windsurf/rules/ on Linux, group policy paths on Windows) that load automatically for every user on a machine, enforcing security policies, compliance constraints, and mandatory coding standards without requiring individual setup. Enterprise Rules are managed and distributed through Windsurf’s enterprise platform — centrally versioned and pushed to all developer machines. With 4,000+ enterprises running Windsurf in production and 59% of Fortune 500 companies building with the platform, this enterprise context system is increasingly critical. For teams using Windsurf in cloud development environments or shared machines, system-level Rules ensure baseline standards are always present from day one — new developers inherit the team’s full Cascade context without any manual configuration steps.

Workflows and Skills: When You Need More Than Context

Workflows and Skills extend Windsurf beyond passive context into active automation. Workflows are prompt templates saved to .windsurf/workflows/ that you invoke via slash commands (e.g., /code-review, /write-tests). They’re useful for repeatable tasks you run frequently but don’t want to type out every time. Skills go further: they’re multi-step workflows with supporting files, able to chain Cascade actions, run shell commands, and produce structured outputs. Skills live in .windsurf/skills/ and can call external APIs, transform files, and run test suites. The distinction from Memories and Rules is important: Workflows and Skills don’t passively inform Cascade — they actively direct Cascade’s behavior for a specific task. Use Memories and Rules to shape how Cascade works generally; use Workflows and Skills to encode repeatable procedures.

Cross-IDE Comparison: Windsurf vs Cursor vs Claude Code Context Systems

All major AI IDEs have converged on persistent context as a core feature, but their implementations differ in ways that matter for team adoption and reliability. Windsurf offers the most layered system: Memories (auto-generated), Rules (multi-file, four activation modes), AGENTS.md (zero-config, location-scoped), Workflows, and Skills. Cursor uses .cursor/rules/ with a similar multi-file structure (.mdc files), activated by Always, Auto (model decision), Manual, or Glob modes — nearly identical to Windsurf’s Rule system with different file extensions. Claude Code uses CLAUDE.md files with hierarchical directory-scoping similar to Windsurf’s AGENTS.md, plus a personal preferences file for cross-project settings. The critical differentiator is Windsurf’s auto-generated Memories — neither Cursor nor Claude Code has an equivalent automatic context capture system. The tradeoff is real: Memories are convenient and low-overhead, but non-deterministic in what gets captured and retrieved; Rules and AGENTS.md are explicit and reliable, but require upfront authoring investment. For teams prioritizing consistency, the explicit systems win.

Cross-IDE Context System Comparison

Step-by-Step Setup Guide: Making Cascade Remember Your Codebase

Here is the exact sequence for setting up a complete Windsurf context stack from scratch. This covers a new project but the same steps apply to migrating an existing .windsurfrules file. Follow these steps once per project; the payoff is a Cascade that consistently understands your codebase from session one.

Step 1: Create your root AGENTS.md. Create AGENTS.md in your project root. Start simple — write two or three paragraphs describing your project’s purpose, the main tech stack, and any non-obvious architectural decisions. Commit immediately. This is the fastest path to useful context and takes five minutes.

Step 2: Create .windsurf/rules/ directory. Add the directory: mkdir -p .windsurf/rules. Create your first rule file — coding-standards.md — with trigger: always_on frontmatter. Populate it with your actual coding conventions: language versions, style preferences, naming rules, tools (linter, formatter, test runner). Don’t copy generic best practices — write what’s specifically true for your project.

Step 3: Add activation-mode-specific rules. Create separate rule files for testing conventions (glob mode, targeting test files), API design patterns (model decision), and hard prohibitions (always_on). Commit all .windsurf/ files to Git.

Step 4: Set up your Global Rules. Open your Global Rules file and add personal preferences: your preferred explanation style, debugging approach, and any cross-project conventions you carry. This is personal — don’t commit it.

Step 5: Teach Cascade with manual memories. As you work, when you share important context that isn’t covered by your Rules, say “remember that…” to create explicit memories. After the first week, review auto-generated memories via “show me your memories for this workspace” — promote any important ones to Rules.

Step 6: Migrate legacy .windsurfrules. If you have an existing .windsurfrules file, open it, split its content into logical files under .windsurf/rules/, add appropriate frontmatter, then delete the original. Test with a fresh Cascade session to verify context loads correctly.

Best Practices and Common Pitfalls

Good Windsurf context management follows a few durable principles. Be specific over generic: “Use React Query v5 for all server state with staleTime of 60s” beats “Use modern React patterns.” Generic rules are harder for Cascade to apply and add noise without value. Group related rules with XML tags for parsability. Keep each Rule file under its character limit (12,000 for workspace, 6,000 for global) — hitting the limit truncates your rules in unpredictable ways. Use AGENTS.md for quick directory-scoped context, Rules for anything that needs activation modes or needs to be named and organized. The biggest pitfall is treating Memories as a substitute for Rules: Memories are auto-generated and non-deterministic, so anything important enough to affect code correctness should live in a Rule, not a Memory. Another common mistake: writing Rules that are too long, too generic, or copy-pasted from the internet. Cascade works best with concise, specific, true-to-your-project instructions.

Common Setup Mistakes

1. Relying on Memories for team standards — Memories are personal and non-version-controlled. Use Rules for team-wide conventions.
2. One giant .windsurfrules file — Split into logical files under .windsurf/rules/ for maintainability and activation mode control.
3. Always On everything — Use glob and model_decision modes to avoid overwhelming Cascade’s context window.
4. Never reviewing memories — Stale memories can confuse Cascade. Audit and prune quarterly.
5. Generic rules — “Write clean code” is useless. “Use functional components with TypeScript strict mode; no class components” is actionable.

FAQ

Below are the most common questions developers ask about Windsurf’s memory and context systems. These cover the practical decisions you’ll face when setting up Cascade for the first time or migrating from a legacy .windsurfrules file: whether to use Memories vs Rules, credit costs, how to create manual memories, the difference between AGENTS.md and the .windsurf/rules/ directory, and how to manage context if you use multiple AI IDEs. Each answer is designed to stand alone so you can jump directly to the question most relevant to your situation. If your question isn’t answered here, the best resource is the official Windsurf documentation at docs.windsurf.com — both the Memories guide and the Rules reference are actively maintained as Windsurf’s context system evolves. With 1M+ active developers using Windsurf, the community forum is also a reliable source for real-world setup patterns beyond the official docs.

What is Windsurf Memories and how does it differ from Rules?

Windsurf Memories are automatically generated by Cascade during your conversations and stored locally in ~/.codeium/windsurf/memories/. They’re personal, workspace-specific, and non-version-controlled. Rules are developer-authored markdown files in .windsurf/rules/ that are explicitly written, committed to Git, and shared with your team. Use Memories for personal, granular, or ephemeral context; use Rules for team-wide coding standards and architecture constraints.

Do Windsurf Memories cost credits?

No. Creating and retrieving Memories is free and does not consume your Windsurf Pro or Teams credits. The credit cost comes from Cascade’s AI processing — Memories are stored and retrieved as plain text files at no additional cost.

How do I make Cascade remember something specific?

During any Cascade conversation, say “create a memory of…” or “remember that…” followed by the context you want to persist. Cascade will confirm the memory was created. You can also verify it was saved by asking “what do you know about this workspace?” in a future session.

What’s the difference between AGENTS.md and .windsurf/rules/?

AGENTS.md is zero-config and directory-scoped — drop the file in any directory, commit it, and it’s active with no frontmatter or configuration. .windsurf/rules/ files require YAML frontmatter to specify activation modes but offer more control: glob patterns for file-type-specific rules, model_decision for context-aware activation, and manual mode for on-demand rules. For simple projects, start with AGENTS.md. For complex projects needing fine-grained activation control, use .windsurf/rules/.

Should I use Windsurf Rules or Cursor Rules if I switch between IDEs?

The formats are similar but not identical — Windsurf uses .windsurf/rules/*.md with YAML frontmatter, Cursor uses .cursor/rules/*.mdc. If you switch between IDEs frequently, consider maintaining both directories in your repo with overlapping content, or use AGENTS.md (which works in both Windsurf and Claude Code) as your primary context layer and supplement with IDE-specific Rules for platform-specific behavior.