autograph

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: 5 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 (new card with immediate linking)

When to use: Creating any new vault card. Always link immediately — orphan cards are wasted knowledge.

Steps

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 dedup clusters for YOUR review
python3 scripts/orchestrate.py dedup-prepare <vault-dir>
# -> writes .graph/dedup-review-input.json
# -> YOU read clusters, mark approved=true, then: dedup.py --apply-manifest

# Phase 2: prep domain catalogs for YOUR link suggestions
python3 scripts/orchestrate.py link-prepare <vault-dir>
# -> writes .graph/link-review-input.json
# -> YOU read catalogs, suggest links per domain, write batch results

# Phase 3: prep graph data for YOUR semantic analysis
python3 scripts/orchestrate.py graph-prepare <vault-dir>
# -> writes .graph/graph-analysis-input.json
# -> YOU analyze contradictions, missing links, stale hubs, write findings

For Phases 1-3: run the prep command, read the output JSON, do the analysis yourself (you ARE the LLM), write results back. Use Agent tool for parallel domain work in Phase 2.

---

---

Decay Engine (Ebbinghaus)

The decay system models memory with three key mechanisms:

1. Access count (spacing effect)

Each touch increments access_count in frontmatter. More retrievals = slower forgetting:

strength = 1 + ln(access_count)
effective_rate = base_rate / strength
relevance = max(floor, 1.0 - effective_rate * days_since_access)

Example: a card touched 5 times has strength = 1 + ln(5) ≈ 2.6, decaying ~2.6x slower than a card touched once.

2. Domain-specific rates

Different content types decay at different rates. Configure in schema decay.domain_rates:

3. Graduated recall

Touch promotes one tier at a time, not a direct jump to active:

archive → cold → warm → active

Each promotion sets last_accessed to a midpoint date, so without re-touch the card naturally drifts back.

Backward compatibility

• Files without access_count → default=1 → 1+ln(1)=1.0 → rate unchanged
• Files without type → default rate applies
• Existing calls calc_relevance(days, schema) → work unchanged (new params optional)

---

Maintenance Commands

uv run scripts/moc.py generate <vault-dir>                                       # MOC generation
uv run scripts/engine.py decay <vault-dir>                                       # decay cycle
uv run scripts/engine.py touch <vault-dir>/path/card.md                          # touch (graduated)
uv run scripts/engine.py creative 5 <vault-dir>                                  # creative recall
uv run scripts/engine.py stats <vault-dir>                                       # stats
uv run scripts/graph.py backlinks <vault-dir> path/to/card                       # backlinks
uv run scripts/graph.py orphans <vault-dir>                                      # orphans
uv run scripts/graph.py fix <vault-dir> --apply                                  # fix links
uv run scripts/daily.py extract <memory-dir> <vault-dir>                         # entity extraction
uv run scripts/engine.py init <vault-dir> --dry-run                              # bootstrap bare files
OPENROUTER_API_KEY=sk-... uv run scripts/enrich.py swarm-links <vault-dir> --apply  # link enrichment
OPENROUTER_API_KEY=sk-... uv run scripts/enrich.py tags <vault-dir> --apply         # tag enrichment
uv run scripts/link_cleanup.py <vault-dir> --apply                               # link cleanup

Scripts

Files

Common Mistakes

Default Models

Both are production-tested. Do not change defaults without benchmarking.

Troubleshooting

Error: Schema not found → Create schema.json from discover output, or pass path: enforce.py vault/ my-schema.json

Score drops after enforce → New files without frontmatter. Run engine.py init vault/

Dedup picks wrong canonical → Content richness wins. Enrich the right file first, re-run.

Low match rate on swarm-links (<60%) → Check if LLM returns paths instead of stems. Try --force for second pass.

swarm-links shows 0 matched for some batches → Usually network errors. Results are cached — rerun and only failed batches retry.