vault-health

Files (3)

• SKILL.md
• cron-output-graph-bloat.md · references/
• vault-audit.py · references/

SKILL.md (first lines)

# Vault Health

{{AGENT_NAME}}'s internal knowledge base (.{{AGENT_NAME_LOWER}}/) IS an Obsidian vault. This skill covers maintaining its health — broken link detection, backlink density, graph connectivity, auto-generated orphan management, and Obsidian compatibility.

## Principles

1. **Prevention over detection.** Fix the root cause so nothing needs ongoing management. "관리할 일이 안생기게 애초에 잘하던가." A rule/cronjob that only reports problems is not a solution — fix the source.
2. **Every file should have ≥1 inbound and ≥1 outbound wikilink.** Orphans defeat the graph.
3. **Body wikilinks > frontmatter `links:`.** Obsidian Graph View prioritizes body links. Frontmatter links should be mirrored in body.
4. **Bidirectional linking.** If A links to B, B should link back to A (or be reachable via a hub node). After any linking pass, verify bidirectionality.
5. **Unique filenames are essential.** Duplicate filenames (e.g., `SOUL.md` × 4, `index.md` × 29) cause broken wikilinks and ambiguous resolution. Every `.md` file in the vault should have a unique slug. Before creating a file, check for naming collisions. This is the vault's SEO: each resource gets one canonical name.
6. **Obsidian compatibility.** `.neuron` files must be registered as markdown extensions. Template variables (`{doc_name}`) are acceptable orphans.
7. **Auto-generated orphans are by design.** Telemetry/log files that are write-only (never read back) should be excluded from graph view or deleted. Their inbound link count is 0 and will stay 0 — that's correct.
8. **Operational files stay out of the graph.** `cron/output`, `source/`, `.trash/`, `_agent/`, `venv/` should be in Obsidian `userIgnoreFilters`. They are runtime artifacts, not knowledge.

## Detection

```bash
# Dangling wikilinks (MEMORY.md targets that don't exist as files)
bash ~/.hermes/scripts/{{AGENT_NAME_LOWER}}_graph_gap_analysis.sh

# Full vault audit (Python — see references/vault-audit.py)
python3 references/vault-audit.py
```

## 3-Step Vault Health Protocol

### Step 1: Obsidian `.neuron` Compatibility

`.neuron` files are the actual rule definitions (13 P0 neurons), but Obsidian ignores non-`.md` extensions.

**Fix** (`~/.{{AGENT_NAME_LOWER}}/.obsidian/app.json`):
```json
{
  "extensionOverrides": [".neuron"]
}
```

This single change makes `[[禁task_qa_gate.neuron]]` resolve in Obsidian Graph View. No file renames, no path changes.

### Step 2: frontmatter `links:` → Body Wikilinks

Many vault files define crosslinks ONLY in YAML frontmatter. Obsidian Graph View sees these weakly or not at all. Mirror them into the body at the end of the file.

**Script approach** (one-time, across all core files):
1. Parse YAML frontmatter for `links:` list
2. Extract wikilink targets from each list item
3. Check which targets already appear in body wikilinks
4. Add missing targets under a `## Links` section at the file end

### Step 3: Bidirectional Crosslinks (incident ↔ neuron)

Incident docs (P6-prefrontal/incidents/) and neurons (P0-brainstem/禁*.neuron) should link to each other. Without this, the graph has two disconnected clusters.

**Mapping**: by topic affinity. Each incident doc gets `## Related Neurons`; each neuron gets `## Related Incidents`.

## ~~GBrain~~ → Knowledge DB (SQLite FTS5 + Ollama)

GBrain was removed on 2026-07-04/05. Replaced by:
- **`knowledge.db`** — SQLite FTS5 (keyword) + Ollama nomic-embed-text (vector)
- **`recall()` / `remember()`** — opencode native MCP tools (auto-discovered)
- **`scripts/recall.py`** — CLI equivalent

