Skip to content

fix(python): keep the session Crystal when the write quota is used up (#749) - #750

Merged
p-diogo merged 1 commit into
mainfrom
fix/hermes-crystal-write-quota
Nov 12, 2026
Merged

p-diogo merged 1 commit into
mainfrom
fix/hermes-crystal-write-quota

Conversation

@p-diogo

@p-diogo p-diogo commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator

Fixes #749.

Problem

When the account's monthly write allowance was used up, the relay refused the session-end summary (Crystal) with 403 quota_exceeded. session_debrief caught every store error and only logged it, so the Crystal was lost. Unless an earlier write in the same session had also been refused, the user was not told. This affected every path that writes a Crystal: session end, the idle-session roll, and the idle sweep.

Changes

  • Queue instead of drop. session_debrief catches RelayWriteQuotaExceeded and passes the Crystal to _handle_write_quota, the same path Hermes: write-quota exhaustion (403 on /v1/bundler) never surfaces to user or agent — auto-extraction facts silently dropped (44+ since Nov 9) #747 uses for refused auto-extracted facts. This handles the encrypted retry queue, billing-cache invalidation and the once-per-session notice.
  • Store it as it would have been stored. _drain_entries recognises a queued Crystal (extra_metadata.subtype == "session_crystal"). It stores the Crystal the way session_debrief does: no write gate, no embedding, v1 summary, provenance derived. Before that, it rebuilds a Crystal and runs _scrub_crystal, so any sentence or list item the user has forgotten since it was queued is removed. If nothing is left, the entry is dropped. The whole-text forget check used for facts would miss a single forgotten sentence inside a longer narrative.
  • Keep the original date. PendingStoreQueue.add stamps extracted_at with the refusal time; existing values are kept. store_fact_batch already turns extracted_at into the blob's created_at. Before this change, a fact or Crystal stored weeks later carried the drain time, so the vault showed it apart from its conversation. This applies to queued facts too, not only the Crystal.
  • Notice grammar. The notice read "1 new memory from this conversation are kept". It now reads "1 new memory is kept on this device …" / "N new memories are kept …", with matching wording for lost items. "From this conversation" is dropped because a session-end notice shows in the next conversation.
  • Docs: CHANGELOG, client-consistency.md rule 4, Hermes SKILL.md, and the CLAUDE.md feature matrix row.

Testing

  • Unit: 13 new tests in python/tests/test_write_quota_747.py (TestSessionCrystalQuota, TestQueuedFactTime, test_notice_counts_read_correctly). All failed before the fix, for the expected reasons. With only the drain-side Crystal handling reverted, the two forget-scrub drain tests fail.
  • Full suite (serial): 3497 passed, 16 skipped, 1 xfailed. All 16 skips are opt-in env gates (staging recovery phrase, slow packaging tests, pyzbar).
  • Staging E2E: 13/13 checks passed. A local stub forwards everything to api-staging.totalreclaw.xyz and returns the relay's real quota_exceeded body for eth_sendUserOperation while refusing. The run used a fresh throwaway account:
    • refusal → Crystal queued, encrypted at rest (plaintext not in the file)
    • notice reads "1 new memory is kept on this device"
    • writes allowed → drain sends a real UserOp to staging
    • the staging subgraph indexes the Crystal and it decrypts
    • it exports as sum with the session's session_id
    • the blob has type: summary, subtype: session_crystal and key_outcomes kept
    • the blob's created_at equals the refusal time, not the drain time
    • the Crystal is then tombstoned

🤖 Generated with Claude Code

…#749)

A session-end Crystal refused by the relay for quota (403 quota_exceeded)
was only logged, so it was lost, and the user was not told unless an
earlier write in the session had also been refused.

- session_debrief now queues a quota-refused Crystal in the #747
  encrypted retry queue and raises the once-per-session notice.
- The drain stores a queued Crystal the way session_debrief does (no
  write gate, no embedding), after a per-sentence forget scrub, so
  anything the user forgot since it was queued is not written.
- Queued facts keep the time they were refused as extracted_at, so
  their created_at matches the conversation they came from.
- Notice grammar: "1 new memory is kept ..." (was "are kept"); drop
  "from this conversation", since a session-end notice shows later.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@p-diogo
p-diogo merged commit 7104a42 into main Nov 12, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hermes: session-end Crystal refused for write quota is dropped instead of queued

1 participant