vaultbase

README

VaultBase

RBAC-aware vault hosting, sync, and AI access layer for markdown knowledge bases.

One knowledge base for your whole company. Humans edit in Obsidian, AI agents read/write files directly, and VaultBase handles permissions, sync, and search.

Why

• No RBAC in Obsidian — if you can see the vault, you can see everything
• No AI access control — every existing MCP server gives agents full vault access
• No single source of truth — company knowledge is scattered across Notion, Confluence, Google Docs, and random markdown files

VaultBase fixes all three. Plain markdown files, granular permissions, and three ways for AI agents to access scoped content.

How It Works

  AI Agent (Claude Code)           Human (Obsidian)
       |                                |
       | reads/writes files             | reads/writes files
       | natively on disk               | natively on disk
       |                                |
       v                                v
  ~/.vaults/company/              ~/.vaults/company/
       |                                |
       +---- vaultbase sync ----------+
                    |
                    v
            VaultBase Server
            (RBAC, search, audit log, MCP, web UI)

Files live on disk. Everyone edits them normally. VaultBase syncs and enforces permissions.

Quick Start

Install

# From source
git clone https://github.com/MimirLLC/vaultbase && cd vaultbase
make build

# Or just Go
go install github.com/MimirLLC/vaultbase/cmd/vaultbase@latest

Set Up a Vault

# Initialize
mkdir -p ~/vault/engineering ~/vault/sales
vaultbase init ~/vault company

# Create a user
vaultbase user create admin@company.com "Admin" "password123"
vaultbase role assign company owner admin@company.com

# Set permissions
vaultbase permission add company owner folder "/**" "read,write,delete,admin"

# Start the server
vaultbase serve --vault=company --addr=0.0.0.0:8990

Connect

Web UI — open http://localhost:8990, log in with email/password

AI Agent (local files) — point your agent at the synced vault directory:

vaultbase clone --server=http://your-server:8990 --email=agent@co.com --password=pass ~/.vaults/company
vaultbase sync --path=~/.vaults/company

AI Agent (MCP) — add to your MCP config:

{
  "vaultbase": {
    "url": "http://your-server:8990/mcp",
    "headers": { "Authorization": "Bearer vk_your_api_key" }
  }
}

AI Agent (skill files) — zero-overhead static bundles:

vaultbase pull-skills --vault=company --role=engineering-agent -o ./skills/
# Drop engineering-agent.skill.md into your project's CLAUDE.md includes

RBAC

Permissions are scoped by folder, file, or frontmatter tag:

# Engineering team reads/writes their folder
vaultbase permission add company engineering-editor folder "/engineering/**" "read,write"

# Sales agents can read anything tagged #public
vaultbase permission add company sales-agent tag "#public" "read"

# Block HR docs from agents
vaultbase permission add company agent folder "/hr/**" "read" --effect=deny

# Per-user folders — {user} expands to the user's email prefix
vaultbase permission add company employee folder "/users/{user}/**" "read,write"
# shane@co.com → can access /users/shane/**
# alice@co.com → can access /users/alice/**

Context Graph

Every decision becomes searchable precedent. The reasoning connecting data to action is captured as data itself.

# Before deciding — check how similar situations were handled
vaultbase trace precedent --type=pricing "annual contract discount"

# After deciding — record the decision with full context
vaultbase trace create --vault=company --type=pricing \
  --summary="8% discount for Acme renewal" --decision=approved \
  --input="/sales/acme.md:primary" --input="/policies/pricing.md:governing" \
  --tag=pricing --tag=discount

# Record what happened
vaultbase trace outcome dt-2026-04-05-001 --status=successful \
  --notes="Contract renewed. Revenue maintained."

# Get a briefing before starting work
vaultbase briefing --vault=company --task="pricing request"

# See what documentation is missing
vaultbase gaps --vault=company

# Track policy revisions — flag stale decisions
vaultbase revision record /policies/pricing.md --vault=company --rev=v4
vaultbase revision stale dt-2026-04-05-001

CLI Reference

# Setup
vaultbase init <path> <name>          Initialize a vault
vaultbase serve --vault=<name>        Start the server
vaultbase login <email> <password>    Get an API key

# Users & teams
vaultbase user create/list            Manage users
vaultbase role list/assign/revoke     Manage roles
vaultbase group create/add/assign-role  Manage teams
vaultbase permission add/list         Manage permissions
vaultbase apikey create/list          Manage API keys

# Vault content
vaultbase vault files/read/search/query   Vault operations (--as=user for RBAC)
vaultbase pull-skills                 Generate skill files

# Context graph
vaultbase trace create/search/precedent/outcome/list/get
vaultbase briefing                    Agent context briefing
vaultbase gaps                        Knowledge gap report
vaultbase revision record/history/stale  Document revision tracking

# Sync
vaultbase clone                       Clone vault from server
vaultbase sync                        Start sync daemon
vaultbase status                      Show sync status

MCP Tools (25)

Vault content: vault_list, vault_read, vault_search, vault_query Context graph: trace_create, trace_find_precedent, trace_update_outcome, trace_search Intelligence: vault_briefing, vault_gaps, vault_doc_revision, vault_revision_history, vault_stale_check Write-back: vault_learn, vault_update_doc, vault_index Admin: admin_list_users, admin_create_user, admin_list_roles, admin_create_role, admin_assign_role, admin_add_permission, admin_list_permissions, admin_create_apikey, admin_audit_log

Self-Hosting

Docker

docker build -t vaultbase .
docker run -p 8990:8990 \
  -v /path/to/vault:/vault \
  -v /path/to/data:/data \
  vaultbase

Systemd

[Unit]
Description=VaultBase
After=network.target

[Service]
ExecStart=/usr/local/bin/vaultbase serve --vault=company --addr=0.0.0.0:8990
Restart=always
User=vaultbase

[Install]
WantedBy=multi-user.target

Architecture

• Go server + CLI + sync daemon (single binary, FTS5 search)
• SQLite for metadata, context graph, revision tracking, search index
• Filesystem for vault content (plain markdown files)
• React + TypeScript web UI
• Astro marketing site
• Tauri 2 desktop editor (vaultbase-editor)
• MCP server with 25 permission-scoped tools
• Claude plugin with skills, commands, and agents

License

AGPL-3.0