OpenClaw Vault Plugin

An OpenClaw plugin that turns a local directory into a structured knowledge vault. It replaces Obsidian by keeping everything in plain markdown, but still delivers fast semantic search and embeddings through qmd.

Features

• Local-first vault directory with opinionated structure
• QMD-powered search (keyword, semantic, hybrid)
• Frontmatter framework for tags, people, projects, sources
• Optional git sync (pull before, push after)
• CLI + tools + Gateway RPC
• Auto-installs qmd via bun or npm when missing

Installation

openclaw plugins install openclaw-plugin-vault

Or from GitHub:

openclaw plugins install github:pepicrft/openclaw-plugin-vault

Configuration

Add to your OpenClaw config:

{
  plugins: {
    entries: {
      "openclaw-plugin-vault": {
        enabled: true,
        config: {
          vaultPath: "/Users/you/Vault",
          collectionName: "vault",
          gitRemote: "origin",
          gitBranch: "main",
          gitSync: true,
          gitAutoCommit: true,
          autoInstallQmd: true,
          mask: "**/*.md"
        }
      }
    }
  }
}

Vault Framework

Folder Convention

• inbox/ -> raw captures and quick dumps
• notes/ -> evergreen notes and cleaned-up knowledge
• people/ -> bios, conversations, relationship notes
• projects/ -> project briefs, decision logs, retrospectives
• concepts/ -> definitions, frameworks, mental models
• logs/ -> daily notes and timelines

Frontmatter Rules

Every note should start with YAML frontmatter. Required keys:

• title
• created
• updated

Recommended keys:

• summary: one-line description
• status: seed | sprout | evergreen | stale
• tags: topical keywords
• people: names or handles
• projects: related project names
• sources: [{ title, url }]

Example:

---
title: "Decision: Use QMD for search"
summary: "Why the vault uses qmd for embeddings and querying"
status: "evergreen"
created: "2026-01-03T12:00:00.000Z"
updated: "2026-01-03T12:00:00.000Z"
tags:
  - "search"
  - "qmd"
people:
  - "Pedro"
projects:
  - "Vault"
sources:
  - title: "QMD README"
    url: "https://github.com/tobi/qmd"
---

Body starts here.

Usage

CLI

# Initialize the vault structure
openclaw vault init

# Add a note
openclaw vault add "Decision: QMD" "We index the vault using qmd" \
  --tags search,qmd --projects Vault --status evergreen

# Query (hybrid search by default)
openclaw vault query "knowledge systems" --mode query --limit 5

# Get a document by path or docid
openclaw vault get "notes/decision-qmd.md"

# Refresh index
openclaw vault index --embed

Tools (for agents)

• vault_add_note
• vault_query
• vault_embed

Gateway RPC

• vault.add
• vault.query

Git Sync

If gitRemote is configured (or the vault already has a remote), the plugin:

1. Pulls before reading or writing
2. Auto-commits changes (when gitAutoCommit is true)
3. Pushes after writing

QMD Setup

The plugin auto-installs qmd if missing:

• Uses bun install -g https://github.com/tobi/qmd when bun is available
• Falls back to npm install -g https://github.com/tobi/qmd

If you want to manage qmd manually, set autoInstallQmd: false.

Requirements

• Node 20+
• bun or npm for installing qmd (unless qmd already installed)

Tests

npm test
npm run build