Windsurf Memories: Persistent Context for Cascade

Windsurf memories are Cascade's mechanism for remembering context between conversations. When Cascade learns something durable about your project — an architectural decision, a preference you stated, a gotcha it hit while running your tests — it can save that as a memory and automatically pull it back into context in future sessions in the same workspace. You stop re-explaining your stack every morning.

That persistence fixes the most annoying part of agentic coding: starting every session from zero. But memories are also opaque, machine-local, and occasionally wrong. This guide covers the full lifecycle — how Cascade memories get created, where to manage them, how they differ from rules, and what to do when a stale memory keeps steering Cascade off course.

What are Windsurf memories and how do they work?

Cascade is Windsurf's agentic engine — it plans multi-step changes, edits files, and runs commands. Between turns of a single conversation, it has the chat history. Between conversations, it has memories.

A memory is a short piece of saved context tied to your workspace. Three properties define how Windsurf memories behave:

• Workspace-scoped. A memory created while working in one repo applies to that workspace. Open a different project and Cascade starts with that project's memories instead.
• Automatically retrieved. You don't invoke memories. When a new conversation touches a topic a memory covers, Cascade decides it's relevant and loads it. There's no glob pattern or activation mode to configure — relevance is the model's call.
• Machine-local. Memories live in Windsurf's internal store on your machine, not in your repository. They never show up in git status, and your teammates never see them.

That last property is the one that shapes everything else in this guide: memories are personal state, not shared configuration. For shared configuration, Windsurf has rules — files in .windsurf/rules/ that are explicit, versioned, and committed. Memories and rules are complementary halves of Windsurf context management, and confusing the two is the most common mistake teams make.

Auto-generated vs user-created memories

Cascade memories come from two places, and they behave differently enough that it's worth knowing which kind you're looking at.

Auto-generated memories

While you work, Cascade decides on its own that something is worth keeping. Typical triggers:

• You correct it ("no, we use Drizzle, not Prisma") and it saves the correction.
• It discovers something non-obvious about the codebase, like a build step that must run before tests.
• You state a preference mid-task ("always use named exports here").

Auto-generated memories are the low-effort win: context accumulates as a side effect of normal work. They're also where staleness comes from, because nothing prompts Cascade to revisit a memory when the fact it captured stops being true.

User-created memories

You can also tell Cascade exactly what to remember. This is a plain chat instruction, not a special syntax:

Create a memory: this repo is a pnpm monorepo. Never run npm install.
Always run commands from the workspace root with pnpm --filter.

Cascade confirms the saved memory in the conversation, and it shows up in the memories panel like any other. User-created memories tend to be higher quality because you wrote the exact wording — treat them as your fast path for anything you catch yourself repeating in prompts.

Managing Windsurf memories: paths and UI

Memories are only useful if you can see them. Here's the workflow for auditing what Cascade currently believes about your project.

1. Open the memories panel. In Windsurf, open the Cascade customizations/settings area (Windsurf Settings → Cascade → Manage Memories, or the customizations menu inside the Cascade panel). You'll see every memory scoped to the current workspace.
2. Read them like documentation. Each memory is a short statement. Scan for anything outdated, wrong, or oddly specific to a task you finished weeks ago.
3. Delete what's wrong. Remove stale or incorrect memories directly from the panel. You can also do this conversationally: "delete the memory about the REST API — we moved to tRPC."
4. Update instead of stacking. If a fact changed, ask Cascade to update the existing memory rather than adding a new one that contradicts it. Two conflicting memories give you nondeterministic behavior depending on which one gets retrieved.

One thing to internalize about paths: memories have no file in your repo. This is the sharp contrast with the rest of Windsurf's context surface:

