Skip to main content
Troubleshooting · graph

Use when

Two entities that are already in the Graph describe the same thing, and each holds some relationships, properties or citations.

Looking for something else?

An item in a workspace that repeats a Graph entity (problem An extraction found an entity the Graph already has). Two entities that may be different things (problem Two entities have the same name).

​
Signs

  • A search returns two entities of one type for one thing, with different ids.
  • Each entity has some of the relationships that the one thing should have.
  • A read of one entity misses a fact, a relationship or a citation that the other holds.

​
Why it happens

Each entity has its own id, relationships and citations. Penumbra keeps no tie between two entities, so it does not know they are one thing. A repeat of capture or extraction, with no search first, makes the second entity.

​
What Penumbra does

By itself:
  • Deletes an entity softly. The entity keeps its history, and you can restore it by id.
  • Deletes the relationships that touch the entity with it.
  • Restores the entity only, with no approval wait. It does not bring back the relationships.
  • Keeps the stored citations of a deleted entity. read with entity:<id> still shows its last properties and citations, marked deleted.
  • Holds a delete made with an API key or as a connected agent until an owner or admin approves it. A person’s own session does not wait.
You must:
  • Choose the entity to keep, and write down what the other holds.
  • Stage a new relationship on the kept entity for each one you keep.
  • Carry over the properties and citations you want, then delete the other entity.
  • Check each part.
Not handled:
  • No merge operation exists in the CLI, the MCP tools, the Program methods or the SDK.
  • No operation moves a relationship to another entity, because its ends never change.
  • Penumbra does not copy properties, citations or times from one entity to the other.
  • Nothing sends the id of the deleted entity to the kept one.

​
Do

  1. Confirm the two are one thing (problem same-name-two-entities).
  2. Follow recipe resolve-duplicates. It stages the new relationships, carries over properties and deletes the extra entity in one workspace.
  3. If a delete waits for approval, give the person the approval URL and stop (problem change-waits-for-approval).

​
Don’t

  • Don’t delete the extra entity before you stage its relationships on the kept one. The delete removes them, and a restore does not bring them back.
  • Don’t name the ends of the new relationships by name. Duplicates make a name fail with node_ambiguous. Use ids.
  • Don’t tell the person it is merged until you have checked each part below.
  • Don’t send the delete again while it waits (problem change-waits-for-approval).

​
Check

  1. The kept entity has each relationship you listed: penumbra graph edges --node <kept-id> --direction both.
  2. The kept entity has each property you carried over: penumbra graph get <kept-id>.
  3. The kept entity lists the Files you cited: penumbra context entity <kept-id> --json.
  4. The extra entity is deleted: penumbra graph get <extra-id> prints a deleted: line.
  5. A search by the name returns the kept entity only: penumbra graph search "<name>" --type <Type>.
Recipe resolve-duplicates. Card rules entity.3, entity.4, relationship.4, relationship.6 and relationship.8. Problem same-name-two-entities. Problem extraction-duplicates-existing-entity. Problem change-waits-for-approval.

​
Keep going

Entity · Relationship · Workspace · Approval · Make two entities one · Two entities have the same name · An extraction found an entity the Graph already has