Configuration

Customize ContextVault's behavior with modes, enforcement levels, and limits.

Settings File

ContextVault settings are stored in ~/.claude/vault/settings.json:

{
  "mode": "local",
  "enforcement": "balanced",
  "limits": {
    "max_global_docs": 50,
    "max_project_docs": 50,
    "max_doc_lines": 100,
    "max_summary_words": 15
  }
}

Vault Modes

The mode setting determines which vaults Claude reads and writes to.

Mode	Reads	Writes	Use Case
`local`	Project vault only	Project vault	Focus on this project, ignore global
`global`	Global vault only	Global vault	General learning, no specific project
`full`	Both vaults	Auto-routed	Full power, best for most users

Changing Modes

# Switch to local mode (project only)
/ctx-mode local

# Switch to full mode (both vaults)
/ctx-mode full

# Switch to global mode (global only)
/ctx-mode global

Recommended Mode

full mode is recommended for most users. It gives you access to both global patterns and project-specific docs, with automatic routing to the right vault.

Enforcement Levels

Enforcement controls how aggressively ContextVault reminds you to document your work.

Level	Mid-Session	Session End	Best For
`light`	No reminders	Reminder only	Experienced users, minimal interruption
`balanced`	After 8+ edits / 2+ files	Blocks if significant work	Most users (default)
`strict`	After 4+ edits / 2+ files	Blocks if significant work	Building documentation habit

Changing Enforcement

# Set to light enforcement
/ctx-mode enforcement light

# Set to balanced (default)
/ctx-mode enforcement balanced

# Set to strict enforcement
/ctx-mode enforcement strict

How Enforcement Works

The enforcement system uses a "remind, don't block" philosophy:

Edit Tracking — The PreToolUse hook counts file edits
Threshold Check — When edits exceed threshold, a reminder appears
Non-Blocking — Reminders suggest documentation but don't stop work
Session End — Stop hook blocks exit only if significant undocumented work

What Counts as "Significant Work"?

Modifications to 2+ files with 4+ total edits. Version bumps, config changes, and single-file tweaks don't trigger enforcement.

Document Limits

Limits keep your vault efficient and context-friendly.

Limit	Default	Purpose
`max_global_docs`	50	Maximum documents in global vault
`max_project_docs`	50	Maximum documents in project vault
`max_doc_lines`	100	Maximum lines per document
`max_summary_words`	15	Maximum words in index summary

Why Limits Matter

Context Efficiency — Smaller docs = faster loading, less token usage
Focus — Forces concise, actionable documentation
Maintainability — Easier to update and keep current

Approaching Limits?

If you're near the 50-doc limit, consider: archiving old docs, merging related topics, or moving less-used docs to archive/ folder.

MCP Server Configuration

If you're using the MCP server, configure it in your AI tool's MCP settings:

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "contextvault": {
      "command": "npx",
      "args": ["-y", "contextvault-mcp"]
    }
  }
}

Windsurf

// .windsurf/mcp.json
{
  "mcpServers": {
    "contextvault": {
      "command": "npx",
      "args": ["-y", "contextvault-mcp"]
    }
  }
}

Claude Code

# Via CLI:
claude mcp add contextvault -- npx -y contextvault-mcp

MCP Server Settings

The MCP server reads the same settings.json file in your vault directory. Mode, enforcement, and limits all apply. Change them with ctx_mode (MCP) or /ctx-mode (native).

Hooks Configuration

Hooks = Native Installer Only

Hooks (SessionStart, PreToolUse, Stop) require the native bash installer and only work in Claude Code. If you use the MCP server with Cursor, Windsurf, or other tools, enforcement is handled server-side instead — no hooks needed.

Hooks are defined in ~/.claude/settings.json (not the vault settings):

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/session-start.sh"
      }
    ],
    "PreToolUse": [
      {
        "matcher": { "tool_name": "Edit" },
        "type": "command",
        "command": "bash ~/.claude/hooks/pre-edit.sh \"$TOOL_INPUT\""
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "bash ~/.claude/hooks/stop.sh"
      }
    ]
  }
}

Hook Types

Hook	Purpose	Can Block?
`SessionStart`	Show vault status at session start	No
`PreToolUse`	Track edits, suggest documentation	Yes (enforcement-based)
`Stop`	Check for undocumented work	Yes (if significant work)

Per-Project Configuration

Each project can have its own CLAUDE.md file with project-specific instructions.

Location

your-project/
├── CLAUDE.md              # Project-specific instructions
└── .claude/
    └── vault/
        └── index.md       # Project vault

Example Project CLAUDE.md

# Project Instructions

## Documentation Requirements
After any task:
- Fixed bug? → /ctx-error
- Made decision? → /ctx-decision
- Learned something? → /ctx-doc

## Project Vault
Location: ./.claude/vault/
Prefix: P### (P001, P002, etc.)

Common Configurations

Minimal Interruption

# Light enforcement, local mode
/ctx-mode local
/ctx-mode enforcement light

Full Power (Recommended)

# Full mode, balanced enforcement
/ctx-mode full
/ctx-mode enforcement balanced

Building Documentation Habit

# Full mode, strict enforcement
/ctx-mode full
/ctx-mode enforcement strict