Memory/Session graph lifecycle telemetry + retention policy
Current Verified State (2026-06-03)
Live V-B-A refreshed this ticket against current source and issue state:
- Parent #10143 is closed and left #10158 as the residual AC4 lane for Memory/Session graph storage-growth observability and retention policy.
HealthService.healthcheck() already exposes migration observability under migration and Chroma migration debt after connection checks. It does not expose the graph lifecycle telemetry this ticket asks for: Memory/Session node counts, Memory/Session incident edge counts, or SQLite on-disk size.get_rem_pipeline_state already exposes REM pipeline freshness axes: undigested, digested, sessionNodes, topologyConflicts, recent cycle state, and optional per-session entity count. #10158 must not duplicate that MCP surface; it should add lifecycle/storage telemetry to healthcheck.GraphService.getOrphanedNodes() explicitly protects MEMORY and SESSION labels from orphan pruning regardless of edge state.GraphMaintenanceService.runGarbageCollection() deletes only nodes returned by GraphService.getOrphanedNodes() and then best-effort purges matching graph vectors. Therefore Memory/Session retention semantics must not be changed casually by broadening apoptosis.learn/agentos/DreamPipeline.md still describes vector apoptosis as deleting orphaned graph nodes. The retention policy doc must preserve the current distinction: Memory/Session nodes are durable provenance anchors, not ordinary orphan candidates.- No open duplicate/successor was found in the live issue search for this exact Memory/Session graph lifecycle telemetry scope.
Problem
Memory and Session nodes are now first-class graph citizens. We have REM freshness observability and migration-debt observability, but not graph lifecycle/storage telemetry for these provenance anchors.
Without a cheap operator-facing payload and explicit retention policy, future agents can only discover graph growth after a storage or query-performance incident. Conversely, adding archival/default-query hiding before telemetry would be premature and risks breaking provenance, mailbox, and memory-recovery paths that depend on durable MEMORY / SESSION anchors.
Accepted Scope
- Add cheap Memory Core healthcheck telemetry for Memory/Session graph lifecycle state.
- Document the retention policy for Memory/Session graph nodes.
- Record an initial baseline from the first post-implementation healthcheck/run evidence.
Contract Ledger
| Surface |
Contract |
| Healthcheck payload |
Extend HealthService.healthcheck() with a top-level graphLifecycle block. Required keys: available, memoryNodes, sessionNodes, memoryIncidentEdges, sessionIncidentEdges, sqliteBytes, sqliteWalBytes, sqliteShmBytes, measuredAt, and optional error. Counts are deployment-wide unless a future tenant-scoped ticket adds per-user slicing. |
| Count semantics |
memoryNodes / sessionNodes count rows in SQLite Nodes where json_extract(data, '$.label') is MEMORY / SESSION. Incident-edge counts count SQLite Edges whose source or target is a node with the corresponding label. |
| SQLite size semantics |
Use the configured SQLite graph storage path (GraphService.db.storage.dbPath) when available. sqliteBytes is the main database file size; sqliteWalBytes and sqliteShmBytes report sibling -wal / -shm file sizes when present, otherwise 0. If the graph DB is not mounted, return available: false with zero counts rather than throwing. |
| REM surface boundary |
Do not add this to get_rem_pipeline_state. That MCP tool remains REM freshness/yield telemetry. #10158 adds lifecycle/storage telemetry to healthcheck. |
| Retention policy doc |
Add learn/agentos/MemorySessionGraphLifecycle.md (or an adjacent accepted Agent OS guide path if implementation finds a better sibling). It must state that MEMORY and SESSION remain protected from GraphService.getOrphanedNodes() / vector apoptosis by default, explain why they are durable provenance anchors, and define the evidence required before any future archival mechanism is introduced. |
| Baseline evidence |
The PR body must include one captured healthcheck.graphLifecycle payload or unit-equivalent evidence and record the baseline in the retention policy doc. |
| Archival mechanism |
Out of scope for this ticket. Do not add archivedAt, default-query exclusion, or an archival sweep here. If telemetry later proves retention pressure, create a follow-up ticket with a separate Contract Ledger for marker names, reversible semantics, include-archived query behavior, and tenant/user visibility. |
| Hard deletion |
Out of scope. Hard deletion of Memory/Session graph nodes remains forbidden unless a future ticket proves safety against memory recovery, mailbox threading, provenance, and agent identity edge creation. |
Acceptance Criteria
Out of Scope
- Automatic pruning or archival sweeps.
- Default-query exclusion for archived Memory/Session nodes.
- Hard deletion of Memory/Session nodes.
- Chroma-side storage telemetry beyond the SQLite graph lifecycle sizes listed above.
- Cross-tenant retention slicing.
Related
- Parent: #10143
- Siblings: #10151, #10152, #10153
- Retention-sensitive source surfaces:
GraphService.getOrphanedNodes(), GraphMaintenanceService.runGarbageCollection(), HealthService.healthcheck(), get_rem_pipeline_state, learn/agentos/DreamPipeline.md
Origin Session ID: 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5
Memory/Session graph lifecycle telemetry + retention policy
Current Verified State (2026-06-03)
Live V-B-A refreshed this ticket against current source and issue state:
HealthService.healthcheck()already exposes migration observability undermigrationand Chroma migration debt after connection checks. It does not expose the graph lifecycle telemetry this ticket asks for: Memory/Session node counts, Memory/Session incident edge counts, or SQLite on-disk size.get_rem_pipeline_statealready exposes REM pipeline freshness axes:undigested,digested,sessionNodes,topologyConflicts, recent cycle state, and optional per-session entity count. #10158 must not duplicate that MCP surface; it should add lifecycle/storage telemetry to healthcheck.GraphService.getOrphanedNodes()explicitly protectsMEMORYandSESSIONlabels from orphan pruning regardless of edge state.GraphMaintenanceService.runGarbageCollection()deletes only nodes returned byGraphService.getOrphanedNodes()and then best-effort purges matching graph vectors. Therefore Memory/Session retention semantics must not be changed casually by broadening apoptosis.learn/agentos/DreamPipeline.mdstill describes vector apoptosis as deleting orphaned graph nodes. The retention policy doc must preserve the current distinction: Memory/Session nodes are durable provenance anchors, not ordinary orphan candidates.Problem
Memory and Session nodes are now first-class graph citizens. We have REM freshness observability and migration-debt observability, but not graph lifecycle/storage telemetry for these provenance anchors.
Without a cheap operator-facing payload and explicit retention policy, future agents can only discover graph growth after a storage or query-performance incident. Conversely, adding archival/default-query hiding before telemetry would be premature and risks breaking provenance, mailbox, and memory-recovery paths that depend on durable
MEMORY/SESSIONanchors.Accepted Scope
Contract Ledger
HealthService.healthcheck()with a top-levelgraphLifecycleblock. Required keys:available,memoryNodes,sessionNodes,memoryIncidentEdges,sessionIncidentEdges,sqliteBytes,sqliteWalBytes,sqliteShmBytes,measuredAt, and optionalerror. Counts are deployment-wide unless a future tenant-scoped ticket adds per-user slicing.memoryNodes/sessionNodescount rows in SQLiteNodeswherejson_extract(data, '$.label')isMEMORY/SESSION. Incident-edge counts count SQLiteEdgeswhosesourceortargetis a node with the corresponding label.GraphService.db.storage.dbPath) when available.sqliteBytesis the main database file size;sqliteWalBytesandsqliteShmBytesreport sibling-wal/-shmfile sizes when present, otherwise0. If the graph DB is not mounted, returnavailable: falsewith zero counts rather than throwing.get_rem_pipeline_state. That MCP tool remains REM freshness/yield telemetry. #10158 adds lifecycle/storage telemetry to healthcheck.learn/agentos/MemorySessionGraphLifecycle.md(or an adjacent accepted Agent OS guide path if implementation finds a better sibling). It must state thatMEMORYandSESSIONremain protected fromGraphService.getOrphanedNodes()/ vector apoptosis by default, explain why they are durable provenance anchors, and define the evidence required before any future archival mechanism is introduced.healthcheck.graphLifecyclepayload or unit-equivalent evidence and record the baseline in the retention policy doc.archivedAt, default-query exclusion, or an archival sweep here. If telemetry later proves retention pressure, create a follow-up ticket with a separate Contract Ledger for marker names, reversible semantics, include-archived query behavior, and tenant/user visibility.Acceptance Criteria
HealthService.healthcheck()includesgraphLifecyclewith the payload keys and fallback semantics above.learn/agentos/MemorySessionGraphLifecycle.mddocuments Memory/Session retention policy and explicitly preserves the currentgetOrphanedNodes()protection.get_rem_pipeline_state, default graph query visibility, or graph apoptosis pruning behavior.Out of Scope
Related
GraphService.getOrphanedNodes(),GraphMaintenanceService.runGarbageCollection(),HealthService.healthcheck(),get_rem_pipeline_state,learn/agentos/DreamPipeline.mdOrigin Session ID: 71dc3cd8-d39d-48e1-ac62-e240ca67d1a5