# Adventure Storyteller — Context and Memory **Status:** Draft v0.1 **Purpose:** Define what information is supplied to the narrator on each turn, how long-term memory works, and how authority, lineage, retrieval, summaries, and imported knowledge interact. ## 1. Design Goal The language model should never be expected to remember an entire long-running story by itself. The application should construct a bounded context for every narrator turn using: - durable narrator rules, - campaign canon, - current authoritative state, - branch-safe summaries, - relevant older story memories, - relevant imported local knowledge, - recent active-lineage turns, - the user's current input. The full campaign history remains stored locally even when only a subset is sent to Ollama. The core rule is: > The application decides what the narrator is allowed to rely on; the model does not decide what counts as canon. ## 2. Context Layers The narrator context should be assembled from distinct layers. Recommended order: ```text 1. System / narrator rules 2. Campaign profile 3. Authoritative canon and world rules 4. Current authoritative narrative state 5. High-level campaign / arc summary 6. Relevant older story memories 7. Relevant imported local knowledge 8. Recent active-lineage turns 9. User's current input ``` Not every layer must appear on every turn. Each layer should have: - explicit authority, - source provenance, - token budget, - branch/lineage rules where applicable. ## 3. Authority Levels The narrator must distinguish between authoritative and suggestive information. Recommended authority hierarchy: ### Level 1 — Explicit Campaign Canon Highest authority. Examples: - FTL does not exist. - Mara is Edrin's sister. - Magic cannot resurrect the dead. - The story takes place in 1892. Sources: - campaign setup, - user-authored canon documents, - manual canon corrections. If narration conflicts with Level 1 canon, Level 1 wins. ### Level 2 — Accepted Story Facts / Current State Facts established by accepted active-lineage story history. Examples: - Aldric currently possesses the silver key. - Mara has already met the protagonist. - The eastern bridge was destroyed. - The Persephone is docked at Ceres Station. These are authoritative unless later invalidated or corrected. ### Level 3 — Accepted Historical Events Important events that occurred earlier on the active lineage. Examples: - Mara warned Aldric not to trust Captain Vale. - The crew discovered a signal beneath Europa's ice. - Aldric promised to return before sunrise. These are historical truth for the active story. ### Level 4 — Derived / Heuristic Memory Useful inferred information that may help continuity but must not be treated as hard canon. Examples: - Mara seemed nervous when Captain Vale arrived. - Aldric probably distrusts the city guard. - The abandoned station may be dangerous. The prompt should identify these as inference or interpretation. ### Level 5 — Imported Reference Material Supporting local information. Examples: - medieval tavern construction, - orbital mechanics reference notes, - technical description of fusion drives, - historical clothing references. Reference material may guide detail and plausibility but does not override campaign canon. ### Level 6 — Imported Inspiration Material Lowest authority. Examples: - public-domain fantasy passages, - science-fiction stories, - descriptive prose samples, - atmosphere/style excerpts. Inspiration can influence tone, imagery, pacing, or ideas. It must never be treated as proof that something exists in the current story world. ## 4. Authority Conflict Rule When two context items conflict: ```text higher authority wins ``` Example: Campaign Canon: ```text FTL travel does not exist. ``` Imported Reference: ```text A fictional source describes warp drives. ``` Narrator behavior: ```text Do not introduce warp drive as established technology. ``` The reference may still inspire descriptive language if relevant, but cannot override canon. ## 5. Pretrained Model Knowledge The local language model contains pretrained knowledge that cannot be erased. The application should instruct the narrator: > Pretrained knowledge may help with language, general plausibility, and invention, but it is not authoritative story canon. The narrator must not silently import: - named characters, - locations, - technologies, - factions, - magic systems, - plot facts from unrelated outside works unless the campaign context explicitly establishes them. The application cannot guarantee perfect suppression of pretrained knowledge, but it can make authority boundaries explicit and inspectable. ## 6. Current Authoritative State Every turn should include the minimum current state necessary for continuity. Potential categories: - current location, - current scene, - characters present, - active relationships, - possessions, - important conditions, - active story threads, - unresolved facts, - current organization/faction relationships, - world constraints relevant to the scene. The state context should be concise and structured. Do not dump the entire database into every prompt. ## 7. State Selection State should be selected based on relevance. Always include: - protagonist identity, - current location, - current scene, - key current conditions, - globally critical canon rules. Conditionally include: - nearby characters, - relevant items, - related factions, - thread-specific facts, - location-specific rules, - technology/magic constraints relevant to the action. ## 8. Recent History Recent active-lineage turns should normally be included verbatim. Purpose: - local conversational continuity, - dialogue coherence, - immediate action continuity, - writing rhythm. Recommended policy: - include as many recent turns as fit within the recent-history token allocation, - prefer complete turn boundaries, - never include abandoned/disposable future history, - preserve speaker/role metadata. The exact number of turns should be token-based rather than fixed. ## 9. Rolling Summary Older active-lineage material should be compressed into summaries. A rolling summary should contain: - major events, - current goals, - important discoveries, - relationship changes, - unresolved threads, - durable consequences. A summary should not preserve every stylistic detail. Important rule: > A summary is derived data, not authoritative history. The original transcript remains the source of truth. ## 10. Summary Scope Potential summary levels: ### Campaign Summary Very compressed overview of the story so far. ### Arc / Chapter Summary More detailed representation of a recent story segment. ### Turn-Range Summary Derived from a bounded range of turns. Recommended v1: - one campaign-level rolling summary, - optional turn-range/chapter summaries if inherited architecture supports them cleanly. ## 11. Summary Lineage Safety Every summary must be associated with the history it summarizes. If the user restores or diverges before part of that source history: - the invalid portion must not be reused, - unaffected ancestral summaries may remain valid, - new summaries should be created for the new continuation. A summary from abandoned history must never leak into active context. ## 12. Story Memory Long-term story memory should retrieve important older information that is not present in recent history or current summary. Examples: - a promise made 80 turns ago, - a minor character encountered much earlier, - the origin of an item, - a clue from a distant chapter, - a prior argument between two characters. Memory exists to restore specific detail that broad summaries may omit. ## 13. Memory Types Recommended memory categories: ### Event Memory Something happened. Example: ```text Turn 42: Mara hid a letter beneath the hearthstone. ``` ### Character Memory Important information about a character. Example: ```text Captain Vale strongly dislikes being touched unexpectedly. ``` ### Relationship Memory A meaningful interaction or relationship change. Example: ```text Aldric broke his promise to Mara. ``` ### Discovery Memory A clue or learned fact. Example: ```text The silver key bears the same symbol as the old abbey crypt. ``` ### Promise / Commitment Memory Future-relevant obligation. Example: ```text Aldric promised to return before dawn. ``` ### Location Memory Important prior detail about a place. ### Heuristic Memory Interpretive information that may be useful but is not hard canon. ## 14. Memory Authority Every memory should carry an authority classification. Examples: ```text accepted_story current_state heuristic ``` The narrator should be told which memories are: - factual, - inferred, - uncertain. This avoids turning guesses into canon. ## 15. Memory Creation Memories may be generated after accepted turns. Potential pipeline: ```text accepted turn | v memory extractor | v candidate memories | v application validation / classification | v stored memory records ``` Not every turn needs a permanent memory. The memory system should favor: - importance, - future usefulness, - uniqueness, - continuity relevance. ## 16. Memory Retrieval Retrieval should be local. Potential mechanisms: - lexical search, - semantic embeddings, - hybrid search. Current preference: > Hybrid local retrieval if practical. Reason: - lexical retrieval is transparent and precise for names/terms, - semantic retrieval is useful for conceptually related old events. Phase 0B should determine what the selected base already supports. ## 17. Embeddings If semantic retrieval is used: - embeddings must be generated locally, - preferably through Ollama, - no remote embedding API, - embeddings are derived data, - embeddings must be rebuildable. Potential local embedding model should be selected later based on actual hardware and model quality. ## 18. Memory Retrieval Query The retrieval query may include: - current user input, - current scene, - active story thread names, - entities mentioned, - current location, - current goals. Do not rely only on raw user input. Example: User: ```text I ask Mara whether she recognizes the symbol. ``` Retrieval query may include: ```text Mara symbol silver key abbey crypt prior discoveries ``` ## 19. Memory Retrieval Filtering Before ranking memories, filter by: - campaign, - active lineage, - allowed authority, - source validity, - enabled status. Never retrieve memories from: - abandoned future paths, - deleted campaigns, - unrelated campaigns. ## 20. Memory Ranking Potential ranking factors: - semantic similarity, - lexical match, - recency, - importance, - entity overlap, - story-thread overlap, - authority, - explicit user pinning. The final ranking formula should be simple and inspectable. ## 21. Memory Budget Retrieved memories should have a bounded token budget. Recommended behavior: - retrieve more candidates than will be used, - rerank locally, - include only the highest-value items that fit, - preserve source IDs for inspection. ## 22. Duplicate Suppression Do not include the same fact repeatedly through: - current state, - summary, - memory, - imported canon. If the current state already says: ```text Aldric possesses the silver key. ``` there is little value in also including three memories that say the same thing. Context builder should prefer the highest-authority concise representation. ## 23. Imported Knowledge Categories Imported local files must be classified as: ### Canon Authoritative campaign truth. ### Reference Supporting factual/descriptive material. ### Inspiration Optional creative influence. The classification must be visible and editable by the user. ## 24. Imported Canon Imported Canon should be treated similarly to manually entered campaign canon. Examples: - a setting bible, - technology rules, - faction descriptions, - map/location notes, - character bible. Imported Canon may be retrieved selectively rather than fully included every turn. ## 25. Imported Reference Reference material supports plausibility or detail. Examples: - medieval medicine, - orbital mechanics, - 19th-century railroad practice, - astronomy notes. It should be labeled in context as reference, not story truth. ## 26. Imported Inspiration Inspiration should be optional and low-authority. Potential behavior: - retrieve only when enabled, - use a small budget, - prefer scene/style relevance, - never allow inspiration to override canon. ## 27. Source Provenance Every retrieved imported chunk should retain: - source file ID, - source title, - classification, - chunk ID, - retrieval score/method. The prompt inspector should be able to show: ```text Reference used: Orbital Mechanics Notes.md Chunk 17 ``` ## 28. User-Pinned Knowledge The user should eventually be able to force certain knowledge into context. Examples: - always include this world rule, - include this character note for the next scene, - pin this reference document temporarily. For v1, campaign canon rules may serve as the primary pinned mechanism. A general pinning UI may be deferred. ## 29. Context Budget The application must explicitly budget tokens. Conceptual allocation: ```text System / narrator rules fixed reserve Campaign canon protected Current state protected Summary medium reserve Retrieved story memories bounded Imported knowledge bounded Recent history elastic Current user input protected Output generation reserve protected ``` Exact percentages should be configurable or derived from model context size. ## 30. Protected vs Elastic Context ### Protected Should not be dropped casually: - system rules, - critical canon, - current state, - current user input, - output token reserve. ### Elastic Can be reduced when context is tight: - old recent-history turns, - lower-ranked memories, - reference material, - inspiration material, - verbose summaries. ## 31. Context Reduction Order When the prompt is too large, recommended removal order: 1. lowest-ranked inspiration chunks, 2. lowest-ranked reference chunks, 3. lowest-ranked heuristic memories, 4. low-importance accepted memories already reflected elsewhere, 5. oldest recent-history turns, 6. compress or shorten summaries, 7. trim noncritical state detail. Do not drop: - critical narrator rules, - hard campaign canon needed for the scene, - current user input, - core current state. ## 32. Output Reserve The context builder must leave space for narrator output. It should not fill the entire model context window with input. Recommended behavior: - reserve a configurable maximum response budget, - add safety margin, - fail gracefully if protected context alone is too large. ## 33. Context Snapshot Every narrator generation should preserve enough information to reconstruct the effective prompt. At minimum record: - context component IDs, - rendered text or reproducible form, - token counts, - ranking scores, - model/settings, - active branch/head. This allows debugging. ## 34. Prompt Inspector The UI should eventually allow the user to inspect: - narrator rules, - current state, - summary, - retrieved memories, - imported knowledge, - recent history, - total token usage. This is particularly important when the narrator behaves unexpectedly. ## 35. User Override The user should be able to manually correct context-driving data. Examples: - fix canon, - disable a bad memory, - disable a knowledge source, - correct a character record, - mark a heuristic memory as wrong. The system should not force the user to manipulate raw embeddings or SQL. ## 36. Memory Correction If a stored memory is wrong: Potential actions: - delete/disable memory, - downgrade authority, - correct text, - replace with authoritative fact. Corrections should preserve provenance when practical. ## 37. Memory vs Fact Important distinction: ### Fact Structured authoritative assertion. ### Memory Retrievable narrative representation. Example: Fact: ```text Mara knows the location of the key. ``` Memory: ```text During the tavern conversation, Aldric accidentally revealed where the key was hidden. ``` The memory may provide richer narrative context. The fact provides concise state authority. ## 38. Memory vs Summary ### Summary Broad compression of a range of story history. ### Memory Specific retrievable detail. They solve different problems and should coexist. ## 39. Memory vs Imported Knowledge ### Story Memory Comes from this campaign's accepted history. ### Imported Knowledge Comes from user-supplied local material. Story memory must be lineage-aware. Imported knowledge is normally campaign-wide and not branch-specific. ## 40. Knowledge Retrieval Query Imported-knowledge retrieval may use: - current scene, - entities, - user input, - active story threads, - campaign genre/profile. Example: Scene: ```text The crew is approaching Europa. ``` Potential reference retrieval: - radiation environment, - orbital dynamics, - ice crust, - local campaign technology rules. ## 41. Canon Retrieval Canonical material should not rely solely on similarity search. Critical canon rules may need: - always-on inclusion, - entity-linked retrieval, - tag-based retrieval, - explicit rule triggers. Example: ```text FTL does not exist. ``` This should not disappear just because the current user input does not semantically resemble "FTL". ## 42. Global Canon Some canon should always be active. Examples: - setting era, - hard technology constraints, - magic existence/nonexistence, - narrator/player-control rules, - protagonist identity. Global canon should remain small. ## 43. Conditional Canon Other canon may be retrieved when relevant. Examples: - details of a distant city, - a faction's internal structure, - a specific ship subsystem, - an NPC's background. ## 44. Character Knowledge Potential future refinement: The narrator may need to distinguish: - objective world truth, - what the protagonist knows, - what an NPC knows. This is useful for secrets and mystery stories. For v1, support at least: - objective canon/state, - optional `knows` relationships/facts where important. A full separate-mind simulation like Sonder Engine is not required. ## 45. Secrets Secrets should not automatically be shown to the player-facing prose merely because they exist in authoritative state. The narrator can know secrets necessary to run the story. The prompt architecture may need separate labels such as: ```text GM-only canon player-known facts character-known facts ``` This should be considered in v1 if the selected base supports it cheaply. ## 46. Spoiler-Safe Context The application must distinguish: > narrator knowledge from: > text that should be revealed to the user. The narrator may receive hidden information while being instructed not to reveal it until narratively appropriate. This is a prompt discipline requirement. ## 47. Story Style Memory Some user preferences may be durable within a campaign: - preferred prose length, - dialogue density, - violence level, - descriptive richness, - pacing, - point of view. These should live in campaign configuration rather than be inferred repeatedly from history. ## 48. Temporary Direction User out-of-character direction may be: - one-turn only, - scene-level, - durable campaign guidance. The UI should eventually distinguish these. Example: ```text For this scene, keep the pacing tense and fast. ``` should not necessarily become permanent campaign canon. ## 49. Memory Extraction Timing Possible strategies: ### Every turn Simple but potentially expensive. ### Threshold/batch Extract after several turns. ### Selective Only when state extractor flags something important. Recommended initial approach: > Reuse the selected base's proven mechanism if it is local and correct; otherwise perform lightweight extraction after each accepted turn and allow later optimization. ## 50. Summary Generation Timing Possible triggers: - token threshold, - number of turns, - scene/chapter boundary, - manual request. Recommended: - automatic token/turn threshold, - preserve source lineage. ## 51. Failure Handling If memory extraction fails: - accepted story turn remains valid, - no corrupted memory should be stored, - retry can occur later. If summary generation fails: - story continues, - older direct history may temporarily remain longer, - failure must not corrupt authoritative state. If embedding generation fails: - lexical retrieval should remain possible if implemented. Derived-memory failures must not block story persistence. ## 52. Offline Operation All context and memory operations must work locally. Permitted v1 data flow: ```text Local browser -> local application -> local SQLite/files -> local Ollama ``` No: - remote vector DB, - remote embedding API, - cloud search, - automatic web retrieval. ## 53. Context Construction Example User input: ```text I ask Mara whether she recognizes the symbol on the key. ``` Possible assembled context: ```text SYSTEM You are the narrator... Do not override canon... GLOBAL CANON Magic is rare. The dead cannot be resurrected. CURRENT STATE Location: Crooked Lantern Tavern Aldric possesses the silver key. Mara is present. Mara trusts Aldric cautiously. STORY SUMMARY Aldric is searching for Edrin... RELEVANT STORY MEMORIES [Accepted event] Turn 38: Edrin's desk contained the silver key. [Accepted discovery] Turn 51: The key bears a symbol matching the abbey crypt. [Heuristic] Mara appeared uneasy when the abbey was mentioned. REFERENCE Source: Abbey Notes.md The symbol is historically associated with... RECENT HISTORY ... USER I ask Mara whether she recognizes the symbol on the key. ``` ## 54. Context Construction Example — Science Fiction User: ```text Can the Persephone reach Europa before the storm hits? ``` Context: ```text GLOBAL CANON FTL does not exist. Persephone uses a fusion torch drive. CURRENT STATE Persephone is departing Ceres Station. Fuel reserve: established as limited. Crew has detected a radiation storm. REFERENCE Orbital Mechanics.md Relevant local transfer notes... STORY MEMORY Turn 112: Chief Engineer stated maximum sustained acceleration... RECENT HISTORY ... USER Can the Persephone reach Europa before the storm hits? ``` ## 55. What Should Not Be Sent Avoid routinely sending: - entire campaign transcript, - all entities, - all imported documents, - abandoned branch memories, - irrelevant character biographies, - duplicate facts, - old low-value heuristics, - raw embeddings, - internal database metadata not useful to narration. ## 56. Context Debugging If the narrator makes an unexpected choice, the system should support questions such as: - Which memory caused this? - Which canon rule was present? - Was the relevant fact omitted? - Did an abandoned branch leak in? - Did an inspiration passage overpower canon? - Was the recent-history window too short? This is why context provenance is a first-class requirement. ## 57. Phase 0B Validation Questions Codex should answer: 1. How does AI-DnD currently rank and retrieve memories? 2. Are AI-DnD memories branch-aware? 3. Can abandoned-branch memories leak into active context? 4. How are Story Cards selected and injected? 5. Can Story Cards be generalized into Canon / Reference / Inspiration classes? 6. What exact embedding provider does local AI-DnD use with Ollama? 7. Can memory retrieval work fully offline? 8. What context components are visible in AI-DnD's Insights view? 9. How does Open Dungeon decide when to summarize old history? 10. Can ai-adventure's FTS lore layer be retained as a deterministic lexical retrieval component? 11. How difficult would hybrid lexical + semantic retrieval be in the selected base? 12. Can current context budgeting preserve hard canon under pressure? 13. Are summaries tied explicitly to source lineage? 14. Can memory extraction failure occur without blocking a successful turn? 15. Can prompt/context snapshots be retained without excessive database growth? ## 58. Acceptance Criteria The final implementation must satisfy: - full campaign history remains stored even when not in context, - only active-lineage story history influences the narrator, - campaign canon outranks all other context, - accepted story facts outrank heuristic memory, - reference material cannot override canon, - inspiration cannot silently become canon, - old important events can be retrieved beyond the recent-history window, - retrieval works locally, - no remote embeddings/search are required, - abandoned branch memories do not leak, - context remains bounded, - output space is reserved, - prompt composition is inspectable, - retrieved sources retain provenance, - summaries are lineage-safe, - memory failures do not corrupt authoritative story state. ## 59. Current Recommendation Use a layered, authority-aware context builder: ```text PROTECTED | v System / Narrator Rules + Global Canon + Current State | v ---------------- + Story Summary + Relevant Story Memories + Relevant Local Knowledge + Recent History + Current Input | v OLLAMA ``` Retrieval should be: ```text local + lineage-aware + provenance-preserving + authority-aware + token-bounded ``` The application should treat context construction as a deterministic subsystem that can be inspected and tested independently of prose generation.