ARCHITECTURE_MEMORY_GRAPH.md

# 🧠 AKIRA Memory + Emotional Intelligence Architecture

## 1. Overview: 3-Layer System

```

┌─────────────────────────────────────────────────────────┐

│ LAYER 1: User Message Input                             │

│ (agressivo, pergunta, pedido, etc)                      │

└──────────────────────┬──────────────────────────────────┘

                       ↓

┌─────────────────────────────────────────────────────────┐

│ LAYER 2: AKIRA Internal Processing                      │

│ ├─ Detect Emotion                                       │

│ ├─ Search Memory Graph (with connections)              │

│ ├─ THINK/Reasoning (INTERNAL - never vaza)             │

│ ├─ Inject Emotional Tag in Prompt                      │

│ ├─ Generate Response (uses tag + thinking)             │

│ └─ Clean Response (_remove_ tags + thinking)           │

└──────────────────────┬──────────────────────────────────┘

                       ↓

┌─────────────────────────────────────────────────────────┐

│ LAYER 3: User Sees (Clean)                              │

│ (no thinking, no tags, no internal context)             │

└──────────────────────┬──────────────────────────────────┘

                       ↓

┌─────────────────────────────────────────────────────────┐

│ LAYER 4: Internal Storage (Never Shown)                 │

│ ├─ Save to MemoryNode                                   │

│ ├─ Create/Update Connections                           │

│ ├─ Update Emotional State                              │

│ └─ Index in Graph (for next session)                   │

└─────────────────────────────────────────────────────────┘

```

---

## 2. Phase 2: Emotional State System

### 2.1 Flow with Example

**Scenario: Aggressive user**

```python

# INPUT

user_message = "você é inútil! essa resposta é ridícula"

numero_usuario = "5531988776655"



# LAYER 2: INTERNAL PROCESSING



# Step 1: Detect Emotion

emotion = BART_emotion_analyzer(user_message)

# Result: "agressivo" (confidence: 0.92)



# Step 2: Search Memory Graph

context = memory_graph.search_with_connections(user_message, numero_usuario)

# Returns: [previous messages about same topic with connections]



# Step 3: Create Prompt WITH TAG

config_emotional_state = {

    "agressivo": {

        "tag": "<!STRICT_MODE_AGGRESSIVE>",

        "instruction": "User is HOSTILE. Be firm, professional, NOT rude. Maintain boundaries..."

    }

}



prompt = f"""

{config_emotional_state['agressivo']['tag']}



Previous context: {context}

{config_emotional_state['agressivo']['instruction']}



User message: {user_message}

"""



# Step 4: Generate (INTERNAL - thinking allowed to be verbose)

thinking = model.think(prompt)  # Can have multiple thinking attempts

response_with_thinking = model.generate(prompt)



# Example thinking (INTERNAL, never shown):

# <!THINKING>

# User is angry about response quality. They think I'm useless.

# Need to:

# 1. Acknowledge their frustration without being defensive

# 2. Show I understand the issue

# 3. Provide concrete solution

# 4. Maintain firm tone (they're hostile)

# </THINKING>

# Sua resposta anterior realmente não foi clara...



# LAYER 3: CLEAN BEFORE SENDING

cleaned_response = _clean_response(response_with_thinking)

# Removes: <!THINKING>, <!STRICT_MODE_AGGRESSIVE>, <!...>

# Result: "Sua resposta anterior realmente não foi clara..."



# OUTPUT TO USER

user_sees = cleaned_response

# "Sua resposta anterior realmente não foi clara..."

# (Firm tone because tag influenced thinking, but tag is removed)



# LAYER 4: SAVE INTERNALLY

profile_update = {

    "numero_usuario": "5531988776655",

    "emotional_state": "agressivo",

    "emotion_history": [..., "agressivo"],

    "is_hostile": True,

    "aggressive_count": 5

}



memory_node = MemoryNode(

    id=uuid(),

    timestamp=now(),

    content=user_message,

    user_id="5531988776655",

    type="user_message",

    tags=["angry", "complaint", "quality"],

    emotion="agressivo",

    connections=[

        {node_id: "prev_msg_id", relation: "follow_up", strength: 0.8}

    ]

)

memory_graph.add_node(memory_node)

save_to_profile(profile_update)

```

**7 Days Later: Same User Returns**

