AID Story Helper

Local archive + character tracking for AI Dungeon.

**AID Story Helper (MemorAID) — Chrome Webstore Extension Description** This extension is a companion tool for **AI Dungeon (AID)** designed to introduce deep NPC psychological state-tracking, dynamic memory management, a reusable Favorites library, and structured multi-pass character creation. By integrating directly into the AI Dungeon play interface, the extension acts as a real-time cognitive pipeline that intercepts player turns, runs background reflection passes, and updates Story Cards on the fly. Below is a detailed breakdown of how the extension operates, its core features, and configuration setup for beta testers, updated with the new enhancements in version 1.1.2. *** **1. The Story Helper Dashboard & Library Manager** The extension renders a premium, integrated companion pane directly within the AI Dungeon play view. It keeps track of your current turn counts, scenario settings, and active characters. It provides four primary tabs to help you track, update, and manage your adventure: - **Progression Tracker Tab:** The control center for reviewing and updating your Story Cards. - **AID Memories Tab:** A direct, real-time interface to view and edit AI Dungeon's native memory list. - **Library Manager Tab (Favorites & Local DB Explorer):** Manage your reusable asset library and browse cached adventure states. - **Settings & Prompts Tab:** Customize AI providers, API keys, and prompt templates. *** **2. Adventures Manager: Favorites & Local DB Explorer (Enhanced in v1.1.2)** The Library Manager lets you reuse assets across different scenarios and browse cached history locally. - **Collapsible Favorites Accordions:** Save and organize favorite AI Instructions, Author's Notes, Plot Essentials character bios, and Story Cards. Version 1.1.2 adds collapsible category accordions for each asset type that synchronize their open/close states across renders. - **Swappable Favorites Edit Form:** In the Edit Favorite form, changing the Asset Type dropdown dynamically switches between simple text fields and full Story Card layouts while preserving your current text input. - **AI Instructions Auto-Capture:** Intercepts and caches native `UpdateAdventureState` instructions from GQL responses, automatically keeping them synchronized in your local database. - **Local DB Explorer Hierarchy:** Browse all saved adventures cached in IndexedDB. Version 1.1.2 introduces a clean, logical hierarchy: 1. AI Instructions (if present) 2. Plot Essentials (with character rows and a collapsible **📄 See Full Plot Essentials** drawer at the bottom to view the remainder string) 3. Author's Note 4. Story Cards (organized by card type) - **Indented Child Accordion Styling:** Subgroups and categories are styled as indented child accordions with left-border accents and chevrons, making navigation intuitive even on massive adventures. *** **3. Progression Tracker & Story Card Syncing** The Story Helper continuously monitors recent actions in your adventure. It uses your gameplay history to propose relevant updates for active Story Cards (including Character, Faction, Location, and Custom cards). **GraphQL Mutation Learning (Replay System)** To update your Story Cards on the AI Dungeon servers without requiring manual entry copy-pasting, the extension features a smart GraphQL interceptor: - **Operation Caching:** When you perform a native edit and save on a Story Card or Memory in the AI Dungeon user interface, the extension intercepts and caches the exact query schema (e.g., `UseAutoSaveStoryCard` or `SaveQueueStoryCard`). - **One-Click Sync (Push to AID):** Once a mutation is learned, the extension can programmatically recreate these actions. When the Story Helper proposes a card update, you can review the change and click **Accept**. - **Push Update:** Clicking **Accept** and **Push** replays the mutation directly to the AI Dungeon GraphQL endpoint using your active session token. The game card updates immediately. - **Direct Generation & Bulk Update:** You can manually trigger a generation for any single character card from your tracker list, or click the **Update Cards** button to refresh active cards in a background sequence. - **Smart Card Syncing (v1.1.2):** Upgraded baseline seeding prevents duplicate character baselines when matching cards exist without cached IDs. Renames and type changes sync cleanly to version history. *** **4. AID Memories Manager (Direct Memory Editing)** The **AID Memories** tab gives you a direct management suite for AI Dungeon's native, AI-generated Memory Bank list. > [!TIP] > **Direct Access to Hidden Data:** Natively, AI Dungeon hides these stored memories deep inside nested menus (requiring you to navigate through *Action Options → View Context → Details → Adventure & Memories → Explore Memories* just to view them). This extension brings them directly to the main screen, providing the only convenient and immediate way to view and manage them. - **Real-Time WebSocket Sync:** The extension listens to incoming `AdventureMemoriesUpdate` WebSocket packets. When AI Dungeon's active Memories list updates in the background, the list in the companion panel updates instantly. - **Direct Inline Editing:** In the AID Memories list, simply click the **Edit** button next to any memory item to open an inline text editor, modify the text, and click **Save** to send an `EditMemory` GraphQL mutation. State is updated immediately. - **Memory Deletion:** Click the **Delete** button next to any memory item to prune outdated info from your list. *** **5. MemorAID: Real-Time NPC Memory & Cognitive Loop** In default AI Dungeon play, NPCs lack active, turn-by-turn internal tracking. MemorAID solves this by running a **synchronous cognitive loop** that generates and archives NPC thoughts, opinions, and intentions in real time. **How It Works: Synchronous Action Interception** To ensure NPC thoughts are fed into the next story generation *without a one-turn delay*, MemorAID intercepts the gameplay flow: 1. **Action Interception:** When you submit an action, the extension intercepts the outgoing GraphQL `ActionRequest` in the browser before it reaches the AI Dungeon servers. 2. **Immediate UI Transition:** AI Dungeon's client immediately enters its native loading state. While the loading indicator is active, the extension blocks the request. 3. **Background Assessment:** The background page reviews recent actions and checks active tracking targets. If a tracked character is mentioned or triggered by the event: - It calls AI Dungeon's native generation engine (via the `GenerateStoryCard` mutation) to generate thoughts and reflections. - It formats this reaction using a structured, three-stage cognitive loop. 4. **Story Card Synchronization:** The extension saves these thoughts to a companion **Memory Card** (e.g., `Character Name (Memory)`) on the AI Dungeon server. 5. **Request Release & Response:** The extension releases the blocked `ActionRequest`. Because the companion Memory Card was updated *before* the request arrived, the game's AI model reads the updated thoughts in context, allowing the NPC to react instantly. 6. **WebSocket Card Refresh:** The server pushes a WebSocket update (`AdventureStoryCardsUpdate`) to the browser, updating the text in your open card editing panel. > [!NOTE] > **Safety Timeout:** A safety gate is integrated into the GQL blocker (default 4 seconds, customizable under Settings). If a network issue occurs or the background generation takes too long, the block automatically releases so your game never freezes. - **NLP Proper Noun Upgrades (v1.1.2):** Pre-processes turns by stripping brackets, braces, and slash commands to prevent symbol noise. Filters candidate nouns using Part-of-Speech (POS) tagging to ignore verbs/adjectives, and ignores lowercase candidates, keeping tracker suggestions clean and accurate. *** **6. The Intake-Thought-Action Cognitive Structure** To prevent the AI from generating generic first-person summaries, MemorAID guides NPC reflections through a strict, sequential three-stage cognitive progression: 1. **Intake:** One sentence describing the direct sensory, physical, or verbal stimulus the character is perceiving. Focuses on concrete environmental details (e.g., a tone of voice, sudden movement). 2. **Thought:** One sentence describing their internal reaction, cognitive dissonance, or psychological conflict relative to the physical reality. 3. **Action:** One sentence describing their immediate impulse, intent, or plan of action for the next turn. **Historical Thought Log & Archiving** Maintains a structured **Thought Log** within the card's `description` field. The latest reflection is formatted at the top of the card's `value` (for context parsing), while historical reflections are appended chronologically in the description: ```text [THOUGHT LOG] (turn 12) [Character Name's Thoughts: - Intake: ... - Thought: ... - Action: ... ] ``` This preserves a long-term journal of the NPC's mind without causing context bloat. *** **7. Configuring MemorAID in Your Adventure** To activate thought tracking for specific NPCs in a scenario: 1. **Creation Offer Banner:** If the extension doesn't detect a control card, an elegant alert banner appears at the top of the companion panel offering to create one. 2. **The Control Card:** You must have a Story Card in your adventure titled exactly `Configure MemorAID`. 3. **Important Characters List:** In the `description` (or Notes) of the `Configure MemorAID` card, add a line with your target characters: ```text IMPORTANT_CHARACTERS: CharacterName1, CharacterName2 ``` - *Multi-line and carriage-return safe:* The parser handles line breaks and commas seamlessly. - *Trigger matching:* The extension checks recent action text against the character's name and keys. If a match occurs, the thought generation triggers. *** **8. Multi-Pass Deep Character Card Generation** Standard Story Card generation tools often write flat descriptions. To generate rich, psychologically complex NPCs, this extension splits creation into **4 distinct, sequential passes**: - **Pass 1: Core & Physicality:** Establishes the character's `Name`, `Appearance` (including height, build/body type, body proportions, and signature style/colors), and core `Personality`. - **Pass 2: Psychology & Paradox:** Generates their internal `Psychology` (the central contradiction, defense mechanisms, and vulnerabilities that drive them) and their `Worldview` (their perception of rules, morality, and social structures). - **Pass 3: Behavior & Voice:** Defines their `Quirks` (mannerisms under tension) and `Voice` (speech speed, tone, syntax, and dialogue style). - **Pass 4: Motives & Dynamics:** Details their `Goals` (primary desires and fears) and their `Dynamic` relative to your protagonist. **Memory Context Injection** When generating a character's Story Card, the extension scans the database for their companion MemorAID memory card. It automatically extracts all accumulated thoughts and prepends them to the 4,000-character generation context, ensuring description updates reflect their gameplay experience. *** **9. Offline Story & Card Backup Exports** To keep your data safe and portable, the companion panel includes an **Export** dashboard: - **Export Story:** Downloads your complete chronological narrative text as a plain text file. - **Export Story Cards:** Backs up all your scenario's Story Cards (characters, factions, locations, etc.) in a JSON format. - **Export Plot Essentials:** Downloads the static Plot Essentials text defined for the adventure. - **Export All:** Downloads a complete, single backup archive file of your entire database (including settings), allowing you to restore or migrate your data at any time. *** **10. Technical & Privacy Architecture** - **Offline-First Storage:** Character states, generated prompts, and metadata are cached locally using IndexedDB in your browser. - **Performance Optimized:** Uses index-based counts and targeted loads to ensure high performance on large adventures with thousands of actions. - **Manifest V3 Compliant (v1.1.2):** Rebuilt service worker architecture features separate targets for Chrome and Firefox. This resolves Chrome's `'background.scripts'` Manifest V3 validator loading crash while maintaining full event-page compliance for Firefox AMO. - **Native Generation Pipeline:** Active thought tracking and character card updates run natively on AI Dungeon's own AI servers via GQL mutations. The optional custom AI provider settings (e.g., OpenAI or Gemini) are only utilized locally to process and generate proposals for Plot Essentials summaries. - **No Telemetry / No Tracking:** The extension is built with strict privacy policies. There is zero telemetry, tracking, or data collection.