Persistent Memory for
Windsurf IDE — MCP Setup Guide

Windsurf is Codeium's AI-native IDE built around Cascade — a powerful agentic AI that can plan, execute, and iterate across your entire codebase. Add the Kronvex MCP server and Cascade will remember your project architecture, past decisions, and recurring patterns across every session, making it dramatically more effective over time.

Windsurf and Cascade — why memory matters more here

Windsurf, built by Codeium, is distinguished from other AI IDEs by its Cascade agentic mode. Where most AI editors respond to individual prompts, Cascade can take a high-level goal — "implement user authentication with email verification" — and autonomously plan and execute the task across multiple files, terminal commands, and browser actions.

This autonomy is exactly why persistent memory is so valuable in Windsurf. Cascade's multi-step plans are only as good as the context they start with. Without memory, every Cascade session begins cold — no knowledge of your architecture, no awareness of previous bugs, no understanding of your team's conventions. The more ambitious the task, the more critical it is for Cascade to have rich historical context.

Consider these scenarios where missing memory causes problems:

• Cascade implements a new API endpoint but uses axios — you already decided to use ofetch three weeks ago.
• Cascade writes a migration but ignores your naming convention (YYYYMMDD_name.sql) that you established after a painful incident.
• Cascade scaffolds a React component using the pattern you deprecated in favour of your new design system approach.
• Cascade fixes a bug in a way that you already tried — and that introduced a worse bug elsewhere.

The Kronvex MCP server gives Cascade access to everything it needs to know before it starts executing — automatically, via semantic search against your persistent memory store.

Get your Kronvex API key

You need two values from your Kronvex account before configuring Windsurf: an API key and an Agent ID.

Configure the MCP server in Windsurf

Windsurf supports MCP servers through a configuration file called mcp_config.json. You can access it via Windsurf → Settings → Cascade → MCP Servers → Configure, or by directly editing the file at ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "kronvex-memory": {
      "command": "npx",
      "args": ["-y", "@kronvex/mcp-server"],
      "env": {
        "KRONVEX_API_KEY": "kv-your-api-key",
        "KRONVEX_AGENT_ID": "your-agent-uuid"
      }
    }
  }
}

Replace the placeholder values with your actual API key and Agent ID. Save the file, then open Windsurf's MCP configuration panel and click Refresh — the kronvex-memory server should appear with a green connected status.

Test the connection

Open a Cascade chat panel (the lightning bolt icon in the sidebar) and type:

Use kronvex-memory to store this project convention:
"All React components must export a named export AND a default export.
The default export is for lazy-loading, the named export is for testing.
Example: export function Button(){...} and export default Button"

Cascade will invoke the Kronvex MCP server's remember tool. You will see the tool call appear in Cascade's action log with a green confirmation. Verify in your Kronvex dashboard — the memory will appear in your agent's list immediately.

Test recall in a fresh Cascade session:

Before writing any components, check my memories for
React component conventions in this project.

Cascade will call the recall tool, retrieve the export convention memory, and apply it automatically to any components it generates.

Memory patterns for Cascade agentic mode

Cascade's multi-step agentic execution benefits from memory in ways that simpler chat interactions don't. Here are patterns designed specifically for long-running Cascade tasks.

Pre-task context loading

Before launching a complex Cascade task, load the relevant context explicitly:

Before starting, query my memories for:
1. Architecture decisions relevant to the authentication system
2. Any known bugs or pitfalls in the user session handling
3. Database schema conventions for the users table
4. Testing patterns we use for API routes

Then implement email verification for the signup flow.

Cascade will perform the memory queries first, load the results into its context, and then proceed with the implementation — applying everything it found from memory throughout the multi-step execution.

Post-task memory consolidation

At the end of a Cascade task, ask it to consolidate what it learned:

Now that we've finished implementing the payment system:
Store the following memories in kronvex-memory:
- The Stripe webhook signature verification pattern we used
- The idempotency key approach for preventing duplicate charges
- The error handling hierarchy for payment failures
- Any gotchas encountered with Stripe's test mode

This builds project knowledge incrementally. Over time, Cascade's starting context for any new task becomes richer and more accurate.

Architecture memory mapping

For complex projects, store an architecture overview as a semantic memory that Cascade can retrieve at the start of any session:

Store in kronvex-memory (type: semantic):

