Deleting data

The knowledge graph stores memories at three levels: edges (one fact each), nodes (an entity — a person, habit, or topic — that facts connect to), and episodes (the raw ingested source text). Deletion works at matching levels, and each level has a different blast radius. This page covers all of them, including what each delete deliberately leaves behind.

All deletes are hard deletes — the data is removed from the graph database and the search overlay, not flagged. There is no undo. (System-side fact invalidation — when a new fact contradicts an old one — is a separate, soft mechanism and is not affected by anything on this page.)

Delete an edge

One edge carries one fact. Deleting the edge deletes the fact.

DELETE https://your-tie-host/memories/{agent_id}/edges/{edge_id}
Authorization: Bearer $TOKEN

Response:

{
  "status": "deleted",
  "edge_id": "edge-abc123"
}

Deleting an edge never deletes the nodes at either end. A node whose last live edge is deleted stays in the graph but disappears from the timeline (entities with zero live edges are not rendered).

The lookup is scoped to the calling user, not to agent_id — you don’t need to know which agent produced the fact, and one user can never delete another user’s data.

Delete a node

Deletes an entity and every edge connected to it, in both directions — the card-level “forget this topic” operation. One call, atomic, instead of a client-side loop over the entity’s facts.

DELETE https://your-tie-host/memories/{agent_id}/nodes/{node_id}
Authorization: Bearer $TOKEN

Response:

{
  "status": "deleted",
  "node_id": "node-def456",
  "facts_deleted": 7
}

facts_deleted counts the removed edges — log it so deletions are verifiable. The node’s search-overlay row (name, summary, embedding) is removed along with the edge rows, so nothing about the entity keeps surfacing in retrieval.

Error cases:

Three kinds of node are protected and always return 422:

• The user’s own User node — it anchors every relationship in the graph.
• Topic nodes — abstract subject areas (“fitness”, “AI”) used for organization.
• Value nodes — taxonomy scaffolding, not memories.

Clear all memories

Erases everything in one scope — a user+agent pair, or a whole graph namespace: edges, nodes, and episodic source content, from both stores. This is the one true erase and the right backend for a “delete all memories” button or a data-removal request.

POST https://your-tie-host/memories/{agent_id}/clear
Authorization: Bearer $TOKEN

Response:

{
  "status": "cleared",
  "scope": "user",
  "deleted_count": 42
}

scope names what was actually cleared — "user" for a pair, or "graph" plus a graph_id field for a namespace — so a caller can verify the blast radius before trusting a deleted_count. A clear of an already-empty scope succeeds with deleted_count: 0.

What edge and node deletes do NOT remove

Edge and node deletes remove derived knowledge. They deliberately do not touch episodes — the raw source text (chat exchanges, ingested documents) the knowledge was extracted from. Two consequences worth designing for:

1. The source remains stored. If your product’s delete must also erase the underlying record, use clear (everything) or delete the source conversation through your own retention flow. Per-episode deletion is not currently exposed.
2. Deleted knowledge can be re-learned. If a later conversation or ingest states the same information again, extraction recreates the entity and its facts. For conversational input this is expected (a user who re-tells you about their cat wants the cat remembered). For batch ingestion this is a trap: pushing a cumulative summary through POST /memories/graph every day restates old information and resurrects whatever the user deleted, usually within a day. Ingest deltas — only what’s new — and deletions stick.