Nexus · research← Working with RDRs

Research with Nexus

Nexus keeps the papers you read, the code you write, and the design records that connect them in one store, with links between them. Everything a piece of research produces becomes a document in that store, linked to the paper and to the work before it. A second reader with access to your code checks each claim on the way. This page shows what you say to Claude at each step and what Claude shows you.

Words in <ORANGE CAPITALS IN ANGLE BRACKETS> are placeholders. The prompts are examples, and your own words work. Read Getting started first for the three stores, the catalog, and renderings. The output blocks are real tool output, trimmed. Research in Nexus explains the thinking behind the method: what was borrowed from experimental science, what was left out, and why.

Terms used on this page
TermMeaning
linkA typed connection between two catalog documents: cites, implements, supersedes, relates, comments, quotes.
critic agentThe agent that checks a plan or a result against the code, the schema, and the design records, and returns a verdict.
mappingA document that says, claim by claim, where a paper touches your own system.
proposalOne change your system could make, with its cost and its falsifier.
falsifierThe result that would show a proposal is wrong. A proposal without one is an opinion.
pre-registrationOne paragraph written before an experiment runs: arms, the one variable, confounds, metrics, statistic, budget, falsifier.
one store, one catalog, every document addressed and linked the paperindexed, enriched, linked readingtwo agents, to memory mappingclaim by claim proposalseach with a falsifier verdictcritic, with the code experimentpre-registered reportrendered from all of it comments cites cites supersedes proposals cites relates your code and design recordswhat the mapping points at implements, relates brass: the links you add by hand, from a paper to what it concerns in your system
A paper and the six documents a piece of research produces from it.
1

Add a paper to the store

A paper in the store is a catalog entry with the paper's text in chunks, its DOI and authors, and its place among the links. Every later step links back to that entry.

You might say
Index <PATH-TO-THE-PDF> into the <SUBJECT> collection, with bibliographic enrichment, and show me the catalog entry.
What Claude does

Claude runs nx index pdf with --enrich. By default a PDF goes through MinerU, which reads layout, tables, and formulas. It falls back to the text layer for a page it cannot read. If you installed with --slim the first PDF installs PDF support first. Enrichment looks the paper up by title in Semantic Scholar. It adds the year, the authors, the venue, and the citation count to the catalog entry. Then Claude shows the entry. A second command, nx enrich bib, adds the DOI and the OpenAlex id in the sample below.

What you see
catalog show  1.12.119
  title:      RAG Deserves an Index: Why Ingest-Time Compilation Beats Query-Time Interpretation
  author:     Kyle Wild, Yusuke Takahashi, Asako Uraki
  collection: knowledge__dt-papers__voyage-context-3__v1
  bib_doi:    10.48550/arxiv.2608.20845    bib_openalex_id: W7204148305
  bib_venue:  arXiv (Cornell University)   index_state: complete
  …

On macOS with DEVONthink, nx dt capture takes a URL, a DOI, or a file, stores it in DEVONthink, and indexes it in one step. A DOI, or a URL captured with --type pdf, stores the PDF, and a URL alone is stored as a web archive. The catalog keeps the DEVONthink identity, so the same paper is never indexed twice. With --link-semantic, nx dt capture and nx dt index also add relates links, made by dt_similar, to the most similar documents already in the store. nx index pdf adds no such links.

Collections are subjects

A paper is stored in a collection named for its subject, such as distributed-systems or semantic-operators, and never for a project or a date. A later question can then be limited to one subject. "What do the semantic-operator papers say about batching" works because those papers are in one place.

Watch the indexing

You might say
Read the index log while it runs. Tell me if any stage did not complete, if no aspects were extracted, or if the citation lookup returned nothing.

Indexing has several stages, and each one writes to the log. A paper indexed with no aspects, or a lookup that returned nothing, is a fact about the pipeline and not about the paper. It is cheap to find now.

Investigate further

2

Read a paper with two agents

Search results are not reading, because a paper's chunks hide what kind of document it is. Two agents at the same time, one inside the paper and one outside it, give you a reading you can build on. Research in Nexus tells how a position paper looked like a full study.

