claude-context-vault

claude-context-vault

Context vault extension for Claude Code. Prevents context loss during compaction by archiving conversation context to a local vault with layered retrieval.

The Problem

Claude Code builds context as you work. When context gets too large, it compacts — and important details can be lost. You lose track of earlier decisions, code changes, and discussions.

The Solution

claude-context-vault archives old conversation context to a local vault before it gets compacted. When you need that old context back, Claude retrieves just the relevant parts — summaries for quick answers, full chunks for deep dives.

Install

pip install claude-context-vault
claude-context-vault install

That's it. The install command registers the MCP server with Claude Code. The vault directory is created automatically per-project at <project>/.claude/context-vault/.

Architecture

Note: PyPI doesn't render Mermaid diagrams. View the full architecture diagram on GitHub.

graph TD
    A[Claude Code Session] -->|grows over time| B{Context Health}
    B -->|Green| A
    B -->|Yellow / Red| C[archive_context]
    C --> D[MCP Server<br>local Python process]
    D --> E[project/.claude/context-vault/]

    E --> G[chunks/<br>chunk_001.json<br>chunk_002.json]
    E --> H[summaries/<br>chunk_001.txt<br>chunk_002.txt]
    E --> I[manifest.json]

    A -->|"What did we discuss about X?"| J[retrieve_context]
    J --> D
    D -->|search by keywords| E
    E -->|summaries + full chunks| A

    style A fill:#4a9eff,color:#fff
    style D fill:#ff9f43,color:#fff
    style E fill:#2ecc71,color:#fff

How It Works

Once installed, Claude Code gains 6 new tools:

Tool	What it does
check_context_health	Estimates context size, reports green/yellow/red status
archive_context	Stores conversation context in the vault with a summary
retrieve_context	Searches archived context by keywords
list_archived	Shows all archived chunks for the current project
get_chunk	Pulls full content of a specific archived chunk
delete_chunk	Removes an archived chunk

Usage

Context archiving is currently manual — you trigger it by asking Claude. Automatic archiving via hooks is planned for v2.

Recommended Workflow

1. Check health periodically — Ask Claude: "Check my context health"

   • Green: no action needed
   • Yellow: consider archiving older context
   • Red: archive now before compaction loses details

2. Archive before compaction — Ask Claude: "Archive the older context"

   • Claude calls archive_context to store a summary + full chunk in the vault

3. Retrieve after compaction — Ask Claude: "What did we discuss about authentication?"

   • Claude calls retrieve_context to search the vault by keywords
   • If the summary isn't enough, get_chunk pulls the full original

Quick Commands

Say this to Claude	What happens
"Check context health"	Calls check_context_health — reports size and status
"Archive the old context"	Calls archive_context — stores context in the vault
"What did we discuss about X?"	Calls retrieve_context — searches vault by keywords
"Show me all archived context"	Calls list_archived — lists all chunks
"Get the full details of chunk_001"	Calls get_chunk — retrieves full original content
"Delete chunk_001"	Calls delete_chunk — removes from vault

Vault Location

All archived context is stored locally at <project>/.claude/context-vault/, inside each project's own .claude directory. Nothing is sent to any server.

Uninstall

claude-context-vault uninstall
pip uninstall claude-context-vault

Links

• GitHub Repository
• PyPI

License

MIT