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:

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

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