feat(recovery): add abandoned session reaper

.env.example

@@ -170,6 +170,10 @@
 # AGENTMEMORY_HIGH_ORDER_CONTEXT=false           # Opt out of semantic/procedural/crystal/insight context blocks and smart-search arrays. Unset follows CONSOLIDATION_ENABLED.
 # EVICTION_ENABLED=true                          # Run mem::evict on a timer. Default on; set false to disable scheduled eviction.
 # EVICTION_INTERVAL_MS=86400000                  # Scheduled mem::evict interval in ms. Default 24h.
+# AGENTMEMORY_REAP_ENABLED=true                  # Recover active sessions abandoned by abrupt process exits. Default on.
+# AGENTMEMORY_REAP_ON_STARTUP=true               # Run one background abandoned-session reconciliation at startup. Default on.
+# AGENTMEMORY_REAP_THRESHOLD_MS=14400000         # Inactivity threshold for recovery. Default 4h.
+# AGENTMEMORY_REAP_INTERVAL_MS=0                 # Optional periodic recovery interval in ms. Default 0 (disabled).
 # CONSOLIDATION_DECAY_DAYS=30                    # Age (days) after which non-reinforced memories decay during consolidation
 # GRAPH_EXTRACTION_ENABLED=true                  # Extract concept-graph edges on remember; powers the graph-traversal recall path
 # GRAPH_EXTRACTION_BATCH_SIZE=8                  # Memories per graph-extraction batch

AGENTS.md

@@ -118,7 +118,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).
 ## Current Stats (v0.9.28)
 
 - 61 MCP tools (8 visible by default, `AGENTMEMORY_TOOLS=all` for all)
-- 134 REST endpoints
+- 135 REST endpoints
 - 6 MCP resources, 3 MCP prompts
 - 12 hooks, 15 skills
 - 50+ iii functions

README.md

@@ -474,6 +474,7 @@ agentmemory stop               # tear it down
 agentmemory remove             # uninstall everything we created
 agentmemory connect claude-code   # wire one agent
 agentmemory doctor             # interactive diagnostics + fix prompts
+agentmemory reap --threshold 4h   # recover sessions abandoned by abrupt exits
 ```
 
 From v0.9.16 onward, the first npx run prompts you to install globally inline — answer `Y` once and you're set. If you skip, fall back to either of these for a fresh fetch:
@@ -505,6 +506,17 @@ For very large imports, set `AGENTMEMORY_IMPORT_TIMEOUT_MS` to raise the CLI's i
 
 > **Heads-up if you rely on `import-jsonl` as your primary capture path:** Claude Code's `cleanupPeriodDays` (in `~/.claude/settings.json`, default **30**) auto-deletes JSONL transcripts older than that window from `~/.claude/projects/`. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run `import-jsonl` on a cron, raise `cleanupPeriodDays` to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.
 
+### Abandoned Session Recovery
+
+If a host sleeps, crashes, OOM-kills the worker, or exits before the session-end hook fires, the worker now reconciles active sessions whose last activity is older than the recovery threshold. Startup runs one background reconciliation by default, and periodic recovery remains opt-in:
+
+```bash
+agentmemory reap --threshold 4h
+agentmemory reap --dry-run
+```
+
+Tune the daemon behavior with `AGENTMEMORY_REAP_THRESHOLD_MS=14400000`, `AGENTMEMORY_REAP_ENABLED=true`, `AGENTMEMORY_REAP_ON_STARTUP=true`, and `AGENTMEMORY_REAP_INTERVAL_MS=0`.
+
 ### Upgrade / Maintenance
 
 Use the maintenance command when you intentionally want to update your local runtime:
@@ -1799,6 +1811,10 @@ Create `~/.agentmemory/.env`:
 # AGENTMEMORY_HIGH_ORDER_CONTEXT=false  # opt out of semantic/procedural/crystal/insight context + smart-search arrays
 # EVICTION_ENABLED=true          # ON by default. Runs mem::evict on a timer.
 # EVICTION_INTERVAL_MS=86400000  # Default: 24h
+# AGENTMEMORY_REAP_ENABLED=true          # ON by default. Recovers sessions abandoned by abrupt exits.
+# AGENTMEMORY_REAP_ON_STARTUP=true       # Default: run one background reconciliation on daemon startup.
+# AGENTMEMORY_REAP_THRESHOLD_MS=14400000 # Default: 4h inactivity threshold.
+# AGENTMEMORY_REAP_INTERVAL_MS=0         # Default: periodic recovery disabled.
 # LESSON_DECAY_ENABLED=true
 # OBSIDIAN_AUTO_EXPORT=false
 # AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
@@ -1823,7 +1839,7 @@ Create `~/.agentmemory/.env`:
 
 <h2 id="api"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/section-api.svg"><img src="assets/tags/section-api.svg" alt="API" height="32" /></picture></h2>
 
-134 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
+135 endpoints on port `3111`. The REST API binds to `127.0.0.1` by default. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set, and mesh sync endpoints require `AGENTMEMORY_SECRET` on both peers.
 
 ### Health Thresholds