We gave our research agent a glossary it builds from your papers, not the dictionary

Here is a failure that does not look like a failure. A user asks the agent about "agency" in a corpus of social-science papers. Retrieval works fine: it finds plausible passages, the citations are real, the synthesis reads well. And it is quietly wrong, because the corpus uses "agency" in two senses, a sociological one and an organizational one, and the synthesis blended them into a single paragraph that no author would endorse.

This is not hallucination in the usual sense. The evidence exists and the citations are honest. The problem is upstream: retrieval did not expose the right evidence. Treating a term as a stable string misses passages that use a synonym and hides cases where the same word appears in distinct conceptual neighborhoods.

We added a small terminology graph as a query-time layer to address that evidence-gathering problem. It brings relevant passages and co-occurrence evidence into the live query, where the agent can interpret them against the specific problem the user asked it to solve. A companion post explains how the graph is built. This post is about the other half: how the design gets the right evidence to the agent without deciding in advance what that evidence means.

A term is not a definition, it is a problem statement

The standard advice for term ambiguity in retrieval is to fix it with embeddings and hope dense vectors capture sense. They partly do, and they partly do not. The known blind spots of dense retrieval are exactly polysemy, domain-specific jargon, and words whose meaning shifts with context. Practitioners working on polysemy and entity ambiguity in RAG keep arriving at the same conclusion: the embedding alone does not disambiguate, and you need some extra structure at indexing time or query time to do it.

Academic vocabulary is the hard case. Terms are local to a subfield, they drift over decades, they split into narrower concepts, and parallel communities use different words for the same construct. A model's general knowledge is useful, but it cannot replace evidence from the user's corpus when one literature uses a term in a narrower or contested sense.

So the unit the agent should reason about is not "the definition of X." It is "how does this corpus use X, and what does it use it alongside?" The graph gathers the evidence needed to answer that question. The agent resolves the meaning against the user's specific problem.

The glossary is evidence with receipts

The terminology graph gives the agent a lookup tool that returns corpus-relative evidence for each term. Not a definition. The tool surfaces the term's top supporting passages, ranked by how substantively each passage discusses it, plus its strongest co-occurring neighbors and the passages behind those connections. Shaped roughly like this:

{
  "results": {
    "<kb_id>": [{
      "term": "agency",
      "matched": true,
      "context": {
        "display_form": "agency",
        "node_paper_count": 14,
        "supporting_chunks": [
          {"content_id": "...", "chunk_id": "...", "information_score": 0.91}
        ],
        "neighbors": [
          {"term": "structure", "edge_paper_count": 9, "supporting_chunks": [...]},
          {"term": "habitus",   "edge_paper_count": 6, "supporting_chunks": [...]}
        ]
      }
    }]
  },
  "chunks": { "<chunk_id>": { "text": "...", "page_range": "12-14", "...": "..." } }
}

The neighbors guide evidence gathering, not interpretation. If "agency" appears near "structure" and "habitus," the graph points the agent toward passages that may support a sociological reading. If it appears near "principal" and "incentive," it points toward a different body of evidence. The graph does not label either sense. The agent compares the passages and decides what they mean for the user's question.

Every entry resolves to a real passage at a real page. That is the whole point of the "with receipts" framing. The graph never hands the agent a generated glossary paragraph to trust. It hands it passages to read.

Why evidence and not a definition

This is the core engineering decision, and it is a decision against a tempting shortcut.

The shortcut is to precompute one definition per term and inject it. It is cheaper at query time and it demos well. It is also wrong whenever the right sense depends on the question, which for a contested term is most of the time. Freezing a single global definition is the exact mistake that caused the blended-"agency" paragraph at the top of this post, just moved one layer earlier.

By returning supporting passages and neighbor evidence instead, resolution happens live. The graph gets the agent quickly to the passages most likely to matter. The agent can then compare contexts, investigate contradictions, and read the underlying pages when the initial evidence is thin. Meaning is resolved against the current query, not against a guess encoded earlier.

The design keeps the graph's analysis deliberately narrow. It reports co-occurrence and traces every connection back to passages, without declaring that two terms are synonymous, equivalent, opposed, or causally related. This avoids inserting a semantic judgment into the evidence-gathering layer.

There is a useful distinction that any honest evaluation has to respect: synonym recall and sense disambiguation are two different jobs. The graph helps with the first by surfacing neighbor terms and passages that string matching or embedding retrieval missed. It enables the second by gathering the evidence the agent needs to distinguish senses in context. Finding more relevant passages is not the same as correctly separating two senses, and a benchmark that measures only the first will flatter the system.

