Thesis stores every hypothesis, experiment, source summary, and insight as a node in a graph. Nodes branch from each other rather than overwriting history, so your research program grows as a navigable map instead of a pile of chat logs. This guide walks you through setting up that structure from scratch.
1

Create a root node

A root node anchors your research program. It has no parent and gives your project a stable identity in the graph.Ask the agent, or call the MCP tool directly:
{
  "name": "thesis_stage_node_create",
  "arguments": {
    "title": "Effect of learning rate schedules on GRPO convergence",
    "summary": "Root node for a research program investigating how LR schedules affect GRPO training stability.",
    "kind": "untyped"
  }
}
The node starts in a staged state, meaning you can edit it freely. Commit it once the title and framing are stable, committed nodes become immutable history.
kind: "untyped" is the right choice for a root or planning node. Use kind: "empirical" when you’re staging a testable experiment, and kind: "insight" for synthesis nodes that summarize conclusions.
2

Add a summary and content

After creating the node, open it in the UI or update it via thesis_stage_node_update. A good root node has:
  • Summary, a single sentence stating the core claim or research question.
  • Content, background context, open questions, prior work pointers, or protocol notes.
The summary is used by search and Oracle jobs to anchor retrieval. Keep it precise.
3

Index your sources

Thesis can index external papers, repositories, and documentation sites and make them searchable alongside your graph content.Index an arXiv paper:
{
  "name": "thesis_index_paper",
  "arguments": {
    "external_ref": "https://arxiv.org/abs/2402.03300",
    "display_name": "DeepSeekMath paper"
  }
}
Index a GitHub repository:
{
  "name": "thesis_index_repo",
  "arguments": {
    "owner_repo": "huggingface/trl"
  }
}
Index a documentation site:
{
  "name": "thesis_index_docs",
  "arguments": {
    "url": "https://huggingface.co/docs/trl",
    "display_name": "TRL documentation"
  }
}
Indexed sources appear in the Knowledge panel and are returned by thesis_search alongside your graph content.
For rapid ingestion of many sources at once, ask the agent to extract claims, methods, assumptions, and follow-up experiments from source material and turn them into linked nodes. Useful when onboarding into a new field or converting prior notes into structured graph state.
4

Branch into sub-experiments

Once your root node is committed, create child nodes to represent individual experiments, source summaries, or sub-hypotheses. Use thesis_branch_node to create a child that inherits the parent’s graph context:
{
  "name": "thesis_stage_node_create",
  "arguments": {
    "title": "Cosine vs. linear decay on 1B GRPO run",
    "summary": "Compare convergence speed and final reward under cosine vs. linear LR decay.",
    "kind": "empirical",
    "parent_ids": ["<root-node-id>"]
  }
}
Edges encode parent/child relationships across your whole program, so Thesis can display ancestor trees, trace where an idea came from, and suggest next-step frontiers based on what’s been completed.
5

Tag nodes for navigation

Tags let you group nodes across branches, useful for marking nodes by status, method family, or review stage.Create a tag (scoped to a root node):
{
  "name": "thesis_create_node_tag",
  "arguments": {
    "root_node_id": "<root-node-id>",
    "expected_revision": 0,
    "name": "needs-review",
    "bg_color": "#f59e0b",
    "text_color": "#ffffff"
  }
}
Then assign it to one or more nodes with thesis_set_node_tag_assignments. Tags appear in the graph canvas and can be used to filter the node list.
6

Set sharing for your nodes

Each node has its own sharing mode. You can keep early-stage work private while making completed results accessible.
ModeWho can see it
privateOnly you
unlistedAnyone with the direct link
publicAnyone
Set sharing via thesis_set_sharing_for_node:
{
  "name": "thesis_set_sharing_for_node",
  "arguments": {
    "node_id": "<node-id>",
    "sharing_mode": "unlisted"
  }
}
Use thesis_set_sharing_for_nodes to update sharing on a batch of nodes at once.

​
What to do next

With your root node committed and sources indexed, you’re ready to design a testable experiment. See Design and stage an empirical experiment to stage an 8-section experiment blueprint and route it through the approval flow.