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)
57 lines
2.3 KiB
Markdown
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.
|