Limits, and where things are kept

The caps you set on a hamlet, and the folder everything lives in.

Hamlet keeps everything as plain files in one folder, the home. You can read all of it, and two of the files are yours to edit.

The home

~/.hamlet/
  config.toml      settings and endpoints
  models.toml      the models you allow, with what each costs
  limits.toml      your limits on agents, roads, spending and tools
  workspace/       the only place the mayor's tools can write
    NOTES.md       its memory, shown to it every turn
    skills/        its skills, one folder each with a SKILL.md
  agents/<name>/   an agent's house, laid out like the home itself
  archive/<id>/    the house of an agent that was removed or merged
  sessions/        the mayor's logs, one file per session
  hamlet.jsonl     the record: agents, roads, mayors, votes
  oversight.jsonl  what waited for you and how you answered

The records are only ever added to, and the app rebuilds everything it shows from them.

Your limits

limits.toml is yours. Only you edit it, and it is read again before every model call, so a change applies at once. It starts like this:

most_agents = 12
most_roads = 24

[budget]
period = "day"
tokens = 2000000
cost = 5.0

[task]
messages = 12
tokens = 500000
cost = 1.0

• most_agents and most_roads cap how far the mayor can grow the hamlet.
• [budget] caps what the whole hamlet spends in a day or a month, in tokens, in cost and, if you add minutes, in model time.
• [task] caps one task, along every agent it touches.

A meter you leave out has no cap. If the file cannot be read, nothing may be spent until it is fixed.

Notes and skills

An agent remembers through its NOTES.md, which is shown to it every turn, and it learns through its skills. Both are files in its house, and you can open them in the Inspector or in any editor.

A new workspace starts with a few skills: web search, reading a page, the weather, calling an API, system information, and guidance on writing skills and notes. They belong to the agent from then on, and it can change them.

A second home

HAMLET_HOME moves the home away from ~/.hamlet:

HAMLET_HOME=~/hamlet-scratch hamlet

Use it to try things without touching your real hamlets, or to keep two sets of hamlets apart.