{"id":51059623,"url":"https://github.com/frudas24/research-tree","last_synced_at":"2026-06-23T00:31:02.878Z","repository":{"id":364339700,"uuid":"1267430001","full_name":"frudas24/research-tree","owner":"frudas24","description":"DAG-based research tracking CLI for humans and agents: nodes, claims, runs, artifacts, history, diffs, supersede, and operational knowledge.","archived":false,"fork":false,"pushed_at":"2026-06-19T22:44:42.000Z","size":197,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T00:17:05.621Z","etag":null,"topics":["agents","artificial-intelligence","dag","nodes","research"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frudas24.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T14:31:47.000Z","updated_at":"2026-06-19T22:44:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frudas24/research-tree","commit_stats":null,"previous_names":["frudas24/research-tree"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/frudas24/research-tree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frudas24%2Fresearch-tree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frudas24%2Fresearch-tree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frudas24%2Fresearch-tree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frudas24%2Fresearch-tree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frudas24","download_url":"https://codeload.github.com/frudas24/research-tree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frudas24%2Fresearch-tree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34671045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","artificial-intelligence","dag","nodes","research"],"created_at":"2026-06-23T00:31:00.583Z","updated_at":"2026-06-23T00:31:02.872Z","avatar_url":"https://github.com/frudas24.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Research Tree\n\n**Research is a graph. Your logbook shouldn't be a flat file.**\n\nResearch Tree maps scientific and engineering work as a directed acyclic graph\n(DAG). Every node is a unit of research — an idea, a claim, an experiment, a\ndecision — connected by epistemic edges (parent, continuation, supersession).\n\nIt replaces linear research logs (logbooks, lab notebooks, markdown dumps)\nwith a structured, queryable, and auditable knowledge graph.\n\n**Stack:** Go standard library + `cobra` (CLI).  \n**Storage:** `.research/` directory — no database, no server, no daemon.  \n**License:** MIT. See `LICENSE`.\n\n---\n\n## Project status\n\nResearch Tree is **released as-is**.\n\n- It is used in real technical research workflows.\n- The CLI and ABI are intended to be integrated by both humans and agents.\n- There is **no support or maintenance commitment**.\n- Bug reports and patches may be reviewed opportunistically.\n\nIf you need a stable local dependency, vendor it or fork it.\nSee `SUPPORT.md` for the maintenance policy.\n\n---\n\n## Why this exists\n\nLinear logs break down the moment research branches. You start with a\nhypothesis, run an experiment, pivot, fork, abandon a path, revisit it three\nweeks later. A flat text file can't answer:\n\n- Which claims are still provisional? Which have been invalidated?\n- What experiment produced this result, on which host, with what command?\n- What did this node look like before I changed my mind?\n- What depends on this assumption?\n\nResearch Tree gives you a DAG, not a timeline. Every node knows its parents,\nits children, its continuations, and its replacements. You navigate the\nstructure of your thinking, not the order you typed it in.\n\n\u003e It was born from tracking 19+ sequential log files during LLM prompt\n\u003e research. When backtracking to a three-week-old experiment took longer than\n\u003e running it again, the tool became necessary.\n\n---\n\n## Five minutes to your first graph\n\n```bash\n# 1. Start a research project\nrt init\n\n# 2. Create a research node\nrt node create --title \"Hypothesis: larger context windows improve recall\"\n\n# 3. Claim hardware and log an experiment run\nrt resource add --id ctx-gpu0 --label \"gpu-node-3 gpu0\" --kind gpu \\\n  --endpoint gpu03.int.lab --endpoint-kind dns --tags cuda,24gb\nrt resource claim 1 ctx-gpu0 --by codex --note \"longqa baseline\"\nrt node logrun 1 \\\n  --resource-id ctx-gpu0 \\\n  --endpoint gpu03.int.lab \\\n  --endpoint-kind dns \\\n  --cmd \"python eval.py --ctx 8192 --dataset longqa\" \\\n  --outdir /tmp/run-001 \\\n  --seed 42 \\\n  --note \"baseline: 8k context, standard attention\"\n\n# 4. Validate the claim with evidence\nrt node close 1 --outcome success \\\n  --append-body \"8k context improved recall by +12% over 4k baseline.\"\n\n# 5. See what happened\nrt feed --hours 24\nrt resource history ctx-gpu0\nrt tree\nrt status\n```\n\n**That's the core loop:** hypothesis → experiment → evidence → conclusion.\nEvery step is a node. Every connection is explicit. Nothing is lost.\n\n---\n\n## The mental model\n\n| Concept | What it means |\n|---------|---------------|\n| **Node** | A unit of research: claim, experiment, decision, or observation |\n| **Parent** | What prior work does this depend on? (epistemic dependency) |\n| **Claim** | A falsifiable statement. Starts `provisional`, ends `validated`, `invalidated`, or `superseded` |\n| **Run** | A concrete experiment execution: resource, endpoint, command, outdir, seed, validity |\n| **Resource** | A declared machine/GPU/cpu-slot with stable `id`, human `label`, and technical `endpoint` |\n| **Lease** | A live occupancy claim from one node to one resource |\n| **Artifact** | A file or dataset attached to a node (linked or embedded) |\n| **Supersede** | A claim replaced by a better one — preserves both, with a traceable edge |\n| **Continue** | A long investigation split across nodes — keeps the thread alive |\n\nA node with `continued_by=[7]` says \"this work isn't done, node 7 picks it\nup.\" A claim with `superseded_by=[12]` says \"this conclusion was valid at the\ntime, but node 12 has a better one.\" No information is destroyed.\n\n---\n\n## Key features\n\n- **DAG, not a tree.** A node can have multiple parents from different\n  branches. Ideas merge, and the graph reflects that.\n- **Claims with lifecycle.** `provisional` → `validated` | `invalidated` →\n  `superseded`. Every transition is evidence-gated.\n- **Experiment runs.** Structured run records with resource, endpoint, command, outdir,\n  seed, ETA, cost, and validity.\n- **Resource coordination.** Explicit inventory plus active leases prevent\n  agents from double-booking the same machine or GPU.\n- **Revision history and diffs.** Every update creates a revision. `rt node\n  diff 42 --rev-a 3 --rev-b 7` shows exactly what changed.\n- **Chronological feed.** `rt feed --hours 24 --status done` gives you a time-\n  sorted activity view without losing the graph structure.\n- **JSON output.** Every command supports `--json` for scripting, dashboards,\n  and agent integration.\n- **Zero dependencies at rest.** Everything is a directory on disk. No\n  database, no server, no daemon. Back up with `rsync`.\n- **Agent-ready.** Both a Go ABI (`pkg/retree`) and a structured CLI for\n  external tooling. Designed to be embedded.\n\n---\n\n## Install\n\nFrom source:\n\n```bash\ngo install ./cmd/rt\n```\n\nBinary lands in `$GOPATH/bin/rt`. Add it to your PATH.\n\nTo build locally:\n\n```bash\nmake build          # -\u003e build/rt\nmake libretree.so   # -\u003e build/libretree.so + build/libretree.h\n```\n\nResearch Tree has two primary integration surfaces:\n\n- `build/rt` — standalone CLI for humans and shell automation\n- `build/libretree.so` + `build/libretree.h` — C ABI for embedding into other software\n\n---\n\n## Quick reference\n\n```bash\nrt init                              # create .research/ in current dir\nrt status                            # dashboard: active, done, paused, claims, hotspots\nrt status --matrix                   # status × outcome matrix\nrt tree                              # visualize the DAG\nrt tree --depth 2                    # limit depth\nrt tree --show-relations             # show relation hints without changing DAG shape\nrt tree --color always | grep '★'    # inspect golden milestones in the graph\nrt feed --by modified --hours 24     # recent activity\nrt golden --verbose                  # list frontier/champion nodes\nrt timeline --days 7                 # activity grouped by day\nrt changes --since 72                # nodes changed in last 72h\n\n# Nodes\nrt node create --title \"...\" --parents 1,2 --tags a,b,c\nrt node create --title \"...\" --milestone-class golden --milestone-kind breakthrough --milestone-reason \"...\"\nrt node show 42\nrt node show 42 --agent --json         # compact handoff for other agents\nrt node edit 42 --title \"better title\" --add-tags urgent\nrt node edit 42 --milestone-class golden --milestone-kind champion --milestone-reason \"best lineage artifact\"\nrt node edit 42 --append-body \"new findings\"\nrt node close 42 --outcome success\nrt node close 42 --outcome failure\nrt node delete 42 --force\nrt node diff 42 --rev-a 3\nrt node ancestors 42\nrt node descendants 42\n\n# Experiments\nrt resource claim 42 gpu-node-0 --by codex\nrt node logrun 42 --resource-id gpu-node-0 --endpoint 10.0.0.14 --endpoint-kind ip --cmd \"...\" --outdir /tmp/run --seed 7\nrt node link 42 --commit auto --artifact /tmp/run --host gpu-1\n\n# Resources\nrt resource add --id gpu-node-0 --label \"GPU Node 0\" --kind gpu --endpoint 10.0.0.14 --endpoint-kind ip\nrt resource list --free\nrt resource report\nrt resource history gpu-node-0\n\n# Queries\nrt node list --status active\nrt node list --tag benchmark\nrt node list --claim-status invalidated\nrt node list --milestone-class golden\nrt node list --milestone-class golden --milestone-kind champion --sort-by modified --order desc\nrt node list --body-contains \"perplexity\"\nrt node list --created-after 2026-06-01T00:00:00Z --sort-by created\n```\n\n### Golden milestones\n\nGolden milestones are a first-class metadata axis for frontier-significant nodes.\n\n- Canonical storage/query fields:\n  - `milestone_class=golden`\n  - optional `milestone_kind=champion|breakthrough|pivot`\n  - required `milestone_reason`\n- Canonical query:\n  - `rt node list --milestone-class golden`\n- Human shortcut:\n  - `rt golden`\n\nGolden milestones are **orthogonal** to `status`, `outcome`, and `claim_status`.\nA node is not golden merely because it is `done`, `success`, or `validated`.\nUse golden metadata when the node breaks a ceiling, becomes the lineage champion,\nor materially shifts the bottleneck/roadmap.\n\n---\n\n## Integrating with your agent or tool\n\nResearch Tree exposes two integration surfaces:\n\n### 1. Go ABI (`pkg/retree`)\n\n```go\nimport \"github.com/frudas24/research-tree/pkg/retree\"\n\nstore, _ := retree.Open(\".research\")\nnode, _ := store.CreateNode(retree.Frontmatter{\n    Title:  \"Hypothesis: ...\",\n    Parents: []retree.NodeID{1},\n    Tags:   []string{\"benchmark\", \"llm\"},\n})\nstore.CloseNode(42, retree.OutcomeSuccess, \"conclusion text\")\n```\n\n### 2. CLI with JSON\n\n```bash\nrt status --json\nrt node show 42 --agent --json\nrt node list --tag benchmark --json\nrt feed --hours 24 --json\n```\n\nParse the JSON from any language. No library needed.\n\n---\n\n## Design principles\n\n- **Epistemic edges, not organizational ones.** A parent edge means \"this\n  depends on that claim or result,\" not \"this belongs to that project.\"\n- **Evidence before conclusions.** Claims must cite runs. Invalidated claims\n  must cite a refuter node.\n- **The graph preserves history.** Nothing is overwritten. Every revision is\n  stored. Every superseded claim stays visible.\n- **Simplicity over features.** Three statuses. Three outcomes. Four claim\n  states. If a concept doesn't earn its place in the graph, it doesn't go in.\n- **Portable by design.** `.research/` is a directory. Move it, back it up,\n  version it. No migrations, no servers, no lock-in.\n\n---\n\n## Documentation\n\n| File | Content |\n|------|---------|\n| `AGENT.md` | Project overview and conventions |\n| `AGENT_INSTRUCTIONS.md` | Operational runbook for agents and contributors |\n| `docs/cli.md` | Full CLI reference |\n| `docs/AGENT_INSTRUCTIONS.md` | Extended agent guide |\n| `docs/abi.md` | Go ABI reference |\n| `docs/architecture.md` | Architecture overview |\n| `docs/data-model.md` | Data model and types |\n| `docs/storage.md` | `.research/` persistence design |\n| `docs/development.md` | Development guide |\n| `docs/testing.md` | Testing guide |\n| `docs/binary-codec.md` | Binary codec specification |\n| `docs/e2e-simulator.md` | End-to-end simulator guide |\n\n---\n\n## Release model\n\nThis repository is published as a usable infrastructure artifact, not as a managed product.\n\n- **License:** MIT. Do what you want. Credit is appreciated, not required.\n- **Maintenance:** best-effort only. See `SUPPORT.md`.\n- **ABI / CLI:** intended to be integrable, but releases are still opinionated and pragmatic.\n- **Philosophy:** build tools that respect how technical thinking actually works — branching, invalidation, reruns, and evidence-driven course correction.\n\n## Contributing\n\nSmall, well-scoped fixes are preferred over broad feature expansion.\nIf you send a patch, include tests where practical and keep the DAG / provenance-first model intact.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrudas24%2Fresearch-tree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrudas24%2Fresearch-tree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrudas24%2Fresearch-tree/lists"}