Who Owes Whom: A Spec for Sending My NPCs Less

The configuration block in the spec is five lines of JSON, and the only value it sets is "message_format": "normal". That’s the default for every configuration, and it means nothing changes. The other values are where the work is, and they have now had their first test runs in NPCSIM. The best configuration saved 6.1% of request bytes on a pirate adventure, against a spec that asked shorthand for at least 25%, and it is still the one I’d keep testing.

Some background for anyone who hasn’t followed the NPC simulator I’ve been building. Millhaven, the village I’ve been running it on, has twelve NPCs, each holding its own beliefs, plus an independent Dungeon Master who adjudicates what they try to do. Every one of those NPCs calls an LLM when it picks an action or answers a private question, and the Dungeon Master does the same when it reviews the outcome. Each request carries the NPC’s observations, its memories, the available actions and the rules for answering, serialized as JSON and sent as a fresh, standalone message. The spec is about sending less of that to the model without the NPCs deciding any worse, and most of the document turns out to be about the second half of that sentence.

compact keeps every field and its meaning but swaps long key names for short aliases, with the dictionary declared inside the same request. shorthand layers a deterministic notation on top for structured context that repeats. fact-shorthand goes further and turns certain long-term memories into labeled, typed one-liners, which is where a lot of the guardrails live. Whichever mode an episode starts in gets frozen into that episode’s configuration snapshot, so changing the global option halfway through a run doesn’t touch it, and old saves that predate the setting load as normal.

Four message modes, each adding one layer, with the byte-reduction target each must hit

The rules before the tricks

Before any compression happens, the spec draws a line around what compression is allowed to touch, and the line is tight. Canonical prompts and the complete history get stored exactly as they are today. The shorter version is a projection, built from a deep copy immediately before the request leaves, and it never writes back into an observation, a memory, a review payload or a saved transcript. It can’t loosen the actor’s observation boundary either. An NPC sees what it personally observed, and the codec has to reject anything that would leak hidden world state into that view, because twelve independent NPCs only stay independent if nobody slips them the answer key.

Request pipeline from canonical state through the codec and validation, with fallback to the normal format

Each compressed request also has to stand entirely on its own. It carries a format marker and a schema version, along with enough of a dictionary that the model can decode every alias without having seen any earlier request. JSON values have to come through intact: arrays, booleans, numbers, null, identifiers and the exact action schemas. And if a safe projection can’t be built, the request goes out in the normal format, with the fallback reported rather than quietly absorbed. Of everything in the document, that last rule is the one I trust most, because it means the worst case is today’s behavior.

Some things got ruled out on principle. Gzip is the obvious one. It shrinks what crosses the wire, but the model reads tokens after decompression, and tokens are what get counted and billed, so the spec measures LLM-visible tokens and prompt bytes and leaves transport compression for some other day. Summarizing or truncating persistent history is also out, and so are undocumented abbreviations the model would have to guess at.

The ruling I expect people to argue with is about references. An ID like MEMORY-42 is short and tidy, and the spec calls it invalid unless the model or proxy on the other end can actually resolve it. Mine can’t. The simulator sends standalone requests to an OpenAI-compatible /chat/completions endpoint, and nothing on the far side knows what memory 42 was. Delta messages run into the same wall, since sending only the paths that changed since the last request assumes somebody kept the last request, and the current contract makes no such promise. So deltas are parked in a later phase that needs an explicit retained-state agreement, base hash and all, before they get anywhere near an NPC. A lot of prompt-compression thinking quietly assumes a memory the API doesn’t have.

Who owes whom

Here’s the string the spec bans by name: Arin|Mara|3 silver. Eighteen characters, and no way to tell whether Arin owes Mara or Mara owes Arin. The friendlier-looking Owes: Arin: Mara: 3 silver is banned right alongside it, for the same reason. Position alone must never establish a relationship.

The allowed form is longer:

DEBT(debtor=Arin,creditor=Mara,amount=3,currency=silver,source=M-12,day=4,confidence=high)
The rejected pipe format Arin|Mara|3 silver beside the allowed labeled DEBT fact

