vault-knowledge

Vault Knowledge

The Obsidian vault ("Claude") is your persistent knowledge layer. Interact with it using vlt (the fast vault CLI) via Bash. Prefer vlt for vault-aware operations (search, create, move with wikilink repair, backlinks, tags).

Vault path: Resolve dynamically with vlt vault="Claude" dir (never hardcode).

Two-Tier Knowledge Model

Tier 1: Global Vault ("Claude")

Shared across ALL projects. Cross-project knowledge only.

Folder	Contains	Auto-Tag
methodology/	Agent prompts, Paivot workflow	#dev-tools/workflow
conventions/	Operating mode, checklists	#dev-tools/workflow
decisions/	Cross-project decisions	Domain-based
patterns/	Cross-project patterns	Domain-based
debug/	Cross-project debug insights	Stack-based
concepts/	Language/framework knowledge	Stack-based
projects/	Project index notes (not logs!)	Project domain
people/	Team preferences	#dev-tools/workflow
_inbox/	Unsorted capture	(triage required)

Governance: New captures can go through /vault-capture. Changes to protected system notes go through /vault-evolve (proposal) and /vault-triage (review/apply).

Tier 2: Project Vault (.vault/ in each repo)

Scoped to a single project. Changes apply directly.

.vault/
  knowledge/         # Project-local knowledge managed via vlt
    conventions/     # Project-specific conventions
    decisions/       # Project-specific decisions
    patterns/        # Project-specific patterns
    debug/           # Project-specific debug insights
    skills/          # Project-specific synthesized skills
    .settings.yaml   # Project settings managed by pvg

Separation: knowledge/ is for durable project knowledge. Other .vault/ paths are runtime state managed by pvg/nd, not a manual session-log area.

Controlled Domain Vocabulary

Use these domain values in frontmatter. Prefer the granular dev-tools-* values for new captures; older seeded notes may still use the legacy values listed here.

Domain	Description	Auto-Tag
ai-training	ML model training, fine-tuning, optimization	#ai/training
ai-inference	Model inference, reasoning, neuro-symbolic	#ai/inference
ai-agents	Agent orchestration, multi-agent systems	#ai/agents
ai-nlp	Natural language processing, NER, classification	#ai/nlp
developer-tools	Legacy seeded Paivot system notes; prefer dev-tools-* for new notes	#dev-tools/workflow
dev-tools-cli	CLI tools, build systems, package managers	#dev-tools/cli
dev-tools-testing	Testing frameworks, test patterns	#dev-tools/testing
dev-tools-workflow	Development workflow, methodology	#dev-tools/workflow
dev-tools-knowledge	Knowledge management, vault patterns	#dev-tools/knowledge
product-management	Product and backlog management practices	#product/management
security-gateway	API gateways, middleware, auth	#security/gateway
security-hardening	Security fixes, vulnerability remediation	#security/hardening
security-compliance	Regulatory compliance, audit	#security/compliance
finance-quant	Quantitative finance, backtesting	#finance/quant
finance-fintech	Fintech applications, payments	#finance/fintech
frontend-ui	UI components, design systems	#frontend/ui
frontend-performance	Web performance, optimization	#frontend/performance
calendar-sync	Calendar federation, scheduling	#calendar/sync

Auto-Tagging Rules

Tags are derived from folder + domain. Never manually add tags to frontmatter.

Folder	Base Tag	Plus Domain Tag
methodology/	#dev-tools/workflow	-
conventions/	#dev-tools/workflow	-
decisions/	-	#<domain> (from domain field)
patterns/	-	#<domain> (from domain field)
debug/	#dev-tools/cli	#<stack> if relevant
concepts/	-	#ai/<subtype> based on stack
projects/	-	#<domain> (from domain field)

Tags appear in the note body as a ## Tags section at the bottom, not in frontmatter.

Note Template

Every note MUST follow this structure:

---
type: <pattern|debug|decision|concept|convention|methodology>
project: <project-name-or-general>
stack: [<list-of-technologies>]
domain: <from-controlled-vocabulary>
status: active
confidence: high|medium|low
created: YYYY-MM-DD
---

# Title

One-line summary of what this note captures.

## Context (optional)

Why this matters, when it applies.

## Content

Main body - the actual knowledge.

## Related

- [[Link to related note 1]]
- [[Link to related note 2]]

## Tags

#auto-derived-tag #another-tag

