Hypothesis Machine

Hypothesis Machine is an official Pi Coding Agent extension that turns the normal interactive Pi session into the supervisor of a recursive research team. It does not fork Pi or provide another UI. Any child is a persistent Pi AgentSession and can dynamically create its own specialized children.

The working MVP includes recursive/parallel agents, persistent tree recovery, research memory with FTS, local web adapters, a bounded research loop, and a Docker-only experiment runner.

Project status: early MVP (0.1.x). The core is tested locally, including a real three-level Pi agent run, but public APIs and stored formats may still change before 1.0.

Requirements

• Node.js 22.19 or newer and npm;
• Pi 0.78 or newer (0.83 recommended) and the normal Pi model/auth configuration;
• Docker + Compose for web infrastructure and computational experiments;
• roughly 12 GB RAM for the full Firecrawl stack (SearXNG alone is much smaller).

Runtime dependencies are limited to the four official Pi packages, typebox (Pi's tool schemas), and yaml (agent/config frontmatter). SQLite comes from Node.js; no external database library is used.

Install and connect to Pi

From this directory:

npm install
npm run typecheck && npm test && npm run build
pi install .

For development without installation:

pi --extension ./src/index.ts

Pi remains the same chat interface, model selector, credential store, session UI, and streaming runtime. Do not install third-party subagent extensions for this package; Hypothesis Machine has its own recursive implementation.

Pi 0.78 passes its official ModelRegistry directly to children. Pi 0.83+ uses the newer shared ModelRuntime. Neither path reads or copies keys in the extension. After updating this local package, restart Pi or run /reload.

Optional project configuration:

mkdir -p .hypothesis-machine
cp .hypothesis-machine.example.yaml .hypothesis-machine/config.yaml

Local web infrastructure

docker compose -f infra/compose.yaml pull
docker compose -f infra/compose.yaml up -d
curl 'http://127.0.0.1:8888/search?q=pi&format=json'
curl -s http://127.0.0.1:3002/ | head

Search routes to SearXNG; reading/crawling routes to self-hosted Firecrawl. The Browser Use fallback is an optional local adapter because current Browser Use requires a separate model credential; see services/browser-worker/README.md.

First run

Start normal Pi in the project, then enter:

Исследуй возможность применения метода A к задаче B.
Создай независимые направления для литературы, данных и критики.
Разреши агентам создавать подагентов.
Продолжай до появления проверяемой гипотезы или до трёх
итераций без информационного прироста.

Or use /research <goal>. The Supervisor calls coded tools; spawn_agent creates a generated Markdown spec and a separate Pi session. A child can call the same tool to create a grandchild. Foreground spawns return the result immediately; background branches are controlled with agent_control.

Commands

• /team — tree, tasks, and statuses;
• /research <goal> — start the explicit bounded loop;
• /research-status, /research-pause, /research-resume, /research-stop;
• /findings, /hypotheses.

The same operations are model-callable tools, so natural language such as “create an independent critic”, “steer agent X”, or “cancel that branch” works without a separate command UI.

State and memory

.hypothesis-machine/
├── runs/<run>/manifest.json, agents/*.md, sessions/*.jsonl
├── memory/{findings,hypotheses,questions,syntheses,decisions,agent-lessons}/
├── sources/<source-id>/{original.bin,metadata.json}
├── artifacts/web-cache/
├── experiments/<exp-id>/
└── index.sqlite

Pi JSONL stores conversations/tool calls/usage. Hypothesis Machine stores only domain results and relationships. Markdown and original bytes are source of truth; SQLite is a rebuildable search index. A model answer without sources cannot be published as corroborated.

Experiments

run_experiment requires hypothesis, data, baseline, split, metrics, success and refutation criteria, confounders, and resource limits before execution. The plan hash is frozen, source is written to an isolated experiment directory, and Docker runs with no network or secrets. Results include logs, environment, metrics/files created by the experiment, and space for independent review.md. A different agent must call review_experiment; code rejects self-review and records one of the final hypothesis verdicts in the experiment manifest.

Security and limitations

Read docs/security.md before autonomous work. Web content is untrusted, private networks are blocked, and Docker never degrades to host execution. Current MVP limitations:

• live recursive model execution requires configured Pi credentials and was not exercised by the free automated suite;
• Browser Use is an adapter contract, not enabled in default Compose;
• Firecrawl consumes substantial resources and its upstream images are not digest-pinned;
• independent review is a dynamic agent pattern, not a hard-coded mandatory role;
• the SQLite API in Node 22 is still marked experimental;
• strict filesystem isolation for Pi read-only tools requires an OS/Pi sandbox.

Troubleshooting: docker compose -f infra/compose.yaml ps, verify SearXNG JSON is enabled, verify Firecrawl at port 3002, run docker info, and use /research-status. Active children from an unclean shutdown restore as interrupted; their session file and lineage remain available.

Design details: docs/architecture.md, verified Pi APIs: docs/pi-capabilities.md, development: docs/development.md.

Contributing and releases

See CONTRIBUTING.md for the local workflow and docs/releasing.md for the maintainer checklist. Please report security issues privately as described in SECURITY.md.

Released under the MIT License.