Memory and Persistent Context Systems

Relevant source files

• Comet Assistant/System Prompt.txt
• Comet Assistant/tools.json
• Google/Antigravity/Fast Prompt.txt
• Qoder/prompt.txt
• README.md
• Windsurf/Tools Wave 11.txt

Purpose and Scope

This document analyzes how different AI coding assistants implement memory and persistent context management to overcome the fundamental limitation of finite context windows. It covers the architectural patterns, storage mechanisms, retrieval strategies, and CRUD operations used to maintain knowledge across conversation sessions.

For information about tool-based architectures in general, see Universal Tool System Architecture. For validation mechanisms that work with memory systems, see Validation and Quality Assurance Mechanisms.

---

The Context Window Problem

AI language models operate with fixed-size context windows, creating a fundamental limitation: information from previous conversations or earlier parts of long sessions becomes inaccessible once the context window is exceeded. Memory systems solve this by persisting important information to external storage that can be selectively retrieved when relevant.

Key challenges addressed:

• Session continuity: Maintaining knowledge across multiple conversation sessions
• Long-term learning: Accumulating project-specific knowledge and user preferences over time
• Selective retrieval: Finding relevant information from potentially large knowledge bases
• Knowledge categorization: Organizing memories by type, scope, and relevance

Sources: Google/Antigravity/Fast Prompt.txt216-250 Qoder/prompt.txt152-175

---

Memory System Architecture Overview

Memory System Comparison Across Assistants

This diagram maps the specific tool names and storage locations used by each system to enable developers to locate and work with these components in the codebase.

Sources: Qoder/prompt.txt152-194 Google/Antigravity/Fast Prompt.txt99-250 Windsurf/Tools Wave 11.txt57-86 Comet Assistant/System Prompt.txt44-50

---

Qoder Memory System

Architecture and Storage

Qoder implements a file-based memory system stored in the .qoder/memory/ directory within the project workspace. The system uses the update_memory and search_memory tools for CRUD operations.

Storage location: .qoder/memory/ (workspace-scoped) or global location for cross-project memories

Memory Categories

Qoder organizes memories into four distinct categories:

Category	Purpose	Examples
user_prefer	Personal info, dialogue preferences, project-related preferences	Code style preferences, communication patterns, personal information
project_info	Technology stack, project configuration, environment setup	Framework versions, build tools, dependency requirements
project_specification	Development standards, architecture specs, design standards	API design patterns, naming conventions, code organization rules
experience_lessons	Pain points to avoid, best practices, tool usage optimization	Common errors encountered, workflow improvements discovered

Scope Mechanism

Scope Types

• workspace: Information specific to the current project, stored in .qoder/memory/ within that project
• global: Information applicable across all projects, stored in a global location

Sources: Qoder/prompt.txt152-175

Usage Guidelines

