← Back to docs

Vault description and VAULKEN.md

An AI assistant connects to Vaulken knowing nothing about the vault. It can read and write files, but it does not know what the vault is for, how the files are organized, or which conventions to follow.

Two mechanisms give it that context before the first message: the vault description and a VAULKEN.md file.

Vault description

The vault description is a short text you set in the dashboard when creating or editing a vault. It goes into the MCP server instructions your AI receives at the start of every session, right after the vault name:

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

Keep it to one or two sentences. Its job is to tell the AI what the vault is about at a glance.

When you have multiple vaults

With several vaults in the same AI session, the description is what lets the AI choose. It sees a list of MCP servers and has to pick one for each task:

  • "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 it only sees vault names and has to guess.

Tips for writing a good description

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

VAULKEN.md

VAULKEN.md is a file you place at the root of the vault. Vaulken reads it and adds its content to the MCP server instructions, so your AI has it before the conversation starts. It works like a system prompt scoped to one vault.

What to put in VAULKEN.md

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

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, the MCP server reads VAULKEN.md from the vault root and puts its first 80 lines in the server instructions. Past that, the AI sees a truncation notice and can read the full file with the read tool.

The file name must be exactly VAULKEN.md, uppercase, at the root. A file in a subdirectory such as docs/VAULKEN.md is ignored.

VAULKEN.md vs vault type

If the vault type is Obsidian, Vaulken already injects Obsidian conventions (frontmatter, wikilinks, canvas files, bases). VAULKEN.md adds to those instructions rather than replacing them, so use it for the project-specific part.

Description vs VAULKEN.md

Description VAULKEN.md
Where Dashboard (vault settings) File at vault root
Length 1-2 sentences As long as needed
Purpose Identify the vault among others Detailed instructions for the AI
Visibility Always shown, even before opening the vault Read when the AI connects
Editable by Dashboard UI Your AI or any sync tool

Use both: the description identifies the vault, VAULKEN.md explains how to work in it.

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