No description
  • Python 99.8%
  • Just 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-08-09 19:41:06 +08:00
tests feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
.gitignore feat: strengthen memory guard batching 2026-07-10 06:08:35 +08:00
__init__.py feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
AGENTS.md feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
justfile feat: strengthen memory guard batching 2026-07-10 06:08:35 +08:00
messages.py feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
plugin.yaml feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
pyproject.toml feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00
README.md Rewrite kuri-memory-guard: fix matchers, soft-block protocol, length thresholds, docs 2026-07-30 01:55:56 +08:00
uv.lock feat: block 主人要求 in user_quote guard, improve rewrite guidance 2026-08-09 19:41:06 +08:00

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:

git clone https://git.xlion.tw/xlionjuan/kuri-memory-guard.git \
    ~/.hermes/plugins/kuri-memory-guard

Enable

hermes plugins enable kuri-memory-guard

Takes effect after a gateway restart (/restart or restart the Hermes gateway service).

Using in other profiles

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

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.