FAQ & Troubleshooting

ContextVault is an external context management system for AI coding assistants. It creates a two-tier documentation system (global + project-level) that helps AI tools remember context across sessions. Instead of starting fresh every conversation, your AI reads your vault and has full project context. Works with Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible tool.

Yes, ContextVault is completely free and open source under the MIT license. You can use it for personal projects, commercial work, or modify it for your needs.

Yes! ContextVault works with any MCP-compatible AI tool via the MCP server (npx contextvault-mcp). This includes Cursor, Windsurf, OpenCode, Cline, Continue, Copilot CLI, and Claude Code itself. The bash installer provides additional Claude Code-specific features like hooks and slash commands.

All data is stored locally on your machine:

• Global vault: ~/.claude/vault/
• Project vault: ./.claude/vault/ (in each project)

No data is sent to external servers. Your documentation stays on your computer (or your git repo if you commit it).

Choose MCP if you:

• Use Cursor, Windsurf, Cline, OpenCode, Continue, or Copilot CLI
• Switch between multiple AI tools
• Want universal compatibility with any MCP-supported tool

Choose Native if you:

• Use Claude Code exclusively
• Want hooks (automatic documentation reminders)
• Prefer slash commands (/ctx-doc) over MCP tools

You can use both — the MCP server auto-detects native vault paths, so both installations read/write the same vault with zero conflicts.

ContextVault works with any MCP-compatible AI tool via the MCP server. Tested tools include:

• Claude Code — MCP server + native installer (hooks & slash commands)
• Cursor — via MCP server
• Windsurf — via MCP server
• Cline — via MCP server
• OpenCode — via MCP server
• Continue — via MCP server
• Copilot CLI — via MCP server

Any tool that supports the Model Context Protocol can use ContextVault.

Common fixes:

1. Check Node.js: Run node --version — you need Node.js 18+
2. Check npx: Run npx contextvault-mcp --version to verify the package works
3. Check MCP config: Ensure your mcpServers JSON is valid and the command/args are correct
4. Restart your AI tool: MCP servers are loaded at startup — restart after config changes
5. Check logs: Most AI tools show MCP server logs in their output panel

On macOS/Linux, you may need to make the installer executable:

curl -sL https://ctx-vault.com/install -o install.sh
chmod +x install.sh
./install.sh

On Windows PowerShell, ensure you're running as Administrator.

Yes! Use the native PowerShell installer:

irm https://ctx-vault.com/install.ps1 | iex

This creates all slash commands and the vault structure. For full hook support, install Git for Windows (includes Git Bash).

There are two types of upgrades:

Global installation (CLAUDE.md, commands, hooks at ~/.claude/):

# Re-run the installer
curl -sL https://ctx-vault.com/install | bash

Project-level (instructions in current project):

/ctx-upgrade

Both preserve your vault documents — only instructions and commands are updated.

Check these common causes:

1. Is ~/.claude/CLAUDE.md present? This file contains the instructions Claude needs.
2. Is the index valid? Run /ctx-health to check for issues.
3. Check the mode: Run /ctx-status to see current mode. If set to local, global vault is ignored.

Hooks require Claude Code's settings.json to be configured. The installer should set this up automatically, but you can verify:

1. Check ~/.claude/settings.json exists and contains hook definitions
2. On Windows, hooks require Git Bash to be installed
3. Ensure enforcement isn't set to light (which disables mid-session reminders)

To reinstall hooks:

/ctx-upgrade

This usually means the index is out of sync with actual files. Run:

/ctx-health

This will identify orphan entries and offer to fix them.

You've hit the 50-document limit per vault. Options:

• Archive old docs: Move less-used docs to vault/archive/
• Merge related docs: Combine similar topics into one document
• Delete obsolete docs: Remove docs that are no longer relevant

After cleanup, update your index to reflect changes.

Use the import command:

/ctx-import ./path/to/existing-doc.md

This will convert the document to vault format, assign an ID, and update the index.

For bulk imports, run /ctx-bootstrap which scans your codebase and creates documentation.

Project vault: Yes! Commit .claude/vault/ to git. All team members will have the same project documentation.

Global vault: Not recommended. This contains your personal patterns and preferences. Each team member should build their own global vault.

Use ContextVault for:

• High-level architecture and decisions
• Bug fix stories (what went wrong, how it was fixed)
• Patterns and best practices
• Session handoffs and work-in-progress

Use code comments for:

• Why specific code works the way it does
• Non-obvious implementation details
• API documentation (JSDoc, etc.)

Document at meaningful milestones:

• After fixing a bug — Use /ctx-error
• After making a decision — Use /ctx-decision
• After completing a feature — Use /ctx-doc
• At session end — Use /ctx-handoff

Don't document trivial changes like typo fixes or version bumps.

Yes! Edit ~/.claude/vault/_template.md to change the default structure for new documents. The slash command files in ~/.claude/commands/ define templates for specific document types (error, decision, plan, etc.).

To remove all ContextVault files:

# Remove global installation
rm -rf ~/.claude/vault
rm -rf ~/.claude/commands
rm ~/.claude/CLAUDE.md

# Remove from a project
rm -rf ./.claude/vault

Then reinstall if desired.

Yes. ContextVault is stored locally and works with any Claude Code session. Different accounts will all read the same vault files on your machine.