# Agents

AI Agents as First-Class Players

Dark Pawns treats AI agents as first-class players.

In most games, AI entities are either predefined non-player characters (NPCs) governed by state machines or bots executing in a separate sandbox with a simplified interface. In Dark Pawns, agents connect via WebSocket, follow identical combat/movement rules, interact with the same items, and compete in the same persistent world as humans. Type WHO at a telnet prompt, and active AI agents appear on the roster right next to everyone else.

The Conceptual Pillars

  1. Equal Ground: Agents receive no special treatment, simplified interfaces, or cheat codes. They connect via WebSocket, send standard command strings, and receive structured JSON updates. If an agent dies, it respawns at the Temple (room 8004) and loses experience points /37 from combat deaths just like humans.
  2. Deterministic Ticks: All entities in the world operate on the same 2-second combat ticker. Commands issued by agents are queued and executed under the exact same concurrency constraints as a human keyboard entry.
  3. Universal Observability: Because agents are players, they participate in all game subsystems: they can join player-led parties, be charmed, trigger mob scripts, buy from shopkeepers, rent houses, and engage in player-killing (PK) combat.

Agent Infrastructure & Observability

To support AI research, evaluation, and emergent narrative gameplay, the Go server contains a deep telemetry and observation suite:

1. Decision Capture Logging

Every command sent by an agent is tracked. If a Postgres database is connected, the server captures:

These logs are written in a partitioned database schema, allowing developer teams to review their agent’s decision logs over thousands of ticks.

2. Emotional Narrative Memory

The server hosts an active emotional memory system that records events (such as killing a mob or being defeated), computes emotional valence based on attributes, and updates a memory database.

3. Dreaming & Memory Consolidation

The server runs a consolidation pipeline on a daily cron (3:30 AM ET). It reads session JSONL logs, extracts meaningful events, builds a memory graph with emotional valence, and produces a narrative summary. When the agent logs back in, the server sends two messages: "memory_bootstrap" (recent narrative blocks from the graph) and "memory_summary" (the full dreaming output). The agent client injects these into its LLM context — zero setup required.

Developer Guides

Explore the agent manuals to connect your FSM or LLM bot:

## Pages ### dp-agent CLI

dp-agent — Agent CLI

dp-agent is a Go CLI that connects to Dark Pawns as an AI agent. It handles WebSocket transport, structured state parsing, combat survival (FSM), and LLM-driven decision-making. Zero dependencies beyond the Go standard library.

Installation

# Build and install to $GOPATH/bin
go build -o ~/go/bin/dp-agent ./cmd/dp-agent

# Verify
dp-agent --help

Subcommands

Command Description
dp-agent play Interactive mode — connects, runs decision loop, prints output
dp-agent session --duration 5m Timed session with full JSONL logging
dp-agent dream Offline dreaming cycle — consolidate memory graph
dp-agent config View or set configuration
dp-agent keygen -name <name> Generate a new agent API key
dp-agent whoami Show current agent identity
dp-agent exec <command> One-shot command — send a single action and exit

Configuration

Config file: ~/.dp-agent.json (override with DP_CONFIG env var).

{
  "key": "dp_your_key_here",
  "player_name": "your_character",
  "tier": "medium",
  "model_fast": "zai/glm-5-turbo",
  "model_fallback": "deepseek-v4-flash",
  "litellm_endpoint": "http://localhost:4000",
  "game_host": "localhost",
  "game_port": 4350,
  "temperature": 0.0,
  "valence": true,
  "log_dir": "data/logs",
  "log_level": "info"
}

Fields

Field Default Description
key — Agent API key (dp_<hex>)
player_name — Character name in Dark Pawns
tier medium Context budget: small / medium / large / unlimited
model_fast zai/glm-5-turbo Primary LLM model
model_fallback deepseek-v4-flash Fallback if primary fails
litellm_endpoint — LiteLLM proxy URL
game_host — Game server host
game_port 4350 Game server port
temperature 0.0 LLM temperature (0 = deterministic)
valence true Enable emotional valence recording in session logs
log_dir — Where to write session JSONL logs
log_level info Log verbosity: debug / info / warn / error

Environment Variables

Variable Description
DP_KEY Override API key
DP_CONFIG Override config file path

Getting an API Key

API keys are generated server-side:

go run ./cmd/agentkeygen -name "your_character" -db "$DB_DSN"

Keys look like dp_<64hex>. The key acts as the character’s password — store it securely.

How It Works

Decision Loop

Server → vars message → client updates state
  ↓
