Guide your AI with vault description and VAULKEN.md

Your AI assistant connects to Vaulken with no prior knowledge of what your vault contains. Out of the box, it can read and write files, but it does not know what the vault is for, how your files are organized, or what conventions to follow.

Two mechanisms let you give your AI the right context from the very first message: the vault description and the VAULKEN.md file.

Vault description

The vault description is a short text you set in the dashboard when creating or editing a vault. It appears in the MCP server instructions that your AI receives at the start of every session.

What your AI sees:

This MCP server gives access to the vault "My notes". Personal knowledge base
with meeting notes, project docs, and reading highlights.

The description is injected as a single line right after the vault name. Keep it concise (one or two sentences). Its purpose is to help your AI understand what this vault is about at a glance.

When you have multiple vaults

If you connect several vaults to the same AI session, the description becomes essential. Your AI sees a list of available MCP servers and needs to decide which vault to use for a given task. A clear description makes that choice obvious:

• "My notes" | Personal knowledge base with meeting notes and reading highlights
• "Work docs" | Technical documentation for the Acme API project
• "Blog" | Draft articles and editorial calendar for my tech blog

Without descriptions, your AI would only see vault names and would have to guess which one to query.

Tips for writing a good description

• Focus on what the vault contains, not how it works
• Mention the type of content: notes, documentation, code snippets, articles
• If the vault has a specific scope, say it: "only contains meeting notes from Q1 2026"
• Keep it under two sentences

VAULKEN.md

VAULKEN.md is a special file you place at the root of your vault. Vaulken reads it automatically and injects its content into the MCP server instructions. Your AI receives these instructions before the conversation starts, so it knows how to behave from the first message.

Think of it as a briefing document for your AI. It is the equivalent of a system prompt, but specific to this vault.

What to put in VAULKEN.md

There are no strict rules. Write whatever helps your AI work better with your files. Common sections include:

Project context:

## Context
This vault contains the documentation for Vaulken, an MCP server
for S3-compatible storage. Stack: Node.js, React Router, Prisma, Qdrant.

File organization:

## Structure
- Architecture/ — ADRs and system design docs
- Specs/ — Technical specifications
- Roadmap/ — Phase plans and task tracking

Conventions:

## Conventions
- File names: PascalCase with dashes (e.g., My-Document.md)
- All notes use YAML frontmatter with: title, date, status, tags
- Status values: draft, review, done
- Tags are always lowercase

Rules and preferences:

## Rules
- Never delete files without asking first
- Always add a "date" property when creating new notes
- Write in French unless the file is already in English
- Use bullet points, not numbered lists

Workflow instructions:

## Workflow
- Before editing a file, always read it first to get the current hash
- When creating meeting notes, use the template in templates/meeting.md
- After modifying a spec, update the related ADR if one exists

How it works technically

When your AI connects to a vault, the MCP server reads VAULKEN.md from the vault root and includes the first 80 lines in the server instructions. If your file is longer, your AI sees a truncation notice and can read the full file with the read_file tool.

The file name must be exactly VAULKEN.md (uppercase) at the root of the vault. Subdirectory files like docs/VAULKEN.md are not detected.

VAULKEN.md vs vault type

If your vault type is set to Obsidian, Vaulken already injects Obsidian-specific conventions (frontmatter, wikilinks, canvas files, bases). Your VAULKEN.md adds to these instructions, it does not replace them. Use it for project-specific context that goes beyond generic Obsidian conventions.

Description vs VAULKEN.md

Use both together. The description is the label on the box. VAULKEN.md is the instruction manual inside.

Example

A vault called "Blog" with this description:

Draft articles, editorial calendar, and publishing workflow for my tech blog.

And this VAULKEN.md:

# Blog vault instructions

## Context
Tech blog at myblog.dev, built with Next.js. Articles are Markdown files
with YAML frontmatter.

## Structure
- posts/ — Published and draft articles (filename = URL slug)
- plan/ — Editorial calendar and series planning

## Frontmatter convention
Every article must have: title, slug, description, date, tags, publishedAt.
Leave publishedAt empty for drafts.

## Rules
- Article filenames must match the slug (e.g., my-article.md for /blog/my-article)
- Always write in French
- Never modify a published article without asking first
- When creating a new article, check plan/ for the editorial calendar

With this setup, your AI knows the vault purpose, the file structure, the naming rules, and the editorial workflow before you even ask your first question.