Memory Hygiene

CLAUDE.md has evolving-claude-md. This governs the other half of the context an agent loads every session: the per-project memory directory under ~/.claude/projects/<slug>/memory/, written by the agent, largely unsupervised.

The failure modes differ, and the difference is the design. Bloat makes an agent ignore instructions; rot makes it confidently recall something false — a version that has moved on, a "latest migration" that isn’t, a path that no longer exists. So where the sibling prunes down, this one re-verifies and invalidates. Across the agent-memory ecosystem, systems evict by size, age, or recency; none evicts a fact because it became wrong. That is the gap this fills, and it needs no database — a lint and two hooks.

Install

/plugin install memory-hygiene@alexmskills

Two hooks register on enable: a SessionStart sweep and a PreToolUse write lint. Nothing to configure; silent when healthy.

The sweep

Every check is grounded against the actual tree — nothing is flagged by pattern alone:

Check Fires when

Check	Fires when
Vanished artifact	A backticked path/class/flag `git grep` can no longer find and that isn’t on disk. Memory-specific filters run first: `--flags`, `<placeholders>`, `…`-abbreviated paths, and paths rooted outside this tree are pointers, not rot here — never checked.
Stale version pin	Memory states `jhelm 1.3.1` and every parseable build-file spec now contradicts it. Reads Maven, Gradle, npm, Go, Cargo, Python, .NET, Bundler and Composer manifests, and the toolchain pin files (`.nvmrc`, `.python-version`, `.tool-versions`, `rust-toolchain.toml`, …). Release lines (`4.1.x`), examples, and struck-through lines stay silent.
Stale sequence fact	"latest is V27`" once `V28__*.sql exists on disk, or "next is `V28`" once V28 already happened.
Index drift	Both directions: `MEMORY.md` lines pointing at files that no longer exist, and memory files with no index line — invisible to recall.

Vanished artifact

A backticked path/class/flag git grep can no longer find and that isn’t on disk. Memory-specific filters run first: --flags, <placeholders>, …-abbreviated paths, and paths rooted outside this tree are pointers, not rot here — never checked.

Stale version pin

Memory states jhelm 1.3.1 and every parseable build-file spec now contradicts it. Reads Maven, Gradle, npm, Go, Cargo, Python, .NET, Bundler and Composer manifests, and the toolchain pin files (.nvmrc, .python-version, .tool-versions, rust-toolchain.toml, …). Release lines (4.1.x), examples, and struck-through lines stay silent.

Stale sequence fact

"latest is V27`" once `V28__*.sql exists on disk, or "next is `V28`" once V28 already happened.

Index drift

Both directions: MEMORY.md lines pointing at files that no longer exist, and memory files with no index line — invisible to recall.

Calibrated against 15 real memory corpora on the author’s machine (184 files): 15 findings, the majority verified rot — including a memory pinning a dependency two minor versions behind the build and three "epic complete" notes citing symbols since renamed.

Supersede, never delete

A flag is a re-verification request, not a verdict. When a fact is genuinely wrong, strike it through and append a dated correction in the same file. The reasoning stays: a memory that keeps a wrong conclusion but loses the why leads to confident re-emission, while an absent memory at least leads to abstention. Struck lines are skipped on the next sweep — the correction is also what silences the auditor.

The write contract

Location is the contract, enforced by the PreToolUse hook — the one mechanism that has held where prose instructions failed:

Fact files must open with frontmatter (name:, description:, metadata.type in user | feedback | project | reference), and added prose must not use relative dates — "last week" expires silently; 2026-08-11 does not.
MEMORY.md stays an index: one-line pointers only. Paragraph prose or frontmatter there is memory content in the wrong territory.

Writes outside a memory directory are never touched.

Shared core

Both this plugin and evolving-claude-md vendor the same freshness.py — stdlib-only, pure functions over (text, repo_root) — so "is this fact still true on disk?" has exactly one implementation. The marketplace harness pins the two copies byte-identical.

Claude Code vs Codex

Tier 3 — lifecycle hooks on both clients.

Claude Code Codex

	Claude Code	Codex
Memory it guards	Claude’s native project memory under `~/.claude/projects/<slug>/memory/`.	Project-owned `.codex/memory/MEMORY.md` plus topic files — plugin-managed, not Codex’s internal memory database.
Hooks	SessionStart audit, PreToolUse format lint on memory writes.	The same two events. SessionStart also loads the memory index into context.
Direct CLI audit	Runs as-is.	Set `SKILL_CLIENT=codex` so the audit reads `.codex/memory/`.

Memory it guards

Claude’s native project memory under ~/.claude/projects/<slug>/memory/.

Project-owned .codex/memory/MEMORY.md plus topic files — plugin-managed, not Codex’s internal memory database.

Hooks

SessionStart audit, PreToolUse format lint on memory writes.

The same two events. SessionStart also loads the memory index into context.

Direct CLI audit

Runs as-is.

Set SKILL_CLIENT=codex so the audit reads .codex/memory/.

The difference that matters: The Codex memory is files this plugin manages. Anything Codex remembers on its own is outside its reach.

Install, hook trust and verified limits: Codex compatibility.