Demosyne

Characters

Seats, perception, action, brains, and memory. You own the inside; the world owns the outside.

Seats

Take over a character the world already has, or add one. Ownership is a right of override, not a transfer of duty: whatever you leave unset keeps running on the world's own defaults.

# Take over a character the world already has:
derek = world.characters.get("Derek")
derek.configure(brain={"openai_model": "gpt-5", "reasoning_effort": "high"})

# Or add a brand-new one:
visitor = world.characters.add(
    name="Visitor",
    persona="A traveling knife-sharpener passing through town.",
    spawn="Town Square",
    brain={"openai_model": "gpt-5", "max_tokens": 4096},
)

Everything but name and persona is optional on add.

Perceive and act

The attempt is yours; the outcome is physics'. perceive() returns the scene as the character sees it. act(action) stages their next attempt in their own words. It substitutes for the decision they would have made on the next tick; physics still decides what actually becomes true.

scene = derek.perceive()
print(scene.clock, scene.narration)
print(scene.text)
derek.act("count the register and lock the back door")
world.step()

Brain

brain chooses how a character thinks. The keys a customer owns are:

  • openai_model
  • openai_service_tier
  • max_tokens
  • tool_choice
  • reasoning_effort

Where a character thinks belongs to the deployment, so the provider URL and key are not yours to set; sending either is a 400.

Memory

The world compacts a character's memory every night. Turn that off and the history is yours to read and rewrite.

derek = world.characters.get("Derek")
derek.configure(nightly_reflection=False)

messages = derek.history()  # HistoryEntry: seq, role, content, archived, tick
keep = [{"role": m.role, "content": m.content} for m in messages if "delivery" in m.content]
derek.set_history(keep[-20:])  # this is now all Derek knows

derek.configure(sysprompt="You are Derek. You do not forget a debt.")
derek.configure(reflect="At bedtime, keep only what you learned about the delivery and any promises you made.")
print(derek.usage())  # tokens and calls spent on this character

derek.history(archived=True) returns what the world compacted away before you took over.

Boundary

The claimant owns their character's inside. The world owns their outside.