---
title: "Merge two entity memories into one"
description: "New POST /memories/{agent_id}/merge endpoint collapses duplicate entity nodes (e.g. \"Fauzaan\" and \"Mohamed Fauzaan\") into a single node, repointing every live relationship at the primary."
date: 2026-05-04
tags: ["TIE AI Gateway"]
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge two entity memories into one

When the graph ends up with two entity nodes that represent the same real-world thing — `Fauzaan` and `Mohamed Fauzaan`, or `Acme` and `Acme Inc.` — you can now collapse them in one call:

```bash
POST /memories/{agent_id}/merge
{
  "primary_id": "node-uuid-keep",
  "duplicate_id": "node-uuid-fold-in"
}
```

## What it does

- Every live edge incident to `duplicate_id` is repointed at `primary_id`. The original edge is soft-deleted so the timeline is preserved for undo.
- The duplicate node is marked with `merged_into` and disappears from List Memories, Search, and the Memory Graph response.
- An `IS_DUPLICATE_OF` audit edge is written from duplicate → primary for traceability.
- The primary's `summary`, `attributes`, and `labels` are rewritten by the LLM to combine both records into one canonical view. Its `name` is kept as-is, so pick the more specific or canonical node as `primary_id`.
- LLM enrichment is best-effort — on a model outage the merge falls back to a blind rewire and the response sets `enriched: false`.

## Caveats

- **Edge fact text is not rewritten.** If an old edge said "Fauzaan likes tea", that text persists; only the endpoint pointer changes.
- **Duplicate facts are not deduped.** If both nodes had similar relationships, you will see two live edges. The next memory-ingestion pass usually collapses them.
- **Same-scope only.** Both nodes must share the same user and `agent_id`.

## Why this matters

Before this endpoint, the only way to recover from a misextracted entity was to delete every memory tied to it and let the graph rebuild over time — costly and lossy. Merge gives you a non-destructive fix that preserves history and stays reversible.

See [Merge Two Memories](/memory/building-uis/#merge-two-memories) for the full reference.

Source: https://truememory-docs.mvstg.com/changelog/tie-ai-gateway/2026-05-04-merge-memories//index.md