Repository navigation
Description
Problem or Use Case
When a session ends abruptly — power loss, kill -9, OOM kill, Docker container restart without graceful shutdown, laptop sleep, SSH disconnect — the SessionEnd hook never fires. As a result:
- Session stays
status="active"forever in the store - No graph extraction, compression, or consolidation runs for that session's observations
- The stale-sweep (
mem::evict) eventually deletes the entire session withreason: "stale_session_without_summary"— all observations are permanently lost - The session's
endedAtis never set, so there's no way to distinguish "still active" from "abandoned"
This is a known design issue (#308) with extensive discussion but no complete solution shipped as of v0.9.24. PR #387 added partial protection (extract before evict) but doesn't address the root cause.
Specific Use Case: Hermes Agent in Docker
Hermes Agent runs in a Docker container. When the host machine shuts down, the container is stopped via docker stop (SIGTERM) or killed abruptly. The Hermes gateway catches SIGTERM and calls on_session_end, but:
- If SIGKILL is used, or power is lost, no cleanup happens
- Even with SIGTERM, async hook work can be killed before completion (anthropics/claude-code#415777)
- Historical JSONL transcripts exist on disk (Hermes saves them automatically) but cannot currently be re-imported after the fact because
import-jsonlonly supports Claude Code format (separate issue)
What We Want
Part A: Abandoned Session Detection and Recovery
A backend process (or CLI command) that:
- Detects abandoned sessions: finds sessions with
status="active"andupdatedAtolder than a configurable threshold (default: 4 hours) - Runs the full session-end pipeline on them:
- Triggers
event::session::stopped(graph extraction, slot reflection) - Runs the consolidation pipeline (compress, extract lessons, build crystals)
- Sets
status="completed"andendedAttimestamp
- Triggers
- Logs the action to the audit trail
CLI interface:
# On-demand: find and recover abandoned sessions
agentmemory reap --threshold=4h
# Background daemon mode (configurable interval)
agentmemory reap --daemon --interval=3600000Configuration:
AGENTMEMORY_REAP_THRESHOLD_MS=14400000 # 4 hours, default
AGENTMEMORY_REAP_INTERVAL_MS=3600000 # 1 hour, 0 = disabledPart B: Post-Restart Session Reconciliation
When agentmemory daemon starts up (especially after container restart):
- Scan for sessions with
status="active"that haveupdatedAtolder than threshold - For each, run the session-end pipeline as in Part A
- Log recovered sessions to audit trail
Part C: Viewer and Diagnostics
- In the AgentMemory viewer (port 3113), show a banner: "N abandoned sessions detected" with a "Reap now" button
- In
doctoroutput, warn about abandoned sessions:⚠ 3 sessions abandoned (>4h since last activity) - In
memory_diagnose, includeabandoned-sessionscheck with actionable output
Scope
Medium-Large. Parts A and B are independently shipable. Part C depends on A/B.
Existing Work
- Sessions never end on crash/SSH-drop/Ctrl-C — graph extraction + consolidation silently skipped, then evicted #308 — design discussion (open)
- Codex Stop hook does not mark sessions ended #493 — Codex Stop hook lifecycle (fixed via fix(hooks): stop also closes session for Codex (closes #493) #579)
- PR fix: recover stale sessions before eviction #387 — extract before evict (partial fix merged)
- PR fix(cli): add --data-dir flag + AGENTMEMORY_DATA_DIR so engine state lives outside repos #314 — data-dir relocation (related, fixed)
Activity
rohitg00 commentedon Oct 8, 2026
@Songraf v0.9.30 adds the detection half: an hourly sweep marks sessions abandoned after
AGENTMEMORY_SESSION_SWEEP_STALE_HOURSwithout deleting anything. Backfill of abandoned sessions is not included. https://github.com/rohitg00/agentmemory/releases/tag/v0.9.30