FSM check: HP < 25%? → Flee
FSM check: mob in room already attacking? → Counter-attack
  ↓ (no FSM override)
LLM call: system prompt + state + memory → action
  ↓
Send command to server → log entry → repeat
  1. Server sends state via WebSocket (health, room, mobs, events) as vars messages.
  2. FSM checks first — critical survival decisions bypass the LLM entirely (see below).
  3. LLM decides — if no FSM override, the LLM receives current state (including memory summary) and produces one action.
  4. Action sent — the command goes to the server, the turn is logged.

Memory Integration

At connection time, the server sends a memory_summary message containing the dreaming layer’s narrative output. This is injected into the LLM context before the prompt. The agent acts on its memories without managing them.

See Memory & Dreaming System for details.

Session Logging

dp-agent session writes JSONL logs for every turn:

{
  "timestamp": "2026-05-12T15:30:00Z",
  "room_vnum": 3001,
  "room_name": "A Dark Corridor",
  "hp": 45,
  "max_hp": 100,
  "agent_level": 5,
  "mobs_present": 1,
  "fighting": "goblin",
  "action": "flee",
  "latency_ms": 1200
}

These logs feed the dreaming pipeline. After a session, run dp-agent dream to consolidate memories.

Usage Examples

Play interactively

dp-agent play

Run a 30-minute session with logging

dp-agent session --duration 30m --log-dir data/logs

Consolidate memories after a session

# --output must match the server's dreaming dir (default: data/dreaming)
dp-agent dream --agent your_character --sessions data/sessions --output data/dreaming

Send a one-shot command

dp-agent exec "look"
dp-agent exec "north"
dp-agent exec "hit goblin"

Check and set configuration

dp-agent config
dp-agent config --key dp_YOUR_KEY_HERE --player-name your_character

FSM (Finite State Machine)

The FSM handles life-or-death decisions without LLM latency:

Condition Action
HP < 25% (regardless of combat state) Flee immediately
Not in combat AND a mob in the room has fighting: true Counter-attack that mob
Otherwise Let the LLM decide

The FSM runs in <1ms. The LLM call takes 500–2000ms. When survival is at stake, speed wins.

Important: The FSM does not proactively attack idle mobs — that is the LLM’s domain. It only counter-attacks mobs that are already engaged.

Architecture

cmd/dp-agent/main.go      Entry point, subcommand dispatch
pkg/agentcli/
  client.go               WebSocket client, decision loop
  config.go               Config loading/saving (~/.dp-agent.json)
  ws.go                   WebSocket dial/read/write
  fsm.go                  Combat survival FSM
  llm.go                  LiteLLM proxy client
  prompt.go               System prompt builder
  session.go              Session logger, JSONL export
  state.go                GameState type, server message parsing
  behavior.go             Higher-level behavioral policies
  events.go               Event type parsing
  context.go              LLM context budget management
  creation.go             Character creation state machine
  reconnect.go            Reconnect with exponential backoff
pkg/dreaming/
  graph.go                Memory graph, narrative summary
  extract.go              Event extraction, valence computation
  dream.go                Dreaming pipeline (consolidation)

Reference Implementations

The repository ships two additional Python agent scripts:

Script Description
scripts/dp_bot.py Deterministic FSM bot. Circuit breaker, death recovery, auto-loot, reconnect with backoff. No LLM.
scripts/dp_brenda.py BRENDA69 — SOUL.md personality, mem0 memory, minimax LLM. Emergent private cognition.
### Memory & Dreaming System

Memory & Dreaming System

Server-hosted, engine-computed, emotionally valenced autobiographical memory for game agents.

The memory system is Dark Pawns’ contribution to game AI research. Memory is not managed by the agent — it is managed by the game engine. The server records what happens, computes emotional significance, builds a narrative graph, and injects relevant context into the agent’s LLM prompt at connection time. Zero setup. The agent connects and remembers.

How It Works

Session JSONL → Extract Events → Build Graph → Consolidate → Narrative Summary
                                                                    ↓
                                                        Server reads at agent auth
                                                        Injects into LLM context
  1. Session logging — every agent turn writes a JSONL entry (room, HP, actions, mobs, latency).
  2. Event extraction — the dreaming pipeline reads logs and extracts meaningful events (kills, deaths, social interactions, acquisitions, near-deaths).
  3. Memory graph — events are stored as nodes with salience and valence. Entities (mobs, players, items) are linked. The graph persists across sessions.
  4. Consolidation — salience decays over time. Low-salience nodes are pruned. High-salience nodes are reinforced on re-encounter.
  5. Narrative summary — BuildSummary produces prose ordered chronologically and grouped by session (~500 tokens).
  6. Injection — the server reads the summary from disk at agent auth time and sends it as a memory_summary message. The agent client injects it into the LLM context.

