Yuragi Engine

Deterministic personality for AI agents and game NPCs. Every agent's mood, traits, and decisions are a pure function of (identity, tick) — zero Math.random() anywhere in the core, so behavior can be proven, not just asserted. Optional BSV mainnet anchoring makes that proof checkable by anyone, not just this server.

License: MIT · Live: yuragiengine.com · npm: yuragi-engine

Embed without the server (SDK)

npm install yuragi-engine

import { createLife, play } from 'yuragi-engine';
// Claude tools: import { createClaudeSession, CLAUDE_TOOLS } from 'yuragi-engine/claude';

Package: npmjs.com/package/yuragi-engine (0.1.1).
Fixed-point twin: createLifeFp / yuragi-engine/fluctuation-fp (v3fp hashes, bit-exact).
Mind fold helpers: yuragi-engine/sdk/mind. Claude tool bridge: adapters/README.md.
Details: sdk/README.md.

Run the world server

From this tree (or after npm install yuragi-engine):

npm install
cp .env.example .env   # BSV_MODE=simulated by default
npm test
npm start
# open http://localhost:4820

Or: node node_modules/yuragi-engine/server.js / import 'yuragi-engine/server'.

Node 18+. Dependencies: express, ws, @bsv/sdk (plus optional OpenAI-compatible LLM).

Optional env (see .env.example):

• BSV_MODE=simulated|dry-run|live — BSV mainnet PushDrop anchoring
• BSV_PRIVATE_KEY=… — WIF for live/dry-run tx building
• OPENAI_API_KEY=… — optional LLM voice layer
• INTEREST_SALT=… — salt for visitor download-interest hashes

World state persists in .data/world.json across restarts.

Start here: docs/UNDERSTANDING.md — the philosophy, the physics, and how every piece of the code works.

User guide: docs/GUIDE.md — how it works, how to use the site, and BSV modes.

Contributing / security: CONTRIBUTING.md · SECURITY.md

Product docs: docs/PRODUCT.md · Backlog: docs/BACKLOG.md

Capabilities

| Capability | Why it matters | Where it lives | |---|---|---| | Equations, not RNG | Behavior can be proven lawful instead of just claimed — no hidden dice roll a vendor could swap out or fake. | core/fluctuation.js — logistic map (die) × phase oscillator (metronome) × driven pendulum (pulling forces balance). Zero RNG anywhere in the codebase. Bit-exact twin: core/fluctuationFp.js (Q32.32). | | Provable identity | Same name → same personality, forever, on any machine. An agent's character can't drift or be secretly reconfigured server-side. | deriveGenome() — identity string → SHA-256 → physics constants. state(n) = F^n(seed). | | Replayable decisions ("prove why it did that") | Any third party — a player, an auditor, a partner studio — can independently recompute an agent's whole history and check it matches. | GET /api/agents/:id/replay?tick=n recomputes from genesis and compares canonical state hashes. UI: "Prove it" panel. | | Growth without noise | Agents change over lived time (not randomly) — same equations, evolving self, so an old character reads differently from a young one without any new mechanism. | Slow memory integrals feed back into personality readouts. | | Deterministic herd sync | Multi-agent coordination (flocking, group mood, coordinated NPCs) without any RNG or message-passing hacks. | Kuramoto phase coupling across agents (core/chain.js), with a live order parameter r. | | Public, third-party proof | State hashes anchored to BSV mainnet — a claim about an agent's past state can be checked by anyone with a txid, not just trusted from server logs. | core/bsvAdapter.js — PushDrop (BRC-0048, spendable) anchors carrying YURAGI\|v1\|agentId\|tick\|stateHash. Modes: simulated, dry-run, live. | | Personality-driven creative output | A cheap way to give agents distinct, non-generic creative signatures (useful for NPC flavor, procedural content, etc.) | GET /api/agents/:id/melody — deterministic pentatonic phrase from the agent's live state. |

Architecture

identity string ──sha256──> genome (physics constants, immutable)
genome + tick n ──F^n────> state (x, φ, θ, θ̇, memory)   [pure function]
state ──projections──────> personality traits ──argmax──> action
state ──canonical hash───> anchored on chain each epoch
blocks ──1 tick each─────> the agent's lived time

The chain never supplies entropy. It supplies time and proof. That separation is the design's core commitment.

Honest limitations (MVP scope)

• Herd coupling mutates live phase permanently. Solo replay is exact only for never-coupled trajectories; verifying most live mainnet anchors needs herd-aware replay (and mind-aware when eventSeq > 0). GET /api/bsv/verify auto-enables those for local agents — pass herd=0 / mind=0 to force solo.
• Local timechain drives tick cadence; BSV mainnet is the chosen proof layer — production is live; local clones default to simulated. See docs/UNDERSTANDING.md's appendix for why BSV specifically.
• Float vs fixed-point: live agents and existing BSV anchors use IEEE float (core/fluctuation.js). For bit-exact cross-machine math use the Q32.32 twin (createLifeFp / ?math=fp) — v3fp hashes, parallel path only.
• mind.events hot log is soft-capped; older events archive under .data/mind-archive/ behind fold snapshots so prove-it stays exact.