hypotree

A persistent, self-revisinghypothesis DAGfor agentic R&D — exposed as anMCP server.

# From PyPI uvx hypotree # or pip install hypotree # From source git clone https://github.com/tygryso/hypotree.git cd hypotree uv sync

hypotree --version # or: uvx hypotree --version hypotree --info # which belief state am I connected to, and where is it?

{ "mcpServers": { "hypotree": { "command": "uvx", "args": ["hypotree"], "env": { "HYPOTREE_WORKSPACE_ID": "my-project" } } } }

The agent creates a tree withparent_idswiring combinations to their premises andexclusion_groupdeclaring competing answers to one question:

# Agent calls over MCP: create_hypotheses(hypotheses=[ {"node_id": "catalyst_A", "statement": "Pd/C catalyst works", "exclusion_group": "catalyst"}, {"node_id": "catalyst_B", "statement": "Pt catalyst works", "exclusion_group": "catalyst"}, {"node_id": "catalyst_C", "statement": "Ni catalyst works", "exclusion_group": "catalyst"}, # Enumerable question → closed by default, so eliminating two confirms the third. # For "which learning rate?" pass exclusion_closed=False: there is always another, # and the engine then refuses to deduce a survivor it cannot justify. {"node_id": "yield_target", "statement": "reach 90% yield", "is_goal": True, "target_metric": 0.9, "parent_ids": ["catalyst_A"]}, ])

3. Record evidence and let the engine infer

# Probe catalyst_A → fails outright, catalyst_B → fails outright. # Two experiments, one call: record_evidence(results=[ {"node_id": "catalyst_A", "success": 0.0}, {"node_id": "catalyst_B", "success": 0.0}, ]) # Engine: catalyst_A, catalyst_B → INVALIDATED; anything depending on them → PRUNED # catalyst_C → VERIFIED by elimination — no probe spent

generate_learning_path() # → markdown briefing + counters: # probes_spent = 2, conclusions = 3, conclusions_without_a_probe = 1

Additionally, you can start the server with these flags:

hypotree # MCP server + dashboard on 127.0.0.1:7331 hypotree --dashboard-port 8080 # start probing from a port you choose hypotree --no-dashboard # MCP server only, no socket opened hypotree --no-mcp # dashboard alone, against an existing belief state hypotree --experimental-cost-aware # rank by value per unit of probe cost (see Experimental features)

It binds127.0.0.1only and mints a session token at startup; the URL, token included, goes to stderr (stdout is the JSON-RPC channel). Ask the agent for it instead —get_workspace_inforeturnsdashboard_url, and so does thehypotree://dashboardresource. If no port in the range is free the MCP server still starts and says so: a viewer must never be able to take the server down.

--no-mcpopens the database read-only, so it is safe to point at a workspace an agent is actively writing — and it needs no client configured to try.

- A live graph.Nodes are laid out server-side withnetworkxand rendered as SVG withd3-zoomfor hardware-accelerated pan and zoom. Untested nodes glow at their real chance of being dispatched next; in-progress nodes pulse;pruned branches desaturate instead of disappearing, because the point being shown is that they were considered and cut.
- New nodes fade in.When the agent creates a hypothesis, it arrives as a ghost and resolves — you watch the search grow without touching the page.
- An activity timeline.status_historyis bi-temporal, so any past instant is aWHEREclause. The bar chart is the shape of the run — where the bursts were, where it stalled — and the handle travels along it. Drag back to see what was believed then, or press play and watch the whole investigation replay.
- Provenance on every card.What each belief cost: the score, the depth, the commit, thesource_ref, any files the experiment left behind, when it was created and when it settled. The graph is a ledger, not a drawing.
- The learning path as typeset markdown, ready to paste into a report — and it rewinds with the graph, so a rewound picture is never captioned with conclusions it has not reached.
- Pin and suspend.Redirect the search without faking evidence — directives change what isoffered, never what is believed.

Everything is vendored (Vue 3, d3 micromodules, marked — 276 KB total). No CDN, no npm, no build step: it works on a plane and in an air-gapped network.

The API is JSON and every/api/call needs the token. Everything is a read except one route — pin and suspend are scheduling instructions, and they never touch a posterior:

The operating contract reaches the model through four channels. You do not have to wire any of them up; they are listed so you know what is already in context and what is not.
- Server instructions.MCP hands a server-levelinstructionsblock to the client duringinitialize, and every major client puts it in front of the model. Hypotree uses it for four rules: one hypothesis per node, mark the goal withis_goal=Trueand wire it to the work, record against the node you actually tested, and report what you were leased. Nothing to configure.
- Tool descriptions.Each tool description carries the one rule that tool is misused without — that a goal never accepts evidence, that a lease reserves a node until you report it, that confirming one member of an exclusion group retires the rest. These are the only text guaranteed to be in context at the moment a tool is chosen.
- Resources.The full guide ishypotree://guide. An agent that hits something surprising can read it without you pasting 23 KB into a system prompt.hypotree://dashboardhands over the live link.
- Your project rules file— optional, and the only part you touch. If you want the agent to reach for hypotreeunpromptedon multi-day work, add the block below.

