hypothesis-machine/docs/architecture.md

Architecture

interactive Pi AgentSession (Supervisor)
  ├─ Hypothesis Machine extension commands/tools
  ├─ explicit ResearchLoop state machine
  └─ AgentTree
       ├─ child AgentSession + SessionManager + recursive tools
       │    └─ grandchild AgentSession + ...
       └─ child AgentSession + ... (parallel)

subject results ──> Markdown memory ──> rebuildable SQLite FTS5 index
web tools       ──> SearXNG / Firecrawl / Browser adapter ──> sources
test plans      ──> Docker-only ExperimentRunner ──> artifacts
                                              └────> independent review verdict

The root conversational session is never replaced. A generated child spec is validated before the tree manifest is changed. The child receives its own Pi session file and custom tool set. Calling its spawn_agent repeats the same factory path, which makes recursion a capability rather than a special role.

AgentTree is model-independent and depends on AgentRuntimeFactory. Production uses PiAgentRuntimeFactory; tests use deterministic fake runtimes without paid API calls. Results are captured from the child's final observable assistant text and returned by foreground spawn or agent_control wait/collect.

The run manifest is small and atomic. On restore, previously running/waiting agents become interrupted; their Pi session path and parent/child relationships remain intact, and start() resumes through SessionManager.open().

The research loop is not an auto-prompt recursion. Each model-driven iteration must call record_iteration with measurable deltas. Code applies termination for goal completion, methodological failure, external-only questions, user decision, no information gain, or the absolute iteration cap.

Markdown/source bytes are authoritative. SQLite contains only derived search and relation data and can be dropped/rebuilt. Pi JSONL remains authoritative for each agent conversation.