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

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

1. Architecture & Component Design

                     ┌───────────────────────────┐
                     │    CanalhandiaCommand     │
                     │  (/ia, /iap, /ia persona) │
                     └─────────────┬─────────────┘
                                   │
                                   ▼
┌─────────────────┐         ┌──────────────┐         ┌────────────────────────┐
│  PlayerMemory   │◄───────►│      Ai      │◄───────►│      Tools / Wiki      │
│ (ia-memoria.yml)│         │(Orchestrator)│         │ (lugares_jogador, etc.)│
└─────────────────┘         └──────┬───────┘         └────────────────────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     │          MiniMax          │
                     │  (HTTP / Tools / Chat)    │
                     └───────────────────────────┘

Components:

1. Persona.java (Enum Enhancement):

   • Add JUDITE (SAC/Telemarketing persona) and NARRADOR (Fantasy narrator).
   • Add displayTag() (e.g. "Judite", "Zoeiro", "Amigão") and tagColor() (Adventure NamedTextColor).
   • Add persona-specific system prompts while maintaining the security invariant (GUARD).

2. PlayerMemory.java (New Persistent Service):

   • Manages plugins/Canalhandia/ia-memoria.yml.
   • Thread-safe, cached in-memory with disk persistence.
   • Stores per-player:
     • Selected persona (judite, zoeiro, etc.) or null (inherit server default).
     • Persistent compressed summary of past conversations.
     • List of key facts learned about the player (e.g., base coordinates, preferred building materials, fear of mobs).
   • Provides sliding-window compression: auto-condenses turns when memory exceeds thresholds.

3. Tools.java (Expanded Function Calling):

   • Add lugares_jogador function: fetches recent deaths from DeathLog, saved coordinates from Notes, and current biome/world.
   • Update definitions JSON to make the tool discoverable to the LLM.

4. Ai.java (Orchestrator Updates):

   • Integrate PlayerMemory.
   • Resolve effective persona per player (playerMemory.persona(player) -> fallback settings.aiPersona()).
   • In compose(): inject effective persona tone + playerMemory.formatContext(player) + location summary.
   • In deliver() and style(): render dynamic tag Msg.tag(persona.displayTag(), persona.tagColor()) instead of fixed [IA].
   • Update saySomething() to support persona-specific spontaneous events.

5. CanalhandiaCommand.java (CLI & Interaction):

   • Enhance /ia persona [nome] to set per-player persona or list available personas with descriptions and click-to-select suggestions.
   • Add /ia persona padrao to reset preference.
   • Add /ia status and /ia esquecer.

6. Canalhandia.java & Event Hooks (Event Expansion):

   • Wire expanded event triggers into saySomething():
     • Player joins (aiWelcome)
     • Player death streaks / notable deaths (onDeath)
     • Milestones & custom achievements (onMilestone)
     • Raid and boss victories (onBossDefeat)

---

2. File Touches

1. src/main/java/dev/marcospaulo/canalhandia/Persona.java — Add JUDITE, NARRADOR, tags, colors, and prompts.
2. src/main/java/dev/marcospaulo/canalhandia/PlayerMemory.java — New class for persistent per-player memory & compression.
3. src/main/java/dev/marcospaulo/canalhandia/Tools.java — Add lugares_jogador tool and integration with DeathLog & Notes.
4. src/main/java/dev/marcospaulo/canalhandia/Ai.java — Integrate PlayerMemory, dynamic persona tags, prompt composition.
5. src/main/java/dev/marcospaulo/canalhandia/CanalhandiaCommand.java — Subcommands for /ia persona, /ia status, /ia esquecer.
6. src/main/java/dev/marcospaulo/canalhandia/Canalhandia.java — Wire PlayerMemory lifecycle, expand event hooks.
7. src/test/java/dev/marcospaulo/canalhandia/PersonaTest.java — Unit tests for personas, tags, and system prompts.
8. src/test/java/dev/marcospaulo/canalhandia/PlayerMemoryTest.java — Unit tests for YAML storage, compression, and per-player state.
9. src/test/java/dev/marcospaulo/canalhandia/ToolsTest.java — Unit tests for lugares_jogador and tool execution.

---

3. Risks & Mitigations

• Risk: Token context blowup from memory/chat history.
  • Mitigation: Hard-cap memory summary length (max 300 chars) and max facts (max 5 items) per player.
• Risk: Thread safety when reading player memory in async AI tasks.
  • Mitigation: Synchronize all PlayerMemory reads/writes under monitor; snapshot memory context as immutable strings on main thread before async dispatch.
• Risk: API costs from spontaneous event comments.
  • Mitigation: All events remain strictly governed by Budget with cooldown windows and hourly/daily spend limits.