Graph expansion & topic re-entry

Control how semantic topic seeds expand through the graph and how returned subjects connect to earlier conversation topics.

Topic graph roles

Temporal edges link adjacent topics.

Semantic edges connect similar topic nodes.

Reentry edges connect a later return to an earlier related subject.

Grafted edges preserve relationships to copied source topics.

Semantic seed selection

graftByRelevance() embeds the query and selects similar topic nodes. Those seed nodes are then passed to the same graft assembly path used for explicit topic IDs.

Expansion controls

topK limits semantic seed topics.

minSimilarity filters weak topic matches.

hopDepth controls neighbour traversal distance.

expansionStrategy: none formats only seed topics.

expansionStrategy: graph includes reachable neighbours within the hop depth.

graph-expansion.ts

const context = await agent.graftByRelevance("database reliability", {
  topK: 4,
  minSimilarity: 0.6,
  hopDepth: 1,
  expansionStrategy: "graph",
});

Topic re-entry

A conversation may discuss databases, switch to authentication, and later return to connection pooling. Reentry detection links the later database topic back to the earlier one instead of merging or rewriting either historical segment.

Original topic

Different topic

Return to subject

Reentry edge

Reentry configuration

reentryDetection enables or disables reentry linking and defaults to enabled.

reentryThreshold controls the required embedding similarity and defaults to 0.85.

Reentry can connect new nodes to durable earlier nodes or to earlier segments in the same ingestion run.

Tradeoffs

Higher hop depth can recover useful context but increase distraction and prompt size.

Seed-only expansion is easier to reason about for user-selected topics.

Semantic similarity does not imply authorization; scope the source graph first.

Evaluate graph expansion using downstream answers, not only visually plausible neighbours.