You might say
Two agents on <THE PAPER>, at the same time. One reads the full text and reconstructs the paper: claims, method, numbers, and what the paper does not say. The other researches everything outside the paper: the authors, independent evaluations, earlier work, and the opinion of the field. The second agent marks every claim with a source or with "could not verify". Both write to memory.
What Claude does

Two agents start. The first reads the full text and writes a technical reconstruction: what is claimed, with what evidence, and what is missing. The second is the research agent, working outward from the paper. Both write memory entries, and Claude shows you where they disagree.

What you see, from the first reading
memory_get  nexus / paper-rag-deserves-an-index-2608.20845-nexus-mapping
Thesis: ingest-time semantic compilation. Compile a corpus's meaning once at write time into
a substrate with two coupled layers, incrementally maintained embeddings plus atomic claims
with byte-exact quote provenance validated at compile time …
Numbers: compiled claims as retrieval payload won all 32 budget-by-model cells on 500 MediaSum
transcripts (85.2% correct at ~2.2k reader tokens vs 72.5% at ~16.3k for best chunking) …
Limitations the paper states: synthetic maintenance pilot; grader and extractor share a model;
the compiled-payload advantage did not survive a tool-using agent layer, which is exactly this
system's consumer shape. That last point is the one to test before deepening aspects …
Companion: arXiv:2608.16621 (maintenance study), Takahashi, Wild, Uraki.

The last two lines are what a summary does not give you. The paper's own limitation names the experiment to run before building anything, and the companion paper holds the protocol.

Read the full source before you use it

Everything built on a reading inherits its errors, so the reconstruction comes from the full text and not from the chunks. A sentence such as "the protocol is in a second paper" changes what can be tested later, and no search result contains it.

Investigate further

  • Ask Claude, after the two readings: "Where do the two readings disagree, and which one has the source?"
  • The research agent: its steps, and why it checks the catalog before it searches.
3

Link a paper to your code

A link is a typed connection between two catalog documents, and it works in both directions. Indexing creates most links for you. The links with the most meaning, from a paper to the module or the design record it concerns, are the ones you add.

You might say
Link <THE PAPER> to <THE MODULE THAT IMPLEMENTS ITS IDEA> with an "implements" link, and to <THE DESIGN RECORD IT CONCERNS> with "relates".
What Claude does

Claude makes one link call on the catalog server per link, with the two documents and the type. It accepts titles, so you never need the addresses.

See what a paper is connected to

You might say
What links to <THE PAPER>, and what does it link to?
What you see
$ nx catalog links "RAG Deserves an Index: Why Ingest-Time Compilation Beats Query-Time Interpretation"
1.12.119 → 1.14.23    (relates)   by dt_similar
1.12.119 → 1.12.53    (relates)   by dt_similar
1.12.119 → 1.1.3642   (relates)   by user
1.12.119 → 1.1.838    (relates)   by user
1.11.529 → 1.12.119   (comments)  by user
1.11.530 → 1.12.119   (cites)     by auto-linker
1.11.532 → 1.12.119   (cites)     by auto-linker
1.11.533 → 1.12.119   (cites)     by auto-linker

Every link names who made it. The dt_similar rows came from DEVONthink indexing. The auto-linker rows were added when a document that cites the paper was stored, and the user rows were added by hand. When the answer matters, ask for links by creator: "Only links made by hand."

Follow the links

A research result names documents, and each one is a place to continue. Ask "Start from <THE PAPER>, follow cites links for two steps, and list what you reach." That walks the graph with traverse, a tool on the nexus server. The query tool can do the same during a search with follow_links, and it ranks a document higher when it has outgoing links. An implements link counts most, and relates and cites links count half as much. The plain search tool does not use links.

A link made from a path-matching heuristic is marked implements-heuristic, and ranking gives it no weight. Links suggested by a model are advisory. The links you add by hand are the ones a later reader trusts.

Investigate further

4

Ask a question across papers

