Resolve duplicate entities

Entity resolution consolidates graph nodes that refer to the same real-world concept. Run the phases in order, review every non-mechanical proposal, and retain the automatic backup made before each applied phase.

For the rationale behind the phases and their confidence boundaries, see Entity resolution.

Execution status

Documentation CI strictly builds this page, but it does not execute these store-reading or store-mutating commands. Run and verify each phase manually against the intended local graph; semantic resolution can also download a model and make paid model calls.

The resolution tools target the repository store

The current graph backend and backup helpers operate on .cognee/ in the repository. Do not assume COGNEE_DATA_PATH retargets these commands. Confirm that .cognee/databases/cognee_graph_kuzu is the intended graph before applying a merge.

1. Preview exact duplicates

uv run python -m scripts.dedup_exact

Exact resolution groups names after lowercasing and stripping leading or trailing whitespace, then selects the highest-degree node as canonical. It does not normalize internal whitespace. Preview mode does not mutate the graph. Apply only after inspecting the listed groups:

uv run python -m scripts.dedup_exact --apply

The apply command snapshots the Kuzu graph under .cognee/backups/ before redirecting edges and deleting duplicate nodes.

2. Review fuzzy proposals

Generate rule-based candidates:

uv run python -m scripts.dedup_fuzzy

Review dedup_fuzzy_proposal.yaml. Remove false matches and verify every canonical node identifier. The proposal is the human approval boundary; do not apply the generated file blindly.

uv run python -m scripts.dedup_fuzzy --apply

3. Review semantic proposals

After exact and fuzzy cleanup, generate embedding candidates and ask the configured model to classify them:

uv run python -m scripts.dedup_semantic --threshold 0.75

This operation can download the embedding model and make paid model calls. Review dedup_semantic_proposal.yaml, especially pairs with broad or nested concept names, then apply the edited proposal:

uv run python -m scripts.dedup_semantic --apply

--skip-llm includes embedding candidates without model confirmation. It does not make the result safe to apply; it increases the importance of manual review.

4. Rebuild and inspect the alias registry

uv run python -m scripts.alias_registry build
uv run python -m scripts.alias_registry find "DDM"
uv run python -m scripts.alias_registry stats

The build command combines current graph nodes with retained fuzzy and semantic proposal files and writes data/alias_registry.yaml. Inspect and commit the registry when the resolved aliases are intended to become repository state.

Avoid --no-backup during normal operation. It exists for controlled tests and removes the recovery point that makes an applied merge reversible.