4.4 KiB
4.4 KiB
kuri-memory-guard
Guards memory tool calls against stale content with a two-tier system:
- Hard block: dates (ISO + M/D + YYYY/MM/DD + dot-date MM.DD + Chinese dates), relative dates (today/今天/本週), placeholder/temp, TODO, session labels, proc session IDs, probe state, commit SHA, WIP/TBD/FIXME/XXX, list-memory probes — always blocks
- Soft block: work verbs, PR/issue numbers, Chinese completion markers, user quotes, status labels, incident markers, reflexive lessons, cron/parallel session artifacts, version snapshots, cleanup meta, 優化方向, re-fetchable markers — first time blocks with explanation; identical operation retry (action+target+content+old_text) within 5-min window passes exactly once
Author: Kuri
Verification
Full reproducible verification:
cd ~/.hermes/plugins/kuri-memory-guard
just verify
just verify uses the locked uv environment and runs Ruff lint, Ruff format check, ty, and pytest. The equivalent standalone commands are:
uv run ruff check .
uv run ruff format --check .
uv run ty check .
uv run pytest -v
All four checks must pass before committing.
How It Works
pre_tool_callhook interceptsmemorytool calls- Checks
content(single operation) andoperations[](batch) - Hard guards run first (hard ceiling → date → placeholder), soft guards second
- Hard ceiling: content ≥ 180 chars always blocked; retry cannot override — content at or above this must be split, redirected to skill/docs, or abandoned. Redirect to USER is only suggested when target is not already
user(code adjusts message accordingly) - Soft block: SHA-256 fingerprint of full operation (scope + action + target + normalized content + old_text) tracked per session; single scope and batch scope are isolated
- First soft hit → block + message; identical operation retry within 5-min window → atomically consumed, pass exactly once; third attempt → re-block; concurrent calls to same fingerprint → at most one wins
- Two or more guarded operations in a batch receive one compact indexed summary and must be split; batch summaries do not create pending retries
- Retry state: atomic one-time pending fingerprints with 5-minute TTL; 128-per-session cap (evicts oldest expiry); session state with 24-hour TTL, 1,024-session LRU cap
Guards
| # | Name | Type | What it matches |
|---|---|---|---|
| 0 | hard_ceiling | hard | content ≥ 180 Unicode chars — absolute limit, retry cannot override |
| 1 | date | hard | YYYY-MM-DD, ISO datetime, YYYY/MM/DD, M/D date shorthand (6/30), Chinese (3月15日), dot-date MM.DD (03.15), relative dates (today/今天/本週/上週/下週/本週一/本星期), 本週五/月底/下個月初 |
| 2 | placeholder | hard | TODO, dummy, placeholder, temp, probe, phase N done, session labels, proc_xxx session IDs, probe current state, commit SHA, WIP/TBD/FIXME/XXX, Chinese placeholder (只是測試/試寫/暫存), test memory, smoke record, sentinel state, list-memory probes (list memory/memory list/show memory) |
| 3 | work_verb | soft | fix/submit/merge verbs, PR/issue numbers, currently/now, next step, Chinese 正在/已 (extended), done with, cron/session_search, status/progress labels (status:/狀態:) |
| 4 | user_quote | soft | 主人說/回/要求, User said/replied, 他說/她說/你說, incident markers (incident/事故/復盤/根因), reflexive lessons (學到了/下次要記得) |
| 5 | cron_session | soft | 平行 session, parallel session/Kuri, coverage edge, 手動 trigger, daily auto-commit, [SILENT] |
| 6 | meta | soft | version/project snapshots (v3.14), memory cleanup meta (記憶條目, skill bloat, sprawl), 優化方向/改善方向, re-fetchable markers (原始碼/git log/official docs) |
| 8 | length | soft | three-stage: refine (80+), split (120+), narrative (150+); early S2 trigger at S1 range (80-119) with 3+ split markers; hard ceiling at 180 |
Testing
Tests organised by component:
TestDateGuard,TestPlaceholderGuard,TestWorkVerbGuard— individual predicatesTestSoftBlockTracking— first-block-then-allow per session+hashTestScanContent— orchestration (hard before soft, retry passes)TestGetBlockMsg— memory call arg interfaceTestOnPreToolCall— hook interface with session_idTestHelpers— normalize and hashTestRegister— registration contract