Metadata-Version: 2.4
Name: claude-context-vault
Version: 0.3.0
Summary: Context vault extension for Claude Code — archive, retrieve, and manage conversation context
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: tiktoken>=0.7.0
Description-Content-Type: text/markdown

# 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

```bash
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](https://github.com/akindejuh/claude-context-vault).

```mermaid
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

```bash
claude-context-vault uninstall
pip uninstall claude-context-vault
```

## Links

- [GitHub Repository](https://github.com/akindejuh/claude-context-vault)
- [PyPI](https://pypi.org/project/claude-context-vault/)

## License

MIT