When to create memories (from Qoder's system prompt):

• User explicitly asks to remember something
• Common pain points discovered during development
• Project-specific configurations learned
• Workflow optimizations discovered
• Tool usage patterns that work well

Operations: The update_memory tool handles create, update, and delete operations. The search_memory tool retrieves relevant memories using semantic search.

Sources: Qoder/prompt.txt152-194 Qoder/prompt.txt326-328

---

Antigravity Knowledge Items (KI)

Architecture Overview

Antigravity implements the most sophisticated memory system through "Knowledge Items" (KI) - curated knowledge packages automatically generated by a dedicated Knowledge Subagent.

Storage location: C:\Users\Lucas\.gemini\antigravity\knowledge

KI Structure

Each Knowledge Item consists of:

Knowledge Item Components

Sources: Google/Antigravity/Fast Prompt.txt203-207

Mandatory Check Before Research

Antigravity enforces a critical workflow pattern: 🚨 MANDATORY FIRST STEP: Check KI Summaries Before Any Research 🚨

Search-Before-Research Workflow

This pattern prevents redundant work by mandating that assistants check existing KI summaries before performing new research or analysis.

Sources: Google/Antigravity/Fast Prompt.txt102-121

Knowledge Subagent

Antigravity uses a separate "Knowledge Subagent" that automatically distills conversations into curated knowledge:

Characteristics:

• Automatic generation: Reads conversations and creates/updates KIs without user prompting
• Metadata tracking: Each KI includes metadata.json with summary, timestamps, and source references
• Artifact organization: Related files stored in artifacts/ directory
• Cross-referencing: KIs can reference other KIs and conversations

Sources: Google/Antigravity/Fast Prompt.txt240-242

Usage Scenarios

When to use KIs (mandatory checks):

Scenario	Action
Before ANY research or analysis	Check if KI already exists on topic
Before creating documentation	Verify no existing KI covers this
When seeing relevant KI in summaries	Read artifacts FIRST before independent work
When encountering new concepts	Search for related KIs to build context
Debugging unexpected behavior	Check for known bugs/gotchas KIs
Adding features similar to existing ones	Check for established pattern KIs

Sources: Google/Antigravity/Fast Prompt.txt138-195

Example Workflow

USER: Can you analyze the core engine module and document its architecture?

✅ CORRECT APPROACH:
1. Check KI summaries provided at conversation start
2. Find "Core Engine Architecture" KI with artifact path
3. Use view_file to read artifacts/architecture_overview.md
4. Build upon existing analysis or ask user if enhancement needed

❌ INCORRECT APPROACH:
1. Immediately call list_dir and view_file to start fresh analysis
2. Create new 600-line analysis document
3. Result: Duplicate work when KI already existed

Sources: Google/Antigravity/Fast Prompt.txt112-136

---

Comet Memory Database

Comet integrates memory with task management through its todo_write tool and conversation logging system.

Todo-Based Memory

The todo_write tool serves dual purposes:

1. Task management: Track current tasks and progress
2. Memory persistence: Maintain task history across sessions

Tool parameters:

Usage requirements:

• Use VERY frequently to track tasks
• Mark todos as completed immediately when done
• Critical for planning and breaking down larger tasks
• Prevents forgetting important tasks

Sources: Comet Assistant/System Prompt.txt44-50 Comet Assistant/tools.json159-174

Conversation Logs

Comet maintains conversation logs that include:

• Full conversation history
• Task completion records
• Browser interactions and screenshots
• Search results and citations

This provides implicit memory through conversation continuity rather than explicit knowledge items.

Sources: Comet Assistant/System Prompt.txt44-50

---

Windsurf Memory Management

create_memory Tool

Windsurf provides a comprehensive create_memory tool with full CRUD capabilities:

Tool Schema from Windsurf

Sources: Windsurf/Tools Wave 11.txt57-86

Memory Parameters

Parameter	Type	Usage	Required For
Action	enum	"create", "update", or "delete"	All operations
Content	string	Memory content text	create, update
CorpusNames	string[]	Workspace URIs (exact match)	create
Id	string	Existing memory ID	update, delete
Tags	string[]	snake_case tags for filtering	create
Title	string	Descriptive title	create, update
UserTriggered	boolean	Explicit user request flag	All operations

Important constraint: Each CorpusNames element must be a FULL AND EXACT string match with a workspace URI provided in the system prompt.

Sources: Windsurf/Tools Wave 11.txt68-84

What to Save

Examples from Windsurf's system prompt:

• USER preferences
• Explicit USER requests to remember or alter behavior
• Important code snippets
• Technical stacks
• Project structure
• Major milestones or features
• New design patterns and architectural decisions
• Any other important information

Deduplication: Before creating a new memory, check for semantically related memories and update instead of creating duplicates.

Sources: Windsurf/Tools Wave 11.txt57-68

trajectory_search Tool

Windsurf provides semantic search across conversation history:

Capabilities:

• Semantic search within specific conversations
• Retrieve all trajectory steps with empty query
• Maximum 50 chunks returned, scored and filtered by relevance
• Call when user @mentions a @conversation

Sources: Windsurf/Tools Wave 11.txt302-312

---

Common Architectural Patterns

Pattern 1: Search-Before-Research

Search-Before-Research Decision Flow

Implementation examples:

• Antigravity: Mandatory check of KI summaries before ANY research Google/Antigravity/Fast Prompt.txt102-107
• Qoder: Search memory before gathering information Qoder/prompt.txt326-328
• Windsurf: Check semantically related memories before creating new ones Windsurf/Tools Wave 11.txt66-68

This pattern prevents redundant work and ensures knowledge accumulation rather than regeneration.

Sources: Google/Antigravity/Fast Prompt.txt102-121 Windsurf/Tools Wave 11.txt66-68

Pattern 2: Automatic Capture

All systems implement proactive memory creation without waiting for explicit user requests:

System	Trigger Conditions
Qoder	Common pain points, project configurations, workflow optimizations, tool usage patterns
Antigravity	Knowledge Subagent automatically distills conversations into KIs
Windsurf	Important code snippets, design patterns, architectural decisions
Comet	Task completion, browser interactions, search results

Key principle: Store information proactively when it's likely to be valuable in future sessions, not just when explicitly asked.

Sources: Qoder/prompt.txt162-169 Google/Antigravity/Fast Prompt.txt240-242 Windsurf/Tools Wave 11.txt57-68

Pattern 3: Categorization

Systems organize memories using different taxonomies:

Qoder Categories (4 types):

user_prefer          → Personal and dialogue preferences
project_info         → Stack, config, environment
project_specification → Standards, architecture, design
experience_lessons   → Pain points, best practices

Windsurf Tags (snake_case):

technical_stack
user_preference
architectural_pattern
project_milestone

Antigravity Knowledge Items (directory-based):

C:\Users\Lucas\.gemini\antigravity\knowledge\
  ├── [KI-Name-1]/
  │   ├── metadata.json
  │   └── artifacts/
  └── [KI-Name-2]/
      ├── metadata.json
      └── artifacts/

Sources: Qoder/prompt.txt156-161 Windsurf/Tools Wave 11.txt78-79 Google/Antigravity/Fast Prompt.txt203-207

Pattern 4: Semantic Retrieval

All systems support semantic search to find relevant memories:

Semantic Search Across Systems

Characteristics:

• Beyond keyword matching: Finds conceptually related content
• Scoring and ranking: Results ordered by relevance
• Filtering: Low-relevance results excluded
• Context-aware: Uses current conversation context to improve relevance

Sources: Qoder/prompt.txt326-328 Google/Antigravity/Fast Prompt.txt337-346 Windsurf/Tools Wave 11.txt302-312

---

Storage Mechanism Comparison

System	Storage Type	Location	Structure	Access Method
Qoder	File-based	.qoder/memory/ (workspace) Global location (cross-project)	Directory with categorized files	update_memory, search_memory tools
Antigravity	File-based	C:\Users\Lucas\.gemini\antigravity\knowledge	KI directories with metadata.json and artifacts/	view_file, codebase_search, grep_search tools
Windsurf	Database	Memory Database (internal)	Tagged entries with corpus names	create_memory, trajectory_search tools
Comet	Database	Memory Database (internal)	Todos and conversation logs	todo_write tool, conversation system

File-Based vs Database Storage

File-Based (Qoder, Antigravity):

• Advantages: Version controllable, inspectable, shareable via git
• Disadvantages: Requires file system access, slower search at scale
• Best for: Project-specific knowledge, documentation artifacts

Database (Windsurf, Comet):

• Advantages: Fast search, efficient updates, better concurrency
• Disadvantages: Less transparent, requires database infrastructure
• Best for: Frequent updates, semantic search, conversation history

Sources: Qoder/prompt.txt152-194 Google/Antigravity/Fast Prompt.txt203-207 Windsurf/Tools Wave 11.txt57-86

---

Conversation Logs and Historical Context

Antigravity Conversation Logs

Antigravity maintains comprehensive conversation logs separate from KIs:

Location: C:\Users\Lucas\.gemini\antigravity\brain\[ConvID]\.system_generated\logs\

Structure:

• overview.txt: Conversation summary
• Task-specific log files
• Artifacts generated during conversation

Usage guidelines:

Use Conversation Logs When	Use Knowledge Items When
Need details of specific conversation	Researching a specific topic
Small number of relevant conversations	Need distilled, curated knowledge
User explicitly mentions conversation	Starting any research task
User alludes to specific past information	Topic appears in KI summaries

Explicit guidance: You should NOT read conversation logs if likely irrelevant or containing more information than necessary. Search for KIs first.

Sources: Google/Antigravity/Fast Prompt.txt222-239

When to Use Conversation Logs vs Knowledge Items

Decision Tree for Antigravity Memory Access

Sources: Google/Antigravity/Fast Prompt.txt225-249

---

Integration with Other Systems

Memory + Validation Pipeline

Memory systems integrate with validation mechanisms to store lessons learned:

Memory Integration with Validation

When validation reveals common errors or important patterns, systems store this as memory for future reference.

Sources: Qoder/prompt.txt160-161 Google/Antigravity/Fast Prompt.txt151-163

Memory + Task Management

Comet uniquely integrates memory with task tracking through todo_write:

Benefits:

• Task history serves as implicit memory
• Progress tracking across sessions
• Completed tasks document what was accomplished
• Active tasks provide context for next session

Sources: Comet Assistant/System Prompt.txt44-50

---

Best Practices Summary

When to Create Memories

Scenario	Category (Qoder)	Priority
User explicitly asks to remember	user_prefer	Mandatory
Common error discovered	experience_lessons	High
Project configuration learned	project_info	High
Design pattern established	project_specification	Medium
Workflow optimization found	experience_lessons	Medium
Tool usage pattern works well	experience_lessons	Low

What NOT to Store

• Temporary information relevant only to current task
• Information already in code/documentation
• Overly specific details unlikely to be reused
• Duplicate information (check for existing memories first)

Sources: Qoder/prompt.txt162-169 Windsurf/Tools Wave 11.txt57-68

Retrieval Best Practices

1. Always check memory first before new research (Antigravity's mandatory pattern)
2. Use semantic search rather than keyword matching
3. Update existing memories rather than creating duplicates
4. Scope appropriately: workspace for project-specific, global for universal knowledge
5. Tag comprehensively: Use multiple tags for better discoverability

Sources: Google/Antigravity/Fast Prompt.txt102-121 Windsurf/Tools Wave 11.txt66-68

---

Implementation Examples

Creating a Memory in Qoder

SCENARIO: User discovers that tests require specific environment variable

ACTION: Use update_memory tool
PARAMETERS:
  - category: "experience_lessons"
  - scope: "workspace"
  - content: "Tests require ENV_VAR=test to run successfully. Without this, 
             database connection fails with timeout error."

Creating a Knowledge Item in Antigravity

SCENARIO: Knowledge Subagent distills architecture discussion

AUTOMATIC PROCESS:
1. Subagent reads conversation logs
2. Creates KI directory: C:\Users\Lucas\.gemini\antigravity\knowledge\core_engine_architecture\
3. Writes metadata.json with summary and timestamps
4. Saves artifacts/architecture_overview.md with findings
5. References original conversation in metadata

Creating a Memory in Windsurf

Sources: Qoder/prompt.txt152-194 Google/Antigravity/Fast Prompt.txt240-242 Windsurf/Tools Wave 11.txt57-86

---

Key Differences and Trade-offs

Aspect	Qoder	Antigravity	Windsurf	Comet
Creation	Manual via tool	Automatic via subagent	Manual via tool	Implicit via todos
Structure	Categorized files	KI with artifacts	Tagged database entries	Todo lists
Scope	workspace/global	Project-based	Corpus-based	Session-based
Search	Semantic	File system + semantic	Semantic trajectory	N/A
Deduplication	Manual check	Manual check	Mandatory pre-check	N/A
Artifacts	Text-based	Files in artifacts/	Text content only	Task metadata
Visibility	File system	File system	Internal DB	Internal DB

Selection criteria:

• Choose Qoder's approach when you need explicit categorization and cross-project sharing
• Choose Antigravity's approach when you want automatic curation with rich artifacts
• Choose Windsurf's approach when you need flexible tagging and semantic search
• Choose Comet's approach when memory is primarily task-oriented

Sources: Qoder/prompt.txt152-194 Google/Antigravity/Fast Prompt.txt99-250 Windsurf/Tools Wave 11.txt57-86 Comet Assistant/System Prompt.txt44-50