Context Hygiene — Verbara Ecosystem (P1)
Context Hygiene — Verbara Ecosystem (P1)
Section titled “Context Hygiene — Verbara Ecosystem (P1)”Status: Approved design — 2026-06-13
Origin: P1 of the 2026-06-13 methodology audit (see [[verbara_methodology_audit]] memory).
Scope: cross-repo CLAUDE.md + memory stores + personal/global context. (Baseline .claude/ and verification hooks are SEPARATE later specs — out of scope here.)
Home: verbara-meta (private cross-repo methodology repo — see docs/decisions/0001-cross-repo-methodology-home.md).
Problem
Section titled “Problem”Per-session context is bloated, against Anthropic’s context-engineering doctrine (“find the smallest set of high-signal tokens that maximize the desired outcome”; anti-patterns = context bloat + context rot). Release-history narrative lives in CLAUDE.md (duplicated in docs/), and memory stores have grown large and inconsistent across repos.
Findings (measured 2026-06-13, post PR #57)
Section titled “Findings (measured 2026-06-13, post PR #57)”| Repo | CLAUDE.md | Memory stores | MEMORY.md index | .project-memory git |
|---|---|---|---|---|
| Sdk (public) | 103L | 74 in .project-memory | 161L | gitignored ✅ |
| Pro (private) | 86L | 130 in .project-memory | 362L | TRACKED (130 files) ❌ |
| Platform (public) | 201L | 76 in .claude/memory (legacy, May-5) + 92 in .project-memory (active, Jun-7) | 143L + 141L | gitignored ✅ |
| Web (public) | 185L | 33 in .project-memory | 87L | gitignored ✅ |
Global ~/.claude/CLAUDE.md | 69L (dense) | — | — | personal |
Key facts: Platform’s .claude/memory/ is a dead legacy store (overlapping filenames with the newer .project-memory/); the release narrative in repo CLAUDE.md is duplicated in CHANGELOG + ADRs + completed plans; Pro commits its personal memory store (contract violation — .project-memory/ must be gitignored, never committed).
Goals / success criteria
Section titled “Goals / success criteria”- Repo CLAUDE.md = constraints + pointers only, no release changelog (target Platform 201→~90L; others proportional).
- One live memory store per repo;
.project-memory/gitignored in all repos. - Lean
MEMORY.mdindexes (one line per LIVE memory). - Global CLAUDE.md without the “Verbara Ecosystem” milestone narrative.
- Alignment with Anthropic’s “right altitude” for instructions.
Non-goals
Section titled “Non-goals”Shared .claude/ baseline; verification hooks (separate specs). No wholesale memory deletion. No product-code changes.
Design
Section titled “Design”Phase A — Mechanical wins (autonomous, reversible)
Section titled “Phase A — Mechanical wins (autonomous, reversible)”- A1 Platform legacy store: confirm
.claude/memory/content is superseded by.project-memory/, then delete.claude/memory/(it’s gitignored — local-only change). - A2 Pro untrack memory: add
.project-memory/to Pro.gitignore+git rm -r --cached .project-memory(untracks 130 files; does NOT delete local). → PRchore: stop tracking local project-memory store. - A3 Drift audit: run
project-memory audit --fixin each repo (broken index links, orphan files, duplicate rules). Mechanical/safe; touches gitignored personal files only. - A4 CLAUDE.md trim (repo): remove release/milestone narrative (already in CHANGELOG/ADRs/plans) → replace with a short “State & references” section of pointers. Keep: AOT/Npgsql/testing constraints, build/test commands, architecture quick-ref. → PR per repo (or one bundled).
Phase B — Semantic compaction (propose → approve → apply)
Section titled “Phase B — Semantic compaction (propose → approve → apply)”- Per repo: group memory files by topic; present a merge plan for approval (e.g. Pro 130→~40: fold redundant feedbacks; archive closed-milestone narratives already in docs).
- Rewrite each
MEMORY.mdlean after merge. - Global CLAUDE.md: trim the ecosystem milestone narrative (R5 / Session-Auth W1–W6 / Typification) → keep the repo table + dependency chain + cross-repo workflow + pointers. Diff presented for approval before applying.
- Gate: nothing applied to personal memory / global CLAUDE.md until the per-repo merge plan + global diff are approved. Local backup taken before compaction.
Phase C — Hygiene standard (durable guardrail)
Section titled “Phase C — Hygiene standard (durable guardrail)”A short “Context Hygiene Standard” doc fixing: what belongs in CLAUDE.md (constraints + pointers, never changelog) vs docs/ vs memory; a size budget (guideline, not hard cap); the .project-memory/-always-gitignored contract; the “right altitude” criterion. Purpose: prevent re-bloat.
Safety / reversibility / git
Section titled “Safety / reversibility / git”- Committed via branch + PR (as in P0): A2 (Pro untrack), A4 (repo CLAUDE.md trims), C (standard doc if homed in a repo).
- Local, no commit: A1 (Platform legacy delete — gitignored), A3 (drift audit), B memory compaction, global CLAUDE.md trim.
- Memory is recoverable (Pro’s is in git history; others backed up locally before compaction). Git changes land on feature branches with PRs.
Sequencing
Section titled “Sequencing”A (this session, autonomous) → B (present plan, await approval, apply) → C (write standard, PR/place). Then proceed to the next audit item (baseline .claude/).