Sessions & Thoughts

When your agent uses Thoughtbox, it produces a structured reasoning trace. This page explains what's in that trace so you can read it back and understand what your agent was thinking.

You don't write thoughts. Your agent does. This is reference for the human reading the dashboard, not for whoever is making the API calls.

Sessions

A session is one continuous reasoning trace — usually corresponding to one task your agent worked on. Sessions have:

  • A title the agent picks (or you can review and rename)
  • Tags for organization (e.g. research, debug, refactor)
  • A status: active while the agent is still reasoning, completed when it finishes cleanly, abandoned if the agent or you stopped it without resolution
  • A thought count — how many distinct steps of reasoning it captured

You can list sessions, search them by content, and open any one to see the full trace. Sessions persist across context resets and resume where they left off.

Thoughts

A thought is one step of reasoning. Thoughts are numbered, timestamped, and linked to the one before them. They're append-only — once a thought is recorded, it isn't edited. If the agent's view changes, it records a revision instead, which preserves the original.

This append-only property is the point. You're reading a faithful record of how the agent's thinking evolved, not a polished summary written after the fact.

What kinds of thoughts you'll see

Every thought has a type that says what kind of reasoning it captured. The most common are:

  • Reasoning — general analysis, exploration, working through a problem
  • Decision frame — choosing between options; lists the alternatives the agent considered
  • Action report — the agent did something (ran a tool, made an API call) and is recording what happened
  • Belief snapshot — a stated belief at a moment in time, useful for comparing later
  • Assumption update — flagging that an earlier assumption changed
  • Context snapshot — capturing the working environment (open files, errors seen, available tools)
  • Progress — tracking completion toward a goal

Most reasoning sessions lean heavily on reasoning and action_report. The other types appear when the moment warrants more structure.

Each thought can also carry a confidence level — high, medium, or low. This is optional, but it's how you can tell where the agent was sure and where it was guessing.

Branches

Sometimes your agent needs to explore two approaches in parallel before picking one. Branches let it do that without losing either track. A branch starts from a specific thought number and continues with its own numbering. When the agent is ready, the main track resumes with a thought that synthesizes what the branches found.

In the dashboard, branched sessions render as a tree. You can click into either branch to see what was tried.

Revisions

When new evidence overturns an earlier conclusion, the agent records a revision rather than rewriting history. The revision is a new thought that points at the one it supersedes — both stay in the record. You can see what the agent originally concluded, when it changed its mind, and why.

This is intellectual honesty over appearing consistent. A trace with revisions in it is a trace where the agent was actually learning.

What's next