A question over several papers on one subject needs several searches, the passages from each result, an extraction, and a comparison. Claude runs that as a plan and returns one answer with a source for each claim. A plan that worked is saved for the next question of the same shape.

You might say
What do the <SUBJECT> papers say about <THE POINT>?
What Claude does

Claude calls nx_answer with the question and the collection. If a saved plan fits, it runs. If none fits, Claude writes a plan, runs it, and saves it.

What you see
nx_answer  question: What do the semantic operator papers say about batching to reduce model calls?
           scope: knowledge__semantic-operators…
  steps: search, store_get_many, search, store_get_many, extract+generate

## Bottom line
The provided passages do not document batching multiple records into a single prompt. …
What the passages do cover is a neighbouring set of call-reduction levers: model cascades,
per-operator model and backend selection, plan-level cost/quality optimization, and semantic caching.

## Call-reduction techniques the passages do name
"Bridge the Last Mile Gap to Semantic Analytics" gives the clearest inventory:
- Palimpzest [12] pioneered the paradigm and explores cost/quality tradeoffs across execution plans.
- LOTUS [14] provides formal accuracy guarantees through model cascades. …

## What would be needed to answer the question as posed
… the LOTUS and Palimpzest papers themselves, the DocETL and Helium papers …

The answer says what the store does not hold as plainly as what it does. "Not in these passages" is a result, because it names the papers to add next. An open web search cannot say that, and a store you curated can.

Limit the question to one collection

"What do the semantic-operator papers say about batching" searches one collection. "What does the literature say about batching" searches everything and mixes subjects.

See the saved plans