Every semantic role has a label. The amount has a currency, M-12 links back to the canonical memory the fact came from, day=4 says when, and the confidence marker is there because some of what an NPC remembers is uncertain. Each fact type needs a recognized name, explicitly labeled roles, stable units and identifiers, provenance, and an exact decoder mapping supplied in the same request. The first version recognizes six: DEBT, OWNS, LOCATED, KNOWS, PROMISED and FEELS_ABOUT. Anything else stays in normal structured form and emits an unencoded_fact diagnostic, which turns every unsupported fact into a line in a log instead of a guess in a prompt.

The decoder instructions are short, and I’d hand them to anyone building agents whether or not they care about tokens. Aliases expand using only the supplied schema, and an omitted optional field is omitted, not false and not empty. That second rule sounds pedantic until you picture an NPC reading a missing confidence marker as proof that nobody believes the debt. Absent facts don’t get inferred. Named roles get read literally, so a debtor owes a creditor every time. The reply comes back in the existing strict JSON, never in shorthand, because a model that starts answering in the compressed dialect is a model you now have to parse twice.

Not everything is a candidate. Arbitrary prose stays explicit in the first version, including the operator’s questions and every action description. The real targets are duller: whitespace, container keys repeated down a long array, stable enum labels, metadata duplicated across structures. Nuance lives in the prose, and the spec doesn’t trust a codec with nuance yet.

Other ways to send less

Shorthand changes how things are written. The bigger savings may come from changing what gets sent at all, and that’s where the spec gets more careful, not less. Relevance-filtered memory ranks an NPC’s canonical memories against its current goal and the action catalog, plus its location and recent results, then sends a bounded set. Alongside that set goes omission metadata: the selection method, the revision, the selected source IDs and a count of what was left out. The spec says in plain words that omitting a memory is not evidence the fact is false. Some facts are mandatory no matter how they rank, starting with anything tied directly to the current goal, and the filter can never reach across the observation boundary to pull in something the NPC shouldn’t know. If relevance selection can’t produce or validate a projection, the fallback is the existing bounded window of recent memories.

Deduplication is simpler. Identical values inside one request can be replaced with request-local references, but only when the dictionary and the target travel together, and a stale or invalid reference sends the whole request back to the normal format. Stable instruction separation splits the invariant rules away from changing episode state. Reordering like that can help a provider cache the prefix, but the spec marks caching as provider-dependent and optional, and it won’t assume caching exists until telemetry shows a hit.

The action catalog gets trimmed with the most suspicion of all. Every action ID still goes out with concise availability facts, but full argument schemas only ride along for actions the NPC could plausibly select, and unavailable actions keep their reason. A compressed catalog is never allowed to hide an action the engine permits. That kind of bug wouldn’t show up as an error, just as an NPC that never tries the obvious thing.

Repeated-event aggregation is the last one. Older observations that are mechanically identical (unchanged failures, mostly) can collapse into a single line:

REPEATED(code=MISSING_TOOL,count=4,first=14:00,last=14:35,sources=E-41,E-44,E-48,E-53)
Four identical MISSING_TOOL events collapsing into one REPEATED line with every source ID kept

Every source ID is retained, so the collapse can be reversed from canonical history. The rule is strict: engine fields and semantic outcome must match apart from timestamp and source ID, and recent events and anything that changed world state stay unabridged. Four missing-tool failures with four different causes stay four lines.

How it gets judged

The unit tests read like a list of ways this could quietly go wrong. Normal mode has to produce byte-for-byte identical messages to current behavior, which is the test that proves the feature is actually off when it’s off. Unknown keys and extension fields have to survive, so the codec can’t drop data just because a schema didn’t mention it. Action schemas have to come through untouched, down to enum restrictions and required fields. And a DEBT fact with its parties reversed is classified as a codec failure, not a lossy approximation.

Integration testing runs the same deterministic episode in all four modes and records actions, refusals, repairs and authoritative world results. Relevance filtering and event aggregation get compared separately before anyone combines them, so a regression can be pinned on one strategy instead of argued about. Saves and reloads have to keep the episode’s frozen mode.

