autograph — typed vault engine

One schema. One graph. Works on any vault.

Overview

No hardcoded domains, types, or paths. The agent discovers structure from data, builds a schema, then enforces it. All scripts share common.py. Zero external dependencies (stdlib only, API calls via urllib).

Quick Reference: 6 Workflows

Workflow 1: BOOTSTRAP (raw vault → structured graph)

When to use: New vault, bulk import, first setup. Run once, then switch to HEALTH.

Full guide: references/bootstrap-workflow.md

Summary (10 phases)

1. Discover: uv run scripts/discover.py <vault-dir> --verbose > /tmp/discovery.json
2. Generate schema: Script baseline (generate_schema.py) + agent swarm (swarm_prepare.py → Wave 1 haiku → swarm_reduce.py → Wave 2 sonnet). NEVER skip the swarm.
3. Review: Human approves schema. Never auto-apply.
4. Bootstrap + Enforce: engine.py init + enforce.py --apply
5. Link cleanup: link_cleanup.py --apply (before enrichment)
6. Tag enrich: enrich.py tags --apply (via OpenRouter API)
7. Deduplicate: dedup.py --apply (before link enrichment)
8. Link enrich: enrich.py swarm-links --apply (always swarm-links, never links)
9. MOC generation: moc.py generate
10. Verify: graph.py health + enforce.py → target 90+/100

Critical Rules

• Always run Phase 2B (agent swarm). Script alone cannot classify unstructured content.
• Always use swarm-links, not links (0.3% vs 81.6% match rate).
• Always dry-run first — run without --apply before applying.
• Dedup before link enrich — prevents links to merged/trashed files.

Workflow 2: HEALTH (daily graph maintenance)

When to use: Daily upkeep, after edits, or when health score drops. This is the most common workflow.

Decision Logic

1. Run `graph.py health <vault-dir>` → check score
2. If health < 90 → investigate:
   a. broken_links > 0  → `graph.py fix <vault-dir> --apply`
   b. orphans > 5       → connect orphans to hub files (see Workflow 4)
   c. desc_coverage < 70% → add descriptions to files missing them
3. Run `moc.py generate <vault-dir>` → regenerate indexes
4. Run `engine.py decay <vault-dir>` → recalculate relevance + tiers
5. Run `graph.py health <vault-dir>` → confirm improvement

Thresholds & Action Triggers

Commands

uv run scripts/graph.py health <vault-dir>           # health check
uv run scripts/graph.py fix <vault-dir> --apply       # fix broken links
uv run scripts/moc.py generate <vault-dir>            # regenerate MOCs
uv run scripts/engine.py decay <vault-dir>            # decay cycle (Ebbinghaus)
uv run scripts/engine.py decay <vault-dir> --dry-run  # preview decay changes
uv run scripts/engine.py stats <vault-dir>            # tier distribution
uv run scripts/engine.py creative 5 <vault-dir>       # resurface forgotten cards

Workflow 3: CREATE / UPDATE (dedup-first, then link)

When to use: Recording any card, or new information about something the vault may already track. Always look up first, always link immediately — a near-duplicate is the most common mistake; an orphan card is wasted knowledge.

Step 0: LOOKUP (mandatory — never skip)

uv run scripts/search.py "<entity / key phrase>" --vault <vault-dir> --json
# fallback: grep -ril "<name>" <vault-dir>

Pick the operation (full rules: references/update-in-place.md):

• ADD — no existing card → create it (steps 1–5 below).
• NOOP — already captured, unchanged → stop.
• UPDATE — same subject, new enrichment → open the card, sharpen description, append a dated line under ## Log, re-touch.
• SUPERSEDE — new fact contradicts a current value → rewrite the current value (frontmatter field + top of description = "Compiled Truth"), move the OLD value to append-only ## History (- 2026-03→2026-06 · company: TDI Group), set updated:. Whole card obsolete → status: superseded + superseded_by: [[new-card]].

Only when the operation is ADD, continue:

Steps (ADD path)

1. Type: Pick from schema node_types
2. Path: Reverse-lookup domain_inference to find target folder:

   # domain_inference maps path→domain. To find folder for domain "crm":
   for path_prefix, domain in schema['domain_inference'].items():
       if domain == 'crm':
           target_folder = path_prefix  # e.g. "work/crm/"
           break
   

3. Frontmatter: Write description (search snippet, not title repeat), tags (2-5, lowercase, kebab-case), status from type's enum
4. LINKING PROTOCOL (mandatory): a. Add ## Related section with [[hub]] file of the domain
   • Hub = _index.md or MEMORY.md of that domain b. Find 2-3 sibling cards of same type+domain → add [[links]]
   • uv run scripts/graph.py backlinks <vault> <hub> → find siblings
   • Or: read vault-graph.json → filter nodes by type+domain c. Run uv run scripts/engine.py touch <new-file>
5. Verify checklist:
   • Hub linked?
   • 2+ related cards found?
   • description ≠ title repeat?
   • tags: 2-5, lowercase, kebab-case?
   • status ∈ schema enum?

Templates: references/card-templates.md

Workflow 4: SEARCH & LINK (find + strengthen connections)

When to use: Looking up information in the vault, or strengthening weak areas of the graph.

Navigation (Hub → Links → Target)

1. Determine domain from the topic (work, personal, research, etc. — whatever your schema defines)
2. Start at hub: _index.md or MEMORY.md of that domain
3. Follow links — max 2 hops from hub to target
4. Fallback: uv run scripts/graph.py backlinks <vault> <target> for reverse links

Orphan Rescue

uv run scripts/graph.py orphans <vault-dir>        # find orphans
# For each orphan: connect to nearest hub or sibling card

Link Strengthening

# Files with <2 links → enrich
OPENROUTER_API_KEY=sk-... uv run scripts/enrich.py swarm-links <vault-dir> --apply
uv run scripts/graph.py health <vault-dir>          # verify improvement

Workflow 5: ORCHESTRATE (automated multi-agent workflows)

When to use: Instead of running scripts manually. No API keys — the Claude Code agent does all judgment directly.

Phase 0: Script sequencing

python3 scripts/orchestrate.py health <vault-dir>      # automated health workflow
python3 scripts/orchestrate.py bootstrap <vault-dir>    # full bootstrap (one command)

health runs: graph check > fix broken links > link cleanup > MOC > decay > verify. bootstrap runs: enforce > cleanup > tags > dedup > swarm-links > MOC > verify.

Phases 1-3: Agent judgment (no API keys)

The agent (you) does the judgment directly — read prepared data, decide, write results.

# Phase 1: prep de