kuri-memory-guard/README.md
XLion c39bd626a8
Rewrite kuri-memory-guard: fix matchers, soft-block protocol, length thresholds, docs
Matcher fixes:
- PR/issue: fix \b boundary, handle PR #42, #57626
- SHA: support mixed-case hex
- TODO/Todo/todo: case-insensitive
- Remove top\s+\d+ (false positive on preferences)
- Split \b patterns for Chinese (next_step + 下一步)
- Work-verb 已: only match at sentence start
- Dot date: validate month/day range, reject IP fragments
- Slash date: YYYY/MM/DD before M/D for full matched text
- Relative dates: move from soft work-verb to hard date guard
- Placeholder: WIP/TBD/FIXME/XXX case-insensitive
- List-memory probes: hard block with _MSG_LIST_WARNING
- Date patterns: Chinese formats, dot/slash, relative weekdays

Soft-block rewrite:
- All guard functions return matched text, not pre-built messages
- Unified SOFT BLOCK protocol: guard name, matched text, ABC options
- Guard-specific notes per guard type
- Target-aware: target=user avoids '改放USER'
- Batch rendering shows per-item guard + matched text
- Hard ceiling: 180, length S1=80/S2=120/S3=150

Tests: 229 passed (22 new regression tests)
2026-07-30 01:55:56 +08:00

57 lines
2.3 KiB
Markdown

# kuri-memory-guard
A Hermes plugin that guards `memory` tool calls against stale, transient, or narrative content. Two-tier system: **hard blocks** always reject; **soft blocks** first time blocks with explanation; identical operation retry (same action/target/content/old_text) within a 5-minute window passes exactly once.
## How it works
- `pre_tool_call` hook intercepts `memory` tool calls
- Checks `content` (single operation) and `operations[]` (batch)
- **Hard guards**: dates (ISO, YYYY/MM/DD, M/D, dot-date MM.DD, Chinese dates), relative dates (today/今天/本週/上週/下週), placeholders, TODOs, WIP/TBD/FIXME/XXX, session labels, proc IDs, commit SHAs, list-memory probes — always blocked
- **Soft guards**: work verbs, user quotes, incident narratives, cron/session artifacts, version snapshots, cleanup meta — first hit blocks with guidance; an identical operation retry (same action/target/content/old_text) within a 5-minute window passes exactly once
- **Batch hygiene**: two or more guarded operations receive one short indexed summary and must be split; this does not consume soft retries
- **Length guard**: three-stage (refine/split/narrative) with early S2 trigger at 3+ markers — soft block; hard ceiling is an unconditional 180-char absolute limit
- Retry state: one-time pending fingerprints (atomic consume) with 5-minute TTL and 128-per-session cap; session state with 24-hour TTL and 1,024-session LRU cap
## Installation
Clone to the Hermes user plugins directory:
```bash
git clone https://git.xlion.tw/xlionjuan/kuri-memory-guard.git \
~/.hermes/plugins/kuri-memory-guard
```
## Enable
```bash
hermes plugins enable kuri-memory-guard
```
Takes effect after a gateway restart (`/restart` or restart the Hermes gateway service).
## Using in other profiles
```bash
mkdir -p ~/.hermes/profiles/<profile>/plugins
ln -s ../../../plugins/kuri-memory-guard \
~/.hermes/profiles/<profile>/plugins/kuri-memory-guard
hermes plugins --profile <profile> enable kuri-memory-guard
```
## 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.