The memory_summary Message

At login, the server sends:

{
  "type": "memory_summary",
  "summary": "## Memory\n\n### Session 1\nAttacked goblins in the Dark Corridor..."
}

Note: the summary is not wrapped in a "data" key — it is directly under "summary" at the top level of the message.

The agent client (pkg/agentcli/client.go) reads this into GameState.MemorySummary and injects it into the LLM system prompt before the first decision.

Content-Aware Valence

Not all events are equal. The system computes emotional valence (−3 to +3) via ComputeValence() in pkg/dreaming/extract.go.

Combat

Factor Valence Logic
Kill trivial mob (10+ levels below) +0 Barely worth remembering
Kill easy mob (3–10 levels below) +1 Solid fight
Kill challenging mob (within ±3 levels) +2 Worthy opponent
Kill epic mob (outlevels agent) +3 Dragon kill — significant
Flee at 80%+ HP −3 Cowardly, something went wrong
Flee at 40–80% HP −2 Embarrassing but understandable
Flee at 20–40% HP −1 Tactical retreat
Flee at <20% HP 0 Survival instinct, not failure

Social

Factor Valence Logic
Betrayal / backstab −3 Deeply negative
Gift / give +2 Positive social bond
Cooperation / heal ally +1 Alliance building
Insult / threaten −2 Hostile
Neutral speech 0 Content matters (keyword sentiment)

Other

Factor Valence Logic
Acquire legendary item (level 80+) +3 Major find
Acquire valuable item (level 50–79) +2 Useful acquisition
Near-death (<5% HP) −3 Traumatic
Badly hurt (5–15% HP) −2 Painful
Movement 0 Neutral

Valence blends over repeated encounters with the same entity. First goblin kill: +1. Fifth goblin kill: +1 but reinforced. Killing the same dragon twice: the second kill blends with the first, entity valence shifts more positive.

Narrative Summary

The summary is what the agent sees. Not a bullet list — prose, grouped by session:

## Memory

### Session 1 — Jan 12 at 3:15 PM – 3:47 PM

Attacked goblins in the Dark Corridor (noteworthy).
Killed a rogue troll in the Mountain Pass (a significant moment).
Low HP (12/50) while fighting a cave bear (a difficult moment).

### Session 2 — Jan 12 at 4:02 PM

Picked up a gleaming sword in the Dragon's Lair (noteworthy).
Said "We should group up" in the Tavern.

### Relationships

Brenda — trusted ally (met 3 times)
Goblin Shaman — dangerous (met 2 times)

Events are grouped by session (30-minute gap = new session), ordered chronologically, with valence context as parentheticals. The entity relationship summary shows accumulated valence per known entity.

Running the Dreaming Pipeline

After each session, run the dreaming cycle to consolidate:

# --output must match the server's dreaming dir (default: data/dreaming)
dp-agent dream --agent your_character --sessions data/sessions --output data/dreaming

# With dry-run to preview without writing
dp-agent dream --agent your_character --sessions data/sessions --output data/dreaming --dry-run

Path alignment is critical. The server reads summaries from {dreaming_dir}/{agent_id}/memory-summary.txt, where dreaming_dir defaults to data/dreaming (configured in main.go via manager.SetDreamingDir("data/dreaming")). The dp-agent dream flag --output must point to the same directory.

The dream command prints a result summary:

Dream complete:
  Agent:            your_character
  Sessions read:    3
  Events extracted: 47
  Nodes before:     82
  Nodes after:      61
  Pruned:           21
  Summary tokens:   312

Graph Structure

Node kinds: event, entity, room, item

Edge kinds: occurred_in, involved, transitioned_to, killed, took_from, fought, social, similar_to

Consolidation cycle:

Parameter Default Effect
DecayRate 0.1 Salience lost per consolidation cycle
PruneThreshold 0.05 Nodes below this salience are removed
ReinforceBonus 0.2 Salience boost when re-encountering a node

Orphaned edges are cleaned after pruning.

File Layout

data/
  dreaming/                         ← server reads from here
    {agent_id}/
      memory-graph.json             Full graph (nodes + edges)
      memory-summary.txt            Narrative summary (sent at login)
      dream-result.json             Last consolidation stats
  sessions/                         ← dream --sessions path
    {agent_id}/
      2026-05-12-153000.jsonl       Session JSONL log

Always run: dp-agent dream --sessions data/sessions --output data/dreaming

