You Don't need to read papers Anymore

YoDA — ask the literature instead of reading it.

YoDA holds 769 paper notes on deep-learning model optimization across 15 topics — quantization, pruning, distillation, efficient attention, serving, scaling laws, on-device inference and the rest — and answers questions from them. Every claim it makes carries its grounding: a claim left unmarked rests on a note in the corpus, and a claim it had to answer from general knowledge instead is keyed [U1], [U2], … so you can check it. You always know which part of an answer the corpus is actually standing behind.

It is built to advise agents that run training experiments, and it answers people just as well.

The three tiers

YoDA is the top of a three-tier deployment in which knowledge is layered by generality — this is the intended shape of the system, not an optional extra:

executing agent  ◀── directions / reports ──▶  domain supervisor  ◀── questions / answers ──▶  YoDA

Tier	Session lives in	Holds	Instruction files
task — the executor	the experiment repo	runs, configs, numbers; the project's full history, in files and git	templates/executor/CLAUDE.md
domain — the supervisor	its own directory, one per project	domain expertise and a small, deep literature base (kb/)	templates/supervisor/CLAUDE.md + SUPERVISOR.md, a pair
general — YoDA	this repo	generalized ML knowledge, the corpus	already in place (.claude/)

The executor talks only to the supervisor; the supervisor abstracts what deserves to go up and is the only one who consults YoDA. Two boundaries keep the tiers apart: run-level detail never leaves the task tier, and domain detail never reaches YoDA — a question climbs only after being abstracted to the general-DL level. The supervisor's kb/ is simple in machinery (no pipeline, no scores; registered on encounter, ids verified at arXiv) but deeper per paper than YoDA's notes: the domain tier holds a few dozen papers, reads them whole, and keeps the methods, the design rationale and the failed paths in enough detail that a paper never needs downloading twice.

All three tiers carry the same standing rules: a subagent writes nothing beyond the one file its brief commissions, papers enter a KB only after verification, and editing an existing rule in an instructions file needs your explicit acceptance (pure additions do not).

Requirements

Claude Code — one concurrent session per tier, so three for the full deployment — and Python 3.8 or newer for the machinery YoDA runs on your behalf. Nothing to install: the pipeline is standard library only, and search and scoring run entirely offline. Only refreshing the citation data touches the network.

Setting up — all three tiers

0. First, decide where the three sessions run

The three sessions must be able to see each other, and exactly two arrangements allow it — pick one before installing anything:

• All three on one computer. Nothing to configure: same-machine sessions discover and message each other (ListAgents / SendMessage) out of the box, over a local socket. Sessions find each other by name — -n sets one at launch, and without it a name is auto-generated from the folder name plus a random tail. The commands in steps 1–3 pass -n; the names themselves are yours to choose.
• Spread across machines — then every session must be connected via Remote Control. In a running session type /remote-control (or /rc), or launch with it — claude --remote-control yoda; the argument names the session, so give each its own name. Remote Control requires a claude.ai login on a Pro / Max / Team / Enterprise plan — API-key auth does not qualify. Execution and files stay on each local machine; a session on another machine is visible only while both ends are connected. In this arrangement, replace claude -n in steps 1–3 with claude --remote-control, keeping the same names.

1. The advisor — this repo

git clone https://github.com/IAURAI/YoDA.git && cd YoDA
claude -n <name>          # the name is your choice — e.g. yoda

That is all. The session reads .claude/CLAUDE.md at startup, works out that nothing launched it, and reads .claude/YODA.md — at which point it is YoDA. Leave it running.

⚠️ Copy the template files out before use — never start a session on templates/ itself. The files there are unfilled starters shared by every future deployment. A first session fills <DOMAIN> and <DATE> into whatever copy it finds; if that copy is the template, every later deployment inherits this project's answers. templates/ is read-only stock: copy, then run.

2. The domain supervisor — its own directory

mkdir <supervisor-dir> && cd <supervisor-dir>            # one per project — NOT inside this repo
cp -r <path-to-yoda>/templates/supervisor/. .            # the pair + its .claude/skills/
claude -n <name>                                         # e.g. supervisor

Nothing to hand-edit. The first session finds <DOMAIN> and <DATE> unfilled and asks you what the project's domain is ("WiFi CSI pose estimation", "diffusion image restoration", ...), then writes the answer into both files itself. It will also ask whether to adopt YoDA-style ticket delegation for its conversation threads — that is a real decision gate, not boilerplate; either answer works, and you can change it later. The copy also brings three on-demand skills (register · delegate · sync-template) under .claude/skills/ — checklist mechanics that load only when invoked and are always current at load time. The standing rules (contamination, write rules, who may write the KB) stay in the injected files, where they bind before any action.

3. The executor — the experiment repo

cd <experiment-repo>                                     # the code, data and results live here
cp <path-to-yoda>/templates/executor/CLAUDE.md .
claude -n <name>                                         # e.g. executor

Same first-run flow: the session asks for the domain and fills the file in. The executor's instructions sit next to the code deliberately — the experiment repo's files and git history are the project's memory; the other tiers keep none.

4. Wire the sessions together

Start all three sessions and greet each one — any first message will do. The initial-setup questions come back in that greeting turn: both ask for the domain (first run only), the executor asks which session is its supervisor, and the supervisor asks which session is the advisor — answer with the names you chose in steps 1–3. An executor introduces itself to its supervisor by reporting, so nobody has to name it twice. Addresses change on every restart, so nothing is ever hardcoded, and they re-ask after any restart. The supervisor also asks its ticket-delegation question here. If a session cannot see its counterparts at this point, step 0 was skipped — same machine, or Remote Control everywhere.

Cross-session messages can be held for approval on the receiving side, depending on that session's permission mode. The sender cannot see the held prompt — if traffic seems to vanish, check the receiving session and approve it there.

From there the chain runs itself: you hand the executor its task, the supervisor directs and verifies, and a question worth a literature answer climbs to YoDA abstracted and comes back with its grounding labels attached.

The corpus

Plain Markdown — 769 notes across 15 topics, and every note carries the same seven headings (Problem · Key idea · Method details · Results · Limitations and criticism · Practical takeaways · Related work), so a reader or an agent opens one section, not a file. No metric is ever written by hand: notes carry none, and every published number is regenerated by one script from one source.

For a summary of what is inside — the topic map, which technique bites on which bottleneck, where gains compound and where they cancel — read docs/OVERVIEW.md. docs/playbook.md, docs/scores.md and docs/conventions.md cover worked scenarios, the score, and the rules that keep the corpus consistent.

Layout

.claude/    CLAUDE.md — the rules every session here works under, injected at startup
            YODA.md — the owner role · LESSONS.md — why each rule exists · skills/ — the register and refresh workflows, loaded on demand
docs/       OVERVIEW.md · playbook.md · conventions.md · scores.md (generated)
corpus/     NN-<topic>/README.md and NN-<topic>/papers/*.md — the notes themselves
pipeline/   the metadata and citation metrics (enriched/), the scripts, the API response cache
templates/  starters for the other two tiers — supervisor/ (CLAUDE.md + SUPERVISOR.md) and executor/