## Long-running R&D: use hypotree For any task that spans more than one session, branches into competing approaches, or where an early assumption could turn out wrong later, keep the belief state in hypotree rather than in the conversation. - Before starting, call generate_learning_path. Something may already be settled, and re-deriving it costs an experiment you do not have to run. - Create the objective with is_goal=True and wire hypotheses to it with parent_ids. Progress is then derived, not asserted. - Competing answers to one question share an exclusion_group. Confirming one retires the rest without testing them — this is where most of the saving is. If the list could always grow ("which learning rate?"), add exclusion_closed: false so the engine does not deduce a survivor it cannot justify. - Ask get_next_targets for work and record every result you were handed. A target is leased to you; anything you hold and never report is work nobody can do. Probed several things in one turn? Report them in one call with record_evidence(results=[...]). - Record against the node whose statement you actually tested. A composition's failure filed against a premise destroys a confirmation that is still true. - When get_next_targets returns DONE, read the reason. Only all_goals_met and empty_frontier mean stop; the rest are instructions. dead_question means one of your questions ran out of candidate answers — add the one you have not thought of to the same exclusion_group.

┌─────────────────────────────────────────┐ │ MCP Client (agent) │ │ Cursor / Cline / Claude Desktop │ └──────────────┬──────────────────────────┘ │ MCP protocol (stdio/HTTP) ┌──────────────▼──────────────────────────┐ │ hypotree MCP Server │ │ ┌─────────────────────────────────┐ │ │ │ Engine (20 tools) │ │ │ │ • Write-back propagation │ │ │ │ • Cascading prune │ │ │ │ • Exclusion-group inference │ │ │ │ • Differential ablation │ │ │ │ • Thompson Sampling navigator │ │ │ └──────────┬──────────────────────┘ │ └─────────────┼───────────────────────────┘ │ ┌─────────────▼───────────────────────────┐ │ SQLite-WAL │ │ • Bi-temporal history │ │ • Belief state + evidence + conflicts │ │ • Keyed by workspace_id │ └─────────────────────────────────────────┘

Hypotree is validated by apre-registered adversarial benchmarkusingqwen3.6:27b-q8_0andgemma4:31b-it-q4_K_M*. The benchmark is a set of 30 seeded combinatorial R&D problems, each with 3125 combinations (5 axes × 5 values). Each arm is run on all seeds, and the gate criteria are scored against the pre-registered thresholds.

Three arms across 30 seeded combinatorial R&D problems:

- Arm A— LLM agent with a manual Markdown scratchpad (ergonomic floor)
- Arm F— LLM agent with perfect-recall auto-transcript (steel-man baseline)
- Arm B— LLM agent on the full hypotree DAG belief state

The moat is inferential, not mnemonic.Arm F remembered every raw fact it ever saw —zeroduplicate probes across the whole run — and still lost 30/0/0, because hypotree closes questions it never has to ask:329 exclusion inferences, 37 answers deduced without a probe, 12 values eliminated by a swap that fell short. None of those is something you can look up.

# Pre-flight: confirm the engine solves every seed (no GPU) uv run python -m eval.runner.engine_selfplay # Pre-flight: score the cost-aware falsifier on a cost-weighted tariff (no GPU) uv run python -m eval.cost_gate # Full gate: 30 seeds × 3 arms ./eval.sh --run-iteration <X> --llm-model <model>

The eval harness lives ineval/and includes the frozen landscape generators, the agent runner, and the gate scorer. Run artifacts are gitignored (eval/runs/).

workspace_id: my-project-name

$ hypotree --info { "workspace_id": "d94da5f61c664f94", "resolved_from": "git_remote", "database": "/home/you/.local/share/mcp_hypotree/d94da5f61c664f94/state.db", "database_exists": true, "warnings": [] }

Workspace names are lowercase[a-z0-9._~-], up to 128 characters.

XDG_DATA_HOMEoverrides on every platform, Windows included — that is how you run isolated instances side by side.

Keep it on a local disk.SQLite runs in WAL mode, which needs shared memory that network shares and most mapped drives do not provide. PointingXDG_DATA_HOMEat a UNC path or a mounted share will fail or corrupt the database.hypotree --infowarns when it detects one.

- Everything buteval.shruns natively; the evaluation harness is a bash script and needs WSL or Git Bash.
- Git is optional. Without it onPATH, layers 3 and 4 both fall through to the path hash — pin the workspace with layer 1 or 2 instead.

# Install in dev mode uv sync # Run tests uv run pytest tests/ -x -q # Lint + format uv run ruff check src/ tests/ eval/ uv run ruff format src/ tests/ eval/ # Type check uv run mypy src/hypotree/

- GitHub:github.com/tygryso/hypotree
- Changelog:CHANGELOG.md— version history with gate results
- Agent guide:src/hypotree/AGENT_GUIDE.md— the full contract, also served live as thehypotree://guideMCP resource

Operational memory for AI agents that persists across sessions and tools.