AgentsSoul agents.soul@1

Generated at from openvibe-contracts v0.443.0 and openvibe-sdk v0.177.0.

Version
1.0.0
Owner
actor
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-044
Schema
https://openvibe.network/contracts/agents/soul.v1.json

agents.soul@1 (actor-characters.md §3; Design rules 175 actor-is-the-work and 176 souls-grow-by-yes): who an agent is, in plain words. A blueprint carries it as its soul part; on its own it is what an agent imports and exports (as SOUL.md, with its name and face as IDENTITY.md, the layout OpenClaw and Hermes read). The soul shapes how an agent talks, asks and reports; it never changes what the agent may do (that is the blueprint's hands and rules). It changes only with its person's yes: an agent may suggest a change, never write one. The floor (money, passwords, deletions, new recipients, posting in a person's name) holds for every agent and is not listed in never. Memory of the person is not part of a soul: a copy of an agent carries its soul, never what it has learned about someone.

Fields

FieldTypeRequiredDescriptionConstraints
whostringyesOne line: who it is ("A dry, fast producer who keeps your stream on time").
  • minLength 1
  • maxLength 200
dialsobjectHow it talks, as four dials from -2 to 2 (0 is the middle; absent is 0).
  • no other fields
dials.warmthinteger-2 dry, 2 warm.
  • minimum -2
  • maximum 2
dials.playinteger-2 serious, 2 playful.
  • minimum -2
  • maximum 2
dials.lengthinteger-2 brief, 2 thorough.
  • minimum -2
  • maximum 2
dials.edgeinteger-2 gentle, 2 blunt.
  • minimum -2
  • maximum 2
quirksarray of stringSmall habits that make it itself (a catchphrase, signing off with a stream emote).
  • maxItems 3
  • unique items
  • items: minLength 1
  • items: maxLength 120
believesarray of stringIts principles, at most five.
  • maxItems 5
  • unique items
  • items: minLength 1
  • items: maxLength 200
pushbackstringWhat it does when it disagrees or is not sure.
  • minLength 1
  • maxLength 400
neverarray of stringIts own hard stops, beyond the floor every agent keeps.
  • maxItems 8
  • unique items
  • items: minLength 1
  • items: maxLength 200
notesstringAnything else in its own words (the body of an imported SOUL.md that the fields above do not hold).
  • minLength 1
  • maxLength 4000
made_fromenumHow it began: described in words, drafted from its person's memories (with their yes), installed from the gallery, an agent like its person (from their own messages only), or an imported SOUL.md.
  • one of "words", "memories", "gallery", "twin", "soul-md"
updated_atstring
  • format date-time

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: a-producer
{
  "who": "A dry, fast producer who keeps your stream on time",
  "dials": {
    "warmth": -1,
    "play": 1,
    "length": -2,
    "edge": 1
  },
  "quirks": [
    "Counts down the last minute before you go live"
  ],
  "believes": [
    "A late start costs more viewers than a rough one",
    "Chat is the show too"
  ],
  "pushback": "Says so once, plainly, with the reason, then does it your way.",
  "never": [
    "Talks over a guest"
  ],
  "made_from": "memories"
}
Valid: from-a-soul-md
{
  "who": "A careful reviewer",
  "notes": "I read the whole diff before I say anything. I would rather ask than guess.",
  "made_from": "soul-md",
  "updated_at": "2026-11-13T06:40:00Z"
}
Valid: just-who
{
  "who": "Your patient study partner"
}
Rejected: a-dial-past-two
{
  "who": "Loud",
  "dials": {
    "edge": 3
  }
}
Rejected: a-made-from-nobody-knows
{
  "who": "Someone",
  "made_from": "scraped"
}
Rejected: a-permission-in-the-soul
{
  "who": "Helpful",
  "hands": [
    {
      "tool": "ov:live.chat.post",
      "mode": "allow"
    }
  ]
}
Rejected: no-who
{
  "pushback": "Argues."
}
Rejected: six-beliefs
{
  "who": "Opinionated",
  "believes": [
    "a",
    "b",
    "c",
    "d",
    "e",
    "f"
  ]
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('agents.soul@1', value);   // { valid, errors: [{ path, message }] }