[Epic] Memory Integration for CUGA

[gaodan-fang]

📋 Executive Summary

Enable CUGA with episodic memory capabilities to leverage previously identified insights and relevant experiences when executing tasks. This Epic encompasses the complete memory system architecture, including fact storage, run tracking, guideline extraction, and integration across all CUGA agents.

🎯 What We Want and Why

Primary Goals

1. Enable Learning from Experience: Allow CUGA to extract and reuse guidelines from successful/failed task executions
2. Improve Task Performance: Reduce execution time and increase accuracy by leveraging historical knowledge
3. Reduce Hallucinations: Ground agent decisions in proven patterns and successful trajectories
4. Enhance Reliability: Build predictable behavior through guideline reuse

Success Metrics

• Performance: 20% reduction in average task execution time for repeated task patterns
• Accuracy: 15% improvement in task success rate through memory-guided decisions
• Adoption: Memory enabled in 80% of production deployments
• Storage: Efficient guideline storage with <100ms retrieval latency

🏗️ How It Could Work

Architecture Overview

The memory system is built on three key components:

1. Kaizen Library Integration (kaizen-integration branch)

   • In-process memory access (no separate service required)
   • Namespace management for multi-tenant support
   • Entity CRUD operations (facts, tips, runs, run_steps)
   • Vector-based semantic search via Milvus
   • SQLite for metadata storage

2. Kaizen MCP Server Integration (kaizen-lite-mode branch)

   • Guideline retrieval via get_guidelines(task)
   • Trajectory saving via save_trajectory(chat_messages, task_id, success)
   • FastMCP client for SSE transport
   • Configurable save triggers (success/failure)

3. Agent Integration Points

   • Task Analyzer: Retrieve relevant guidelines before analysis
   • Task Decomposition: Use memory for subtask planning
   • API Shortlist: Filter based on historical success
   • Code Agent: Reuse proven code patterns
   • API Code Planner: Leverage successful API sequences
   • CugaLite: Guidelines injected into system prompts ✅ (Complete)

Current Implementation Status

✅ Completed (Phase 1 & Partial Phase 2)

• Kaizen client wrapper with lazy loading
• Namespace CRUD operations
• Entity storage (facts, tips, runs, run_steps)
• Run tracking for trajectory capture
• CugaLite guideline injection
• Trajectory capture and saving to Kaizen
• User preferences context module
• Configuration system (enable_memory, Kaizen settings)
• CLI commands for memory operations
• Integration and E2E tests

🚧 In Progress (Phase 2 & 3)

• Task Analyzer memory retrieval (0%)
• Task Decomposition integration (0%)
• API Shortlist integration (0%)
• Code Agent integration (0%)
• API Code Planner integration (0%)
• Background guideline extraction for full CUGA graph
• Guideline classification and quality filtering

📋 Planned (Phase 4 & 5)

• Cross-namespace learning
• Guideline ranking and scoring
• Memory visualization tools
• Performance optimization
• Production hardening (scalability, HA, monitoring)

Key Technical Specifications

Data Models:

• Namespace: Multi-tenant isolation (user_id, agent_id, app_id)
• RecordedFact: Guidelines with content, metadata, embeddings
• Run: Execution trajectories with steps
• MemoryEvent: Change tracking for guidelines

Storage:

• Milvus: Vector embeddings for semantic search
• SQLite: Namespace catalog and entity metadata
• Kaizen: Unified interface for memory operations

Configuration:

[kaizen]
enabled = false
url = "http://127.0.0.1:8201/sse"
lite_mode_only = true
save_on_success = true
save_on_failure = true
async_save = true
timeout = 30.0

🔗 Links and Context

Related Documentation

• Epic Document: docs/epics/EPIC-001-Memory-Integration.md
• Memory README: docs/memory/README.md
• Feature: Personalization Integration (docs/features/FEATURE-001-Personalization-Integration.md)
• Feature: Learning From Experience (docs/features/FEATURE-002-Learning-From-Experience.md)

Key Branches

• kaizen-integration: Kaizen memory backend implementation
• kaizen-lite-mode: Kaizen MCP integration for learning

Dependencies

• Kaizen Library: External memory/entity management system
  • Install: uv sync --extra memory
  • Configuration: src/cuga/configurations/memory/kaizen.settings.toml
• Kaizen MCP Server: Guideline generation and trajectory analysis
  • Protocol: SSE transport via FastMCP client

Implementation Files

• Memory client: src/cuga/backend/memory/memory.py
• Kaizen integration: src/cuga/backend/kaizen/kaizen_integration.py
• User preferences: src/cuga/backend/cuga_graph/state/user_preferences_context.py
• Configuration: src/cuga/settings.toml
• CLI: src/cuga/backend/memory/cli.py
• Tests: src/system_tests/e2e/test_memory_integration.py

📊 Current Progress

Overall: ~45% Complete

• ✅ Phase 1 (Foundation): 100% Complete
• 🚧 Phase 2 (Agent Integration): 50% Complete (CugaLite done)
• 🚧 Phase 3 (Guideline Extraction): 40% Complete (Kaizen MCP integration)
• ⏳ Phase 4 (Advanced Features): Not Started
• ⏳ Phase 5 (Production Hardening): Not Started

🎯 Acceptance Criteria

This Epic will be complete when:

1. ✅ All Phase 1 (Foundation) stories are complete
2. ✅ All Phase 2 (Agent Integration) stories are complete
3. ✅ All Phase 3 (Guideline Extraction) stories are complete
4. ✅ Performance targets met (latency, scalability)
5. ✅ Test coverage >80% for memory components
6. ✅ Documentation complete and published
7. ✅ Production deployment successful
8. ✅ User adoption >80% in target deployments

📝 Next Steps

1. Complete agent integration for remaining 4 agents (Task Analyzer, Task Decomposition, API Shortlist, Code Agent, API Code Planner)
2. Implement background guideline extraction pipeline for full CUGA graph
3. Add guideline classification and quality filtering
4. Develop memory analytics dashboard
5. Optimize performance and add monitoring

---

Reference: This issue tracks the implementation of EPIC-001 as documented in docs/epics/EPIC-001-Memory-Integration.md