Entity retention
Understand which entities expire by observation time, which follow a parent, and which remain only while connected to the graph.
#Retention policies
Entities use one of four policies:
| Policy | Entity types | Collection rule |
|---|---|---|
| Observed | Channel, Document, Email, Folder, Message, Spreadsheet, Task, Video | Delete when observed_at (or created_at if never observed) is outside the retention window. |
| Owned | Gmail attachment Document entities | Delete with the parent Email. |
| Connected | Person | Delete when the Person has no incoming or outgoing edges. |
| Persistent | Configured RSS feed Folder entities | Never delete automatically. |
#Bookmarking
Bookmarking an entity protects it from being removed when it expires or when its parent is deleted.
#Expiration
The server runs expiration daily and applies the following rules:
- Bookmarked entities are never deleted
- Detach bookmarked children before deleting an expired parent.
- Delete observed-policy entities whose effective retention timestamp is outside the window; parent-linked Messages also cascade when their parent expires.
- Delete owned entities left without a parent, including detached attachments after they are unbookmarked.
- Delete connected-policy Persons that have no edges.
The retention period is controlled using AGENTGRAPH_RETENTION_DAYS, which defaults to 90 days.