Data And Memory

Shared Data Versus Session Data

Use one session_id per save game and a stable engine ID as npc.id: bios, facts and history all follow that ID. History keeps the newest history_limit lines (0-50, default 10).

NPC Bios And Facts

Nothing is added automatically. To try two fictional NPCs (Mira = npc_guide, Oren = npc_scout) and a few facts, run once in WSL from the server folder (safe to repeat; it never overwrites your edits):

php scripts/seed_example.php

Then edit them on Configuration > NPC bios. Facts can belong to one NPC or be global, and can be searched and edited there. Try it from the client folder:

.\example_mod.exe --say "Who are you?"
.\example_mod.exe --say "When does the market open?"

Mira answers from her bio, then from the market fact.

How Facts Are Retrieved

• The server takes up to 8 words of 4-32 letters or digits from the player's line, minus a short stopword list.
• It runs PostgreSQL full-text search (simple configuration) and returns at most 3 facts for that NPC or global facts, plus the stored bio.
• This is keyword matching, not semantic search: "market" matches, but a synonym such as "bazaar" does not.

Each turn's details in Control Panel > Logs keep a copy of what was retrieved under "Retrieved for this request". Later fact edits do not change that copy.

Profiles

1. Open Configuration > World & Behavior > Profiles.
2. Create a profile with a name and a short system prompt. Model, reply mode and TTS voice are optional; empty fields inherit the config.
3. Assign NPC IDs, or tick Default to apply it to every NPC without its own profile.

In mock mode, ask what is your profile? and the NPC answers My profile is <name>. A profile can switch only to mock or LLM Studio (dwemerllm), so a stored profile never sends your key to another provider.

Memory And Vector Search

Both are off by default. Open Configuration > AI & Voice > Memory settings:

• Enabled gives each turn this session's saved summary and newest diary entries.
• Automatic notes and Automatic fact proposals call the NPC's model after each reply. With a paid provider, these extra calls cost money.
• Review on Roleplay > Memory: edit or regenerate the summary, manage diary entries, and approve or reject candidate facts. An approved candidate becomes a fact for that NPC in every session.

Vector search over facts is optional. Choose mock (hashed words, not semantic) or openai (any OpenAI-compatible embeddings URL), enable it, save, and press Reindex. Turns fall back to keyword search when the embedding call fails or a fact has no current vector. Editing a fact clears its vector.

Session Checkpoints

A checkpoint is a named copy of one session's conversation lines and memory notes, inside this database. It is not a backup. Run these in WSL as dwemer from the server folder:

php scripts/checkpoint.php save    demo-save-1 before-boss
php scripts/checkpoint.php list    demo-save-1
php scripts/checkpoint.php restore demo-save-1 before-boss
php scripts/checkpoint.php delete  demo-save-1 before-boss

Roleplay > Checkpoints on the dashboard does the same, and asks for confirmation before restore and delete.

• Stop or cancel the client's pending requests first. Any turn still in flight for that session is answered 409 stale and not saved.
• The server never reads game saves. You match a checkpoint to a save by hand, using the client's session_id.
• Each session keeps at most 20 checkpoints of up to 2000 lines.

For whole-database backups, see Updates and Backups.

Full reference: SETUP.md, Bios, knowledge and session checkpoints and CONNECTORS.md, Memory and vector search.

Next step: Test conversations, events and logs.