Project architecture overview:
- Frontend: Next.js 15 App Router, deployed on Vercel
- Backend: FastAPI (Python), deployed on Railway
- Database: Supabase PostgreSQL with pgvector for embeddings
- Auth: Supabase Auth with JWT, not NextAuth
- Payments: Stripe Checkout (not Elements) — redirect flow
- Email: Resend, all templates in /emails/*.tsx (React Email)
- File storage: Cloudflare R2 via @aws-sdk/client-s3
- Queue: Trigger.dev for background jobs
- Monitoring: Sentry (frontend) + Datadog (backend)

Key directories:
- app/ → Next.js routes (App Router)
- components/ → Shared UI (shadcn/ui base)
- lib/ → Utilities and API clients
- server/ → Server actions and data fetching
- api/ → FastAPI backend (separate repo)

High-value use cases for Windsurf + memory

Cascade "remembers" previous failed approaches

One of the most powerful memory use cases is storing failed approaches — not just successes. When Cascade tries a solution that doesn't work, storing the failure prevents it from trying the same thing again in a future session:

Remember this failed approach:
We tried using react-hook-form's array field with useFieldArray
for the dynamic form, but it caused re-render performance issues
with 50+ items. The solution was to use a controlled state array
with React.memo on each row instead. Never suggest useFieldArray
for large dynamic lists in this project.

Convention enforcement across Cascade tasks

Store your naming conventions, file structure rules, and code patterns once. Every future Cascade task that touches those areas will apply them automatically:

• API routes return { success: boolean, data?: T, error?: string } — no raw returns
• Database operations always go through service layer in lib/services/ — never direct Supabase calls in components
• All external API calls are wrapped in retry logic from lib/retry.ts
• Feature flags are checked via useFeatureFlag() hook — no hardcoded conditions

Cross-session Cascade task continuity

Long features often span multiple sessions. Store progress checkpoints so Cascade can resume exactly where it left off:

Store progress checkpoint for the "multi-tenant billing" feature:
- DONE: Stripe webhook handler (stripe_router.py, fully tested)
- DONE: Database schema (billing_subscriptions table, migration done)
- IN PROGRESS: Dashboard billing page — sidebar works, main grid pending
- TODO: Usage metering (needs Stripe usage records API)
- TODO: Email notifications for payment failures
- BLOCKED: Waiting for Stripe enterprise pricing confirmation

The next session: "Check my memories for the billing feature progress" — and Cascade picks up from the exact state you left it.

Team knowledge base

If your team shares a Kronvex agent (same API key + Agent ID across all developers), Windsurf becomes a team knowledge tool. When a senior developer documents a critical architectural decision in memory, every junior developer's Cascade sessions automatically have access to that knowledge. Onboarding new developers effectively becomes: "install Windsurf, configure Kronvex, and Cascade will know the codebase."

Tips and best practices

MCP server not showing as connected

If the Kronvex server fails to connect in Windsurf's MCP panel:

• Run npx -y @kronvex/mcp-server directly in a terminal to see any errors at startup
• Verify Node.js version: node --version — minimum 18.0
• Check that the mcp_config.json is valid JSON with no trailing commas
• Ensure no firewall is blocking outbound connections to api.kronvex.io
• Try restarting Windsurf entirely after saving the config

Getting the best recall results

Kronvex uses cosine similarity on OpenAI text-embedding-3-small embeddings. Recall quality improves significantly when memories are written in complete sentences with relevant technical terms. Compare:

• Low quality: "use ofetch not axios"
• High quality: "All HTTP requests in this project use the ofetch library (not axios, not native fetch). The configured client is in lib/api-client.ts with interceptors for auth tokens and error handling."

The second version will be recalled in response to far more query variations: "HTTP client", "API calls", "request library", "ofetch", "authentication headers", and more.

TTL for time-sensitive memories

Not all memories should live forever. When storing memories via the Kronvex API directly, set a TTL for context that will become stale:

• Sprint tasks and in-progress features: 14 days TTL
• Bug reports being investigated: 30 days TTL
• Temporary workarounds: 60 days TTL with a note to review
• Architectural decisions: no TTL — permanent
• Library and dependency choices: no TTL — permanent

EU data residency for compliance

Windsurf itself is a US-based product, but your memory data stored in Kronvex never leaves the EU. All embeddings are computed and stored in Frankfurt. For teams with GDPR obligations or EU data residency requirements, this is a significant advantage over US-based memory alternatives. The Kronvex API endpoint (api.kronvex.io) routes all requests through EU infrastructure exclusively.