Windsurf Cascade AI Memory

Windsurf IDE with Cascade AI is powerful — but it forgets everything between sessions. Here's how to give Windsurf persistent project context.

Persistent Context MIT License 100% Local

The Windsurf Context Problem

Windsurf's Cascade AI is a powerful coding agent — but like all AI agents, it starts every session from zero. The architectural decisions you made two weeks ago? Forgotten. The API strategy you settled on? Never happened. The testing conventions that took three sessions to establish? Gone.

"If Cascade didn't save it as a Memory — either automatically or at your prompt — that information was only in the conversation history, which gets lost when sessions end." — Markaicode, March 2026

Cascade Memory Bank — GitHub Open Source

cascade-memory-bank by GreatScottyMac is an MIT-licensed project memory system for Windsurf IDE:

📄 activeContext.md

Tracks session state and goals. Updates every session automatically.

📄 productContext.md

Defines project scope and architecture. Updates when scope changes.

📄 progress.md

Tracks work status and milestones. Updates as tasks progress.

📄 decisionLog.md

Records important decisions. Updated when decisions are made.

Cascade Memory Bank works by creating a memory-bank/ directory in your project with these four markdown files. Cascade reads them at session start and updates them during the session.

"Enhanced Productivity: No context loss between sessions. Reduced onboarding time for new tasks. Automatic documentation maintenance." — cascade-memory-bank on GitHub

Windsurf Context Management — Full Comparison

Solution	Platform	Storage	Auto-Capture	Encryption	License
★ agent-memory	Windsurf + Any MCP agent	JSON/SQLite/Redis	Yes	AES-256	MIT
cascade-memory-bank	Windsurf only	Markdown files	Manual prompt	—	MIT
Windsurf built-in	Windsurf only	Session memory	Partial	—	Proprietary

How to Give Windsurf Real Persistent Memory

For Windsurf users who want more than markdown files:

# Option 1: agent-memory MCP server (recommended)
pip install agent-memory

# Run the MCP server
python -m agent_memory.mcp_server --storage json --path ./memory.json

# Configure Windsurf to connect via MCP config:
# Add to your claude_desktop_config.json:
# {
#   "mcpServers": {
#     "agent-memory": {
#       "command": "python",
#       "args": ["-m", "agent_memory.mcp_server", "--path", "./memory.json"]
#     }
#   }
# }

# Option 2: cascade-memory-bank (markdown-based)
# Clone from: github.com/GreatScottyMac/cascade-memory-bank
# Copy .windsurfrules to your project root
# Tell Cascade: "Follow the protocol in your rules"

agent-memory gives Windsurf what cascade-memory-bank can't:

AES-256 encryption — Project decisions and code are sensitive
TTL auto-expiration — Stale context auto-deletes
Semantic search — Find memories by meaning, not just filename
MCP native — Works with any MCP agent: Windsurf, Claude Code, Cursor, OpenClaw
JSON/SQLite/Redis backends — Choose your storage

What to Remember Between Sessions

The most important things to preserve for Windsurf sessions:

Architecture decisions — "We use event-driven microservices for X"
Coding conventions — "We use early returns, max 2 levels of nesting"
API design patterns — "REST for external, GraphQL for internal"
Testing strategy — "Unit tests for utils, integration tests for API"
Deployment approach — "We deploy to Fly.io, use Docker"

agent-memory on GitHub cascade-memory-bank on GitHub