feat(memory): integrate memory system with context engine (#97)

## Changes

### New Context Type
- Add MEMORY to ContextType enum for agent memory context
- Create MemoryContext class with subtypes (working, episodic, semantic, procedural)
- Factory methods: from_working_memory, from_episodic_memory, from_semantic_memory, from_procedural_memory

### Memory Context Source
- MemoryContextSource service fetches relevant memories for context assembly
- Configurable fetch limits per memory type
- Parallel fetching from all memory types

### Agent Lifecycle Hooks
- AgentLifecycleManager handles spawn, pause, resume, terminate events
- spawn: Initialize working memory with optional initial state
- pause: Create checkpoint of working memory
- resume: Restore from checkpoint
- terminate: Consolidate working memory to episodic memory
- LifecycleHooks for custom extension points

### Context Engine Integration
- Add memory_query parameter to assemble_context()
- Add session_id and agent_type_id for memory scoping
- Memory budget allocation (15% by default)
- set_memory_source() for runtime configuration

### Tests
- 48 new tests for MemoryContext, MemoryContextSource, and lifecycle hooks
- All 108 memory-related tests passing
- mypy and ruff checks passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

backend/app/services/context/engine.py

@@ -7,6 +7,7 @@ Provides a high-level API for assembling optimized context for LLM requests.
 
 import logging
 from typing import TYPE_CHECKING, Any
+from uuid import UUID
 
 from .assembly import ContextPipeline
 from .budget import BudgetAllocator, TokenBudget, TokenCalculator
@@ -20,6 +21,7 @@ from .types import (
     BaseContext,
     ConversationContext,
     KnowledgeContext,
+    MemoryContext,
     MessageRole,
     SystemContext,
     TaskContext,
@@ -30,6 +32,7 @@ if TYPE_CHECKING:
     from redis.asyncio import Redis
 
     from app.services.mcp.client_manager import MCPClientManager
+    from app.services.memory.integration import MemoryContextSource
 
 logger = logging.getLogger(__name__)
 
@@ -64,6 +67,7 @@ class ContextEngine:
         mcp_manager: "MCPClientManager | None" = None,
         redis: "Redis | None" = None,
         settings: ContextSettings | None = None,
+        memory_source: "MemoryContextSource | None" = None,
     ) -> None:
         """
         Initialize the context engine.
@@ -72,9 +76,11 @@ class ContextEngine:
             mcp_manager: MCP client manager for LLM Gateway/Knowledge Base
             redis: Redis connection for caching
             settings: Context settings
+            memory_source: Optional memory context source for agent memory
         """
         self._mcp = mcp_manager
         self._settings = settings or get_context_settings()
+        self._memory_source = memory_source
 
         # Initialize components
         self._calculator = TokenCalculator(mcp_manager=mcp_manager)
@@ -115,6 +121,15 @@ class ContextEngine:
         """
         self._cache.set_redis(redis)
 
+    def set_memory_source(self, memory_source: "MemoryContextSource") -> None:
+        """
+        Set memory context source for agent memory integration.
+
+        Args:
+            memory_source: Memory context source
+        """
+        self._memory_source = memory_source
+
     async def assemble_context(
         self,
         project_id: str,
@@ -126,6 +141,10 @@ class ContextEngine:
         task_description: str | None = None,
         knowledge_query: str | None = None,
         knowledge_limit: int = 10,
+        memory_query: str | None = None,
+        memory_limit: int = 20,
+        session_id: str | None = None,
+        agent_type_id: str | None = None,
         conversation_history: list[dict[str, str]] | None = None,
         tool_results: list[dict[str, Any]] | None = None,
         custom_contexts: list[BaseContext] | None = None,
@@ -151,6 +170,10 @@ class ContextEngine:
             task_description: Current task description
             knowledge_query: Query for knowledge base search
             knowledge_limit: Max number of knowledge results
+            memory_query: Query for agent memory search
+            memory_limit: Max number of memory results
+            session_id: Session ID for working memory access
+            agent_type_id: Agent type ID for procedural memory
             conversation_history: List of {"role": str, "content": str}
             tool_results: List of tool results to include
             custom_contexts: Additional custom contexts
@@ -197,15 +220,27 @@ class ContextEngine:
             )
             contexts.extend(knowledge_contexts)
 
-        # 4. Conversation history
+        # 4. Memory context from Agent Memory System
+        if memory_query and self._memory_source:
+            memory_contexts = await self._fetch_memory(
+                project_id=project_id,
+                agent_id=agent_id,
+                query=memory_query,
+                limit=memory_limit,
+                session_id=session_id,
+                agent_type_id=agent_type_id,
+            )
+            contexts.extend(memory_contexts)
+
+        # 5. Conversation history
         if conversation_history:
             contexts.extend(self._convert_conversation(conversation_history))
 
-        # 5. Tool results
+        # 6. Tool results
         if tool_results:
             contexts.extend(self._convert_tool_results(tool_results))
 
-        # 6. Custom contexts
+        # 7. Custom contexts
         if custom_contexts:
             contexts.extend(custom_contexts)
 
@@ -308,6 +343,65 @@ class ContextEngine:
             logger.warning(f"Failed to fetch knowledge: {e}")
             return []
 
+    async def _fetch_memory(
+        self,
+        project_id: str,
+        agent_id: str,
+        query: str,
+        limit: int = 20,
+        session_id: str | None = None,
+        agent_type_id: str | None = None,
+    ) -> list[MemoryContext]:
+        """
+        Fetch relevant memories from Agent Memory System.
+
+        Args:
+            project_id: Project identifier
+            agent_id: Agent identifier
+            query: Search query
+            limit: Maximum results
+            session_id: Session ID for working memory
+            agent_type_id: Agent type ID for procedural memory
+
+        Returns:
+            List of MemoryContext instances
+        """
+        if not self._memory_source:
+            return []
+
+        try:
+            # Import here to avoid circular imports
+
+            # Configure fetch limits
+            from app.services.memory.integration.context_source import MemoryFetchConfig
+
+            config = MemoryFetchConfig(
+                working_limit=min(limit // 4, 5),
+                episodic_limit=min(limit // 2, 10),
+                semantic_limit=min(limit // 2, 10),
+                procedural_limit=min(limit // 4, 5),
+                include_working=session_id is not None,
+            )
+
+            result = await self._memory_source.fetch_context(
+                query=query,
+                project_id=UUID(project_id),
+                agent_instance_id=UUID(agent_id) if agent_id else None,
+                agent_type_id=UUID(agent_type_id) if agent_type_id else None,
+                session_id=session_id,
+                config=config,
+            )
+
+            logger.debug(
+                f"Fetched {len(result.contexts)} memory contexts for query: {query}, "
+                f"by_type: {result.by_type}"
+            )
+            return result.contexts[:limit]
+
+        except Exception as e:
+            logger.warning(f"Failed to fetch memory: {e}")
+            return []
+
     def _convert_conversation(
         self,
         history: list[dict[str, str]],
@@ -466,6 +560,7 @@ def create_context_engine(
     mcp_manager: "MCPClientManager | None" = None,
     redis: "Redis | None" = None,
     settings: ContextSettings | None = None,
+    memory_source: "MemoryContextSource | None" = None,
 ) -> ContextEngine:
     """
     Create a context engine instance.
@@ -474,6 +569,7 @@ def create_context_engine(
         mcp_manager: MCP client manager
         redis: Redis connection
         settings: Context settings
+        memory_source: Optional memory context source
 
     Returns:
         Configured ContextEngine instance
@@ -482,4 +578,5 @@ def create_context_engine(
         mcp_manager=mcp_manager,
         redis=redis,
         settings=settings,
+        memory_source=memory_source,
     )