The lookup belongs to routing and research, not editing

Where in the agent loop the tool is available is a deliberate boundary, and it maps onto what each role is for.

Terminology lookup is available only where meaning affects how a request is understood or how evidence is retrieved. It helps the system recognize specialized language, clarify ambiguous terms, and connect findings to the right concepts. By the time those findings are added to the mindmap, that interpretation should already be settled. Reopening it during writing would blur the line between understanding the evidence and presenting it.

The tool also has a hard gate. If no terminology graph has been built for the project's knowledge bases, the tool short-circuits and tells the agent so, rather than failing or pretending:

if context.has_terminology_graphs is False:
    return ("term_enrichment_tool is unavailable because no co-occurrence "
            "graph has been built for this project's knowledge bases")

And it respects the same corpus scoping the rest of retrieval uses. If the user has pinned a tag filter, terminology lookups are pruned to that same subset of documents, so the supporting passages, neighbors, and counts only reflect the corpus the user actually pointed at. A term that is absent from the filtered subset comes back unmatched, which is the correct answer, not an error.

The cost guard matters as much as the graph

Terminology support is useful only when its cost remains proportional to the research task. Building and consulting a corpus-specific graph takes computation, so Agent Bayes does both selectively. Terminology data is prepared when the feature is used, rather than adding work to every document by default, and the graph is consulted only when a term genuinely benefits from corpus context.

The costly extraction stage is also incremental. When papers are added to a knowledge base, the next rebuild extracts terminology only from papers that have not been processed before. It then regenerates the graph so the new evidence can add terms and change the relationships among terms already present. As explained in the companion post on building the graph, adding ten papers to a 200-paper knowledge base means paying for extraction on ten, not 210.

That distinction matters. Familiar names and routine editing requests rarely need terminology resolution. Terms such as "resilience," "agency," or "culture" often do, because their meaning can shift across disciplines and collections. The system avoids unnecessary or repeated work, keeping the additional effort focused on cases where the graph can improve evidence gathering.

Lookup time can still vary depending on whether the relevant terminology data is readily available. We design repeated access to be efficient without pretending that every request has the same cost or latency. The principle is simple: spend the additional computation only when corpus-specific meaning is likely to change the answer.

Co-occurrence is a clue, not a truth predicate

I keep coming back to this because it is the line between a useful tool and an oversold one.

A neighbor edge means two terms are discussed together in this corpus. The graph's truth claim is deliberately narrow: these terms co-occurred in these passages. It does not mean they are conceptually related. Co-occurrence merges polysemes when one word carries two senses. It produces dense, useless stars around generic terms. It manufactures false proximity when a sentence merely lists two things. The information score is the main defense, since a bare list scores low and a real discussion scores high, but it is a defense, not a guarantee.

So the agent's reasoning after a lookup is not "the graph said X, therefore X." The graph has already done the specialized work of finding supporting passages and relevant neighbors. The agent reads that evidence, uses it to confirm or refine the sense, and reads further when the evidence is insufficient.

There is also a limit worth stating plainly. Cross-language term linking remains a known limitation worth tackling. For now, multilingual term search can look for a term both in the language it appears in and in translation. That may be sufficient to surface the relevant evidence, but it is not guaranteed to connect equivalent terms reliably across languages.

What it buys

The right way to think about this layer is small and specific. It is not "graphs improve RAG." It is: a small, evidence-backed terminology graph can gather the corpus evidence an agent needs to resolve terminology during a live query. It finds the supporting passages and relevant co-occurrences quickly, while keeping every connection inspectable and making no claim that co-occurrence equals meaning.

The good cases look like this. The graph surfaces passages across a synonym variant that plain retrieval missed. It gathers distinct bodies of evidence for two senses that would otherwise have been blended. It reveals when support is sparse. The agent then interprets that evidence for the user's problem and decides what belongs in the answer.

The design assumes the agent can reason over evidence. The engineering work is to gather the right evidence quickly without encoding a semantic conclusion that could bias that reasoning. As agents improve, the same passages and truthful co-occurrence analysis remain useful. The terminology tooling in Agent Bayes is our version, built per knowledge base and available to the agent once a graph exists. The test I would apply to any version, ours included, is whether it finds the evidence behind both senses of an overloaded term without quietly choosing one in advance.