feat: adaptive sleep advisory — memory-health-driven scheduling hints (Sprint F)

[salishforge]

Summary

ROADMAP Phase 2 adaptive sleep scheduling. Completes Phase 2.

MemForge is intentionally designed without a built-in scheduler (CLAUDE.md architectural rule). This PR instead exposes a read-only advisory that external orchestrators (cron, control plane, dashboards) can use to decide when to trigger a sleep cycle.

`MemoryManager.sleepAdvisory(agentId)` signals

Signal	Source	Semantics
`hot_backlog`	`count(hot_tier)`	Raw, un-embedded, non-searchable events; draining is the primary sleep purpose.
`contradiction_rate`	`reflections.contradictions` last 30d	Rising contradictions signal knowledge drift → Phase 2.5 conflict resolution needed.
`revision_debt`	warm rows with `confidence < 0.4`	Low-confidence rows need Phase 3 LLM revision.
`time_since_last_sleep`	`agents.last_sleep_cycle` (v2.4)	Periodic maintenance when any activity has occurred.
`stability` (inverse)	`graduated / warm_count`	High stability → frequent sleep is wasted LLM spend; clamps overall urgency down.

Overall urgency = max of the four active signals, then clamped to `'low'` if stability ceiling exceeded. `recommended = urgency >= 'medium'`.

Thresholds (all tunable via env)

• `SLEEP_ADVISORY_HOT_BACKLOG_LOW` / `MEDIUM` / `HIGH` = 25 / 100 / 500
• `SLEEP_ADVISORY_CONTRADICTION_HIGH` = 0.20 (0.10 medium, 0.05 low are inline)
• `SLEEP_ADVISORY_REVISION_DEBT_MEDIUM` = 50 (20 low)
• `SLEEP_ADVISORY_MAX_AGE_HOURS` = 24
• `SLEEP_ADVISORY_STABILITY_CEILING` = 0.80

Public surfaces

• `GET /memory/:id/sleep/advisory` (read-scoped)
• `memforge_sleep_advisory` MCP tool
• `sleepAdvisory()` on TS `MemForgeClient` + `ResilientMemForgeClient`
• `sleep_advisory()` on Python equivalents
• OpenAPI route documented with full response schema

No schema migration — all required columns already present.

Tests (`tests/sleep-advisory.test.ts`, 281 lines, 7 cases)

1. No activity → `'none'`, recommended false.
2. 600 hot rows → `hot_backlog` urgency `'high'`.
3. 2/10 reflections w/ contradictions (ratio 0.20) → urgency `'high'`.
4. 60 low-confidence warm rows → `revision_debt` urgency `'medium'`.
5. `last_sleep_cycle` 25h ago + activity → urgency `'medium'`.
6. 85/100 graduated + 600 hot → stability ceiling clamps to `'low'`.
7. Custom `hotBacklogHigh=50` override → 60 hot rows → urgency `'high'`.

All use explicit timestamps, no sleeps.

Test plan

• CI type-check / lint / build pass
• CI test-integration (Node 20 + 22) runs the new suite
• Existing sleep cycle + budgeting tests unaffected

Phase 2 scorecard (closed out after this merge)

• ✅ Memory namespaces (Memory namespaces/tags for content organization #16) — C.1 + C.2 (PRs feat(namespaces): memory namespaces backend — schema + MemoryManager + tests (Sprint C.1, #16) #100, feat(namespaces): propagate namespace through public surfaces (Sprint C.2, #16) #101)
• ✅ Cold tier search + restoration (Cold tier querying and restoration #14) — D (PR feat(cold-tier): search + restoration for audit/recovery (Sprint D, #14) #102)
• ✅ Memory budgeting — E (PR feat(sleep-cycle): memory budgeting — per-agent warm_tier hard cap (Sprint E) #103)
• ✅ Adaptive sleep scheduling — F (this PR)
• ✅ Per-agent scoring weights (Configurable importance scoring weights per agent #17) — shipped in v2.4 migration
• ⚠️ Multi-model revision (Multi-model revision strategy for sleep cycles #13) — basic plumbing already in place (REVISION_LLM_PROVIDER); "two-pass triage" variant deferred