cerebrocybersolutions memory-attribution-lint
Write-time validator + auto-injector for memory file frontmatter. Enforces an 11-key
provenance contract on .md files in memory directories. Closes the "where did this
memory come from?" gap by capturing source surface, tool, host, and session at write
time.
Why provenance matters
Memory entries accumulate across sessions, tools, and surfaces. Without provenance, stale or contradictory entries are hard to triage. The 11-key contract gives every memory file a complete audit trail: who wrote it, from what tool, on what host, in what session, at what time, with what confidence, and at what lifecycle stage.
Contract
Required frontmatter keys:
| Key | Source | Auto-derived |
|---|---|---|
| name | author | NO |
| description | author | NO |
| type | author (user/feedback/project/reference) | NO |
| source_surface | env CLAUDE_SURFACE or default | YES |
| host | socket.gethostname() |
YES |
| tool | env CLAUDE_TOOL or default unknown |
YES |
| session_id | env CLAUDE_SESSION_ID or unknown |
YES |
| written_at_utc | datetime.now(timezone.utc).isoformat() |
YES |
| source_path | author declares | NO |
| confidence | author: high/med/low | NO |
| lifecycle | author: pinned/active/archived/closed/superseded/stale-by:YYYY-MM-DD | NO |
Scripts
Scripts/lint.py— validate + auto-inject; exit 0=pass, 1=blocked, 2=injectedScripts/backfill.py— bulk backfill existing memory filesScripts/tests/fixtures/— golden samples for validation cases
Invocation
# Validate single file
python3 Scripts/lint.py path/to/memory.md
# Dry-run (report only)
python3 Scripts/lint.py --dry-run path/to/memory.md
# Backfill all memory dirs
python3 Scripts/backfill.py --dry-run
python3 Scripts/backfill.py --execute
Hook wire (PreToolUse)
See .claude/settings.json hooks.PreToolUse → Write/Edit matching **/memory/*.md.
The hook fires lint on any Write/Edit to a file matching the pattern; exit 1 blocks the
write until missing required keys are supplied, exit 2 auto-injects derivable keys and
allows the write to proceed.
Environment variables consumed
| Variable | Purpose | Default if unset |
|---|---|---|
CLAUDE_SURFACE |
Tool surface label (cc / hermes / etc.) | unknown |
CLAUDE_TOOL |
Specific tool that initiated the write | unknown |
CLAUDE_SESSION_ID |
Session identifier for cross-reference | unknown |
Set these at session start to capture full provenance automatically. Without them, the
required keys still pass validation (defaulted to unknown) but lose audit value.
Scope Contract (Least-Privilege)
| Dimension | Scope |
|---|---|
| Read paths | Any .md file passed as target argument |
| Write paths | Same file (auto-inject mode only); never writes outside target |
| MCP / tool surface | None — pure Python, stdlib only |
| Network egress | None |
| Surface | Any (hook fires at write-time regardless of surface) |
| Credentials | None |
| Escalation trigger | Exit 1 (blocked write) — operator must add missing required keys manually |