claude-memory-lint

Disclaimer: This is an independent third-party tool. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic and are used here nominatively to identify the official CLI/product this tool integrates with.

A static lint for Claude Code memory directories. Catches the file-quality problems that lead to context pollution before they reach the prompt — stop generic-keyword noise at the source instead of chasing it at runtime.

cml check  ~/.claude/projects/<id>/memory/   # exits 1 on ERROR
cml fix    ~/.claude/projects/<id>/memory/   # auto-add missing aliases
cml stats  ~/.claude/projects/<id>/memory/   # counts only, no contents

Why

Claude Code memory directories grow quickly. Once frontmatter is inconsistent and a meaningful fraction of files only carry generic keywords (api, github, claude, task, agent, …), runtime routing degrades into "every common word matches every file": context gets stuffed with unrelated memory and the model's attention drifts.

Runtime routers can patch the symptom. The cause is on the write side: missing frontmatter, empty aliases:, oversized files, stale copies. claude-memory-lint raises those defects to ERROR / WARN / INFO at write-time so they never reach the auto-load path.

Privacy posture

This is the privacy-conscious choice in the memory-tooling space:

• No LLM calls. Period. Heuristics only.
• No file body in stdout. stats and check --format json print filenames, rule IDs, and counts — never the file content.
• Auto-fix writes a .bak next to the original and never sends anything off-machine.
• A separate hook (claude-memory-router) handles runtime routing with the same posture; this lint is its compile-time companion.

Install

pip install claude-memory-lint
# or for development:
pip install -e .[dev]

Python 3.10+. No required runtime dependencies.

Rules

Thresholds are tunable in code; runtime config file support is on the roadmap.

R009 (added in v0.2.0) is the response to a real-world incident where a GitHub PAT literal sat in a memory file for days under .gitignore "protection" while still being one filesystem-read away from the LLM context. The rule deliberately reports only the pattern type and the line — the matched substring is never written to stdout, JSON, SARIF, or any error path — because a lint that leaks the secret it caught is worse than no lint.

Use as a pre-commit hook

Add to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/hinanohart/claude-memory-lint
    rev: v0.4.0
    hooks:
      - id: claude-memory-lint
        args: [check, --rule, R001, --rule, R002]

This blocks commits that introduce a memory file without proper frontmatter or aliases.

Use in CI

- name: lint memory directory
  run: |
    pip install claude-memory-lint
    cml check --format sarif path/to/memory > cml.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: cml.sarif

Companion: claude-memory-router

This lint pairs with claude-memory-router:

• The lint enforces write-time quality (aliases, size, freshness).
• The router consumes that quality at read-time and only injects the most relevant memory files into the prompt.

Garbage-in, garbage-out is real for routers as for any other engine. The lint exists so the router can do its best work.

Output formats

text   default — human-readable, one finding per line + summary
json   machine-readable; convenient for CI gates
sarif  SARIF 2.1.0 — uploadable to GitHub code scanning

Testing

pip install -e .[dev]
pytest -v

The current suite is 95 tests covering parser edge cases (no frontmatter / unterminated frontmatter / inline lists / multi-line lists), per-rule positive and negative cases for R001-R017, the corpus rules R007 and R011, and the CLI front-end including JSON / SARIF reporters.

License

MIT. See LICENSE.