Character Studio Documentation ← Table of Contents

← Table of Contents

Context & World Building

Give your character background knowledge without bloating the Instructions file.

• What Context Files Do
• The Context Tab
• What Belongs in Context
• Context vs Instructions
• When Context Is Too Much
• Agent-Only Files (Dot Prefix)
• Remapping the Context Location

What Context Files Do

Context files are supplementary documents that live in the context/ subfolder of your project. Character Studio automatically loads all of them and sends their content to the model before every conversation turn — the model receives this material as grounding, treating it as established background knowledge it can draw on at any point in the conversation.

The purpose of this separation is clarity of purpose. Your instructions.txt should be about your character: who they are, how they think, how they speak, what they want, what they fear. Context files are for the world they inhabit — the setting, history, people, and rules that exist independently of the character's personality. Keeping these concerns in separate files makes both easier to write and maintain. When you need to update the lore around a faction, you open the context file about that faction. When you need to adjust the character's speech patterns, you open instructions. You don't have to search through one long file to find the right section.

Context files are also more easily shared. If you're building multiple characters in the same fictional universe, they can all reference the same world-lore context files while maintaining their own distinct instructions. Characters coexist in a consistent world without duplicating lore across every project.

The Context Tab

Click the Context tab in the left pane. Rather than opening a single file, this tab reveals a set of sub-tabs — one for each context file in your context/ folder. If you're starting fresh, the panel is empty except for an Add File button.

Clicking Add File prompts you for a filename. Use the .txt extension. The file is created immediately in the context/ folder and a new sub-tab appears for it. Click the sub-tab to open a Monaco editor for that file, write your content, and save with Ctrl+S. Every context file behaves like any other project file: full undo history, included in version control snapshots, editable at any time.

Context files are loaded in alphabetical order by filename. This matters when you have multiple files, because the concatenation order affects which information appears first in the context block. If your files reference each other — if your NPC list refers to locations described in your locations file, for example — you may want to control the order explicitly. The simplest way to do this is to prefix filenames with a number: 01_world.txt, 02_locations.txt, 03_npcs.txt. The numeric prefix forces alphabetical sorting to match your intended reading order.