.windsurf/rules/*.md     # project rules — committed, shared, reviewable
~/.windsurf/rules/*.md   # global rules — personal, apply to all projects
(internal store)         # memories — per-workspace, per-machine, UI-managed

If you're ever unsure whether a piece of context is a memory or a rule, check the repo. If it's not in a file, it's a memory — and it will not follow you to a new laptop or a teammate's machine.

Windsurf memories vs rules: when to promote one to the other

The windsurf memories vs rules decision comes down to one question: should this context be shared and versioned, or is it personal and provisional?

A good mental model: memories are a scratchpad, rules are documentation. The scratchpad is where facts get discovered; documentation is where confirmed facts go to live.

How to promote a memory to a rule

When a memory has proven itself — Cascade has relied on it for a couple of weeks and it's still true — promote it:

1. Copy the memory's content from the memories panel.
2. Write it into a rule file, cleaned up and generalized:

# .windsurf/rules/package-management.md

## Package manager
This is a pnpm workspace monorepo.

- Never run npm or yarn commands
- Install with: pnpm install
- Run package scripts with: pnpm --filter <package> <script>
- Add dependencies to a specific package, never the root, unless it is tooling

3. Delete the original memory so the two can't drift apart. The rule is now the single source of truth, and it activates deterministically instead of depending on Cascade's relevance judgment.
4. Commit the rule so the whole team — and every fresh clone — gets it.

Promote aggressively. Anything about the tech stack, build commands, code conventions, or architecture belongs in a rule. Leave in memories only what's genuinely personal (your own workflow preferences) or genuinely provisional (facts about a migration in progress).

Going the other direction is rare: you'd only demote a rule to a memory if it was a personal preference accidentally committed to the shared rules folder — in which case it likely belongs in your global rules (~/.windsurf/rules/) rather than a memory anyway.

Team workflows: what memories can't do

Memories don't solve team consistency, and it's worth being blunt about why:

• They don't sync. Your memories live on your machine. Your teammate's Cascade has a different, independently accumulated set. Two developers in the same repo can get systematically different agent behavior.
• They can't be reviewed. There's no PR for a memory. Nobody approves what Cascade decided to remember, and nobody notices when it's wrong but plausible.
• They don't onboard anyone. A new hire's Windsurf starts empty. Every gotcha your memories encode, they get to rediscover the hard way.

The team-grade path is rules files, managed like the shared artifacts they are. This is exactly what localskills.sh is built for: you publish your conventions once as a versioned skill, and everyone installs it into their tool of choice:

npm install -g @localskills/cli
localskills login
localskills install your-org/frontend-conventions --target windsurf cursor claude

The CLI writes each tool's native format from the same published skill — .windsurf/rules/ for Windsurf, .cursor/rules/ (.mdc) for Cursor, .claude/skills/ for Claude Code. Skills are versioned with rollback, so "which version of the conventions are you on?" has an actual answer, unlike memories, which have no versions at all. Teams get folders, roles, and access restrictions on top, and GitHub sync can mirror the whole library to a repo so edits flow both ways.

The division of labor that works in practice: memories for the individual, published rules for the team. Cascade's scratchpad stays personal; the standards everyone depends on live in versioned, installable files. If you're orchestrating longer Cascade sessions on top of that foundation, see our guide to Windsurf Cascade workflows.

Troubleshooting stale or wrong memories

The symptom is always the same: Cascade confidently does the wrong thing, repeatedly, across fresh conversations. Fresh conversations rule out chat-history contamination — repeated cross-session wrongness means persisted context, which means a memory or a rule. Debug it in this order:

1. Reproduce in a new conversation. If the behavior only happens in one long chat, it's the conversation context, not a memory. Start clean and try again.
2. Check rules first. Rules are files, so they're greppable: look through .windsurf/rules/ and your global rules for the bad instruction. If it's there, fix the file — done.
3. Audit the memories panel. Open Manage Memories and hunt for the stale fact. Common offenders: memories from before a framework migration, memories captured from an experiment that was later reverted, and half-right paraphrases of something you said months ago.
4. Delete, don't argue. Correcting Cascade in chat fixes the current conversation, but the memory survives and the bad behavior returns tomorrow. Delete the memory itself, then optionally save a corrected replacement.
5. Pin the truth as a rule. If a fact is important enough that a stale memory about it caused real damage, it's important enough to be a rule. Deterministic, versioned activation beats probabilistic retrieval for anything load-bearing.

A monthly two-minute sweep of the memories panel prevents most of this. Memories accumulate silently; pruning is the part you have to do on purpose.

FAQ

Do Windsurf memories sync across machines?

No. Memories are stored locally per machine and per workspace. If you work on two computers, each accumulates its own set. Anything you need on both machines should be a rule file in the repo or a global rule — or a published skill you install on each machine.

Can I commit Windsurf memories to git?

Not directly — memories don't exist as files in your repository. The supported way to make context shareable is to promote it to a rule in .windsurf/rules/, which is a normal markdown file you commit and review like any other code.

How are Windsurf memories different from Cursor memories?

They solve the same problem — persistent, automatically-applied context that survives across sessions — with the same core limitation: they're personal to your machine rather than shared with your team. The management UI and generation behavior differ; see our Cursor memories guide for the Cursor side and a deeper comparison.

Should I use memories or rules for my project's conventions?

Rules. Conventions are shared, stable, and worth reviewing — all three point to versioned files. Use memories for what's left: personal preferences, in-progress facts, and things Cascade discovered that you haven't confirmed yet. When a memory stops being provisional, promote it.

Why is Cascade ignoring one of my memories?

Memory retrieval is relevance-based — Cascade decides per conversation whether a memory applies, and sometimes it decides wrong. If a piece of context must always be present, that's the definition of an always-on rule, not a memory. Move it to .windsurf/rules/ with always-on activation.

---

Ready to turn your best Windsurf rules into a shared, versioned library your whole team can install? Get started with localskills.sh.

npm install -g @localskills/cli
localskills login
localskills publish