canalhandia/specs/ai-personalities-and-memory/spec.md

# Spec: AI Multi-Personalities, Judite (SAC), Dynamic Tags, Persistent Memory & Event Expansion

## 1. Objective & Motivation

Transform the `ia` module in the `Canalhandia` plugin into a rich, personalized companion system:
1. **Per-Player AI Selection:** Each player can pick their own AI persona (or use server default).
2. **Dynamic Chat Tags:** Replace static `[IA]` tag with the active persona's name (e.g. `[Judite]`, `[Zoeiro]`, `[Amigão]`, `[Seco]`, `[Aldeão]`, `[Narrador]`).
3. **Judite Roleplay Persona:** A hilarious Brazilian SAC/telemarketing attendant (Porta dos Fundos style) with fictitious protocols, bureaucratic quirks, hold music jokes, and deadpan efficiency.
4. **Persistent Compressed Memory (`ia-memoria.yml`):** Retain player memories, key facts, past locations, and sliding-window conversation summaries across server reboots.
5. **Rich Location & Stat Grounding:** Grant the AI direct knowledge of places the player has been (death locations via `DeathLog`, saved pins via `Notes`, current biomes/coords, statistics).
6. **Expanded Event Reactivity:** Broaden spontaneous AI commentary to include death streaks, boss/raid triumphs, milestone achievements, first-time dimension visits, and custom join greetings with persona-specific voice.

---

## 2. Personas Specification

### A. Tag & Persona Definitions

| Persona Key | Display Tag | Tone & Character Description |
|---|---|---|
| `judite` | `[Judite]` | Atendente de SAC/telemarketing burocrática e impaciente, viciada em gerundismo ("estaremos verificando no sistema"), gera números de protocolo ("Protocolo 2026-MC-..."), pede para aguardar na linha, cobra pendências (fome/vida baixa) com frieza corporativa e dá respostas precisas. |
| `zoeiro` | `[Zoeiro]` | Veterano debochado do servidor que usa mortes e estatísticas contra o jogador, mantendo o bom humor. |
| `amigao` | `[Amigão]` | Amigo paciente, caloroso e prestativo, ideal para acolher novatos sem sarcasmo. |
| `seco` | `[Seco]` | Minimalista, direto e sarcástico, 1 a 2 frases curtas sem emoção. |
| `aldeao` | `[Aldeão]` | Solene e místico, falando como um sábio aldeão ancestral de Minecraft. |
| `narrador` | `[Narrador]` | Narrador épico e dramático de RPG de fantasia medieval ("Eis que o bravo viajante indaga..."). |
| `neutro` | `[IA]` | Assistente direto, neutro e sem persona marcante. |

### B. Dynamic Tag Rendering
- In `/ia`, `/iap`, and chat responses: Tag is rendered as `Msg.tag(persona.displayTag(), persona.tagColor())` instead of fixed `[IA]`.
- Java players retain rich hover cards detailing the persona name and question prompt.

---

## 3. Player Preferences & Commands

- `/ia persona` / `/ia personalidade`: Lists all available personas and highlights the player's active selection.
- `/ia persona <nome>`: Sets the player's personal persona (persisted in `ia-memoria.yml`).
- `/ia persona padrao` / `/ia persona reset`: Resets to the server-wide default persona configured in `config.yml`.
- `/ia status`: Displays active persona, memory status, and summary of stored facts for the player.
- `/ia esquecer`: Clears the player's stored conversation memory/facts.

---

## 4. Persistent Memory & Chat Compression Engine (`PlayerMemory`)

### File: `plugins/Canalhandia/ia-memoria.yml`

```yaml
players:
  <uuid>:
    name: "Diguin_n"
    persona: "judite"
    updated_at: 1771450000000
    summary: "Jogador explorou o Nether e perguntou sobre poções de agilidade. Tem base na vila das coordenadas 120, 64, -300."
    facts:
      - "Tem base na vila (120, 64, -300)"
      - "Morreu recentemente no Void"
      - "Gosta de criar axolotes e golfinhos"
```

### Memory Mechanics:
1. **Short-Term Session Memory:** Live exchanges stored in memory for immediate follow-ups.
2. **Key Facts Extraction / Journaling:** Maintained per player to keep long-term context across restarts.
3. **Sliding Compression:** When conversation turns exceed limits, compress previous interactions into the player's persistent summary string, ensuring bounded token usage.

---

## 5. Context Grounding & Tools

- **Tool `lugares_jogador`:**
  - Retrieves player's recent deaths from `DeathLog` (`mortes.yml`).
  - Retrieves player's saved pins/bases from `Notes` (`notas.yml`).
  - Retrieves current coordinates, world dimension, and biome.
- **Tool `estatisticas_jogador`:**
  - Reads mined blocks, mob kills, total deaths, playtime from `OfflineStats`.
- **Tool `conquistas_jogador`:**
  - Reads unlocked titles and achievements.
  - Server leaderboards, recent public milestones, online player list.

---

## 6. Expanded Event Engine

The AI can react to diverse gameplay triggers (gated by `aiBudget` and configurable settings):
1. **Death Streaks & Notable Deaths:** Void deaths, falling, explosions, Warden/Wither encounters.
2. **Player Joins (`aiWelcome`):** Persona greets returning player with contextual facts (e.g. Judite mentions pending tickets or absence duration).
3. **Milestone Crossings:** When a player crosses round milestones (e.g. 100km walked, 10,000 blocks mined) or earns rare achievements.
4. **Boss Defeats & Raids:** Dragon/Wither defeats or raid victories.

---

## 7. Acceptance Criteria

1. All existing 316 unit tests continue to pass without regressions.
2. New unit tests covering:
   - `PersonaTest`: Validation of all personas including `JUDITE` and `NARRADOR`, display tags, system prompts, safety guard invariant.
   - `PlayerMemoryTest`: YAML serialization, compression, fact storage, and per-player persona retention.
   - `ToolsTest`: Verification of `lugares_jogador` and updated tool definitions.
   - `AiTagTest`: Dynamic persona tag rendering in chat and hover styling.
   - `EventTest`: Event triggers formatting prompts with appropriate persona context.
3. `/ia persona <nome>` persists choices across restarts.
4. Full clean compilation with `mvn test` and `mvn package`.