AID Story Helper

About

AID Story Helper + MemorAID — Beta Extension
This extension is a companion tool for AI Dungeon (AID) designed to introduce deep NPC psychological state-tracking, dynamic memory management, and structured 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.

1. The Story Helper Dashboard
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 three primary sections 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.
Settings & Prompts Tab: Customize AI providers, API keys, and prompt instruction templates.
2. 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 all active cards in your scenario in a bulk background sequence.
3. 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 (which can be toggled on/off in the game settings, and dynamically stores key story details as bullet points).

[!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: You don't have to navigate through deep game menus to fix a stale memory. In the AID Memories list, simply click the Edit button next to any memory item:
An inline text editor opens directly in the panel.
Modify the text to adjust the story context.
Click Save to send an EditMemory GraphQL mutation back to the AI Dungeon server. The game's memory state is updated immediately for the next turn.
Memory Deletion: Click the Delete button next to any memory item to prune outdated info from your local list.
Configuration Warning: If the extension detects that the necessary config cards or important settings are missing, a premium banner will alert you at the top of the interface and offer to create them with a single click.
4. MemorAID: Real-Time NPC Memory & Cognitive Loop
In default AI Dungeon play, NPCs lack active, turn-by-turn internal tracking. They react based on the general story context, often resulting in inconsistent behaviors or delayed reactions to critical events. 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:

Action Interception: When you submit an action (e.g., typing in the input box and pressing Enter), the extension intercepts the outgoing GraphQL ActionRequest in the browser before it reaches the AI Dungeon servers.
Immediate UI Transition: AI Dungeon's client immediately enters its native loading state, replacing the input text box with the loading spinner. While this loading indicator is active, the extension blocks the request.
Background Assessment: The extension's background page reviews the latest 5 actions in your gameplay context and checks your list of 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 the character's thoughts and reflections using the customized MemorAID prompt instructions.
It formats this reaction using a structured, three-stage cognitive loop (described below).
Story Card Synchronization: The extension saves these thoughts to a companion Memory Card (e.g., Character Name (Memory)) in your adventure's Story Cards on the AI Dungeon server.
Request Release & Response: The extension releases the blocked ActionRequest. AI Dungeon's server processes your action. 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 to the new stimulus on the very same turn.
WebSocket Card Refresh: Once the response is generated, the server pushes a WebSocket update (AdventureStoryCardsUpdate) to the browser, updating the text in your open card editing panel.
[!NOTE]
Safety Timeout: A 4-second safety gate is integrated into the GQL blocker. If a network issue occurs or the background generation takes too long, the block automatically releases so your game never freezes.

5. 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:

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, a sudden movement, heat, distance).
Thought: One sentence describing their internal reaction, cognitive dissonance, or psychological conflict (e.g., how their worldview/status clashes with the physical reality of the situation).
Action: One sentence describing their immediate impulse, intent, or plan of action for the next turn.
Historical Thought Log & Archiving
When a companion Memory Card is updated, the extension doesn't discard previous reflections. Instead, it maintains a structured Thought Log within the card's description (notes) field. The latest reflection is formatted and wrapped at the top of the card's value (which the AID context reader parses), while all historical reflections are appended in chronological order in the description field:

[THOUGHT LOG]
(turn 12)
[Character Name's Thoughts:
- Intake: ...
- Thought: ...
- Action: ...
]
This historical record keeps the active memory card clean and concise (slicing text to prevent context bloat) while preserving a long-term journal of the NPC's mind in their card description.

6. Configuring MemorAID in Your Adventure
To activate thought tracking for specific NPCs in a scenario:

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.
The Control Card: You must have a Story Card in your adventure titled exactly Configure MemorAID.
Important Characters List: In the description (or Notes) field of the Configure MemorAID card, add a line with your target characters:
IMPORTANT_CHARACTERS: CharacterName1, CharacterName2
Multi-line and carriage-return safe: The parser handles line breaks and commas seamlessly, meaning you can list characters on separate lines or as a comma-separated list.
Trigger matching: The extension checks the latest action text against the character's name and keys. If a match occurs, the thought generation triggers. If no listed characters are triggered, the interception resolves instantly.
7. Multi-Pass Deep Character Card Generation
Standard Story Card generation tools often write flat descriptions, or cut off mid-sentence because of output token limits on the AI Dungeon server. 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 (tells or 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 (specific psychological friction, alignment, or evolving attitude).
Memory Context Injection
When you trigger the native "Generate" button on a character's Story Card, the extension scans the database for their companion MemorAID memory card. If found, it automatically extracts all thoughts generated since their last card update and prepends them to the 4,000-character generation context. This ensures that the generated character description adapts to reflect the experiences and memories they accumulated during gameplay.

8. 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 adventure state, allowing you to restore or migrate your data at any time.
9. Technical & Privacy Architecture
Offline-First Storage: Character states, generated prompts, and metadata are cached locally using IndexedDB in your browser.
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.