You might say
List the saved retrieval plans for this project that match "batching".
What you see
plan_search  query: batching semantic operators   project: nexus
[365] What do the semantic operator papers say about batching and …
  outcome=success  tags=ad-hoc,grown
  plan: {"steps": [{"args": {"limit": 12, "query": "semantic operators over documents LLM call batching …

If an answer surprises you, ask which plan it used and what each step returned. A plan that searched the wrong collection is visible in its first step.

Investigate further

  • Querying guide and plan-centric retrieval.
  • For one kind of fact across many papers, ask for the table directly: "From every paper in <COLLECTION>, extract the dataset, the baseline, and the reported metric." The appendix says when this reads structured fields instead of the text.
5

Map a paper and write proposals

A mapping says, claim by claim, where a paper touches your own system. Each claim gets one of three answers. A module already does it, a design record rejected it for a reason, or it applies and nothing does it. Only the third kind leads to a proposal, and a proposal is written with the result that would show it is wrong.

The mapping

You might say
Map <THE PAPER> onto our system. For each claim: does it apply to us, which module or design record does it touch, and does it agree with what we decided. Link the paper to those modules and records in the catalog.
What Claude does

Claude reads the reconstruction from lesson 2 and searches the code and the design records for each claim. It writes the mapping to the store and adds the links from lesson 3.

What you see
Mapping onto the system (links created in the catalog):
- RDR-089 aspects at ingest (1.1.3896, implements-heuristic): the document_aspects table is the
  paper's claims layer, but per document, not atomic, and without the byte-exact provenance gate.
  The gap is claim granularity and provenance validation, not the architecture.
- RDR-181 server-side embed-skip (1.1.2822, implements-heuristic): the "cost scales with change"
  half; unchanged chunks are skipped, but there is no low-rank incremental update, because
  pgvector stores raw vectors and needs none.
- RDR-199, RDR-108, RDR-096, RDR-055 (relates): the paper's tombstoning and redo log correspond
  to the catalog manifest, the tombstones, and the aspect queue.

The proposals

You might say
Write proposals from the mapping of <THE PAPER>. Give the agent the mapping, the linked design records, the code paths, and a web check. Every proposal states what it changes, the result that would show it is wrong, and a cost. Include a do-nothing option.
What Claude does

The research agent runs with that instruction and returns its proposals, each with its falsifier and its cost, plus the do-nothing case. The document goes to the store with a cites link to the paper. A proposal with no way to be wrong is an opinion, and the falsifier is what makes the next experiment obvious.

A mapping often finds that a claim is already handled or already rejected. The mapping records that too, linked to the record that decided it. The next reader of the paper then finds the decision instead of repeating the argument.

Investigate further

6

Check the proposals with the critic

A synthesis alone produces a plausible plan with false premises. A second reader with access to your code finds the false premises before anything is built.

You might say
Have the critic read the proposals on <THE PAPER> with access to the code, the schema changelogs, and the design records. For each proposal: survives, survives with amendment, or dies, with the artifact that decides it.
What Claude does

The critic agent runs with the paths to check. It returns its critique in a fixed format: the issues it found, each with the evidence, and an outcome of justified, partial, or not justified. Claude then writes a verdict document and links it to the proposals and the critique.

What you see, from the critic
## Critical Issues
### Issue: Proposal 3's central premise is false — the run table has no document-read signal
- Evidence: service/…/telemetry-001-baseline.xml (changeset telemetry-001-7); telemetry-007-nx-answer-steps.xml
### Issue: Proposal 4 cites RDR-108 as a template already built, but RDR-108 rejected exactly that pattern
- Evidence: docs/rdr/rdr-108-graph-identity-normalization.md ("Alternatives Considered" / Alternative A)
### Issue: Proposal 2 conflates quote provenance with the paraphrase-only aspect schema
- Evidence: src/nexus/aspect_extractor.py field specs

## Verdict

- **outcome**: not-justified
- **confidence**: high
…
What you see, in the verdict document
## The ideas, and which survived
1. Replicate the agent-layer experiment before building anything.   Survives.
2. The redo-log idea maps onto a known gap.                          Survives, and the synthesis had missed it.
3. Compile-time provenance validation gate.                          Dies as specified. Amendment: a narrow gate over extractable sub-facts.
4. Break-even instrumentation.                                       Dies as "free". A small schema change survives.
5. Atomic claims layer.                                              Blocked on item 1, and the synthesis cited the wrong precedent.
6. Incremental embedding maintenance.                                Rejected on the merits.
## Recommendation
Run item 1. Fold item 2 into the existing beads. Do not build item 5 on faith.

A changelog shows a table has no document identity. The alternatives section of a design record shows an idea was rejected and not adopted. A field holds a paraphrase and not a quote. None of that is in any paper, and semantic search over prose does not find it, so tell the critic which files to read.

Investigate further

7

Measure a proposal

A surviving proposal with a falsifier you can measure becomes an experiment. Three steps keep the experiment honest. Write the pre-registration before you spend anything. Build a harness that can be audited. Have a second reader recompute the result from the raw data.

Pre-register the measurement

Write one paragraph before the run, and have every later check run against it.

You might say
Write the pre-registration paragraph for <THE EXPERIMENT>: the arms, the one variable that differs between them, the confounds you know of, the metrics, the statistic, the budget, and the result that would show the hypothesis is wrong. Do not run anything until I have read it.

Build the harness so it can be audited

You might say
Build the harness for <THE EXPERIMENT>. Fix the random seed and the model identifiers. Retrieve once per question and cache the result. Save, for each trial, the exact text each arm received, the structured flags, and the cost of every model call. Report McNemar, Wilson intervals, and a cluster-robust paired difference.

A harness that produces only a summary table cannot be audited. A harness that keeps the input text, the reader's flags, and every cost can answer, later, why any trial failed.

Recompute the result

You might say
Methodology critique of <THE EXPERIMENT>. Give the critic the raw trial data, not the report. Recompute every number. Classify every outcome as correct, wrong, or no answer. Check that the generated data follows its own generation rules. Validate the grader on a sample labelled by a person.
What you see, from the recompute
Verdict: NOT-JUSTIFIED, confidence high. Do not proceed to an engine change on this evidence.

ARITHMETIC IS CLEAN. Every number in report.md reproduces exactly from retrievals.jsonl by independent
recomputation … The instrument, not the arithmetic, is the problem.

SHIP-BLOCKER 1 — THE HEADLINE IS FORCED BY CONSTRUCTION. … A control that knows nothing about the
treatment reproduces more than half of the gap between the arms.

SHIP-BLOCKER 2 — THE LEG THAT PASSED DOES NOT TEST THE SIGNAL. …

WHAT A FAIR RERUN NEEDS. …

A report may say "the treated arm mostly answered wrongly" while the raw log shows most failures were no answer at all. Those are two different findings, and only the recompute finds the second. Here it found a clean report over a broken instrument, which no reading of the report could have shown.

Investigate further

  • Ask Claude, before any run: "Count the questions on which the treatment can act at all. If that is fewer than the discordance floor, stop."
  • Research in Nexus: why the method pairs a critique before the run with a recompute after it.
8

Write the report

The material is already in the store and linked, put there by sessions that may be weeks apart. A rendering is one document written from the current content of the stores for a reader. It can be a report, a briefing for people who did not follow the work, or a precis of a paper. Ask again later, and the document is current.

You might say
Render everything we did with <THE PAPER> as one document: what the paper claimed, what applied to us, what we proposed, what the critic removed and why, what the experiment showed, and what is still open.
What Claude does

Claude starts at the paper's catalog entry, follows the links to every document produced from it, and writes the report from their current content. The report goes into the store, linked to all of them.

What you see, when you ask what the paper is now linked to
links to 1.12.119 (the paper):
  1.11.529  first-pass mapping                       comments
  1.11.530  research synthesis, five proposals        cites
  1.11.531  critique pattern, recorded for reuse      cites
  1.11.532  verdict after critique                    cites   supersedes 1.11.529, 1.11.530
  1.11.533  the experiment and its result             cites   relates 1.11.532
  1.11.534  findings on the method                    cites   comments 1.11.533

The verdict supersedes the mapping and the synthesis it reduced. A reader who opens the paper a year from now can follow the supersedes link from the verdict to the earlier drafts behind it.

Check that the record was kept

You might say
What did you write to the stores today, and what does it link to?

If the answer is "nothing", the work exists only in this conversation, and the next session starts without it. Ask after each piece of work, not once a day. A person who was not present should be able to follow the links from the paper through everything done with it.

When there is an idea and no paper

You might say
Brainstorm the design space around <THE IDEA>: related designs, what we could merge into existing parts, what would be new. Then write where it sits among systems that do similar things. Store both as exploration, each with a decision line: adopted, parked, or scrapped.

An exploration with no decision line is a question that waits for you. Ask "Which explorations have no decision line?" to list them.

Investigate further

  • A design record is the rendering that ends in a decision to build. Working with RDRs shows how its research section is the mapping, the verdict, and the result already written.
  • Getting started, rendering, for system documentation rendered from the code and kept current the same way.

Appendix: how the store is built

Nothing here is needed to do the lessons. It is here for the reader who wants to know why an answer carries sources and what the store builds beyond its chunks.

Tools and commands

Most of the time you use none of these directly, because you say what you want and Claude chooses the tool.

SurfaceWhat it is
Search toolssearch over chunks, query over documents with follow_links, nx_answer for a planned answer with sources, search_aspect_scoped and search_topic_scoped to limit a search by a structured field or a topic.
Catalog toolsshow, links, and link on the nexus-catalog server. Titles work as addresses. traverse is on the nexus server.
Store toolsstore_put for a document, memory_put for a note by project and title, plan_search for the saved plans.
Operatorsextract, compare, check, verify, and the rest are steps inside the plans nx_answer runs. You do not call them directly, so ask nx_answer to use them.
Commands and skills/conexus:research is the command for the research agent. /conexus:substantive-critique runs the critic, and /conexus:knowledge-tidying consolidates what was stored.
nx commandsnx index pdf, nx dt capture, nx enrich, nx catalog show and links, nx doc cite, nx taxonomy, nx search --where.
nx doc cite "<A CLAIM>" --against <COLLECTION>

nx doc cite finds the chunk that grounds a sentence and returns a link to it, or says that nothing in the collection does.

What you see
$ nx doc cite "compiled claims as the retrieval payload won all 32 cells on MediaSum at 85.2 percent correct" --against knowledge__dt-papers
[to floating-point precision. And on a held-out sample of 500](chash:e97331ff10ab59c8c97537bc440fbd6c4e85cd167579af89fa133b550418bf5d)

$ nx doc cite "compiled claims as the retrieval payload beat chunking" --against knowledge__dt-papers
top candidate distance … above threshold … — no cite emitted. Try a narrower claim or broaden the collection.

The second call shows the refusal. A claim too vague to ground returns no link and says so.

Grounding

A grounded answer rests on a document you can open. Retrieval runs before generation, so a question about a paper that is not in the store gets "not found" and not an invented summary. Every source is addressable: a chunk by its content hash, a document by its catalog entry, and a memory entry by project and title. A citation in an answer names one of these. A check across several documents returns, for each one, whether it supports or contradicts the claim, with the passage.

Grounding does not make a source true, because a paper in the store can be wrong. It tells you where a claim came from, so that you can judge the source. The outward reading in lesson 2 and the critic in lesson 6 do that judging.

Three kinds of record
WhatWhereWritten by
A mapping, proposals, a verdict, a result, a reportThe store, as a document registered in the catalog and linked to its sourceThe agent that produced it, when its work ends
A reading, a decision, a finding, the state of the workMemory, by project and titleThe reading agents and Claude, as they work and at the end of a session
A connection between two documentsThe catalog, as a typed linkIndexing and enrichment automatically. Claude or you, by hand

All three share one database and one credential. A memory entry can therefore name a catalog document, and a link can point at a chunk.

Topics

After a collection is indexed, the chunk embeddings are clustered into topics. Each topic gets a name, and every document is assigned to its nearest topic. The result is the topic map that nx taxonomy list --collection <COLLECTION> shows. Results that share a topic with the best match are ranked closer to it. A search can be limited to one topic with the topic argument of the search tool. nx taxonomy review goes through every topic and asks what to do with it. nx taxonomy hubs lists topics that appear in many collections. These are sometimes the central ideas of a project and sometimes generic words that need a new name.

Aspects

For a scientific paper, the store extracts a fixed set of structured fields at index time or later. The fields are the problem the paper addresses, the proposed method, the datasets, the baselines, and the main result. Each record has one confidence value. Questions such as "which papers used dataset X" or "group the papers by baseline" run against these fields directly. The filter, group-by, and aggregate operators use that fast path when the fields exist and read the text when they do not. The search_aspect_scoped tool applies a field condition inside the same query as the vector search. A strict filter then does not lose results the way "search first, filter after" does.

What you see
search_aspect_scoped  query: retrieval payload compiled claims versus chunks
                      field: experimental_datasets   pattern: %MediaSum%
[knowledge__dt-papers__voyage-context-3__v1] 1.12.119 …
  … What is new here is compiling the payload the reader consumes, and validating it against
  the span it came from. Proposition-level indexing [3] decomposes passages into standalone
  propositions and indexes those …
Sections and projections

Every chunk carries a section label. For prose it is abstract, introduction, related work, methods, results, discussion, conclusion, references, acknowledgements, appendix, or other. For code it is class, method, or imports. The label is a filter: nx search "<QUESTION>" --where section_type!=references keeps bibliography chunks out of a result. A projection applies the topic map of one collection to another. A code chunk can then be found under the topic names of the documentation for the same repository. nx taxonomy audit reports how well a projection fits.

Where research work ends
OutcomeForm
A report or a briefingA rendering for a named reader: what was asked, what the sources say, what was checked, what is open
A precisOne condensed document per source, linked to what it condenses
A test designThe pre-registration paragraph and the harness plan from lesson 7
A decision to buildA design record whose research section is the mapping, verdict, and result already written (Working with RDRs)
A confirmed decisionThe mapping, marked with its disposition, linked to the paper and to the record it confirms
A parked explorationThe brainstorm and the landscape document, marked as exploration, with a decision line and an owner
A lesson about methodA memory entry, or a findings document in a methods collection