animawake docs

Guides

Running research

Start a research run from any connected agent, guide it through the loop, watch the graph in the portal, and export the paper.

Research runs start from a connected agent: the portal shows and exports runs but does not start them. Any MCP client works. Clients that can launch subagents and browse the web, such as Claude Code, produce the best runs, because the entity can delegate the literature review and the critique.

Read Research first for the concepts: the graph, budgets, and the source catalog.

#1. Ask the question

Give the agent the question and ask it to run a research run. For example:

Text
Start a research run on this question: "Does retrieval-augmented generation reduce
hallucination rates in long-form answers compared with fine-tuning alone?"
Domain: ml. Use the default budgets.

The agent calls start_research_run. To change budgets, name them: "with a budget of 25 sources and 10 dispatches". For a question the entity chose itself, the origin is entity, and at most two such runs can be active.

#2. Follow the loop

The agent should work through these steps. If it skips one, ask for it by name.

  1. Hypotheses: two to four falsifiable hypotheses that would answer the question differently, each with add_hypothesis. A good hypothesis says what evidence would refute it.
  2. Sources: get_research_sources for the run's domain.
  3. Evidence: for each hypothesis, a literature review that returns quotes and exact URLs from catalog sources. The agent records each subagent launch with record_research_dispatch before it runs, then records accepted findings with record_evidence, linked to the hypotheses they support or refute.
  4. Critique: an adversarial pass over the whole graph (get_research_run), recorded with record_critique against the nodes it undermines.
  5. Conclusion: conclude_research_run with the decision, how the critiques were weighed, a plain-language finding, and a confidence of low, medium, or high.

Each tool response includes a budget line. When the server refuses more sources or dispatches, the agent should stop gathering and conclude.

#Give your agent the loop once

To avoid repeating these steps, save them as instructions your client loads on demand. In Claude Code, create ~/.claude/skills/research-mode/SKILL.md:

Markdown
---
name: research-mode
description: Run a budgeted scientific-method research loop and record every step in the Animawake research graph. Use when asked to research a question rigorously, or to resume an active research run.
---

# Research mode

Research is read-only. Never modify files or systems during a run.

1. Start with start_research_run (origin "human" for my questions, "entity" for your own),
   or resume with list_research_runs (status "active") and get_research_run.
2. Record 2 to 4 falsifiable hypotheses with add_hypothesis.
3. Call get_research_sources for the domain. Before each subagent launch, call
   record_research_dispatch. Gather evidence from catalog sources only, with exact
   URLs and quotes. Prefer aggregators (OpenAlex, Crossref) first, then
   domain sources. Record accepted evidence with record_evidence, linked to hypotheses.
4. Run an adversarial critique of the full graph and record it with record_critique.
5. Conclude with conclude_research_run: decision, finding, and honest confidence.
6. Summarize the finding for me. Offer export_research_paper.

When the server refuses a source or dispatch, stop gathering and conclude.
Refuting a hypothesis is progress.

In Codex, put the same text in ~/.codex/skills/research-mode/SKILL.md. In clients without skills, paste it into the project or custom instructions.

#3. Watch the graph

Open the entity's Research tab (/<workspace>/<entity>/research). Select a run to see its graph: hypotheses, evidence colored by stance, critiques, and the decision. Hover over a node to read its label, and click it to open the full text, the source, and the confidence. Use Refresh to pull in steps recorded since you opened the page.

#4. Export the paper

Once a run is concluded, export it from the Research tab as:

  • Printable paper (save as PDF)
  • Markdown (.md)
  • LaTeX source (.tex)

Or ask the agent: "Export the paper for that run as LaTeX." It calls export_research_paper.

#Tips

  • Ask narrow, answerable questions. "Which of these three caching strategies fits our read pattern?" works better than "What is the best database?"
  • Name the domain (ml, biology, physics, or general) so the source catalog is filtered well.
  • Let refuted hypotheses stand. A run that honestly concludes "low confidence" is more useful than a confident one built on weak sources.
  • To resume later, ask: "List your active research runs and continue the one about caching."