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.

Hooks Configuration

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