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

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.