Obsidian and durable knowledge

Obsidian is the human-facing knowledge layer, but Markdown is the durable format. The distinction is important: the notes should remain readable in VS Code, searchable from a terminal, and usable by agents without requiring Obsidian itself.

What belongs in the vault

• project briefs and current state;
• research notes with provenance;
• decision records and their consequences;
• active task lists;
• experiment observations;
• session summaries when continuity would otherwise be lost.

Canonical code and application configuration still belong in their repositories. The vault explains the work; it should not become a shadow copy of the codebase.

Links and indexes

Wiki links are convenient inside Obsidian, but ordinary Markdown links travel better across GitHub, documentation generators, editors, and agent tools. Explicit index pages provide reliable entry points even when graph views and backlinks are unavailable.

Use links to expose meaningful relationships, not to connect every noun. A small number of useful paths beats a dense graph with no clear starting point.

Provenance and confidence

Notes should distinguish sourced facts, human decisions, working hypotheses, and generated ideas. Where accuracy matters, record the source and the date. This allows an agent to reason about whether a note is authoritative, provisional, or stale.

The workspace uses YAML frontmatter to keep these trust signals consistent and visible in both Obsidian and ordinary text tools.

Avoiding knowledge landfill

Capture is only the first step. Notes need a destination and responsibility:

• raw material is preserved with provenance;
• useful findings are distilled into project documentation;
• decisions move into a durable decision log;
• completed operational detail can move into history;
• obsolete claims are corrected or explicitly superseded.

The vault becomes valuable when it reduces rediscovery, not simply when it contains more text.