```python

# INPUT

user_message = "como faço isso funcionar?"

numero_usuario = "5531988776655"



# LAYER 2: INTERNAL PROCESSING



# Step 1: Load Profile

profile = load_profile(numero_usuario)

# Result: emotional_state = "agressivo", aggressive_count = 5



# Step 2: Search + Connections

context = memory_graph.search_with_connections(user_message, numero_usuario)

# Returns: [messages from 7 days ago + connections]

# AKIRA remembers: "Este usuário estava furioso há 7 dias"



# Step 3: Create Prompt WITH TAG (REUSE EMOTIONAL STATE)

prompt = f"""

<!STRICT_MODE_AGGRESSIVE>

Previous context: [7 days ago user was angry about...]

User has history of being demanding. Maintain firm professional tone.



User message: como faço isso funcionar?

"""



# Step 4: Generate

response = model.generate(prompt)



# LAYER 3: CLEAN

cleaned = _clean_response(response)



# OUTPUT

user_sees = cleaned

# (Maintains firm tone from tag influence)



# Result: ✅ "GUARDOU RANCOR" - Remembered user was aggressive!

```

### 2.2 Implementation Details

#### File: config.py
```python

EMOTIONAL_STATES = {

    "agressivo": {

        "tag": "<!STRICT_MODE_AGGRESSIVE>",

        "instruction": """

User is HOSTILE or AGGRESSIVE. Maintain these principles:

- Be firm and professional

- Don't match their aggression

- Set clear boundaries

- Provide concrete help

- Never apologize excessively

- Be direct and honest

""",

        "response_style": "defensive",

        "memory_days": 30  # Remember 30 days

    },

    

    "feliz": {

        "tag": "<!WARM_FRIENDLY_MODE>",

        "instruction": """

User is HAPPY and POSITIVE. Match their energy:

- Be warm and encouraging

- Use friendly language

- Share enthusiasm

- Build on their positive momentum

- Celebrate their wins

""",

        "response_style": "warm",

        "memory_days": 15

    },

    

    "triste": {

        "tag": "<!EMPATHETIC_SUPPORTIVE_MODE>",

        "instruction": """

User is SAD or FRUSTRATED. Show empathy:

- Acknowledge their feelings

- Be supportive, not dismissive

- Provide actionable help

- Offer encouragement

- Don't minimize their concerns

""",

        "response_style": "supportive",

        "memory_days": 20

    },

    

    "confuso": {

        "tag": "<!CLEAR_PATIENT_MODE>",

        "instruction": """

User is CONFUSED. Simplify:

- Break down complex ideas

- Use examples and analogies

- Be patient

- Confirm understanding

- Offer step-by-step guidance

""",

        "response_style": "patient",

        "memory_days": 10

    },

    

    "neutro": {

        "tag": "<!NEUTRAL_PROFESSIONAL_MODE>",

        "instruction": "Standard professional tone",

        "response_style": "neutral",

        "memory_days": 0

    }

}

```

#### File: persona_tracker.py (Add Fields)

```python

def create_user_profile(numero_usuario):
    return {

        # ... existing fields ...

        

        # PHASE 2: Emotional State Fields

        "emotional_state": "neutro",           # Current emotion

        "emotion_history": [],                 # [timestamp, emotion]

        "is_hostile": False,                   # Flag for security

        "aggressive_count": 0,                 # Tracks patterns

        "last_emotion_change": None,           # When state changed

        "emotion_confidence_score": 0.0,       # How sure are we?

        

        # PHASE 3: Memory Graph Fields

        "memory_nodes": [],                    # Node IDs related to this user

        "favorite_topics": {},                 # topic → frequency

        "communication_style": "neutral",      # Learned style

    }

```


#### File: api.py - New Methods

```python

def _detect_and_store_emotional_state(self, message, numero_usuario):

    """

    Detect emotion from message and save to profile

    Returns: emotion_state (str)

    """

    # Use existing BART emotion analyzer

    emotion = self.emotion_analyzer(message)

    # emotion = {"label": "agressivo", "score": 0.92}

    

    if emotion["score"] < 0.5:

        return "neutro"

    

    emotion_state = emotion["label"]

    

    # Load profile

    profile = self.persona_tracker.get_profile(numero_usuario)

    

    # Update emotion

    profile["emotional_state"] = emotion_state

    profile["emotion_history"].append({

        "timestamp": datetime.now(),

        "emotion": emotion_state,

        "confidence": emotion["score"]

    })

    profile["last_emotion_change"] = datetime.now()

    profile["emotion_confidence_score"] = emotion["score"]

    

    # Track aggression pattern

    if emotion_state == "agressivo":

        profile["is_hostile"] = True

        profile["aggressive_count"] += 1

    elif profile["aggressive_count"] > 0 and emotion_state in ["feliz", "neutro"]:

        # User calmed down

        profile["is_hostile"] = False

        # But aggressive_count stays for history

    

    # Save updated profile

    self.persona_tracker.save_profile(numero_usuario, profile)

    

    return emotion_state





def _inject_emotional_tag_in_prompt(self, prompt, numero_usuario):

    """

    Inject emotional state tag into prompt

    Returns: modified_prompt (str with tag prepended)

    """

    profile = self.persona_tracker.get_profile(numero_usuario)

    emotion_state = profile.get("emotional_state", "neutro")

    

    # Check memory retention (should we keep old emotion?)

    if emotion_state != "neutro":

        last_change = profile.get("last_emotion_change")

        if last_change:

            memory_days = EMOTIONAL_STATES[emotion_state].get("memory_days", 7)

            age = (datetime.now() - last_change).days

            if age > memory_days:

                emotion_state = "neutro"

    

    # Get tag and instruction

    config = EMOTIONAL_STATES.get(emotion_state, EMOTIONAL_STATES["neutro"])

    tag = config["tag"]

    instruction = config["instruction"]

    

    # Prepend to prompt

    modified_prompt = f"{tag}\n\nEmotional Context Instructions:\n{instruction}\n\n{prompt}"

    

    return modified_prompt

```

