English

Lore Books

Help: Quick Start · Stories · Characters · Lore Books · Multiplayer · Discover · Advanced · Templates · FAQ

A lore book is a collection of entries — facts, world-building snippets, character details, historical events — that are selectively injected into the AI prompt based on relevance. Instead of cramming everything into the system prompt or character descriptions, you maintain a large library of lore and let Dream Scrolls pull in only the entries that matter for the current moment in the story.

Lore Book Types

TypePurpose
World BookGlobal world-building facts relevant across multiple stories in the same setting. Attach to any story where the world applies.
Story BookLore specific to a single story — ongoing events, NPCs, locations that only exist in this narrative.
Character BookCharacter-specific lore; attach to a character and it is automatically available in any story that character participates in.

A single story can have multiple lore books attached simultaneously. All their entries are retrieved together during generation.

Creating Entries

Each lore book contains one or more entries. To add an entry, open a lore book and click Add Entry.

FieldDescription
LabelA short name for your own reference. Not sent to the AI; used only to identify entries in the editor.
ContentThe text injected into the prompt when this entry is triggered. Write it as prose the AI will read directly — it becomes part of the context.
TagsA comma-separated list of keywords. When any of these words appear in recent message history, this entry is triggered. Matching is case-insensitive and checks for the whole word or substring.
WeightA priority score from 0 to 5. When the lore context budget is tight and not all triggered entries can fit, higher-weight entries are kept first. Use weight 5 for critical lore that must never be dropped, and lower weights for background detail.
PermanentIf checked, this entry is always injected regardless of whether its tags appear in context. Use sparingly — permanent entries always consume budget, even when irrelevant.

How Retrieval Works at Generation Time

Every time the AI generates a response, Dream Scrolls runs the following process:

  1. Tag scan — recent message history is scanned for words that match any entry's tags.
  2. Candidate list — all entries whose tags match are added to the candidate list, along with all permanent entries.
  3. Budget enforcement — the candidate list is sorted by weight (descending). Entries are added to the prompt one by one until the lore context budget is exhausted.
  4. Injection — surviving entries become available to the prompt template as the lore array; wherever your System Prompt places {{#lore}}...{{/lore}} (see Templates) is where they appear.

Permanent entries are always included first and count against the budget before any tag-triggered entries.

If you find that important entries are being dropped, you can:

  • Increase their weight.
  • Mark them as Permanent.
  • Increase the Lore Context Length in the story's Context settings.
  • Shorten the content of lower-priority entries.

Vector Search

In addition to tag matching, lore books can use semantic vector search to retrieve entries that are relevant by meaning rather than exact keywords.

Enabling Vector Search

  1. Open the lore book settings.
  2. Select an Embedding Model from the dropdown (embedding-capable models are configured by an admin under Config → Models).
  3. Click Re-vectorize — this generates vector embeddings for all entries in the book. You must re-vectorize whenever you add or substantially edit entries.
  4. Set the Vectorization Threshold (0–1). This is the minimum cosine similarity score an entry must reach to be included. A higher threshold (e.g. 0.85) is stricter and only returns very close matches; a lower threshold (e.g. 0.6) casts a wider net.

When to Use Vector Search

Vector search is most useful for:

  • Character backstories that are relevant to plot discussions rather than name mentions.
  • Historical events described in ways that may not use the exact keyword an entry is tagged with.
  • Large lore libraries where maintaining exhaustive tag lists is impractical.

Tag-based and vector-based retrieval work together — an entry can be triggered by either mechanism.

Attaching Lore Books to Stories

From the Story Settings

When creating or editing a story, you can attach lore books in the story settings form.

From the Play Screen (without leaving)

  1. Open the play screen config panel.
  2. Go to the Lore tab.
  3. Use the attach/detach controls to add or remove lore books in real time.
  4. You can also create a new lore book directly from this tab.

Lore Context Length

Each story has a configurable Lore Context Length — the maximum number of tokens reserved for lore entries in every prompt. If you notice that relevant entries are not appearing, or that the AI seems unaware of important lore, try increasing this value in the story's Context accordion settings.

Keep in mind that the lore context budget comes out of the total Context Length. Increasing lore context means less room for message history, so balance the two based on your story's needs.

Export and Import

Lore books can be exported as JSON from the lore book list menu. The JSON contains all entries with their labels, content, tags, weight, and permanent flag. If the lore book has vector search enabled, its Embedding Model selection is also carried along as a portable hint and re-matched by name on import — if no matching model exists on the importing install, it falls back to that install's default embedding model. You can import a JSON lore book via Lore Books → Import Lore Book, or clone one directly from Discover Lore Books.