---
name: vaultbase
description: >
  VaultBase is a decision memory layer for organizations — a knowledge base
  with RBAC, a three-tier identity stack, decision traces, and 27 MCP tools.
  Drop this file into your agent (CLAUDE.md, Cursor rules, system prompt) to
  get installation, MCP wiring, identity setup, and the full tool reference
  in one place.
source: https://getvaultbase.com/skill.md
---

# VaultBase — Agent Skill File

You're reading this because an agent (or the human supervising one) wanted to
connect to VaultBase. This file tells you everything you need: how to install
it, how to authenticate, how to wire up MCP, how the identity stack and
decision traces work, and the full behavioural rules for being a good citizen
of a VaultBase vault.

> **TL;DR** — VaultBase stores knowledge **and the reasoning behind decisions
> made from that knowledge.** Read the identity stack first, check precedent
> before making judgment calls, record the decisions you make, and write
> learnings back. The next agent (or human) finds your reasoning and builds
> on it.

---

## 1. What is VaultBase?

- **A knowledge base** — plain markdown files on disk, full-text searchable,
  version-controlled by the filesystem.
- **RBAC-aware** — folder/file/tag permissions, per-user folders via
  `{user}` expansion, deny-wins resolution, groups and roles.
- **A decision graph** — every judgment call is captured as a trace with
  inputs, policies, reasoning, tags, and outcomes. Searchable precedent.
- **An identity stack** — three tiers of context (org, team, individual) that
  load at the top of every agent briefing.
- **Offline-first sync** — durable local queue, 3-way merge conflict
  resolution, live SSE updates when online.
- **An MCP server** — 27 tools covering vault reads, trace ops, briefings,
  admin, identity, and knowledge write-back.

Self-hostable (AGPL-3.0, single Go binary) or cloud-hosted at
`getvaultbase.com` from $4/mo.

---

## 2. Installation

### Option A — Cloud (fastest)

1. Sign up at https://getvaultbase.com/signup — pick a vault slug like
   `acme` → you'll get `acme.getvaultbase.com`.
2. You land in the web UI as the vault owner with full permissions.
3. Create an API key for your agent:
   ```
   Web UI → Admin → API Keys → Create
   Name: "claude-code"
   Role: owner   (or a more scoped role)
   ```
4. Copy the `vk_...` key (shown once). This is your agent's auth.

### Option B — Self-host

```bash
# Build from source (requires Go 1.24+, CGO, FTS5)
git clone https://github.com/MimirLLC/vaultbase
cd vaultbase
make build

# Initialize a vault
mkdir -p ~/vault
./vaultbase init ~/vault company

# Create an owner user
./vaultbase user create you@example.com "You" "your-password"
./vaultbase role assign company owner you@example.com
./vaultbase permission add company owner folder "/**" "read,write,delete,admin"

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

# Create an API key for your agent
./vaultbase apikey create you@example.com --name="claude-code"
```

### Option C — Native editor only (no server)

If the human just wants a markdown editor with AI, they can download the
VaultBase Editor (Tauri desktop app) from https://getvaultbase.com/download.
No server or account needed. The editor works fully offline; cloud sync is
opt-in.

---

## 3. Connecting your agent via MCP

Add VaultBase to your MCP config. For Claude Code, edit `~/.claude.json` or
`.mcp.json` in the project:

```json
{
  "mcpServers": {
    "vaultbase": {
      "url": "https://acme.getvaultbase.com/mcp",
      "headers": {
        "Authorization": "Bearer vk_your_api_key_here"
      }
    }
  }
}
```

For self-hosted:

```json
{
  "mcpServers": {
    "vaultbase": {
      "url": "http://localhost:8990/mcp",
      "headers": {
        "Authorization": "Bearer vk_your_api_key_here"
      }
    }
  }
}
```

Restart your agent. You should now have all 27 `vault_*`, `trace_*`, and
`admin_*` tools available.

---

## 4. First moves in a new session

**This is the most important section of this file. Follow it every time.**

### 4a. Call `vault_briefing` first

Always. Before reading anything else. It returns a three-tier identity stack
followed by decision history. Read it **in order**:

1. **Org identity** (`/vault-context.md`) — the outermost frame. What this
   company does, what it values, what decisions need extra care. Every
   decision you make must respect these guardrails.
2. **Team identity** (`/groups/<name>/context.md`) — shared context across
   the team you're working with. Current focus, team-level conventions,
   things the team already knows so you don't re-teach them.
3. **Individual identity** (`/users/<you>/context.md`) — the specific human
   you're working with. Their role, current focus, personal preferences.

Missing identity files silently drop from the briefing. If **all three** are
missing, ask the human whether they want to set one up and then call
`vault_identity_set` for the appropriate scope. A configured identity stack
is the single highest-leverage improvement to every future session.

### 4b. Read identity outermost-to-innermost