#### File: api.py - Modify generate()
```python

def generate(self, prompt, numero_usuario, ...):

    """

    Modified generate to include emotional state

    """

    # PHASE 2: NEW - Detect and store emotion

    emotion_state = self._detect_and_store_emotional_state(

        user_message, numero_usuario

    )

    

    # PHASE 2: NEW - Inject emotional tag in prompt

    prompt = self._inject_emotional_tag_in_prompt(prompt, numero_usuario)

    

    # Generate response (thinking allowed internally)

    response = self._call_provider(prompt)

    

    # Clean response (removes tag + thinking)

    cleaned = self._clean_response(response)

    

    # PHASE 3: NEW - Save to memory graph

    # (to be implemented next)

    

    return cleaned

```

---

## 3. Phase 3: Memory Graph System

### 3.1 Why Memory Graph?

**Without Graph** (Current):
```

User Session 1: "Tenho dor de cabeça"

  Memory: [msg1]



User Session 2: "Tomo remédio?"

  Memory: [msg1, msg2]

  Problem: AKIRA doesn't know msg2 is related to msg1



User Session 3 (next month): "Ficou melhor?"

  Memory: [msg1, msg2, msg3]

  Problem: AKIRA doesn't know msg3 is asking about msg1

  Result: "Melhorou o quê?" (Lost context!)

```

**With Graph** (Proposed):
```

MemoryNode(msg1): "Tenho dor de cabeça"

  tags: [health, pain, symptom]



MemoryNode(msg2): "Tomo remédio?"

  tags: [medicine, treatment]

  connections: [(msg1, "follow_up_question", strength=0.9)]



MemoryNode(msg3): "Ficou melhor?"

  tags: [status, improvement]

  connections: [(msg1, "status_update", strength=0.95)]



Result:

  search("Ficou melhor?") finds:

    - msg3 (direct match)

    - msg1 (connected: status_update)

    - msg2 (connected: related_problem)

  

  AKIRA now knows: "Mês atrás você tinha dor de cabeça. Melhorou?"

```

### 3.2 Data Structure

```python

class MemoryNode:

    """Represents a single message/thought in the graph"""

    

    id: str                              # UUID

    timestamp: datetime                  # When created

    content: str                         # Message text

    user_id: str                        # Isolation

    type: str                           # "user_message", "akira_response", "observation"

    tags: List[str]                    # [health, pain, question]

    emotion: str                        # "agressivo", "feliz", etc

    connections: List[Connection]      # Links to other nodes

    

    class Connection:

        node_id: str                    # Points to which node

        relation_type: str              # "follow_up", "related", "solution_for", "reference"

        strength: float                 # 0.0-1.0 (relevance score)

        explanation: str                # Why connected?





class MemoryGraph:

    """Graph of user memories with logical connections"""

    

    nodes: Dict[str, MemoryNode]        # All nodes

    user_index: Dict[str, List[str]]    # user_id → [node_ids]

    

    def add_node(node: MemoryNode) → str:

        """Add new node to graph"""

        

    def connect(from_id, to_id, relation, strength, explanation) → None:

        """Create connection between nodes"""

        

    def search(query, user_id, limit=10) → List[MemoryNode]:

        """Search with BFS through connections"""

        

    def get_context(node_id, depth=2) → enriched_context:

        """Get node with all connected nodes up to depth"""

```

### 3.3 Connection Detection