The spec set the bar before anything ran. On the representative NPC decision fixture, compact has to send at least 15% fewer LLM-visible prompt bytes and shorthand at least 25% fewer. On a matched memory fixture, fact-shorthand has to beat compact by another 15% with every relation and provenance ID intact. Relevance filtering plus deterministic deduplication needs a 20% cut in total input tokens on a long-memory fixture. None of it counts if invalid responses or action-validation retries rise against an agreed baseline, and any later delta experiment has to report total tokens and calls across the whole decision, not the one request that happened to look good.

The test I care about most has no percentage attached. A behavioral fixture puts “Arin owes Mara 3 silver” beside “Mara owes Arin 3 silver” and checks that the model reverses neither. The spec is careful to say that identical actions across modes don’t prove semantic equivalence, but a reversed debt would prove the opposite in a single turn.

Proxy._completion is supposed to record diagnostics separately from model content: requested and effective mode, the fallback reason, normal and sent byte counts, provider-reported token usage, cache hits where the proxy exposes them, and whether response validation passed. No request payload text goes into telemetry beyond the existing transcript policy.

What the first runs showed

The first evaluation ran all 32 option combinations through Locked Room, a deliberately small scenario. Every one of them finished. Every configuration hit 100% valid decisions and 100% applied actions, and every trial took exactly five actions and five model calls. The best byte saving was 5.1%, from shorthand plus deduplication. Average wall time by format barely moved: 26.63 seconds for normal, 26.33 for compact, 25.38 for shorthand and 25.43 for fact shorthand.

Fact shorthand made the requests bigger. Locked Room has no eligible typed memory facts, so every request carried decoder metadata for a notation it never used, and in a scenario that short the metadata is pure overhead.

Moonwake Treasures, a longer pirate adventure, got five shortlisted configurations, one run each:

Moonwake Treasures results for five compression configurations: actions, goal, valid and applied rates, wall time, latency and bytes saved

The best overall configuration stacked shorthand, deduplication, relevance filtering and event aggregation. Against the normal baseline it saved 6.1% of request bytes and finished in 483.7 seconds instead of 531.1, roughly 9% less wall time. It also got there in 133 actions instead of 146. Its applied-action rate of 99.2% was the highest of the five, and mean decision latency dipped from 2.981 seconds to 2.929. Nobody produced an invalid decision, and all five configurations reached the goal.

Look at the bytes column again, though. Shorthand plus deduplication saved the most, at 6.5%. Adding relevance filtering nudged that down to 6.2%, and fact shorthand with every option on managed only 3.6%. Most of the best run’s time saving lines up with its 13 fewer actions rather than faster decisions, and with one run per configuration I can’t tell whether event aggregation earned those actions or the path the NPCs happened to take did. Decision latency didn’t improve consistently across the configurations either.

Measured against the spec’s own bar, this doesn’t pass. The spec asked shorthand for at least 25% fewer bytes on its NPC decision fixture, and the best I’ve seen is 6.5%. Those aren’t the same fixture, so it isn’t a clean comparison, but it isn’t close either. What held was the safety side: every decision valid, every goal reached. The Arin and Mara reversal fixture isn’t part of these results.

What worked was the unglamorous end of the spec. Repeated records went into compact tables, long repeated values became request-local references, relevant memories replaced the full history, and identical events collapsed with their source IDs intact. Original memories and transcripts stayed outside the prompt, and every encoded request was validated locally with the fallback to normal format armed. Aggressive abbreviation was never the winner.

The proxy returned no token counts, so bytes were the only size metric available, and the spec says tokens decide whenever the two disagree. Latency varies between runs on its own. One run per pirate configuration makes all of this directional, not conclusive. The next round needs repeated runs across seeds and models, and memory histories long enough to give relevance filtering something to throw away.


The NPC simulator is on GitHub at github.com/atinkerersnotebook/NPCSIM.

My book Gamifying the Enterprise: Game Mechanics for Continuous Proficiency is on Amazon. All my books are on my Amazon author page.

The AD&D365 configuration guides are at adnd365.com/start.

Connect with me on LinkedIn.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.