| type | note |
| description | Vault health monitoring, MOC generation, link repair, and system evolution. Use this skill when checking vault quality metrics, regenerating MOC indexes, fixing broken links, finding backlinks, or triggering weekly system reflections. Also use it when the user mentions health score, link density, orphans, dead-ends, or description coverage. |
| name | vault-health |
| depends_on | ["graph-builder"] |
Vault Health
Monitoring and improving knowledge graph health. Built on patterns from arscontexta — derivation engine for Claude Code.
Origin
Skill based on arscontexta analysis (Heinrich's derivation engine, 249 research claims).
Key adopted patterns:
- Health scoring — composite metric for quantitative vault assessment
- Explicit wikilinks in MOC — instead of dataview (invisible to agents)
- Operational learning loop — observations → patterns → improvements
- Typed relationships — links with context phrases, not bare
related:[]
- Description as retrieval filter — progressive disclosure for agents
Quick Start
uv run vault/.claude/skills/graph-builder/scripts/analyze.py
uv run vault/.claude/skills/vault-health/scripts/generate_moc.py
bash vault/.claude/skills/vault-health/scripts/backlinks.sh "business/crm/acme-corp"
uv run vault/.claude/skills/vault-health/scripts/fix_links.py
uv run vault/.claude/skills/vault-health/scripts/fix_links.py --apply
Health Score
Composite metric in analyze.py. Formula:
health_score = 100
- (orphan_ratio × 30) # orphans = knowledge loss
- (broken_ratio × 30) # broken links = fragmentation
- max(0, (3 - avg_links) × 15) # target: 3+ links/file
- ((1 - desc_ratio) × 10) # description coverage
Metrics and targets
| Metric | Target | How to improve |
|---|
| Health Score | >80 | All other metrics |
| Avg links/file | >3.0 | generate_moc.py, typed relationships |
| Broken links | <50 | fix_links.py, manual review |
| Orphans | <30 | graph-builder orphan resolution |
| Dead-ends | <100 | Add backlinks to CRM |
| Desc coverage | >50% | Add description to frontmatter |
Trend tracking
History stored in .graph/health-history.json (up to 90 entries). Each analyze.py run adds a data point.
cat vault/.graph/health-history.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for d in data[-10:]:
print(f\"{d['date']}: {d['health_score']}/100 | links: {d['total_links']} | broken: {d['broken_links']}\")
"
MOC Generation
generate_moc.py creates Maps of Content with explicit wikilinks and context phrases (arscontexta pattern). Dataview queries preserved at end of files.
What it generates
MOC-business.md:
- Active Deals (with deadline and deal value)
- High Priority clients
- Grouping by industry (FMCG, Banks, Retail, ...)
- Within industry: Active first, then Prospect
MOC-projects.md:
- Hot/Active leads
- Clients
- Projects, Resources
Wikilink format
- [[business/crm/acme-corp\|Acme Corp]] — Active, p1, Project $XXK, deadline YYYY-MM-DD
Each link contains: status, priority, deal info, region, deadline — agent sees context without opening file.
When to run
- After adding new CRM files
- After updating status/deal_status in CRM
- Recommended: weekly or when changes in
business/crm/ / projects/
Link Repair
fix_links.py
Finds broken links and suggests fixes via fuzzy stem matching.
Strategies:
- Trailing backslash — Obsidian table escaping artifact (
\|)
- Wrong prefix —
crm/company → business/crm/company
- Stem match —
old-name → finds new-name.md by stem match
Exclusions: backup directories, attachment embeds, directory links.
uv run vault/.claude/skills/vault-health/scripts/fix_links.py
uv run vault/.claude/skills/vault-health/scripts/fix_links.py --apply
backlinks.sh
Find files linking TO specified file (incoming links).
bash vault/.claude/skills/vault-health/scripts/backlinks.sh "business/crm/acme-corp"
bash vault/.claude/skills/vault-health/scripts/backlinks.sh "MEMORY"
Dead-end detection
Dead-end = file with outgoing links but no incoming (knows about others, but nobody knows about it). Detected by analyze.py, output in report.md.
Weekly Reflection
Operational learning loop: observations → patterns → proposals.
Trigger
- Every Sunday
- When observations in
.session/handoff.md reach ≥10
Process
- Read
.session/handoff.md → collect ## Observations
- Read
.graph/health-history.json → week's trend
- Group observations by type (friction/pattern/idea)
- Find recurring patterns (>2 occurrences)
- Propose concrete improvements (file + change)
- Write reflection file
- Clear processed observations from handoff.md
Output
thoughts/reflections/YYYY-WNN-system-reflection.md
Detailed template: .claude/rules/weekly-reflection.md
Observation format
In .session/handoff.md, section ## Observations:
- [friction] 2026-02-19: mcp-cli timeout 3x — retry saved, -60 sec
- [pattern] 2026-02-19: 65 "broken links" were attachment embeds
- [idea] 2026-02-19: generate_moc.py in process.sh chain
Types: friction (something broke/slow), pattern (recurring), idea (improvement).
Typed Relationships
When adding links between files, use context phrases (arscontexta pattern):
| Type | When | Example |
|---|
| extends | Develops an idea | [[note]] — extends: deepens analysis |
| context | Background info | [[note]] — context: meeting where discussed |
| supports | Supports a goal | [[goal]] — supports: annual target |
| contradicts | Contradicts | [[note]] — contradicts: different approach |
| enables | Makes possible | [[tool]] — enables: workflow |
| requires | Dependency | [[resource]] — requires: API key |
Description Guidelines
Description = retrieval filter, NOT summary. Adds information BEYOND title.
description: "Company Acme Corp"
description: "Key client in [industry], active deal $XXK, [project] in progress"
Target: ~150 chars. Scope, mechanism, implication — not retelling.
Automation in process.sh
analyze.py runs automatically every day through scripts/process.sh:
- If daily is empty → graph-only rebuild
- After full processing → final rebuild
generate_moc.py, fix_links.py, backlinks.sh — manual run as needed.
References
references/arscontexta-patterns.md — patterns from arscontexta, adapted for agent-second-brain
.claude/rules/weekly-reflection.md — template for weekly reflections
Relevant Skills
- [[vault/.claude/skills/graph-builder/SKILL|graph-builder]] — core graph analysis (analyze.py)
- [[vault/.claude/skills/dbrain-processor/SKILL|dbrain-processor]] — daily processing pipeline