Skip to content

Deleting a memory

This guide explains how to remove a memory from Hadron — which path applies to which memory, what happens to the data, and what cannot be undone in MVP. For the underlying model (who owns what, why some memories cascade with their parent), see Memory ownership and lifecycle.

Target behavior — implementation rolling out alongside the user-installing-app spec

This page describes the target deletion model for MVP. Pieces are live today (the soft-delete columns, basic resolvers); the parent-cascade behavior and the reference-block check land alongside spec-kits #43. Today's portal still exposes a per-memory delete on all classes; treat that as transitional.

Which path applies

Memory deletion follows the ownership chain. You don't delete memories owned by an Agent or App directly — you delete the parent, and the parent's memories soft-delete with it.

If you want to delete... Delete via
An Agent's system memory The Agent's "Delete agent" affordance. System memory cascades with the Agent.
An App's app-mem, group-mem, app-user, or priv memory The App's "Uninstall app" affordance. All four roles cascade with the App.
A standalone knowledge-class memory (no Agent or App owns it) The memory detail page's "Delete memory" affordance. Direct soft-delete via Mutation.deleteMemory.

Deleting an Agent

On the Agent's detail page, the Danger zone at the bottom exposes "Delete agent." Confirming:

  • Soft-deletes the Agent.
  • Cascades soft-delete to the Agent's system memory.
  • Hard-deletes the Agent's AgentMemoryItem rows. The knowledge memories those rows referenced are untouched — they keep living in their owning org.

Blockers. An Agent cannot be deleted while any other Agent or App still references it. Concretely: live AppAgent rows (Apps that have installed this Agent) and live AgentImport rows (other Agents that have imported this one as a dep) block the delete. The rule applies across organizations — an install in another org keeps your Agent alive until that org uninstalls. If the delete is blocked, the error lists the blockers, and the foreign-org admin has to act on their side before yours can proceed.

Deleting (uninstalling) an App

On the App's detail page, the "Uninstall app" affordance soft-deletes the App and cascades soft-delete to all four App-owned memory roles: app-mem, group-mem:*, app-user:*, priv:*.

The Agent the App was built from is not affected. The blueprint outlives the house. Another org may have installed the same Agent; your uninstall doesn't touch their data.

There is no foreign-ref block on Apps — no entity references an App from outside, so an App is freely uninstallable from its owner's side.

Deleting a standalone knowledge memory

On the memory's detail page (/app/orgs/<id>/memories/<gid>), the Danger zone at the bottom exposes "Delete memory." This path applies only to knowledge-class memories owned directly by an Organization (no Agent or App in the ownership chain).

The interaction is two-step:

  1. Click "Delete memory" to reveal the confirmation row.
  2. Click "Yes, delete" to confirm — or "Cancel" to back out.

Blockers. The delete is rejected with a typed error if any live AgentMemoryItem row references the memory. You'll need to detach the memory from those Agents first (or soft-delete those Agents) before the delete can proceed. There is no force-delete path in MVP.

Who is authorized

Action Authorized
Delete an Agent Org admin on the Agent's owning org
Uninstall an App Org admin on the App's owning org
Delete a standalone knowledge memory Org admin on the memory's owning org
Delete a personal-class memory Cannot be deleted directly in MVP — priv:* memories soft-delete only when their owning App is uninstalled

If the affordance isn't visible to you, you don't have authority for that action. The server enforces the same rules; a manual HTTP request will be rejected.

Soft-delete and recovery

Deletion is soft: the row is preserved in the database with deletedAt and deletedBy set, but every read surface (search, listings, agent attachment pickers, blended-graph queries) filters it out. References from elsewhere resolve to a typed not-found error rather than crashing.

There is no recovery / undelete in MVP. Once soft-deleted, the memory stays gone from user-facing surfaces. There is no in-portal restore and no operator restore path. If you delete a memory by mistake, the data is recoverable only by direct database manipulation, which is not a supported operation.

There is also no auto-purge in MVP — soft-deleted rows accumulate indefinitely in the database. This is a known compliance gap and will be addressed via an ops-only hard-delete CLI before EU PII enters the system at scale.

What about nodes and edges inside the memory?

They're hidden along with the memory, automatically — read paths join through the parent memory's deletion state. Once the memory is soft-deleted, none of its nodes or edges appear in any list, search, or detail view.

See also