🧠 MindForge

# 🧠 MindForge **Lightweight NPC memory for AI Dungeon.** One NPC. One unresolved memory. One conversation that can change how they see you. MindForge gives recurring characters persistent private thoughts, beliefs, goals, secrets, plans, and relationship notes. A promise, a withheld detail, or a changed opinion can influence what they do later. Built for compact context, character-driven roleplay, and hands-off memory maintenance. ━━━━━━━━━━━━━━━━━━━━ ## ✦ Before You Play ### ⚙️ MindForge starts ON MindForge is enabled from the first turn — there is nothing to configure before you play. A one-time notice appears when the adventure starts. To pause or resume later: - Type **`/mf off`** in-game to pause, and **`/mf on`** to resume, or - Open **Story Cards → Configure MindForge** and set **`Enabled: false`**. While paused, MindForge can still prepare the configuration and identify the main NPC, but it does not inject memories, update brains, or process ordinary story output. You can leave it paused and play the scenario normally. ━━━━━━━━━━━━━━━━━━━━ ## ✦ What MindForge Adds - ⚙️ **On by default** — works from the first turn with no card editing or setup answer. - 🔔 **One-time startup notice** — a transient toast tells you it is on and how to pause it; it never enters the story or the context. - 🕹️ **In-game control** — `/mf off` pauses and `/mf on` resumes NPC memory at any time. - 🧠 **Persistent private memories** — NPCs retain compact thoughts, promises, goals, and relationship notes. - 🎭 **Independent perspectives** — characters can hold incomplete beliefs, keep secrets, and gradually change their views. - 💬 **Continuity across turns** — earlier conversations and choices can influence later reactions. - 🧩 **Individual Brain Cards** — inspect or edit each registered NPC’s stored thoughts. - 🛠️ **Automatic maintenance** — recognizable card damage, repeated memories, and growing brains are handled in the background. - 🛡️ **Improved output cleanup** — recognized hidden operations and unfinished memory commands are removed from visible responses. - ⚡ **Compact context handling** — relevant memories share a controlled budget; passive turns use a lighter read-only format. - ♻️ **Cache-friendly transport** — preserves the incoming context when the host signals cache-efficient mode. - 👥 **Optional supporting minds** — manually added NPCs can maintain their own separate memories. - 🌍 **Optional World Memory and World Cards** — retain public observations about recurring places and objects. - ⚙️ **Hands-off play** — no commands are required during normal gameplay. Memory behavior still depends on the selected model, available context, and what actually happens in the story. ━━━━━━━━━━━━━━━━━━━━ ## ✦ Showcase Setup Five answers establish the scene: - Your character’s name - Your role or background - One important NPC - Their connection to you - What that NPC remembers, suspects, regrets, wants, or blames you for The scene begins inside the **Memory Vault**, beneath an abandoned shopping arcade. A sealed capsule waits with your name on it. Someone from your past arrives. Part of the label has been scraped away. The NPC’s account of your shared history may be incomplete or mistaken. Your own interpretation, intentions, and next move remain open. Question them. Compare accounts. Make a promise. Withhold information. Inspect the capsule—or refuse. Keep playing after the first revelation. What matters is how earlier choices affect what happens next. ━━━━━━━━━━━━━━━━━━━━ ## ✦ Main NPC & Supporting Characters Automatic discovery prepares **one clear main NPC**. It does not automatically give every character in the scenario a simulated mind. Want another character to remember and react across turns? Add their name below the main NPC in: **Configure MindForge → Notes/Description** Use one NPC per line, with a simple first name followed by optional comma-separated aliases. Once MindForge is enabled, manually registered NPCs can become active when their names appear and update their own Brain Cards. The active-NPC limit and context budget still apply. ━━━━━━━━━━━━━━━━━━━━ ## ✦ Gameplay Tips - Use a simple first name for the main NPC. - Mention their name naturally when bringing them into a scene. - Start with one NPC to make memory changes easier to observe. - Use **Balanced** for most adventures, including cache models. - Use **Stable** for smaller or fragile models. - Check **Player Name** in the config card if automatic detection misses it. - Inspect a Brain Card’s **Notes/Description** to see stored thoughts—these may contain spoilers. - Try following up on an earlier promise, disagreement, or discovery. - Leave **World Memory** and **World Cards** off for the most focused showcase. - A completely full cache context may leave no room for additional memories. ━━━━━━━━━━━━━━━━━━━━ ## ✦ Use MindForge in Your Own Scenario **GitHub:** https://github.com/Leolynns/MindForge