See AGENTS.md "Knowledge Management" section for full architecture.

## Auto-Generated Orphan Management

### Brain Signal Pattern (brain_signals_*.md)

The agent's `BrainSignalMonitor` writes session telemetry to `monitor/brain_signals_{ts}.md` when DeliveryRouter is unavailable. These files:

- Are **write-only by design** — agent never reads them back
- Accumulate rapidly (~170/day, 5000+/month)
- Clutter the Obsidian Graph as orphan nodes (0 inbound links)
- Duplicate data already in `gateway.log` and `brain_signal_log.jsonl`

**Fix**:
1. **Stop generating them**: remove the fallback `_deliver_fallback()` call in `brain_monitor.py:_deliver()`
2. **Delete existing**: `rm monitor/brain_signals_*.md`
3. **Keep**: `brain_signal_log.jsonl` (compressed, single-file alternative)

### General Pattern

When encountering auto-generated orphans:
1. Check if any code reads them back → if no, they're write-only telemetry
2. Check if the same data exists elsewhere (log files, JSONL) → if yes, the .md files are redundant
3. Decision: stop generating OR filter from graph view

## Cron Output Graph Bloat

Cron job output files (`~/.{{AGENT_NAME_LOWER}}/cron/output/<job_id>/`) accumulate every run as `.md` files. When a cron job loads a skill with frontmatter `links:` containing wikilinks, each output file embeds those links — creating a **massive star cluster** in the Obsidian graph view where a few hub nodes each have thousands of connections.

**Signature**: 3-5 hub nodes with 10K+ inbound edges each, forming a cluster that dwarfs the rest of the graph. The hub nodes are skill pages or implementation plans referenced in cron job context.

**Diagnosis**:
```bash
# Find the most common wikilinks — rank by frequency
grep -roh '\[\[[^]]*\]\]' ~/.{{AGENT_NAME_LOWER}} --include='*.md' | sort | uniq -c | sort -rn | head -20

# Check cron output volume
find ~/.{{AGENT_NAME_LOWER}}/cron/output -name '*.md' | wc -l

# Verify cron output embeds a skill with frontmatter links
head -30 ~/.{{AGENT_NAME_LOWER}}/cron/output/<job_id>/<recent-run>.md | grep -A5 '^links:'
```

**Root cause**: Cron job loads a skill → output template includes full skill text (frontmatter + body) → frontmatter `links:` wikilinks get baked into every output file → N runs × M links = N×M extra graph edges.

**Fix options** (in priority order):

| Option | When to use | How |
|--------|-------------|-----|
| 1. Exclude from Obsidian | Cron outputs are reference-only (agent reads via `session_search`, not vault browser) | Add `"userIgnoreFilters": ["cron/output"]` to `~/.{{AGENT_NAME_LOWER}}/.obsidian/app.json`. Note: use `cron/output` (not `cron/output/*`) — Obsidian interprets directory patterns as recursive. |
| 2. Move to `.trash/` | Need recovery option before deletion | `mkdir -p ~/.{{AGENT_NAME_LOWER}}/.trash && mv ~/.{{AGENT_NAME_LOWER}}/cron/output/<job_id> ~/.{{AGENT_NAME_LOWER}}/.trash/<label>-$(date +%Y%m%d)` |
| 3. Periodic cleanup | Old outputs accumulate without value | `find ~/.{{AGENT_NAME_LOWER}}/cron/output -name '*.md' -mtime +X -delete` as a cron job |
| 4. Fix cron template | You control the cron job; skill inline is unnecessary overhead | Strip frontmatter from output template, or remove wikilinks from stored artifact |

**Reference**: `references/cron-output-graph-bloat.md` has a full session diagnosis with concrete numbers and commands used. Read it when investigating an active graph bloat incident.

From humanerd-drew/opencode-drewgent, MIT.

More from humanerd-drew/opencode-drewgent