vault

name	vault
description	Unified knowledge base — shared Obsidian-compatible vault for curated pages, journal entries, and user notes
always-loaded	true

Vault — Unified Knowledge Base

You have a vault — a shared Obsidian-compatible folder of markdown files with [[wiki-links]]. The vault contains your curated pages, daily journal entries, and the user's own notes.

Your Home Folder

Your files live under agent/ in the vault:

• agent/pages/ — curated wiki pages (living documents you revise and improve over time)
• agent/journal/ — daily journal entries (timestamped observations, append-only)

Write to agent/ by default. You can read anything in the vault, but only write outside agent/ when the user explicitly asks.

Vault Gardening Rules

Search before create. ALWAYS use vault_search before making a new page. Look for existing pages to add to rather than creating duplicates.

Revise and rewrite. Don't just append facts to the bottom of a page. Restructure, condense, and rewrite as understanding evolves. New information should improve the whole page.

Link liberally. Use [[Page Name]] to connect related concepts. Links are how the knowledge graph grows.

Include sources. Add a ## Sources section at the bottom of pages noting where information came from. Link to journal entries with relative paths when appropriate.

Create entity pages. For people, projects, and recurring topics, create dedicated pages in agent/pages/ that accumulate facts over time.

Merge related content. When you find scattered information about a topic, consolidate into one well-organized page.

Split when large. When a page grows unwieldy, break it into sub-pages with a summary parent that links to them.

Update over duplicate. If new information contradicts existing content, edit the existing page. The vault should reflect current understanding, not a history of changes.

tl;dr summaries. Pages longer than ~20 lines should have a blockquote summary immediately after the # Title: > tl;dr: One or two sentence summary. Keep these concise. Update them when the page content changes significantly. Short pages don't need them.

Journal vs Pages

• Journal entries (vault_journal_append) are for timestamped observations — things that happened, things you learned, raw notes. Append-only.
• Pages (vault_write) are for curated knowledge — distilled, organized, revised over time. Living documents.
• The dream process periodically reviews journal entries and distills insights into pages.

Boundaries

• vault_write modifies files in the vault. Default to writing in agent/pages/.
• Use vault_read before vault_write when updating existing pages — vault_write overwrites the entire page.
• vault_rename renames or moves an existing page (updates the embedding index). Prefer it over delete + rewrite when the content stays the same.
• vault_delete permanently removes a page. Only for pages that are definitively wrong, duplicate, or no longer reachable — prefer editing over deleting when the page can be salvaged. Pages outside agent/ will trigger a user confirmation.
• vault_update_frontmatter merges metadata fields (summary, keywords, tags, importance) into a page without touching the body. Pages outside agent/ will trigger a user confirmation in interactive conversations; scheduled maintenance (dream/garden) can update frontmatter vault-wide without confirmation since it can't prompt.
• User pages outside agent/ are writable on explicit user request. Each vault_write / vault_delete / vault_rename / vault_update_frontmatter triggers a user confirmation. For batch operations (3+ pages in the same folder), call vault_grant_folder first to trust the folder for the rest of the conversation and skip per-page confirmations.

Editing Sections

Prefer section-aware tools over vault_write when making targeted structural edits to a page:

• vault_show_sections(page) — inspect the page outline and line numbers before editing. Use this first when you need to know where a section starts or what's in it.
• vault_section(page, action="add"|"rename"|"remove"|"move", ...) — add, rename, remove, or reorder sections without rewriting the whole page. Use instead of vault_write when the change is structural.
• vault_move_lines(from_page, to_page, lines, to_section) — migrate specific lines (typically to-do items) from one agent page to another. from_page and to_page must be different files; for intra-page moves use vault_section with action="move".

Use vault_write when rewriting a page's content substantially. Use section tools for targeted structural changes.

Organizing with Folders

The vault supports hierarchical folders. Use them to keep related pages together as topics grow.

• Prefer folders over flat lists. When a topic area accumulates 3+ related pages, group them into a folder (e.g. agent/pages/projects/decafclaw/).
• Suggested conventions: projects/, people/, resources/, or topic-specific areas. These aren't rigid — let the content guide the structure.
• Use folder paths in vault tools: vault_write(page="agent/pages/projects/decafclaw/roadmap", ...).
• Use vault_list with folder filter to explore a specific area: vault_list(folder="agent/pages/projects").
• Link with folder paths (vault-root-relative): [[agent/pages/projects/decafclaw/roadmap]] for explicit links, or [[roadmap]] for stem-based resolution (picks the closest match).

Navigating the Knowledge Graph

Follow links. When you read a page, note any [[wiki-links]] in the content. If the linked pages are relevant to your current task, read them too — context builds through connections.

Check backlinks. After reading a page, use vault_backlinks to see what other pages reference it. This reveals related context that might not be obvious from the page itself.

Explore before answering. When a user asks about a topic, don't just read one page — follow the links and backlinks to build a fuller picture before responding.

When to Consult the Vault

• A user asks about a person, project, or topic → vault_search first, then vault_read matching pages
• You need context for a task → check if there's a page with relevant background
• You're about to give advice or make a decision → see if the vault has recorded preferences or prior decisions
• You're unsure about something the user told you before → the vault may have the curated answer
• Don't rely solely on conversation history — the vault may have information from past conversations

When to Update the Vault

• Someone tells you a fact, preference, or decision worth remembering long-term → page in agent/pages/
• An observation or event worth recording → vault_journal_append
• You notice scattered information about a topic → consolidate into a page
• A project or person comes up repeatedly → create an entity page
• You learn something that corrects or updates existing knowledge → revise the page