kuri-memory-guard/AGENTS.md

63 lines
4.4 KiB
Markdown

# 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:**
```bash
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:
```bash
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