```python

def detect_connections(new_message, user_id, existing_nodes):

    """

    Detect if new message relates to existing nodes

    Returns: [(node_id, relation_type, strength), ...]

    """

    connections = []

    

    # Strategy 1: Keyword matching

    for node in existing_nodes:

        common_tags = set(new_message.tags) & set(node.tags)

        if common_tags:

            strength = len(common_tags) / max(len(new_message.tags), len(node.tags))

            connections.append((

                node.id,

                "related_by_tags",

                strength

            ))

    

    # Strategy 2: Temporal proximity (follow-up detection)

    recent_nodes = [n for n in existing_nodes if (now - n.timestamp) < timedelta(hours=2)]

    if recent_nodes:

        # Likely follow-up

        connections.append((

            recent_nodes[0].id,

            "immediate_follow_up",

            0.95

        ))

    

    # Strategy 3: Embedding similarity

    new_embedding = embed(new_message.content)

    for node in existing_nodes:

        node_embedding = embed(node.content)

        similarity = cosine_similarity(new_embedding, node_embedding)

        if similarity > 0.7:

            connections.append((

                node.id,

                "similar_topic",

                similarity

            ))

    

    return connections

```

### 3.4 Smart Search

```python

def search_with_connections(query, user_id, depth=3):

    """

    BFS search that follows connections

    Returns: List[MemoryNode] with relevant nodes

    """

    queue = []

    visited = set()

    results = []

    

    # Start: find nodes matching query

    initial_nodes = [n for n in graph.nodes.values() 

                     if n.user_id == user_id and query in n.content]

    

    for node in initial_nodes:

        queue.append((node, depth))

    

    # BFS: follow connections

    while queue:

        current_node, remaining_depth = queue.pop(0)

        

        if current_node.id in visited:

            continue

        visited.add(current_node.id)

        results.append(current_node)

        

        if remaining_depth > 0:

            # Add connected nodes to queue

            for connection in current_node.connections:

                if connection.node_id not in visited:

                    next_node = graph.nodes[connection.node_id]

                    queue.append((next_node, remaining_depth - 1))

    

    return results

```

---

## 4. Integration Timeline

### Phase 1 ✅ Done
- Context isolation
- Recursion protection
- User validation

### Phase 2 (30-40 min)
- Emotional detection + storage
- Tag injection
- Profile persistence

### Phase 3 (2-3 hours)
- MemoryNode + MemoryGraph
- Connection detection
- Smart search
- Integration into generate()

---

## 5. Security Guarantees

✅ **Thinking never shown**
- Removed by _clean_response() before sending
- Tags removed
- Internal context removed

✅ **Context always preserved**
- MemoryNodes save everything
- Graph persists across sessions
- Connections maintained

✅ **User isolation**
- Every node has user_id

- Search filters by user_id
- No cross-user leakage

✅ **Emotional state private**
- Profile only for that user
- Historical emotions saved
- Pattern tracking for safety (aggressive_count)



---



## 6. Example: Full Flow



**Day 1, User A**

```

Input: "Tenho ansiedade social"

→ Detect: neutro (baseline)

→ MemoryNode_1: tags=[mental_health, anxiety]

→ No connections (first message)

→ Save to profile

→ Output: "Entendo... ansiedade social é..."

```



**Day 1, 5 min later, User A**

```

Input: "Fico nervoso em grupos"

→ Detect: confuso (from word analysis)

→ Tag: <!CLEAR_PATIENT_MODE>

→ Search finds: MemoryNode_1 (similar topic)
→ Connect: MemoryNode_2 → MemoryNode_1 (related_by_tags, 0.85)
→ Add context: "Você mencionou ansiedade social... fico nervoso em grupos é relacionado?"
→ Output: "Sim, isso está muito relacionado. Aqui estão estratégias... [patient tone]"
→ Save: MemoryNode_2 with connection

```



**Day 30, User A**

```

Input: "Como faço para melhorar minha sociabilidade?"

→ Detect: neutro (but check profile)

→ Profile shows: emotion_history = [confuso]
→ Search with connections finds:
    - MemoryNode_1: "Tenho ansiedade social"

    - MemoryNode_2: "Fico nervoso em grupos"
→ AKIRA context: "Você tem trabalhado na sua ansiedade social. Aqui estão 5 técnicas práticas..."
→ Output: Highly relevant because graph understood multi-turn journey
```



Result: ✅ Context improved automatically. Graph made AKIRA smarter!



---



## 7. Deployment Checklist



- [ ] Phase 1 deployed to production

- [ ] Phase 2 code written and tested

- [ ] Phase 2 deployed

- [ ] Phase 3 design reviewed

- [ ] Phase 3 code written and tested

- [ ] Phase 3 deployed

- [ ] Monitor: emotional detection accuracy

- [ ] Monitor: graph connection quality

- [ ] Collect user feedback