kuri-memory-guard/AGENTS.md

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_call hook intercepts memory tool calls
  • Checks content (single operation) and operations[] (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 predicates
  • TestSoftBlockTracking — first-block-then-allow per session+hash
  • TestScanContent — orchestration (hard before soft, retry passes)
  • TestGetBlockMsg — memory call arg interface
  • TestOnPreToolCall — hook interface with session_id
  • TestHelpers — normalize and hash
  • TestRegister — registration contract