Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
Session Lifecycle Capture Durability β implementation plan
Branch: feat/session-lifecycle-capture-durability
Overall release scope (ships together in this single release):
t_c181f92bβ Capture interrupted sessions:on_session_end(interrupted=True)+ persisted transcript (#50004/#50003/#50312).t_3b8fe3a1β Verify memoryon_session_endfires on/exitnow native (#49315); drop any workaround.t_12c8b256β Post-compaction pinned-anchor survival audit and selective re-assertion.
Combined design: docs/brainstorm/session-lifecycle-capture-durability/design.md.
Full variant audit: docs/brainstorm/session-lifecycle-capture-durability/variants.md.
Drive these cards one at a time on the shared branch. Each worker MUST
git log and git status before editing, build on the commits previously-driven
in-scope cards already landed, and must not duplicate or conflict with sibling
tasks. Follow each section under TDD (write the failing test first).
Recommended drive order: t_c181f92b first (lands the interrupted field that
the other two reason about), then t_3b8fe3a1 (verification, smallest), then
t_12c8b256 (the new audit module, largest, builds on the pinned/continuity
substrate the first two also touch).
t_c181f92b β Capture interrupted sessions: on_session_end(interrupted=True) + persisted transcript
Files
plugins/hermes/provider.pysrc/core/brain/session-lifecycle.tssrc/cli/brain/verbs/session-hook.ts(typed access only; payload is read verbatim from stdin)- Focused tests under
tests/
Plan
- Add an optional
interrupted?: booleanfield toNormalizedPayload(session-lifecycle.ts), normalized from the host hook payload. Absent by default β when the host does not emit it, behaviour is byte-identical. - In
provider.py, surface theinterruptedkwarg fromon_session_end(**_kwargs) onto the hook payload the provider emits, and forward the transcript path (session-transcript.jsonl). Python makes no capture decision. - In the
SessionEndbranch ofcaptureSessionLifecycleEvent, wheninterrupted === true: consume the pre-restart transcript (themessageslist and/or the persistedsession-transcript.jsonl) so in-flight turns reach marker/fact/handoff extraction like a clean close. - Reuse
resolveSessionLineageto recognize a resume as a lineage child of the interrupted session; reuse the existing capture-boundary dedupe, signaldedup_hash, and continuity payload-leveldedupe_keyconventions (scoped to the samesessionId/turn range) so turns already captured by the pre-interrupt flush are not re-captured on resume. - Record the interrupted status honestly in the audit record:
interrupted: trueplustranscript_consumed: true|false. If the transcript cannot be consumed, surfacetranscript_consumed: falseβ never coerce to a cleanSessionEnd. - Keep it fail-soft: a transcript read or extraction failure must never raise into Hermes.
Acceptance (passing test)
- A test drives
captureSessionLifecycleEventwith aninterrupted: trueSessionEndpayload carrying a transcript, and asserts:- the in-flight turns from the transcript are captured (markers/facts reach storage);
- the audit record carries
interrupted: trueandtranscript_consumed: true; - resuming the same
sessionIddoes NOT create duplicate continuity records (same existing dedupe seams / payload-leveldedupe_keypattern) and does not re-capture turns already captured by the interrupted close.
- A second test asserts an absent
interruptedfield leaves the clean-close path byte-identical (no auditinterruptedkey, existing tests unchanged).
Depends on
- No in-scope card dependency. Land first;
t_3b8fe3a1andt_12c8b256reason about the same field/substrate.
t_3b8fe3a1 β Verify memory on_session_end fires on /exit now native (#49315); drop any workaround
Files
plugins/hermes/provider.py(delete any workaround/poll found at verification time)plugins/hermes/_base.py(only if the fallback ABC needs threading; likely no change)- A regression test under
tests/
Plan
- Confirm against merged Hermes #49315 that the provider's
on_session_endnow fires on CLI/exit. Static grep acrossplugins/hermes/andsrc/found noatexit/poll/workaround compensating for the missing hook β confirm at runtime that none exists and none is needed. - If a workaround/poll IS discovered during verification, delete it (it is now dead/misleading code that duplicates the native hook). Update any comment that referenced the missing hook.
- Add a regression test that drives the provider's
on_session_endhook directly (unit-level, no live Hermes required) and asserts the drain+flush capture path runs β guarding against a future regression of the/exitbinding.
Acceptance (passing test)
- A test constructs
OpenSecondBrainMemoryProviderwith a fake bridge, callson_session_end(messages=[...]), and asserts the buffered turns are flushed to the bridge (brain_pre_compact_extractcalled) and the capture threads are drained β proving end-of-session capture runs on the path/exitnow drives. grep -rni "atexit\|poll\|workaround\|missing hook" plugins/hermes/returns no compensating workaround code (or, if one is found and removed, the test passes without it).
Depends on
- Ideally after
t_c181f92b(shares theon_session_endsurface), but no hard dependency β can land in either order on the shared branch.
t_12c8b256 β [upstream:hermes-memlock] Post-compaction pinned-anchor survival audit and selective re-assertion
Files
src/core/brain/post-compact-audit.ts(new)src/core/brain/pinned.ts(expose read helper if needed; reusereadPinnedContext; no budget change)- A CLI verb / host hook entry under
src/cli/brain/verbs/for the post-compaction audit src/core/config.ts(add absent-by-defaultpost_compact_survival_auditkey) if config-gated- Focused tests under
tests/
Plan
- Create
post-compact-audit.tssymmetric topre-compact-extract.ts. It is deterministic and LLM-free. Reuse the continuity store (ContinuityRecord,listContinuityRecords) andreadPinnedContext. - Compaction detection: scan the conversation for Hermes compressor handoff prefixes
(
SUMMARY_PREFIX, ASCII fallback, and legacy[CONTEXT SUMMARY]:); hash the summary body; compare against a per-session audited-compaction set (apost_compact_auditcontinuity record carrying a payload-level dedupe key derived fromsessionId + summaryHash) so only a genuinely NEW compaction triggers an audit. - Survival audit: for each pinned anchor, run a keyword probe (derived from the anchor text, locale-agnostic) scoped to the ACTIVE (non-summary) region. An anchor whose probes hit only inside the summary block counts as drifted.
- Selective re-assertion: re-inject only drifted anchors as a reminder block via
appendPinnedContext(or a dedicated re-assertion entry). Survivors cost zero tokens. Re-injection is on-drift only, never a blanket per-turn injection. - Optional windowed-embedding probe: off by default (config flag
post_compact_survival_audit_embedding); keyword probes are the default. - Fail-open: any probe or re-injection failure is logged to a bounded drift log
and must never break a turn. Wire the audit behind an absent-by-default config
flag (
post_compact_survival_audit) so unchanged installs are byte-identical.
Acceptance (passing test)
- A test seeds pinned anchors, feeds a conversation containing a Hermes
compaction-prefix block with one anchor demoted into the summary and one still
in the active region, runs the audit, and asserts:
- the drifted anchor is re-asserted (a re-assertion record / reminder block is written);
- the surviving anchor is NOT re-injected (zero tokens spent);
- a second audit of the SAME summary (same hash) does not re-run the audit (idempotent via the per-session audited-compaction key);
- a malformed/empty conversation does not raise (fail-open) and produces a bounded drift-log entry.
Depends on
- After
t_c181f92b(sharedsession-lifecycle.ts/ continuity substrate). No dependency ont_3b8fe3a1. Reusepinned.tsand the continuity store as-is.