Setup Windsurf Memories: Teach the AI Your Codebase 2026

Configure Windsurf Memories to persist codebase context across sessions. Covers auto-generated vs manual memories, Rules files, and .windsurfrules setup. Tested on Windsurf 1.13.x.
·
8 min read
·
Mark
·
AI Coding

Problem: Cascade Forgets Everything Between Sessions

Windsurf Memories fix the most painful part of AI-assisted coding: re-explaining your project from scratch every session. Without Memories configured, Cascade has no idea that your team moved to GraphQL three months ago, that you use Zod for all validation, or that the auth/ folder follows a specific pattern you spent two sprints establishing.

You'll learn:

  • How Windsurf's two Memory types work and when each fires
  • How to write .windsurfrules files that actually change Cascade's behavior
  • How to manually pin critical architectural decisions as permanent memories
  • How to handle stale memories after major refactors

Time: 20 min | Difficulty: Intermediate

Why This Happens

Each Cascade conversation starts with a fresh context window. Without persistent memory, the AI reasons only from what's visible: the open file, whatever you paste in, and the live workspace index. That index is powerful — it spans your entire codebase — but it doesn't know why things are structured the way they are.

Memories solve this by storing facts and decisions that carry across sessions. When you open a new Cascade conversation, relevant memories load automatically before the first token is generated.

Symptoms when Memories are missing or misconfigured:

  • Cascade suggests patterns inconsistent with your codebase (e.g., class components in a hooks-only project)
  • You repeat yourself every session: "We use Axios interceptors, not fetch"
  • After a refactor, Cascade keeps referencing the old folder structure
  • New teammates onboarding with Cascade get contradictory suggestions

How Windsurf Memories Work

Windsurf assembles context through three layers before responding to any prompt:

  1. Cascade context engine — tracks your real-time edits, terminal commands, and file navigation
  2. Rules files — persistent instructions that govern Cascade's behavior (how to respond, what stack to use)
  3. Memories — persistent facts about your project and decisions (what you've built, choices you've made)

The distinction matters. Use Rules for standards and conventions. Use Memories for facts and decisions.

Auto-Generated Memories

Cascade generates memories automatically during conversations when it identifies something worth retaining. If you say "We switched from REST to tRPC for all internal APIs last quarter," Cascade saves that as a memory. Auto-generated memories do not cost flow action credits.

The initial indexing process takes approximately 48 hours on a new project. After that, Cascade's pattern matching improves significantly — on a 50,000-line React/Node.js codebase, Memories matched existing naming conventions and architectural patterns with around 78% accuracy.

Limitation: After large refactors, auto-generated memories sometimes lag. Cascade may suggest the old folder structure for a day or two before self-correcting. The fix is manual pinning, covered in Step 4.

Manual Memories

You can instruct Cascade to save any fact at any time:

Remember: this project uses Zod v3.22 for all input validation — never use class-validator

Cascade confirms the memory was saved. You can view, edit, and delete memories from the Customizations panel in the Cascade sidebar.

Solution

Step 1: Open the Customizations Panel

In Windsurf, click the Customizations icon in the Cascade panel (top-right of the chat sidebar). This is where you manage both Memories and Rules.

You'll see two sections:

  • Memories — auto-saved and manually pinned facts
  • Rules — .windsurfrules behavior configuration

Expected output: Both sections visible with any existing entries listed.

If the panel is missing:

  • Windsurf version too old → Update to 1.13.x or newer via Help → Check for Updates

Step 2: Create a Global .windsurfrules File

Rules files tell Cascade how to behave. A global rules file applies across all your projects.

Create the file at:

  • macOS/Linux: ~/.codeium/windsurf/memories/global_rules.md
  • Windows: %APPDATA%\Codeium\windsurf\memories\global_rules.md
# Global Cascade Rules

## Communication Style
- Respond concisely. Skip filler phrases like "Great question!" or "Certainly!".
- When proposing a change, explain WHY before showing the code.
- Always name the exact file path when referencing code changes.

## Code Standards
- TypeScript strict mode always. Never use `any`.
- Prefer `const` over `let`. Never use `var`.
- All async functions must handle errors explicitly — no silent catches.

## Testing
- New functions need a corresponding test in `__tests__/` unless pure UI components.
- Use Vitest, not Jest.

Expected output: Cascade picks up global rules within the same session after saving the file.

If rules are ignored:

  • Path mismatch → Confirm the exact directory path for your OS. Windsurf won't create missing directories.
  • Still using old style → Prompt: "Check your active rules and confirm you're following the global rules file."

Step 3: Add a Project-Level .windsurfrules File

Project-level rules override global rules for that specific codebase. Create the file at the project root:

touch .windsurfrules

A practical example for a Next.js 15 + tRPC project:

# Project Rules — acme-dashboard

