This document describes Windsurf Cascade's persistent memory system, which enables the AI assistant to retain important context across conversations and sessions. The memory system addresses the fundamental limitation of context windows by storing critical information—user preferences, project structure, technical decisions, code patterns, and task history—in a persistent database that can be retrieved semantically when needed.
For information about code search and discovery capabilities, see Code Search and Discovery Tools. For task planning features, see the planning architecture described in the system prompt.
Sources: Windsurf/Prompt Wave 11.txt87-97
The memory system operates as a persistent knowledge layer that sits between the conversational context and the workspace filesystem. It consists of two primary tools: create_memory for CRUD operations and trajectory_search for semantic retrieval.
Memory System Architecture
The diagram illustrates how the create_memory and trajectory_search tools interact with the persistent memory database, compensating for the limited conversation context window.
Sources: Windsurf/Prompt Wave 11.txt87-97 Windsurf/Tools Wave 11.txt57-86 Windsurf/Tools Wave 11.txt303-312
Each memory in the database contains structured metadata and content. The system uses this structure to enable filtering, retrieval, and workspace scoping.
| Attribute | Type | Required | Purpose |
|---|---|---|---|
Id | string | Update/Delete only | Unique identifier for existing memory |
Title | string | Create/Update | Descriptive title for the memory |
Content | string | Create/Update | Full content of the memory |
Tags | string[] | Create only | Snake_case tags for filtering/retrieval |
CorpusNames | string[] | Create only | Workspace associations (exact match required) |
UserTriggered | boolean | Always | Whether user explicitly requested this memory |
Action | enum | Always | One of: "create", "update", "delete" |
Sources: Windsurf/Tools Wave 11.txt57-86
Memories are associated with specific workspaces using CorpusNames. The system prompt provides the mapping between workspace URIs and CorpusNames:
[URI] -> [CorpusName]
c:\Users\crisy\OneDrive\Escritorio\test4 -> c:/Users/crisy/OneDrive/Escritorio/test4
When creating a memory, the CorpusNames parameter must contain FULL AND EXACT string matches from this mapping, including all symbols and path separators.
Sources: Windsurf/Prompt Wave 11.txt10-12 Windsurf/Tools Wave 11.txt74-75
The create_memory tool provides CRUD (Create, Read, Update, Delete) operations on the memory database. The tool signature enforces strict parameter validation.
create_memory Tool Parameter Flow
The diagram shows the parameter requirements for each operation type.
Creating a new memory:
Updating an existing memory:
Deleting a memory:
Sources: Windsurf/Tools Wave 11.txt57-86
The system prompt establishes aggressive memory creation guidelines to compensate for context window limitations.
The prompt explicitly states at Windsurf/Prompt Wave 11.txt88-95:
Memory Creation and Update Flow
Before creating a new memory, the system checks for semantically related existing memories to avoid duplication.
The tool documentation Windsurf/Tools Wave 11.txt58-66 lists examples of information worth storing:
Sources: Windsurf/Prompt Wave 11.txt87-97 Windsurf/Tools Wave 11.txt57-86
The trajectory_search tool enables semantic search across conversation history (trajectories). It returns scored, sorted, and filtered chunks based on relevance.
| Parameter | Behavior |
|---|---|
Query (empty string) | Returns all trajectory steps |
Query (with content) | Returns semantically relevant chunks, scored and sorted |
| Maximum Results | 50 chunks |
SearchType: "cascade" | Searches conversation trajectories |
SearchType: "user" | Searches user activity trajectories |
The prompt Windsurf/Prompt Wave 11.txt122 includes specific instructions:
SearchType: 'user'Sources: Windsurf/Tools Wave 11.txt303-312
Unlike manual tool calls, memory retrieval operates automatically. The system retrieves relevant memories from the database and presents them to Cascade based on the current context.
Automatic Memory Retrieval Flow
Memories are automatically retrieved and injected into Cascade's context based on semantic relevance to the current task.
The prompt emphasizes at Windsurf/Prompt Wave 11.txt95-96:
"Relevant memories will be automatically retrieved from the database and presented to you when needed.
IMPORTANT: ALWAYS pay attention to memories, as they provide valuable context to guide your behavior and solve the task."
Sources: Windsurf/Prompt Wave 11.txt87-97
Memories are scoped to workspaces using the CorpusName system. This enables workspace-specific context management.
The user information section Windsurf/Prompt Wave 11.txt8-12 provides the active workspace mapping:
<user_information>
The USER's OS version is windows.
The USER has 1 active workspaces, each defined by a URI and a CorpusName.
Multiple URIs potentially map to the same CorpusName.
The mapping is shown as follows in the format [URI] -> [CorpusName]:
c:\Users\crisy\OneDrive\Escritorio\test4 -> c:/Users/crisy/OneDrive/Escritorio/test4
</user_information>
A single memory can be associated with multiple workspaces by including multiple CorpusNames in the array:
Sources: Windsurf/Prompt Wave 11.txt8-12 Windsurf/Tools Wave 11.txt74-75
The tool documentation Windsurf/Tools Wave 11.txt67-68 includes a critical instruction:
"Before creating a new memory, first check to see if a semantically related memory already exists in the database. If found, update it instead of creating a duplicate."
Memory Deduplication State Machine
The system checks for semantically related memories before creating new ones to maintain a clean, non-redundant knowledge base.
This strategy prevents memory database pollution and ensures that related information is consolidated in a single, comprehensive memory rather than scattered across duplicates.
Sources: Windsurf/Tools Wave 11.txt67-68
The system can delete incorrect or outdated memories using the delete action. The prompt instructs Windsurf/Tools Wave 11.txt68:
"Use this tool to delete incorrect memories when necessary."
When deleting, only the Id and Action parameters are required:
The UserTriggered flag should be set to true if the user explicitly requested the deletion, and false if Cascade identified the memory as incorrect on its own.
Sources: Windsurf/Tools Wave 11.txt68 Windsurf/Tools Wave 11.txt72-73 Windsurf/Tools Wave 11.txt76-77 Windsurf/Tools Wave 11.txt80-81
Tags use snake_case formatting Windsurf/Tools Wave 11.txt78-79 and serve as filters for memory retrieval. Effective tagging strategies improve retrieval accuracy.
| Category | Example Tags |
|---|---|
| Entity Type | user_preference, project_info, code_pattern, architecture_decision |
| Technology | react, typescript, nextjs, python, postgres |
| Domain | web_development, api_design, database_schema, testing |
| Scope | workspace_specific, cross_project, temporary, permanent |
| Priority | critical, important, reference, deprecated |
react_component_pattern instead of just patternweb_development + nextjs)Sources: Windsurf/Tools Wave 11.txt78-79
The memory system directly addresses Cascade's context window limitation, as emphasized in the prompt Windsurf/Prompt Wave 11.txt93-94:
"Remember that you have a limited context window and ALL CONVERSATION CONTEXT, INCLUDING checkpoint summaries, will be deleted."
| Context Type | Persistence | Scope | Retrieval |
|---|---|---|---|
| Conversation Context | Temporary | Current session | Immediate |
| Checkpoint Summaries | Temporary | Session-scoped | Automatic |
| Memory Database | Permanent | Cross-session | Semantic retrieval |
Context Persistence Across Sessions
While conversation context and checkpoints are deleted, memories persist across sessions and are automatically retrieved when relevant.
This architecture enables Cascade to maintain long-term knowledge about projects, user preferences, and technical decisions despite having a limited working memory window.
Sources: Windsurf/Prompt Wave 11.txt87-97
Refresh this wiki