Required Fields

• type: pattern, debug, decision, concept, convention, methodology
• project: Project name or "general" for cross-project
• domain: MUST be from controlled vocabulary above
• status: active, superseded, archived
• confidence: high (verified), medium (tested once), low (hypothesis)
• created: ISO date

Required Sections

• Summary: First paragraph after title
• Related: At least ONE wikilink to connect the knowledge graph
• Tags: Auto-derived, placed at bottom

When to Capture

Trigger	Type	Folder
Chose X over Y	decision	decisions/
Found reusable solution	pattern	patterns/
Solved non-obvious bug	debug	debug/
Learned framework gotcha	concept	concepts/
Established team rule	convention	conventions/
Session starting	(read)	projects/ + linked notes
Session ending	(update)	projects/

How to Create Notes

Step 1: Determine if Cross-Project or Project-Specific

Ask: "Would this help someone working on a DIFFERENT project?"

• Yes -> Global vault
• No -> Project vault .vault/knowledge/

Step 2: Create with vlt

pvg notes create "_inbox/<Title>.md" --title "<Title>" --body "---
type: <type>
project: <project>
stack: [<stack>]
domain: <from-vocabulary>
status: active
confidence: <level>
created: $(date +%Y-%m-%d)
---

# <Title>

<one-line summary>

## Content

<main content>

## Related

- [[<related note>]]
"
# (vlt-only `silent` flag dropped)

Step 3: Triage Immediately

Don't leave notes in _inbox/. Move to correct folder:

vlt vault="Claude" move path="_inbox/<Title>.md" to="<folder>/<Title>.md"

Step 4: Verify Links

Ensure at least one wikilink exists. If creating a new concept, link to related concepts or the project note.

How to Read

# Single note (provider-abstracted; pass full path if not at vault root)
pvg notes read "<Note Title>"

# Graph operations are vlt-specific (no provider abstraction): wikilink traversal
# and backlink computation do not generalize to non-Markdown backends. Use these
# escape hatches when you need transitive context from the Claude vault:
vlt vault="Claude" read file="<Note Title>" follow      # graph traversal
vlt vault="Claude" read file="<Note Title>" backlinks   # incoming links

How to Search

# Text search
pvg notes search "<term>"

# By domain
pvg notes search "[domain:ai-agents]"

# By project
pvg notes search "[project:reader]"

How to Update

# Append to note
pvg notes append "<Note Title>" --body "<new content>"

# Replace a section (vlt-only: `patch` has no pvg equivalent yet)
vlt vault="Claude" patch file="<Note Title>" heading="## Section" content="<new section>"

# Set property
pvg notes property:set "<Note Title>" "status" "superseded"

Session Workflow

Session Start

1. Detect project from git remote or directory
2. Read project note + follow links:

   pvg notes read "<Project>"
   # For transitive expansion (linked decisions, patterns, debug, sessions),
   # use the vlt escape hatch -- graph traversal is vlt-specific:
   #   vlt vault="Claude" read file="<Project>" follow
   

3. Check for project-specific knowledge in .vault/knowledge/

Session End

1. Run /vault-capture to save new knowledge
2. Update project note with session summary
3. Check _inbox/ size - warn if > 5 notes

Pre-Compact

Warn if vault needs attention:

inbox_count=$(vlt vault="Claude" files folder="_inbox" total)
orphans=$(vlt vault="Claude" orphans --json | jq length)
if [ "$inbox_count" -gt 5 ] || [ "$orphans" -gt 10 ]; then
  echo "Vault needs attention: $inbox_count in inbox, $orphans orphans"
fi

Project Notes Are Indexes, Not Logs

The project note in projects/ should be:

• A summary of the project (stack, domain, purpose)
• Links to key decisions, patterns, and concepts
• Brief session log entries (1-2 lines each, including the ## Session log (...) entries appended by pvg at session end)

NOT:

• Full execution logs
• Story-by-story completion records
• Verbose session transcripts

Keep detailed execution history in nd story notes, git history, or Claude memory when needed. Paivot does not manage a .vault/sessions/ tree.

The Rules

1. Every note needs a link - No orphans. Knowledge is a graph.
2. Use controlled domains - No ad-hoc domain values.
3. Tags go in body - Not frontmatter (Obsidian limitation).
4. Triage immediately - Don't let _inbox/ accumulate.
5. Capture as you go - Not at the end. Memory decays.