To delete a context file, right-click (or use the tab's menu) and choose Remove. The file is deleted from the project and disappears from the sub-tab list. This is permanent and not undoable outside of the version history — if you're unsure whether you'll need a file again, save the project first so you have a snapshot to revert to.

What Belongs in Context

Context files are flexible. There's no fixed set of categories you're required to create. That said, here are the types of content that tend to work well as context rather than instructions:

World lore and setting

Geography, history, political structures, factions, religions, magic systems, technology levels, cultural norms — anything that defines the world the character exists in. This is the stuff a novelist would put in a world-bible: the background that makes the setting feel real and internally consistent. Your character knows this material implicitly, the way a real person knows the history of their country without having to look it up. Putting it in context means the model has it available when the conversation touches on these subjects.

NPC roster

A list of recurring characters the user might ask about or that your character might mention. For each NPC, record what your character knows about them: their name, their role, their relationship to the character, their current status, maybe a few personality descriptors. You don't need to write a full biography — a few lines per NPC is often enough. The goal is that when a user asks "what does Aria think of Commander Thessen?", the model has something concrete to draw on instead of making up a relationship on the spot.

Location descriptions

The places your story might visit. What does the capital city feel like? What's unusual about the market district? What does the abandoned fortress smell like at night? Location descriptions give the model the sensory and atmospheric detail needed to describe places vividly and consistently, rather than generating plausible-sounding but vague generics.

Rules and constraints

Things the world operates by that the character knows to be true. "Portals only function during the three hours around dawn." "The king has been dead for six months and there is no acknowledged heir." "Magic leaves a visible residue that fades over four hours." These are facts that define the playing field. Putting them in context means the model won't casually contradict them.

Ongoing state (for simple characters)

For characters without the Agent System (covered in Chapter 7), context files can serve as a simple persistent state store. A running quest log, a list of things the character has discovered, a set of tracked scores or outcomes. You update the file manually as the story progresses. This is a lightweight approach that works well for smaller stories, though it requires manual maintenance. The Agent System is more powerful for complex state tracking — it updates automatically based on conversation events.

Context vs Instructions

The line between context and instructions isn't always obvious at first. Here's a practical guide:

Put this in Instructions	Put this in Context
Personality traits and emotional range	World lore, history, and geography
The character's speech patterns and vocabulary	NPC names, roles, and relationships
Behavioral rules ("never reveal real name")	Location descriptions and atmosphere
The character's personal backstory and formative experiences	Factions, organizations, and political structures
Goals, motivations, and what the character wants from the conversation	World rules and mechanics ("how magic works")
How the character feels about specific topics or people	Timelines of key historical events
What the character knows and doesn't know	Glossaries of setting-specific terms

The core test: is this information about who the character is, or about the world they exist in? Character-defining information goes in Instructions. World-defining information goes in Context. When content spans both — "the character has strong feelings about the war that destroyed her home city" — the subjective, personal dimension (the feelings, the trauma, the opinions) belongs in Instructions; the objective, world-level dimension (the war, the city, the political context) belongs in a Context file that both the instructions and the model can reference.

When Context Is Too Much

The appeal of context files is easy to overdo. A rich world with interesting lore makes for a more immersive character — but every word in every context file costs tokens on every single message. A conversation with 10 context files totaling 20,000 words is spending those tokens before your first actual message even appears. This has real consequences.

The most obvious symptom is hitting token limits early in long conversations. As your conversation history grows turn by turn, the fixed overhead of a large context block leaves less and less room for actual dialogue before the conversation gets truncated or the model starts losing earlier context. What felt like plenty of space in early testing becomes a problem after 30 turns.

Other signs that you've over-loaded your context:

• Slower first responses — more tokens to process means more latency before the first word streams back.
• Confused or contradictory details — when too much information is present at once, models occasionally blend details from different files, producing inconsistencies that weren't in your source material.
• Irrelevant detail surfacing unprompted — a model that knows everything tends to mention everything; context files describing places your story hasn't visited yet can appear in responses before they're relevant.

Several approaches help:

• Trim ruthlessly. Every line that isn't necessary is a line you're paying to send on every turn. A 5,000-word world history document that the model draws on three times in a 200-turn roleplay campaign is expensive for what it delivers.
• Split by relevance. Keep the most relevant material in active context files and move less-relevant material somewhere else — archived in a notes folder, or commented out, or simply deleted if you're confident it won't be needed.
• Write densely. Context that communicates the same information in fewer words is strictly better. Bullet-point formats tend to be more token-efficient than prose for reference material like NPC lists and world rules.
• Use the Agent System. For complex characters with rich state — quest logs, relationship tracking, inventory, calendar — the Agent System (Chapter 7) is architecturally superior to context files. Agents load specific state on demand instead of including everything on every turn.

Agent-Only Files (Dot Prefix)

Context files whose names begin with a . are excluded from the automatic context block sent to the model. They appear in the context tab and behave like any other context file for editing purposes, but their content is never included in the per-turn context sent with your messages.

To create an agent-only file, prefix the filename with a dot when adding it: .baby-names.txt, .npc-database.json, .world-map.txt. Character Studio recognises the dot and skips the file when assembling the model context.

This is useful for two situations:

• Large reference data — a comprehensive item catalog, a full NPC database, an exhaustive location list. This material is too large to send on every turn, but you want it available in the project for agents to query selectively.
• Draft or scratchpad files — notes and working material you want to keep in the project folder without them affecting the model.

Remapping the Context Location

By default, Character Studio reads context files from the context/ subfolder of your project. This default works for most projects and requires no configuration.

If you have an unusual project structure — or if you're sharing a context folder across multiple projects in the same parent directory — you can change where Character Studio looks for context files using the fileMappings key in your project's config.json. This is an advanced configuration option covered in Chapter 8. For most users, the default context/ folder is exactly right and no remapping is needed.