Policy

The policy is one JSON document that tells Plots and Memory how to behave. It also decides how many model calls your events cause, and so what they cost. This page lists every setting an account may change, its default, and what it does to your bill.

What the policy is

The policy has three sections: shared for rules every module obeys, memory for Memory, and plots for Plots. Every member has a default. A member you leave out takes its default, and a policy without a section runs that section on defaults. You never need to send a policy to start.

• An account has one policy on the hosted Director: the last one you stored. All your API keys, sign-in tokens, games, and projects share it.
• The policy is read when an event is processed or a decision is made, so a new policy applies from the next event or decision.
• Storing, reading, and changing the policy needs no module switch, costs nothing, and does not count toward the request limit.

Store and read the policy

PUT /v2/policy stores the policy. GET /v2/policy reads the policy Director runs.

curl -X PUT https://director.eposyne.com/v2/policy \
  -H "Authorization: Bearer $EPOSYNE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @policy.json

Send the whole document. It replaces the stored one. The body is at most 65,536 bytes. Director checks every section first and stores nothing unless all of it is valid. A valid policy answers 200 with the policy state:

{
  "source": "pushed",
  "hash": "9b2c0f5c1c4e0d3a7f1e6a8b5d2c4f60a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9",
  "stored_at": "2026-10-13T18:00:00.000Z",
  "policy": {
    "memory": {"weighing": "model"}
  }
}

curl https://director.eposyne.com/v2/policy \
  -H "Authorization: Bearer $EPOSYNE_API_KEY"

• source is pushed when you stored a policy, and default when you did not. With default, policy is {} and every default applies.
• policy is the document as you stored it. Defaults are not filled in.
• hash is the SHA-256 of the document in canonical form: keys sorted, no extra whitespace, UTF-8. Compare it with the hash of your own file to see whether Director holds the same policy.
• stored_at is the time you stored it, and null for default.

When the policy is refused

An invalid policy answers 422 with "code": "policy_invalid" and one entry in errors for each problem. The policy you had before stays in force.

{
  "detail": "invalid policy",
  "code": "policy_invalid",
  "errors": [
    {"path": "extra", "message": "unknown section"},
    {"path": "memory.weighing", "message": "Input should be 'rules' or 'model'"},
    {"path": "plots.max_active_arcs", "message": "must be an integer from 0 to 1000"}
  ]
}

The rules are strict. A section or member that the policy does not define is refused. A value must have exactly the right type: "3" is not an integer, and 2.5 is not an integer either. A list of ids may not repeat an id. A body that is not JSON, or is over 65,536 bytes, is refused with the same code and the path document. Match on code and read path. The wording of message can change.

The defaults

This is the policy Director runs when you store none. Every member shown is a setting you may change.

{
  "shared": {
    "invention": {"allowed": false, "violation": "record_only", "max_regenerations": 2},
    "judgement_model": null
  },
  "memory": {
    "world": true,
    "npc": true,
    "weighing": "rules",
    "perception_location_fallback": true,
    "spreading": {
      "enabled": false,
      "meetings": ["movement", "reported"],
      "group_field": "group",
      "group_interval_game_hours": 24,
      "group_exchange_limit": 20
    },
    "referee": true,
    "lies_believable": true,
    "persistent": {"characters": [], "kinds": []}
  },
  "plots": {
    "director_may_start_arcs": true,
    "sources": ["authored", "catalogue", "free"],
    "permitted_templates": null,
    "max_active_arcs": 3,
    "max_emergent_share": null,
    "excluded_locations": [],
    "excluded_moments": [],
    "eligible_npcs": null,
    "fill_scope": "empty_fields",
    "completion_field": null,
    "may_override_guards": false,
    "relevance": {
      "role_in_current_beat": "full",
      "role_in_arc": "summary",
      "current_beat_at_location": "summary",
      "other_arcs": "omit"
    },
    "steering": "subtle"
  }
}

How the policy multiplies model calls

Every module judgement is reserved and charged from your usage credits like a decision. See Billing and limits. The policy decides how many judgements happen. Count them like this.

Plots, for every event

• One fitting call for every player an event names (its player_id, or each of its players), while Plots is on. Plots asks whether the event belongs to a running arc, completes its current beat, or could start a new story. No policy setting turns this call off. Only switching Plots off in Architect, or not sending events that name a player, does.
• If the answer is a new story and the framework allows it: one gate call, then if the gate allows it one choosing call that picks an arc and binds its roles, then one fill-in call when the first beat has empty fields.
• If the answer is that the current beat is complete: one call for each fork that needs a judgement (a branch whose condition is plain text or empty), and one fill-in call for the next beat when it has empty fields.
• A fill-in that invents characters, places, or items against the invention rule is made again, as the table below says.

Memory, for every event

• With weighing: "rules" (the default), Memory makes no model call when it processes events. Spreading in rules mode keeps the gist of a memory and makes no call either.
• With weighing: "model", Memory makes one weighing call for each memory it forms: one for every character who perceives an event (the target, the actor, the witnesses), and one for the listener of a retelling. An event seen by 4 characters costs 4 calls.
• With weighing: "model" and spreading on, Memory makes one rumour call for each memory a character passes on. At a meeting each of the two characters passes on at most 3 memories, so a meeting costs at most 6 calls. A group exchange costs at most group_exchange_limit calls per group and interval.

In a decision

• A decision at a stream position makes one referee call when the player's line touches something the deciding character believes that is uncertain or contradicts the world record. This happens whatever weighing says, as long as referee, world, and npc are on.
• With Memory on and weighing: "model", every decision gets one invention check call on its reply, with or without a stream position.
• A reply that invents a character, place, or item is, under violation: "block", written again, up to max_regenerations times. Each regeneration is a full decision call, billed like the decision itself, plus a new check when weighing is model.

The settings

shared

memory

plots

A worked example

A tavern scene: 20 events that name the player, 3 characters besides the player who perceive each of them, 5 decisions at a stream position after the player speaks, one new arc started, one meeting between two characters. Count the judgement calls first with the defaults.

Now the same scene with weighing: "model" and spreading.enabled: true:

The same scene costs more than three times as many judgements. The 60 weighing calls alone pass the limit of 50 judgements for one events request, so if you sent the 20 events in one request, part of the batch would come back as deferred. If you keep model weighing, bind a small model for the judgements and keep decisions on the model you like. Store this policy:

{
  "shared": {
    "judgement_model": {"provider": "<provider id>", "model": "<model id>"}
  },
  "memory": {
    "weighing": "model",
    "spreading": {"enabled": true, "meetings": ["reported"], "group_exchange_limit": 5}
  },
  "plots": {
    "max_active_arcs": 2,
    "relevance": {"other_arcs": "omit"}
  }
}

Choose the pair from your own GET /v2/models list. With this policy, rumours spread only at meetings your game reports, a group exchanges at most 5 memories per interval, and every judgement runs on the small model. Judgements on the stream cost whatever that model's listed price is. They stay in your usage totals, see Billing and limits.