Org values constrain team conventions which constrain individual preferences.
If the human's personal preference conflicts with an org guardrail, surface
the conflict instead of silently picking one.

### 4c. Capture identity when it surfaces

When the human says "I prefer X" or "our team always does Y" or "this
company never ships on Fridays" — call `vault_identity_set` immediately.
Don't wait. The cost of asking later is that the next session re-learns the
same thing.

Distinguishing identity from other write-backs:
- **Identity** if it applies to every future session → `vault_identity_set`
- **Decision** if it's a specific judgment call with reasoning → `trace_create`
- **Learning** if it's new factual content worth storing → `vault_learn`
- **Correction** if an existing doc is wrong → `vault_update_doc`

---

## 5. Decision traces — the core differentiator

VaultBase isn't just a file store. It's a **context graph**. Every judgment
call you make should leave a trace so future agents can find it as
precedent.

### Before making a judgment call

Call `trace_find_precedent`. This applies when you're:
- Approving/denying a request
- Choosing between options with trade-offs
- Applying a policy to a specific situation
- Making an exception to a standard process
- Pricing, hiring, technical architecture, or any repeatable decision

Even if you're confident, precedent may reveal edge cases or outcomes you
haven't considered.

### After making a decision

Call `trace_create`. Structure:

```
type: "pricing"                 ← category for future search
summary: "10% discount for Acme annual renewal"
decision: "approved"            ← what was decided
reasoning: "Within discount authority per pricing-v3 §4.2..."
inputs:
  - { path: "/sales/acme-contract.md", role: "primary" }
  - { path: "/policies/pricing-v3.md", role: "governing" }
policies_applied:
  - "pricing-v3 §4.2: discounts up to 10% for annual"
tags: ["pricing", "discount", "annual"]
deviation: false
```

Rules:
- **Record decisions, not actions.** A trace is for "I decided to approve the
  discount," not "I read the file."
- **Be specific in reasoning.** Future agents will read this. Include the
  specific policy sections, numbers, and logic — not just "it seemed reasonable."
- **Tag generously.** Tags are how future precedent searches find your trace.
- **Note deviations explicitly.** If you're making an exception to standard
  process, set `deviation: true` and explain why.

### When you learn the outcome

Call `trace_update_outcome`. A decision with a known outcome is 10x more
valuable as precedent than one without.

### Heed consistency warnings

When `trace_create` returns consistency warnings (contradictory prior
decisions), acknowledge them in your reasoning. Either follow precedent or
explicitly explain why you're diverging.

### Check for stale references

When using a prior decision as precedent, call `vault_stale_check` to
verify its governing documents haven't been revised. Stale precedent can
lead to wrong decisions.

---

## 6. Knowledge write-back

The vault should **grow** with every meaningful conversation. Don't wait to
be asked — if you produce knowledge worth keeping, write it back. The goal
is that the next agent working on the same topic finds the answer already
in the vault.

### `vault_learn` — write new content

Categories:
- `learning` — new information discovered
- `correction` — existing doc was wrong/outdated, now fixed
- `insight` — pattern or synthesis across multiple sources
- `runbook` — step-by-step procedure figured out in conversation
- `faq` — question that keeps coming up, now documented

Modes: `write` (new/overwrite) or `append` (add to existing).

### `vault_update_doc` — correct an existing document

Automatically records a revision for stale detection. Include a `reason` so
the audit trail explains the change.

### When to write back

- A conversation reveals new information that others should know
- You research a topic and produce a summary worth keeping
- A human corrects a misunderstanding — update the source document
- You discover a pattern, workaround, or best practice
- FAQ-style questions get answered repeatedly — write a FAQ doc

---

## 7. Sync behavior (important for conflict avoidance)

If the human is using the VaultBase Editor as well as you, or if multiple
agents share a vault, you need to understand how writes resolve.

- **Every write carries a `base_hash`** — the server version the edit was
  based on.
- **Server refuses stale writes** — if another actor changed the file since
  your base, the server returns its version and you must merge.
- **Conflicts never silently overwrite** — the server always preserves both
  sides. The editor auto-merges when it can and surfaces markers when it
  can't.
- **Live SSE updates** — when you write a file, every connected editor sees
  `file_updated` in milliseconds (RBAC-filtered).
- **Offline edits survive restarts** — the editor queues edits to disk; you
  should never see "lost work" as a failure mode.

As an agent, you generally don't deal with conflicts directly (the MCP
tools handle the protocol), but you should:
- Prefer `vault_update_doc` (which tracks revisions) over raw file writes
  for policies and controlled documents
- Re-read a file before writing to it if significant time has passed
- If a write unexpectedly fails, re-read and retry

---

## 8. RBAC quick reference

You don't manage permissions (unless the human asks you to), but
understanding the model helps you explain errors:

