Context
PR #12502 adds the Memory Core embedding write-canary so healthcheck can detect the write-side embedding degradation behind #12487. During review, @neo-opus-grace approved the V1 resilience PR but surfaced a non-blocking follow-up: the canary currently performs a live embedding probe on healthcheck paths, and that probe may itself add load to the serialized embedding model during exactly the contention window it is meant to diagnose.
The Problem
The #12487 failure mode is batch embedding monopolizing the embedding provider so interactive add_memory queues behind maintenance work. A live canary on every healthcheck risks becoming another interactive-class embedding request. If healthcheck is polled frequently during nightshift or diagnostics, the observability probe can add embedder pressure and make contention noisier.
This is not a merge blocker for PR #12502 because the write canary is still valuable and the risk is frequency-dependent. It is a follow-up that needs measurement and, if confirmed, a throttle/cache shape.
The Architectural Reality
- Memory Core healthcheck is an operator-facing observability surface.
add_memory depends on embeddings and is protected by AGENTS.md's no-skip memory gate.add_message does not embed, which is why #12487 isolated the failure to the embedding path.- PR #12502's reviewer identified
#applyEmbeddingWriteCanary / buildEmbeddingWriteCanaryBlock as the new probe surface and suggested a short TTL cache if healthcheck frequency is high.
The Fix
Measure healthcheck call frequency and write-canary embedding count during representative agent/nightshift usage. If the canary is low-frequency, document the evidence and close this as no-change. If it is high-frequency or materially adds embedding load, add a short TTL cache for the canary result so healthcheck can report recent write-side health without embedding on every call.
Contract Ledger Matrix
| Target Surface |
Source of Authority |
Proposed Behavior |
Fallback |
Docs |
Evidence |
| Memory Core healthcheck embedding write-canary |
PR #12502 review follow-up + #12487 AC3 |
Avoid making every healthcheck call perform a fresh embedding probe when recent canary evidence is still valid |
If measured frequency is low, document no TTL needed |
Healthcheck docs / PR body if behavior changes |
Frequency measurement + unit coverage for TTL reuse if implemented |
| Canary TTL cache |
This ticket |
Reuse a recent canary result for a bounded interval, preserving fail-loud behavior outside the TTL |
No cache when TTL disabled/zero |
Config/comment if a new leaf is added |
Unit test: repeated healthcheck within TTL does not call embedder twice; expired TTL calls again |
Decision Record impact
aligned-with #12487 and PR #12502's evidence ladder; none to ADRs.
Acceptance Criteria
Out of Scope
- V2 priority lane / pause-on-interactive QoS for batch embedding. That is tracked separately.
- Reworking the broader healthcheck cache.
- Live L4 proof of #12487 AC1 during an operator KB-sync batch.
Related
Parent: #12487
Source PR: #12502
Related: #12450, #11393, #12090
Origin Session ID: dcdaac0b-9ae0-45b5-b4da-da39541af497
Handoff Retrieval Hints: query_raw_memories embedding write canary healthcheck TTL contention; PR #12502 review by @neo-opus-grace at head 6822412e88c56b3bb5904225f212283f04e9b77d.
Context
PR #12502 adds the Memory Core embedding write-canary so
healthcheckcan detect the write-side embedding degradation behind #12487. During review, @neo-opus-grace approved the V1 resilience PR but surfaced a non-blocking follow-up: the canary currently performs a live embedding probe on healthcheck paths, and that probe may itself add load to the serialized embedding model during exactly the contention window it is meant to diagnose.The Problem
The #12487 failure mode is batch embedding monopolizing the embedding provider so interactive
add_memoryqueues behind maintenance work. A live canary on every healthcheck risks becoming another interactive-class embedding request. If healthcheck is polled frequently during nightshift or diagnostics, the observability probe can add embedder pressure and make contention noisier.This is not a merge blocker for PR #12502 because the write canary is still valuable and the risk is frequency-dependent. It is a follow-up that needs measurement and, if confirmed, a throttle/cache shape.
The Architectural Reality
add_memorydepends on embeddings and is protected by AGENTS.md's no-skip memory gate.add_messagedoes not embed, which is why #12487 isolated the failure to the embedding path.#applyEmbeddingWriteCanary/buildEmbeddingWriteCanaryBlockas the new probe surface and suggested a short TTL cache if healthcheck frequency is high.The Fix
Measure healthcheck call frequency and write-canary embedding count during representative agent/nightshift usage. If the canary is low-frequency, document the evidence and close this as no-change. If it is high-frequency or materially adds embedding load, add a short TTL cache for the canary result so healthcheck can report recent write-side health without embedding on every call.
Contract Ledger Matrix
Decision Record impact
aligned-with #12487 and PR #12502's evidence ladder; none to ADRs.
Acceptance Criteria
Out of Scope
Related
Parent: #12487 Source PR: #12502 Related: #12450, #11393, #12090
Origin Session ID: dcdaac0b-9ae0-45b5-b4da-da39541af497
Handoff Retrieval Hints: query_raw_memories
embedding write canary healthcheck TTL contention; PR #12502 review by @neo-opus-grace at head6822412e88c56b3bb5904225f212283f04e9b77d.