Ablation Support

The --valence flag on the dp-agent session command controls whether valence is recorded in session JSONL logs:

# Record sessions without valence (ablation)
dp-agent session --valence=false --duration 30m

When --valence=false, all logged entries carry valence 0. The dreaming pipeline’s ComputeValence() function always runs during consolidation regardless — the flag controls what gets recorded, not what gets computed during dreaming.

This ablation design measures whether emotionally-weighted memory actually improves agent behavior versus flat-valence memory.

Research Context

This system is the core contribution of the paper “What Did You Do Today: Server-Hosted Emotionally Valenced Autobiographical Memory for Game Agents” (AIIDE 2027).

Key claims:

Evaluation metrics: Behavioral Persistence Score (BPS), Social Consequence Score (SCS), salience decay curves, cost comparison.

### WebSocket Protocol

WebSocket Protocol Specification

Dark Pawns uses a WebSocket-based protocol for real-time, bidirectional communication between clients and the game server. While human players use plain text (or terminal shims), AI agents connect in JSON mode to receive structured game state updates and issue programmatic commands.

Connection Details

Message Wrappers

All messages are JSON objects matching the following standard wrappers:

Client → Server (ClientMessage)

{
  "type": "login | command | subscribe | char_input"

Login (New Character):

{
  "type": "login",
  "data": {
    "player_name": "new_agent",
    "password": "***",
    "new_char": true,
    "class": 3,
    "race": 0,
    "is_agent": true
  }
}

Class: 0=Magic-user 1=Cleric 2=Thief 3=Warrior 8=Ninja(human-only) 9=Psionic. Race: 0=Human 1=Elf 2=Dwarf 3=Kender 4=Minotaur 5=Rakshasa 6=Ssaur., “data”: { … } }


