Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ba737de9b438582727160cdb9622b7851fc20300
interactive-story/planning/CONTEXT-AND-MEMORY.md
T

1169 lines
26 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink