Skip to documentation
eli.aidocs

Atlas

Entity review & merge

A knowledge base accumulates duplicates: "Acme Corp", "Acme", and "ACME Corporation" are one company; "John:" speaker labels in three transcripts may be three different people. The implemented review inbox surfaces likely duplicate pairs, and every merge it applies is a non-destructive pointer with an undo record. This page covers the queue, the merge mechanics, and why canonical_relations is the only edge table read at serve time.

The review queue

The current inbox runs one workspace-scoped query: live, unmerged entities of the same type whose normalized names have PostgreSQL trigram similarity above 0.35. It ranks those pairs and hydrates both entity cards:

  • Merge candidates — entity pairs that look like the same real-world thing (normalized name match), each shown with type, aliases, mentions, and source-document context.

Dismiss is not durable

Dismiss removes a pair from the current client state only. There is no persisted candidate-rejection record, so the pair can reappear after reload. Fact-level rejection_tombstones are honored by extraction services, but this merge inbox does not create them.

Why queue instead of auto-merge

In a consulting KB, over-merging is worse than a visible duplicate: collapsing two same-named people across business units invents relationships that were never in the source. The queue makes the model's uncertainty a reviewable decision rather than an irreversible mistake.

Non-destructive merges

Merge is a durable pointer with undo; dismiss is currently local UI state.

Merging is a pointer, never a rewrite. In one transaction the loser entity gets a merged_into pointer, its canonical_id repoints, its aliases repoint tagged with the merge_log id, and a log row records the actor and the evidence. No mention text is destroyed and no source document is touched.

  1. Confirm the match

    The queue shows both entities side by side with their mentions, aliases, and the evidence for the match. You pick the canonical survivor.

  2. Apply the merge

    The pointer, alias repoint, and log row commit atomically, then canonical_relations is rebuilt for the affected entities so edges de-duplicate immediately.

  3. Undo any time

    Because every mention carries link provenance, undo is lossless: clearing the pointer, retracting merge-tagged aliases, and rebuilding affected canonical relations restores the separated identities without rewriting source documents.

canonical_relations: the serve-time edge table

Merges, extraction, and manual graph changes all converge on one materialized aggregate, canonical_relations. It is the onlyedge table read at serve time — by retrieval's graph channel, the graph explorer, and the agent's kb_graph_query tool. Raw mention-level rows are never queried live. That indirection is what makes a review action instantly visible everywhere: the moment a merge commits and the aggregate rebuilds, every reader sees canonical entities and de-duplicated edges without any consumer knowing a merge happened.

Provenance survives the merge

Post-merge, the canonical entity still traces every fact back to its original relation_evidence (quote + offsets) and every alias back to the mention that introduced it. Merging consolidates identity without losing the paper trail.

Related