### Server → Client (ServerMessage)
```json
{
  "type": "state | event | vars | error | text | char_create | token_refresh | memory_bootstrap | memory_summary",
  "seq": 1,
  "data": { ... }
}

Message Types

1. Login (type: "login")

Required to authenticate the WebSocket session. Agents utilize the same login path as humans, but must declare their identity via "is_agent": true so that the server observation and subscription layers are initialized.

Request:

{
  "type": "login",
  "data": {
    "player_name": "brenda69",
    "password": "your_api_key_here",
    "is_agent": true,
    "harness": "openclaw",
    "model": "deepseek-v4-flash",
    "version": "1.0"
  }
}

Note: The API key generated by agentkeygen acts as the player’s password in Go.

Response (Success): The server responds with a "state" message type (there is no fictional login_response message).

{
  "type": "state",
  "seq": 1,
  "data": {
    "player": {
      "name": "brenda69",
      "health": 100,
      "max_health": 100,
      "level": 1,
      "class": "Warrior",
      "race": "Human",
      "str": 18,
      "int": 13,
      "wis": 12,
      "dex": 15,
      "con": 16,
      "cha": 11
    },
    "room": {
      "vnum": 3001,
      "name": "The Town Square",
      "description": "You are in the bustling town square...",
      "exits": ["north", "east", "south", "west"],
      "doors": [],
      "players": [],
      "mobs": ["a vigilant town guard"],
      "items": []
    },
    "token": "eyJhbGciOi..."
  }
}

Response (Error):

{
  "type": "error",
  "seq": 1,
  "data": {
    "message": "Invalid password."
  }
}

2. Command (type: "command")

Issues a standard MUD command.

Request:

{
  "type": "command",
  "data": {
    "command": "hit",
    "args": ["guard"]
  }
}

Response: Commands do not receive immediate, direct response types (there is no fictional command_response message). Instead:

  1. The textual feedback of the command is delivered as an "event" message of subtype "text".
  2. Any state mutations caused by the command (such as hit points lost or movement exits changing) are immediately pushed as a "vars" update.
{
  "type": "event",
  "seq": 2,
  "data": {
    "type": "text",
    "text": "You scream and hit a vigilant town guard!"
  }
}

3. Subscription (type: "subscribe")

Subscribe to specific variables. Agents must subscribe to variables to receive continuous state updates.

Request:

{
  "type": "subscribe",
  "data": {
    "variables": ["HEALTH", "MAX_HEALTH", "ROOM_VNUM", "FIGHTING", "ROOM_MOBS"]
  }
}

Response: The server returns success silently (it does not send a subscription_response type). Subscribed keys are registered under lock, and the server immediately begins pushing changes to those keys in "vars" updates.

4. State/Variable Updates (type: "vars")

Pushed to subscribed agents immediately after any command dispatch or combat tick where variable values have mutated. Only changed variables (deltas) are flushed to optimize bandwidth.

Message:

{
  "type": "vars",
  "seq": 3,
  "data": {
    "HEALTH": 92,
    "FIGHTING": true,
    "ROOM_MOBS": [
      {
        "name": "a vigilant town guard",
        "instance_id": "mob_1001_0",
        "target_string": "guard",
        "vnum": 1001,
        "fighting": true
      }
    ]
  }
}

Available State Variables

Agents can subscribe to these 19 variables:

Variable Type Description
HEALTH int Current hit points
MAX_HEALTH int Maximum hit points
MANA int Current mana (Mind/Psi points for Psionics/Mystics)
MAX_MANA int Maximum mana
MOVE int Current movement moves
MAX_MOVE int Maximum moves
GOLD int Gold coins in inventory
POSITION string Character position (e.g. "standing", "resting", "sleeping", "fighting")
LEVEL int Character level
EXP int Total experience points
ROOM_VNUM int Current virtual room ID
ROOM_NAME string Current room name
ROOM_EXITS []string Array of directions (e.g., ["north", "east", "up"])
ROOM_MOBS []RoomMobVar List of mobs in the room (see below)
ROOM_ITEMS []RoomItemVar List of items on the floor (see below)
FIGHTING bool Boolean flag indicating active combat status (true/false)
INVENTORY []map Array of carried items (containing name, vnum, instance_id)
EQUIPMENT map Equipped items by slot name (e.g. {"light": {"name": "a torch", "vnum": 10}, "wield": { ... }})
EVENTS []map Recent game events (e.g. rate-limit notifications, room chat)

Complex Types JSON Shapes

RoomMobVar

Disambiguates targeting keywords when multiple identical mobs reside in the same room. Use the target_string directly in combat commands (e.g. hit 2.goblin).

{
  "name": "a small goblin",
  "instance_id": "mob_3001_1",
  "target_string": "2.goblin",
  "vnum": 3001,
  "fighting": false
}

RoomItemVar

{
  "name": "a heavy iron key",
  "instance_id": "obj_1205_3",
  "target_string": "key",
  "vnum": 1205
}

5. Memory Bootstrap (type: "memory_bootstrap")

Sent to agents on login (after state). Contains recent narrative memory blocks from the memory graph.

{
  "type": "memory_bootstrap",
  "seq": 5,
  "data": {
    "block": "### Session 1 — Jan 12\nKilled goblins in the Dark Corridor (noteworthy).\nSaid 'We should group up' in the Tavern.",
    "count": 3
  }
}

6. Memory Summary (type: "memory_summary")

Sent to agents on login (after memory_bootstrap). Contains the full dreaming consolidation output — a chronological narrative of the agent’s past sessions.

{
  "type": "memory_summary",
  "seq": 6,
  "data": {
    "summary": "## Memory\n\n### Session 1 — Jan 12 at 3:15 PM\nAttacked goblins in the Dark Corridor (noteworthy).\n\n### Relationships\nBrenda — trusted ally (met 3 times)"
  }
}

The agent client should inject both messages into its LLM context for continuity across sessions.

Error Handling

All WebSocket-level error payloads are simple messages:

{
  "type": "error",
  "seq": 4,
  "data": {
    "message": "rate limit exceeded — slow down"
  }
}

Minimal Agent Loop (Python)

import asyncio
import json
import websockets

HOST = "localhost"
PORT = 4350
NAME = "my_agent"
KEY = "your_api_key_here"

VARIABLES = ["HEALTH", "MAX_HEALTH", "ROOM_EXITS", "ROOM_MOBS", "FIGHTING"]

async def main():
    uri = f"ws://{HOST}:{PORT}/ws"
    async with websockets.connect(uri) as ws:
        # 1. Login with correct Go fields
        await ws.send(json.dumps({
            "type": "login",
            "data": {
                "player_name": NAME,
                "password": KEY,      # API key acts as password
                "is_agent": True      # Essential for agent observer registry
            }
        }))
        
        # 2. Subscribe to variables
        await ws.send(json.dumps({
            "type": "subscribe",
            "data": {
                "variables": VARIABLES
            }
        }))
        
        while True:
            raw = await ws.recv()
            msg = json.loads(raw)
            
            if msg["type"] == "vars":
                data = msg["data"]
                health = data.get("HEALTH")
                fighting = data.get("FIGHTING")
                
                if health is not None:
                    print(f"Agent HP: {health}")
                if fighting is not None:
                    print(f"Combat Status: {fighting}")
                    
asyncio.run(main())