Upgrade Guide

Keep ContextVault up to date with the latest features and improvements.

MCP Server Upgrade

The MCP server runs via npx, which caches the first version it downloads. It does not auto-update. You need to clear the cache to get a new version.

Step 1: Check Your Current Version

Run this in your terminal (not inside Claude Code):

npx contextvault-mcp --version
# Example output: 1.0.7

Step 2: Clear the npx Cache

This removes the cached package so npx will download the latest on next run:

# macOS / Linux
rm -rf ~/.npm/_npx

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

Step 3: Verify the New Version

npx -y contextvault-mcp --version
# Should output: 1.0.8 (or latest)

Step 4: Restart Your MCP Client

Close and reopen Claude Code, Cursor, Windsurf, or whichever MCP client you use. The MCP server is launched fresh on each session start.

Step 5: Confirm Inside Your AI Tool

Inside Claude Code (or your MCP client), run:

ctx_changelog    # Should show the latest version at the top
ctx_status       # Should show vault status without errors

{
  "mcpServers": {
    "contextvault": {
      "command": "npx",
      "args": ["-y", "contextvault-mcp@1.0.8"]
    }
  }
}

MCP Quick Reference

# MCP UPGRADE CHECKLIST
# ─────────────────────────────────────────

# 1. Check current version
npx contextvault-mcp --version

# 2. Clear npx cache
rm -rf ~/.npm/_npx

# 3. Pull latest and verify
npx -y contextvault-mcp --version

# 4. Restart your MCP client (Claude Code, Cursor, etc.)

# 5. Verify inside your AI tool
ctx_changelog
ctx_status

Troubleshooting MCP Upgrades

Version still shows old number after cache clear

Cause: npm registry CDN cache (usually resolves within 5 minutes).

Fix: Wait a few minutes, then run npx -y contextvault-mcp --version again.

Running npx contextvault-mcp in terminal shows nothing

This is expected. MCP servers use stdio transport — they wait silently for JSON-RPC messages from an MCP client. You should see a helpful banner now (v1.0.8+), but the server still waits for input. Press Ctrl+C to exit. You don't need to run it manually — your MCP client launches it automatically.

--version flag not recognized

Cause: You're running an older cached version (pre-1.0.8) that doesn't have CLI flags.

Fix: Clear the npx cache first: rm -rf ~/.npm/_npx, then try again.

Native Installer Upgrade

The native installer has two layers that can be upgraded independently:

Complete Upgrade Process

Follow these steps to fully upgrade ContextVault:

Step 1: Check Your Current Version

In Claude Code, run:

/ctx-status

Note your current version number.

Step 2: Upgrade Global Installation

This updates the core ContextVault system on your machine.

macOS / Linux

curl -sL https://ctx-vault.com/install | bash

Windows PowerShell (Run as Administrator)

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

Step 3: Restart Claude Code

After upgrading the global installation, you must restart Claude Code to load the new instructions.

# Close Claude Code completely, then reopen it
# Or if using CLI:
claude

Step 4: Upgrade Project Installation

Navigate to each project that uses ContextVault and upgrade its local files:

cd /path/to/your/project

# In Claude Code, run:
/ctx-upgrade

This updates:

• ./CLAUDE.md — Project-specific instructions
• ./.claude/settings.json — Project hook settings

Step 5: Verify the Upgrade

/ctx-status

Confirm the new version is displayed and all components are healthy.

/ctx-changelog

Review what's new in the version you just installed.

Quick Reference

# COMPLETE UPGRADE CHECKLIST
# ─────────────────────────────────────────

# 1. Check current version
/ctx-status

# 2. Upgrade global (run in terminal, not Claude Code)
curl -sL https://ctx-vault.com/install | bash   # macOS/Linux
# or
irm https://ctx-vault.com/install.ps1 | iex     # Windows

# 3. Restart Claude Code
#    Close and reopen the application

# 4. Upgrade each project (in Claude Code)
cd /path/to/project
/ctx-upgrade

# 5. Verify
/ctx-status
/ctx-changelog

Upgrading Multiple Projects

If you have several projects using ContextVault:

1. Upgrade global installation once
2. Restart Claude Code once
3. Run /ctx-upgrade in each project individually

# After global upgrade and restart:

cd ~/projects/project-a
/ctx-upgrade

cd ~/projects/project-b
/ctx-upgrade

cd ~/projects/project-c
/ctx-upgrade

Troubleshooting Upgrades

Commands not recognized after upgrade

Cause: Claude Code hasn't reloaded the commands.

Fix: Restart Claude Code completely (close all windows/terminals).

Hooks not triggering

Cause: settings.json may have old hook format.

Fix: Re-run the installer which regenerates hook configs.

Version still shows old number

Cause: Reading cached CLAUDE.md.

Fix: Ensure you restarted Claude Code after the global upgrade.

/ctx-upgrade fails

Cause: Missing or corrupted project files.

Fix: Re-initialize the project:

/ctx-init

This recreates project structure while preserving existing vault documents.

Downgrading (If Needed)

To install a specific older version, download from GitHub releases:

# View available releases
https://github.com/ahmadzein/ContextVault/releases

# Install specific version (replace TAG with version)
curl -sL https://raw.githubusercontent.com/ahmadzein/ContextVault/TAG/install-contextvault.sh | bash

Staying Updated

Check for updates periodically:

• GitHub Releases — See all versions
• Changelog — What's new in each version
• Star the repo on GitHub to get notified of new releases