feat(harness): add memoize sub-action for memory hygiene

[datashaman]

Closes #5.

Issue

Memory under ~/.claude/projects/<slug>/memory/ is reactive — entries get written when the agent notices something worth saving, but nothing prunes or consolidates. Over time, project memories cite renamed files, feedback memories accumulate near-duplicates, and MEMORY.md drifts out of sync with the actual files. The current "verify before recommending from memory" rule in CLAUDE.md is a read-time check, not a maintenance pass.

Effect on the user

Stale memory leaks into responses. The agent recalls a function that no longer exists, or repeats the same feedback rule three different ways because nobody noticed the duplicate. Trust in memory erodes, and the user ends up suppressing the system rather than maintaining it.

Root cause

There's no maintenance surface. The harness has install / update / doctor for hooks and commands, snapshot + audit for the broader setup, but nothing that touches memory. The only existing safeguard runs at read-time, per-recall, and can't fix structural drift like a missing index entry or a frontmatter typo.

The fix

A new memoize sub-action — deterministic, idempotent, report-only.

skills/harness/scripts/memoize.sh runs four checks against ~/.claude/projects/<slug>/memory/:

1. Index sync — every memory/*.md is listed in MEMORY.md; every entry points at a real file.
2. Frontmatter hygiene — every memory has name, description, type.
3. Stale citations — path-shaped tokens (~/, /Users/, ./, or ending in a known source extension) that resolve nowhere across ~/.claude/projects/ and ~/Projects/. Conservative on purpose — false positives cost more than misses; slash-commands, brace expansions, and regex-shaped strings are filtered out.
4. Possible duplicates — pairs within a type whose name or description are lexically similar (Jaccard ≥ 0.5). Flag, don't merge.

Output goes to <memory>/_memoize-report.md (leading underscore so it's never indexed by MEMORY.md). The report is byte-stable on equal runs — running twice produces an identical file. Flags: --dry-run, --target=PATH. Env knobs mirror snapshot.sh: CLAUDE_DIR, USER_PROJECT_KEY, MEMOIZE_SEARCH_ROOTS.

skills/harness/scripts/memoize-prompt.md is the /schedule recipe for a weekly remote routine that runs the script, layers in the semantic checks the lexical pass can't catch (conceptual duplicates, outdated facts, conflicting guidance), and PRs audits/memory/YYYY-MM-DD.md against the snapshot repo. Suggested cron 0 6 * * 0 (Sunday 06:00 UTC), model claude-opus-4-7. The remote agent never modifies memory directly — the user reviews and applies.

skills/harness/SKILL.md picks up memoize in the frontmatter description (so the skill auto-routes on "memoize" / "consolidate memory" / "prune memory"), a row in the dispatch table, a new ## memoize section, and an entry in the Files-in-this-skill table.

Validation

• ./scripts/harness-check.sh passes — shellcheck clean (resolved three SC2005 stylistic warnings on echo $(dim …) patterns), ruff, mypy, pytest.
• bash skills/harness/scripts/memoize.sh --dry-run against the real ~/.claude/projects/-Users-marlinf/memory/ reports zero findings.
• Two consecutive memoize runs produce a byte-identical report (diff empty) — idempotency confirmed.
• The path-resolution heuristic was tightened mid-implementation after the initial run flagged six false positives (slash commands like /grade, /harness-check, brace expansion stacks/{typescript,python,go,laravel}, regex /MFC/class-based). Restricting to hard path prefixes + known source extensions dropped the noise to zero against the same input.

[Copilot]

Pull request overview

This PR adds a new memoize sub-action to the harness skill so users can run a deterministic memory-hygiene pass over Claude Code memory and optionally wire a weekly remote review workflow around it. It extends the existing harness surfaces (snapshot, audit, doctor, etc.) with a maintenance path for keeping memory indexes, frontmatter, and stale references from drifting over time.

Changes:

• Adds skills/harness/scripts/memoize.sh, a new report-generating script that checks memory index sync, frontmatter hygiene, stale citations, and possible duplicates.
• Adds skills/harness/scripts/memoize-prompt.md, a /schedule prompt template for a weekly remote memory-review routine.
• Updates skills/harness/SKILL.md to advertise, route, and document the new memoize action and its related files.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 14 comments.

File	Description
skills/harness/scripts/memoize.sh	Implements the new memory-hygiene scan and report generation logic.
skills/harness/scripts/memoize-prompt.md	Defines the weekly remote workflow for reviewing memory and opening a PR with findings.
skills/harness/SKILL.md	Documents the new memoize action, routing keywords, and supporting files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.