| name | memory-guard |
| description | When QWEN.md auto-memory format/completeness keeps failing, close the gap with a PreToolUse hook that checks frontmatter (name/description/type) and MEMORY.md indexing — same pattern as todo_gate_guard |
| source | auto-skill |
Memory Guard Hook
When to use
When auto-memory format violations (missing frontmatter, unindexed files in MEMORY.md) are a recurring problem, or when the user asks for mechanical enforcement of the memory discipline from QWEN.md.
Pattern
The hook lives at .qwen/local-scripts/memory_guard.py with tests at .qwen/local-scripts/test_memory_guard.py. It's a PreToolUse hook on Write/Edit to files under ~/.qwen/projects/ or ~/.qwen/memories/.
Checks
-
Frontmatter — every .md file in a memory subdirectory must have ---\nname:\ndescription:\ntype:\n---. The type: field must be one of user, feedback, project, reference.
-
MEMORY.md indexing — when writing MEMORY.md itself, all .md files in the memory subtree must have a one-line - [Title](file.md) — description pointer in the index. File writes without a MEMORY.md write are NOT blocked (the user can update MEMORY.md next). The MEMORY.md write gate ensures completeness.
Architecture
- Discover memory roots from
~/.qwen/projects/ and ~/.qwen/memories/
_memory_files_in_dir() walks the directory tree finding .md files (excluding MEMORY.md)_indexed_files() parses MEMORY.md extracting ](file.md) references_check_frontmatter() validates the --- frontmatter block fields- Fail-open: if
docs/TODO.md doesn't exist, allow (infrastructure error shouldn't block)
Test structure
Tests create temp directories with .qwen/memory/MEMORY.md and memory files, mocking _find_project_root to point at the temp dir. Key test cases:
- Non-memory file passes
- Missing frontmatter denies
- Valid frontmatter passes
- Unindexed file denies when writing MEMORY.md
- All indexed passes
- Missing TODO.md (fail-open) passes
Why
The QWEN.md memory discipline (one lesson per file, frontmatter, MEMORY.md index) is a recurring failure point because it requires the agent to remember a multi-step protocol that has no mechanical enforcement. A PreToolUse hook catches the violation at the point it happens (Write/Edit to a memory file), same as todo_gate_guard catches TODO omissions at the Write/Edit point.
