# A durable identity: model, charter, its own memory, a daily budget
nool persona create builder-api --model <model-spec> --charter ./charters/builder-api.md --memory --budget-usd-per-day 25
nool persona status builder-api
# One bounded pass, claimed against a task, with replayable evidence
nool persona run builder-api --task <task-id> --max-turns 8 --compaction-every 3
# The council: a cross-vendor reviewer quorum that tightens with blast radius
nool fleet start --builder <builder-spec> --reviewer <reviewer-a> --reviewer <reviewer-b> \
--intent "Add idempotency keys to webhook handlers" --base-quorum 0.6 --isolation worktree --max-iterations 2
# Grade the run against a named eval set, from evidence
nool eval set-create webhook-quality --goal "Idempotent handlers with bounded retries"
nool eval run --set webhook-quality --run-id <run-id>
nool eval report --run-id <run-id>Persona memory recalls the soul's own prior runs, capped in count and length, so it improves without dragging every transcript into context.
Why give an agent a soul
A prompt is not an identity. When the same model is invoked with a slightly different prompt by a different person on a different day, nothing connects the runs: no budget, no memory of its own prior work, no accountability for what it landed. A soul, which Nool implements as a persona, is a durable identity for an agent: a name, a model, a charter file describing its role and limits, its own memory of its prior runs, and a daily budget. Runs are claimed against tasks and recorded as replayable evidence. The agent becomes something a team can reason about, grade and, if necessary, retire.
The loop: announce, lease, propose, council, solidify
Souls do their work inside Nool's governed loop rather than in a free-running conversation. A run starts by announcing intent and taking a lease on scope, so two souls cannot collide. Work is proposed under that intent and checked against the envelope and the policy gates. A council of reviewers judges it: nool fleet start runs a builder against a cross-vendor reviewer quorum whose required fraction tightens as blast radius rises, and a denied verdict's rationale is fed back to the builder for a bounded number of retries. Approved work solidifies into the ledger with the evidence attached; denied work is replanned, not forced through. The loop is the same whether one soul runs alone or a fleet runs in parallel waves.
Measuring the output, not the confidence
Because every run is recorded, souls can be graded. nool eval defines named eval sets with a goal and criteria, scores a recorded run against one, and reports past results by run or task. Structural criteria, such as the terminal state reached, the budget consumed, the tools used and the knots produced, are graded from the evidence rather than from the agent's own summary. nool usage agent reports bug rate and patterns per agent, and nool insights loops flags repeated failures. Signed council evidence stays on the knot, so the verdicts are auditable long after the run.
Choosing the shape before spending
Not every task deserves a council. nool fleet advise takes each task's footprint and a few measurable signals, such as blast radius, expected iterations, context size and tools granted, and recommends single, parallel independent, or a centralised quorum, and can dispatch the recommendation directly. nool fleet plan partitions tasks into waves whose node sets do not overlap, with a hard cap on concurrency per wave, and runs each in its own branch, identity and lease. The cost of a fleet is decided from signals before the first token is spent, which is how a soul loop stays affordable.
Charters: what a soul is allowed to do
A charter is a plain file that describes a soul's role, the kinds of work it takes, the boundaries it must not cross and the standard its output is held to. It is the part of the identity a human writes and a reviewer can read. nool persona edit changes the model, the charter, the memory setting or the daily budget without creating a new identity, so a soul can be retrained or restricted while keeping its run history. Memory recall is bounded on purpose: how many of the soul's own prior runs are recalled and how long the recalled summary may be are both configurable, which keeps a soul improving without dragging every past transcript into every new run.
Frequently asked questions
- Is a soul the same as a subagent?
- No. A subagent is a temporary worker inside one session. A soul is a persistent identity with a charter, memory, budget and a record of every run it has made. Subagents can run inside a soul's pass; the soul is what stays accountable.
- Which models can a soul use?
- Any model Nool can address with a spec. Reviewer councils are cross-vendor on purpose, so a soul built on one vendor's model is judged by others.
- What stops a soul from running away?
- A daily USD budget on the persona, a maximum number of turns per run, per-agent token budgets, and the gates every proposal passes through. A denied council verdict replans; it does not retry forever.
- How is council evidence stored?
- As signed evidence on the knot the run produced, alongside gate results and attestations. nool evidence knot retrieves the transition proof, and nool debug replay steps through the run itself.
- Can I change a soul's model or budget later?
- Yes. nool persona edit updates the model, charter, memory or daily budget in place, and the soul keeps its name and its recorded runs. nool persona status shows the current configuration for one soul or all of them.