FAQ & Troubleshooting

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

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.

ContextVault is designed specifically for Claude Code (Anthropic's CLI tool). The CLAUDE.md instructions and hooks system are tailored to Claude's capabilities. Other AI assistants may not understand the vault format or follow the documentation protocols.

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).

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.