## Stack
- Next.js 15 App Router. Never suggest Pages Router patterns.
- tRPC v11 for all internal API calls. No REST endpoints except `/api/webhooks/`.
- Prisma ORM with PostgreSQL (Supabase, us-east-1).
- Tailwind CSS 3.4 for styling — no CSS modules, no inline styles.
- Zustand for client state. No Redux, no Context API for global state.

## Folder Structure
- Server components live in `app/` directly.
- Client components go in `components/` with a `"use client"` directive.
- tRPC routers live in `server/routers/`. One router per domain (users, billing, etc.).
- Shared types go in `types/` — always import from there, never redefine inline.

## Patterns
- Auth is handled by Clerk. Never roll custom JWT logic.
- All monetary values stored in cents (integer). Format to USD on the client only.
- Feature flags live in `lib/flags.ts` — check there before adding new env vars.

## Do Not
- Do not suggest `getServerSideProps` or `getStaticProps` — this is App Router only.
- Do not import from `@/server` in client components.
- Do not add `console.log` to committed code.

The more specific you are, the less Cascade hallucinates project-irrelevant patterns. Commit this file to version control so all team members run from the same ground truth.

Step 4: Pin Critical Architectural Decisions as Memories

Auto-generated memories are probabilistic. For decisions you never want Cascade to contradict, pin them manually in the Cascade chat:

Remember permanently: We migrated from Prisma to Drizzle ORM in February 2026.
All new queries use Drizzle. No new Prisma client calls anywhere in the codebase.

Remember permanently: The billing/ module calls Stripe directly using
stripe-node v16. Do not suggest any other billing library.

Remember permanently: We run on Node 22 with Bun as the package manager.
Never suggest npm or yarn install commands.

Pin memories immediately after any major architectural change — before Cascade has a chance to auto-generate an outdated one.

Expected output: Each confirmation shows "Memory saved" in the Cascade panel.

Step 5: Verify Memories Are Loading

Open a brand new Cascade conversation (click the + icon — not just a new message in the current thread). Then ask:

What do you know about this project's tech stack and conventions?

Cascade should summarize your key rules and memories without you providing any additional context. If it can't, go to the Customizations panel and confirm the memories appear in the list.

For a targeted spot-check:

What ORM does this project use and when was it last changed?

Expected output: Accurate answer from memory with no prompting from you.

Step 6: Handle Stale Memories After Refactors

After a large structural change, don't wait for auto-correction. In the Customizations panel, delete outdated memories. Then manually re-pin the current state:

Remember permanently: As of March 2026, auth logic lives in lib/auth/
(moved from middleware/auth/). All new auth code goes in lib/auth/.

You can also prompt a re-index after major file moves:

# In Cascade chat — use @codebase for project-wide re-scan
@codebase Scan the current folder structure and update your understanding
of how this project is organized.

Verification

Open a fresh Cascade session and run through this checklist:

1. What stack does this project use?
2. Where do tRPC routers live?
3. What ORM are we on and when did we switch?
4. What testing framework should I use for new code?

You should see: Accurate, specific answers matching your .windsurfrules and pinned memories — with zero context provided by you in this session.

What You Learned

  • Memories and Rules are separate systems: Rules govern behavior, Memories store facts
  • Auto-generated memories work well for stable codebases but lag after major refactors
  • .windsurfrules is the highest-leverage file in a project for consistent Cascade behavior
  • Manually pinning decisions immediately after architectural changes prevents context drift
  • Auto-generated memories are free and don't consume flow action credits

When NOT to rely only on Memories: On teams with multiple developers actively refactoring, auto-generated memories can conflict. Commit a shared .windsurfrules to the repo so every team member's Cascade operates from identical conventions.

Tested on Windsurf 1.13.x, Node 22, macOS Sequoia and Ubuntu 24.04

FAQ

Q: Do Windsurf Memories cost flow action credits? A: Auto-generated memories are free. Manual memory creation from a prompt uses the normal per-message credit. Memory loading at session start is also free.

Q: Can I share Memories across my team? A: Auto-generated and manual memories are per-user. The .windsurfrules file at your project root is the correct way to share conventions — commit it to version control so everyone on the team starts from the same baseline.

Q: What is the difference between .windsurfrules and Memories? A: .windsurfrules is a static file you write and maintain — it defines permanent conventions and Cascade behaviors. Memories are dynamic facts Cascade saves and retrieves automatically. Use .windsurfrules for "always use Vitest," and Memories for "we switched to Drizzle in February."

Q: Does the Memories feature work on the Windsurf free plan? A: Yes. Memories and Rules are available on all plans including free. The free plan caps flow action credits at 25 total, but memory generation and loading don't consume those credits.

Q: What happens to Memories after a Windsurf version update? A: Memories survive Windsurf updates. They're stored in your local Codeium profile directory, not the project folder, so they persist through IDE reinstalls as long as you don't wipe your profile data.