Context, Memory & the Codebase Index
Windsurf's context system determines what information Cascade has when generating code. Mastering it is the difference between generic AI suggestions and deeply codebase-aware outputs that match your team's exact conventions.
Codebase Index
Windsurf automatically indexes your repository and updates the index as you edit. The index enables semantic search -- Cascade finds relevant code by concept, not just by filename or literal text match. This is what enables zero-shot multi-file edits.
Pinned Context
Pin specific files, functions, or selections in the Cascade panel to always be included in context. Use for core architectural files, API contracts, style guides, or any file that should inform every edit in a session.
@ Mentions
Reference specific files, functions, or symbols using @ in your prompts: "@src/api/auth.ts fix the rate limiting logic". Cascade focuses attention on the referenced item and fetches its full content regardless of what the auto-selection algorithm chose.
Memories
Cascade can persist facts about your project across sessions -- coding conventions, architectural decisions, team preferences, recurring patterns. Define memories explicitly via the Memories panel or let Cascade infer them from patterns it notices.
Example .windsurfrules File
# Project: Agiaki Platform API # Stack: Python 3.12, FastAPI, SQLModel, PostgreSQL, pytest ## Coding Conventions - Use SQLModel for all ORM models, never raw SQLAlchemy - All endpoints must have Pydantic response models with explicit field types - Use dependency injection via FastAPI Depends() for all DB sessions - Never use print() -- use structlog for all logging - All functions must have Google-style docstrings ## Architecture Rules - Repository pattern: all DB queries live in *_repository.py files - Services orchestrate repositories; they never query the DB directly - Routers only call services; they never call repositories directly ## Testing - Use pytest with pytest-asyncio for async tests - Mock external services with respx; never make real HTTP calls in tests - Every new endpoint requires: happy path, validation error, auth failure ## Forbidden Patterns - Do NOT use mutable default arguments - Do NOT catch bare Exception -- always catch specific exceptions - Do NOT import from app.main in any module other than app.main itself
The .windsurfrules file should be version-controlled and shared with your whole team. Every developer gets the same Cascade behaviour from day one. Update it whenever your conventions change -- treat it like a living document.
ShopMate -- Cascade Memories
# Add these to Windsurf Memories for the shopmate/ workspace
ShopMate is an AI-powered e-commerce assistant for ThreadCo, a sustainable T-shirt brand.
All Claude API calls use shopmate/logging/audit.py logged_create() -- never client.messages.create() directly.
All customer-facing replies use shopmate/safety/reply_guardrails.py safe_reply().
Brand configurations are in shopmate/config/brands.yaml -- never hardcode brand names.
The FastAPI entry point is shopmate/api/main.py.
Tests use pytest and respx to mock the Anthropic API -- never make real API calls in tests.
Environment variables are loaded from .env via python-dotenv.
The product catalogue is in data/catalogue.json and indexed in data/shopmate_kb/ via ChromaDB.
# Reference specific ShopMate files in Flow prompts for better results # Adding a new Claude feature: Add a product comparison feature following the same pattern as @shopmate/prompts/product_description.py and logging via @shopmate/logging/audit.py # Fixing the safety layer: The safe_reply() function in @shopmate/safety/reply_guardrails.py is blocking replies that mention "free returns" even when the store policy in @data/store_policy.txt explicitly states free returns are offered. # Adding a new brand: Add a new brand "NightOwlThreads" to @shopmate/config/brands.yaml following the exact same structure as the existing threadco entry. Then update @shopmate/multi_brand.py to handle the new brand. # Pin for all sessions touching Claude integration: Pin @shopmate/logging/audit.py and @shopmate/safety/reply_guardrails.py