# From: apps/api/app/agents/memory/client.py:10-46

class MemoryClientManager:
    """Manages mem0 client with graph memory enabled."""
    
    async def get_client(self) -> AsyncMemoryClient:
        client = AsyncMemoryClient(
            api_key=settings.MEM0_API_KEY,
            org_id=settings.MEM0_ORG_ID,
            project_id=settings.MEM0_PROJECT_ID,
        )
        
        # Enable graph memory for entity relationships
        await client.project.update(enable_graph=True)
        return client

# From: apps/api/app/utils/memory_utils.py

async def store_user_message_memory(
    user_id: str,
    message: str,
    conversation_id: str
):
    """
    Store user message in background (fire-and-forget).
    
    Extracts:
    - Named entities (people, places, organizations)
    - Dates and deadlines
    - Preferences and opinions
    - Action items and commitments
    """
    # Run as background task
    # Non-blocking, doesn't slow down responses

# From: apps/api/app/agents/tools/memory_tools.py

@tool
async def search_memory(
    config: RunnableConfig,
    query: str,
    limit: int = 10
) -> dict:
    """
    Search user's memory for relevant information.
    
    Examples:
    - "What projects am I working on?"
    - "Who is Sarah Johnson?"
    - "What are my preferences for meetings?"
    - "When is the Q4 deadline?"
    """
    # Semantic search across memory graph
    # Returns contextual information with sources

# From: apps/api/app/agents/memory/skill_learning/service.py:29-94

class SkillLearningService:
    """Orchestrates skill extraction and storage."""
    
    async def learn_from_conversation(
        self,
        messages: List[AnyMessage],
        agent_id: str,  # e.g., "gmail_agent", "twitter_agent"
        session_id: Optional[str] = None,
        executing_llm: Optional[ChatOpenAI] = None,
    ):
        """
        Runs two extraction strategies in parallel:
        1. LLM Extraction - Cheap model analyzes conversation
        2. Self-Reflection - Executing LLM documents experience
        """

# From: apps/api/app/agents/memory/skill_learning/models.py

class Skill(BaseModel):
    # Core identification
    trigger: str              # "When user asks to..."
    procedure: str            # "Do this sequence..."
    agent_id: str             # "gmail_agent"
    
    # Execution details
    tools_used: List[str]     # ["GMAIL_SEARCH_MESSAGES", "GMAIL_SEND_EMAIL"]
    
    # Learning insights
    what_worked: str          # "Searching history first provided context"
    what_didnt_work: str      # "Direct reply without context felt abrupt"
    gotchas: str              # "Always check for email threads"
    optimal_approach: str     # "Search → Analyze → Draft → Review"
    unnecessary_tools: List[str]  # Tools tried but not needed
    
    # Quality tracking
    success_criteria: str     # "Email sent with proper context"
    confidence_score: float   # 0.0 - 1.0
    
    # Metadata
    session_id: str
    learned_at: datetime
    times_validated: int      # How many times this skill proved useful

# From: apps/api/app/agents/memory/skill_learning/storage.py

async def store_skills_batch(skills: List[Skill]) -> int:
    """
    Store multiple skills in MongoDB.
    
    Index on:
    - agent_id (which agent learned this)
    - trigger (semantic embeddings for search)
    - tools_used (find by tool combinations)
    - confidence_score (prioritize high-confidence skills)
    """

async def search_skills(
    query: str,
    agent_id: str,
    limit: int = 5
) -> SkillSearchResult:
    """
    Search for relevant skills using semantic similarity.
    
    Returns best matching procedures for current task.
    """

# From: apps/api/app/agents/core/nodes/memory_learning_node.py

async def memory_learning_node(
    state: State,
    config: RunnableConfig,
    store: BaseStore
) -> State:
    """
    End-of-graph hook that runs after every agent execution.
    
    Learns:
    1. Skills (procedural knowledge) → MongoDB per agent
    2. User memory (personal info) → mem0 per user
    
    Runs as fire-and-forget background task.
    """
    
    # Extract user_id and agent_id from config
    # Run both learning processes in parallel
    await asyncio.gather(
        skill_learning_service.learn_from_conversation(...),
        memory_client.add(...)  # User memory
    )

# Stored in mem0 with user_id as namespace
await memory_client.add(
    messages=[...],
    user_id="user_123",  # Isolates this user's memories
    metadata={...}
)

# Search only returns this user's memories
results = await memory_client.search(
    query="my preferences",
    user_id="user_123"
)

# Stored in MongoDB with agent_id as namespace
skill = Skill(
    agent_id="gmail_agent",  # This skill is for gmail_agent only
    trigger="compose professional email",
    procedure="..."
)

# Search only returns skills for this specific agent
skills = await search_skills(
    query="send email",
    agent_id="gmail_agent",  # Won't return twitter_agent skills
    limit=5
)

# From: apps/api/app/agents/core/nodes/manage_system_prompts.py

async def manage_system_prompts_node(state, config, store):
    """
    Injects relevant memories and skills into system prompt.
    """
    
    user_id = config.get("user_id")
    agent_id = config.get("agent_name")
    
    # Get user memories
    memories = await memory_client.search(
        query=state.query,
        user_id=user_id,
        limit=10
    )
    
    # Get relevant skills
    skills = await skill_service.search_skills(
        query=state.query,
        agent_id=agent_id,
        limit=5
    )
    
    # Build enhanced prompt
    prompt = f"""
    {base_system_prompt}
    
    ## User Context:
    {format_memories(memories)}
    
    ## Learned Procedures:
    {skill_service.format_skills_for_prompt(skills, agent_id)}
    """

# User memory search is cached per conversation
@cache(ttl=300)  # 5 minutes
async def get_user_context(user_id: str, query: str):
    """Cache prevents repeated mem0 API calls."""
    
# Skill search is cached per agent
@cache(ttl=600)  # 10 minutes
async def get_agent_skills(agent_id: str, query: str):
    """Cache prevents repeated MongoDB queries."""

# From: apps/api/app/agents/core/agent.py:95-100

# Memory storage is non-blocking
task = asyncio.create_task(
    store_user_message_memory(user_id, message, conversation_id)
)
_background_tasks.add(task)
task.add_done_callback(_background_tasks.discard)

# User gets instant response
# Memory processing happens in background

# From: apps/api/app/agents/tools/memory_tools.py

MEMORY_TOOLS = [
    search_memory,      # Search user's memory
    list_memory,        # List all user memories
    add_memory,         # Manually add memory
    update_memory,      # Update existing memory
    delete_memory,      # Remove memory
]

# These tools are included in every agent's toolkit

# Memory retention policies
class MemoryRetention:
    USER_MEMORIES = "indefinite"  # Until user deletes
    SKILL_MEMORIES = "indefinite"  # Continuous improvement
    
    # But confidence degrades over time
    async def decay_confidence(skill: Skill):
        """Lower confidence score if not validated recently."""
        days_since_validation = (now - skill.last_validated_at).days
        if days_since_validation > 90:
            skill.confidence_score *= 0.9  # 10% decay

// Available in dashboard
interface MemoryStats {
  user_memories: {
    total: number;
    categories: Record<string, number>;
    last_updated: string;
  };
  
  skills_learned: {
    total: number;
    by_agent: Record<string, number>;
    avg_confidence: number;
  };
  
  memory_usage: {
    queries_this_week: number;
    memories_used: number;
    skills_applied: number;
  };
}