- Permissions have a **resource_type**: `folder`, `file`, or `tag`
- A **resource_pattern** like `/engineering/**`, `#public`, or `/users/{user}/**`
- **Actions**: comma-separated `read`, `write`, `delete`, `admin`
- **Effect**: `allow` or `deny` — **deny always wins**
- Resolution order: file > folder > tag > vault default
- `{user}` in a pattern expands to the authenticated user's email prefix:
  `shane@example.com` → `/users/shane/**`

Common patterns:
- `folder "/engineering/**" "read,write"` — team folder access
- `tag "#public" "read"` — tag-based access
- `folder "/users/{user}/**" "read,write"` — per-user folders
- `folder "/hr/**" "read" effect=deny` — block sensitive content

---

## 9. Full MCP tool reference (27 tools)

### Vault content (read-only)
| Tool | Purpose |
|---|---|
| `vault_list` | List files the role can see. Optional `path` filter. |
| `vault_read` | Read a specific file by path. |
| `vault_search` | Full-text search (FTS5 BM25) across permitted content. |
| `vault_query` | Query files by frontmatter tag or path pattern. |

### Context graph
| Tool | Purpose |
|---|---|
| `trace_create` | Record a decision with inputs, policies, reasoning. Returns consistency warnings. |
| `trace_find_precedent` | Find similar past decisions by type/tags/context. Returns traces with edges + outcomes. |
| `trace_update_outcome` | Record what happened (successful/failed/mixed/superseded). |
| `trace_search` | Filter traces by type, tag, actor, outcome status, or free text. |

### Intelligence & briefings
| Tool | Purpose |
|---|---|
| `vault_briefing` | Identity stack + recent traces + pending outcomes + gaps + stale alerts. **Call first.** |
| `vault_gaps` | Queries that returned zero results, aggregated by frequency. |
| `vault_doc_revision` | Record a new revision of a policy/procedure. |
| `vault_revision_history` | Full revision history for a document. |
| `vault_stale_check` | Flag trace references to documents revised since the decision. |

### Identity (L0 context)
| Tool | Purpose |
|---|---|
| `vault_identity_set` | Write/append identity at scope `org`, `team:<group>`, or `me`. |

### Knowledge write-back
| Tool | Purpose |
|---|---|
| `vault_learn` | Write a new learning/insight/runbook/FAQ. |
| `vault_update_doc` | Update an existing document (auto-records revision). |
| `vault_index` | Re-index after bulk writes. |

### Admin (role-gated)
| Tool | Purpose |
|---|---|
| `admin_list_users` | List all users. |
| `admin_create_user` | Create a user. |
| `admin_create_apikey` | Create an API key scoped to user + role. |
| `admin_list_roles` | List roles for a vault. |
| `admin_create_role` | Create a new role. |
| `admin_assign_role` | Assign a role to a user. |
| `admin_add_permission` | Add a permission rule (folder/file/tag pattern, actions, effect). |
| `admin_list_permissions` | Show permissions for a role. |
| `admin_audit_log` | View recent access and modification events. |

---

## 10. Behaviour rules (in priority order)

1. **Always check precedent first** before making a judgment call.
2. **Record decisions, not actions.** Only create traces for judgment calls.
3. **Get briefed first.** Call `vault_briefing` at the start of every session.
4. **Read identity outermost-to-innermost.** Surface conflicts between tiers.
5. **Capture identity when it surfaces.** Don't wait to be asked.
6. **Be specific in reasoning.** Future agents read these.
7. **Tag generously.** Tags are how precedent searches find your traces.
8. **Note deviations explicitly.** Exceptions are the most valuable traces.
9. **Close the loop.** Record outcomes when you learn them.
10. **Track document revisions** when policies change.
11. **Heed consistency warnings.** Acknowledge contradictions explicitly.
12. **Check for stale references** before relying on old precedent.
13. **Write back continuously.** The vault should grow with every meaningful
    conversation.

---

## 11. Troubleshooting

**"Unauthorized"** — API key is wrong or expired. Regenerate in the web UI
under Admin → API Keys.

**"Permission denied" on read** — the role your API key is scoped to doesn't
have `read` on that path/tag. Ask the human to check
`admin_list_permissions` for your role.

**Briefing is empty** — no identity files exist yet. Offer to create them
via `vault_identity_set`.

**`trace_find_precedent` returns nothing** — expected for new projects.
Your own traces will populate it over time.

**Conflict on write** — another actor edited the file after your last read.
Re-read and retry. The MCP layer handles the `base_hash` protocol for you.

**Can't connect** — verify the server is up at `/api/health` (no auth
required, returns `{"status":"ok"}`).

---

## 12. Links

- Marketing site: https://getvaultbase.com
- Documentation: https://getvaultbase.com/docs
- GitHub: https://github.com/MimirLLC/vaultbase
- Signup: https://getvaultbase.com/signup
- Download editor: https://getvaultbase.com/download

---

*VaultBase is open source under AGPL-3.0. Built by Mimir.*