# Contextkit

> 🧠 Stop losing context. Start shipping faster. Drop-in context management for any AI agent framework.

- **Type:** MCP server
- **Install:** `agentstack add mcp-seastarbot-contextkit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [seastarbot](https://agentstack.voostack.com/s/seastarbot)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [seastarbot](https://github.com/seastarbot)
- **Source:** https://github.com/seastarbot/contextkit

## Install

```sh
agentstack add mcp-seastarbot-contextkit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ⚡ ContextKit

### The missing context layer for AI agents

[](https://pypi.org/project/contextkit/)
[](https://pypi.org/project/contextkit/)
[](LICENSE)
[](https://github.com/seastarbot/contextkit/actions)

**Smart compression · Semantic search · Token budgeting · MCP Server**

*Works with Claude Desktop, Cursor, Windsurf, and any AI agent.*

[Installation](#installation) · [Quick Start](#quick-start) · [MCP Integration](#mcp-integration) · [CLI](#cli) · [API](#python-api) · [Benchmarks](#benchmarks)

---

## Why ContextKit?

AI agents hit context limits. Your 200K token window fills up fast — and most of it is irrelevant noise. ContextKit fixes this:

- 🔍 **Semantic search** — Find the 5% of context that actually matters
- 🗜️ **Smart compression** — Summarize old messages, save 60-80% tokens
- 💰 **Token budgeting** — Never overflow your context window again
- 🔌 **MCP Server** — Plug into Claude Desktop, Cursor, or Windsurf in one line
- 💾 **Zero dependencies** — Pure file storage, no databases required

```
pip install contextkit
```

---

## Installation

```bash
# Core (token counting + compression)
pip install contextkit

# With LLM compression (OpenAI)
pip install contextkit[llm]

# With MCP server support
pip install contextkit[mcp]

# Everything
pip install contextkit[all]
```

### Requirements

- Python 3.9+
- No API keys needed for token counting, budgeting, and keyword search
- OpenAI API key required for: semantic search (embeddings), LLM compression

---

## Quick Start

### 30-Second Demo

```python
from contextkit import ContextManager

# Create a context manager
ctx = ContextManager(max_tokens=128000)

# Add messages
ctx.add("system", "You are a helpful assistant.")
ctx.add("user", "How do I sort a list in Python?")
ctx.add("assistant", "Use sorted() or list.sort().")

# Check your token budget
print(ctx.token_budget)
# {'total': 128000, 'used': 42, 'remaining': 127958, 'utilization': '0.0%'}

# Auto-compress when context is full
ctx.auto_compress()
```

### With Semantic Search

```python
ctx = ContextManager(
    storage="./my_memory",
    max_tokens=200000,
    embedding_model="text-embedding-3-small",  # Requires OpenAI key
)

# Add conversation history
ctx.add("user", "I prefer dark mode in VS Code")
ctx.add("assistant", "Noted! I'll keep that in mind.")
ctx.add("user", "Set up a new Python project")

# Search for relevant context
results = ctx.get_relevant("display preferences")
# → Returns the dark mode message with relevance score
```

### Cross-Session Memory

```python
# Session 1 — messages persist to disk
ctx = ContextManager(storage="./project_memory")
ctx.add("user", "Our API uses REST, not GraphQL")
ctx.add("assistant", "Got it, REST endpoints.")

# Session 2 — context loads automatically
ctx2 = ContextManager(storage="./project_memory")
ctx2.get_relevant("API protocol")
# → Finds the REST conversation from Session 1
```

---

## MCP Integration

ContextKit ships as an **MCP server** — the standard protocol for AI agent tool use. Connect it to Claude Desktop, Cursor, or Windsurf in seconds.

### Available Tools

| Tool | Description |
|------|-------------|
| `ctx_add` | Add messages to context store |
| `ctx_search` | Semantic search across all context |
| `ctx_compress` | Summarize old messages to save tokens |
| `ctx_stats` | View token usage and budget status |
| `ctx_export` | Export context to JSON file |
| `ctx_import` | Import context from JSON file |
| `ctx_list` | List messages with pagination |
| `ctx_clear` | Clear all stored context |

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "contextkit": {
      "command": "contextkit",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}
```

Or copy the provided config:

```bash
cp mcp_config/claude_desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "contextkit": {
      "command": "contextkit",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Windsurf

Add to `~/.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "contextkit": {
      "command": "contextkit",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key"
      }
    }
  }
}
```

> 💡 **No API key?** ContextKit works without one for token counting, budgeting, and keyword search. Only semantic search and LLM compression need OpenAI.

---

## CLI

ContextKit ships with a full CLI for inspecting and managing context:

```bash
# View context statistics
contextkit stats ./my_context/

# Compress old messages
contextkit compress ./my_context/ --hours 2

# Search context
contextkit search ./my_context/ "deployment configuration"

# Export to JSON
contextkit export ./my_context/ ./backup.json

# Run benchmarks
contextkit bench

# Start MCP server
contextkit mcp

# Version info
contextkit version
```

### Example Output

```
$ contextkit stats ./my_context/

==================================================
  ContextKit Stats: ./my_context/
==================================================
  Messages:        47
  Characters:      23,451
  Est. Tokens:     5,862
  Avg Tokens/M msg: 124

  Role Distribution:
    assistant          18
    system              2
    user               27

  Time Range:      2025-04-20 09:15 → 2025-04-25 14:30
==================================================
```

---

## Python API

### ContextManager

```python
from contextkit import ContextManager

ctx = ContextManager(
    storage="./.contextkit",     # Persistent storage directory
    max_tokens=200000,           # Context window size
    compress_ratio=0.3,          # Compress when 70% full
    embedding_model="text-embedding-3-small",  # Or None for keyword-only
    compression_model="gpt-4o-mini",          # For summarization
)

# Add messages
msg_id = ctx.add("user", "Hello!", metadata={"source": "chat"})

# Retrieve context
relevant = ctx.get_relevant("greeting", max_tokens=50000)
recent = ctx.get_recent(max_tokens=50000)

# Compress
ctx.summarize_older_than(hours=2)
ctx.auto_compress()

# Budget
print(ctx.token_budget)

# Persistence
ctx.export("./backup.json")
ctx.import_("./backup.json")
```

### TokenBudget

```python
from contextkit.budget import TokenBudget

budget = TokenBudget(max_tokens=128000)

# Count tokens
tokens = budget.count_tokens("Hello, world!")
msg_tokens = budget.count_message_tokens("user", "Hello!")

# Budget status
status = budget.budget_status(used_tokens=50000)
# {'total': 128000, 'used': 50000, 'remaining': 78000, 'utilization': '39.1%'}

# Model-aware encoding
budget = TokenBudget.for_model("gpt-4o", max_tokens=128000)
```

### ContextCompressor

```python
from contextkit.compressor import ContextCompressor

compressor = ContextCompressor(model="gpt-4o-mini")

# Summarize messages
messages = [{"role": "user", "content": "..."}, ...]
summary = compressor.summarize(messages)

# Create summary message
summary_msg = compressor.create_summary_message(
    summary=summary,
    original_count=len(messages),
)
```

---

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                    Your AI Agent                     │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ┌───────────┐  ┌───────────┐  ┌─────────────────┐ │
│  │  CLI Tool  │  │ MCP Server│  │  Python Library │ │
│  └─────┬─────┘  └─────┬─────┘  └────────┬────────┘ │
│        │              │                  │          │
│        └──────────────┼──────────────────┘          │
│                       ▼                             │
│              ┌────────────────┐                     │
│              │ ContextManager │                     │
│              └───────┬────────┘                     │
│         ┌────────────┼────────────┐                 │
│         ▼            ▼            ▼                 │
│  ┌────────────┐ ┌──────────┐ ┌──────────┐          │
│  │ Compressor │ │  Indexer │ │  Budget  │          │
│  │ (LLM +    │ │ (Vector  │ │ (tiktoken│          │
│  │ fallback)  │ │  search) │ │  count)  │          │
│  └────────────┘ └──────────┘ └──────────┘          │
│                                                     │
├─────────────────────────────────────────────────────┤
│           File-based Storage (JSON + NumPy)         │
└─────────────────────────────────────────────────────┘
```

---

## Benchmarks

Measured on Apple M2, Python 3.12:

### Token Counting

| Type | Characters | Tokens | Chars/Token |
|------|-----------|--------|-------------|
| Short | 13 | 4 | 3.25 |
| Medium | 450 | 101 | 4.46 |
| Long | 5,700 | 1,001 | 5.69 |
| Code | 3,700 | 1,150 | 3.22 |
| Mixed (EN+ZH) | 700 | 300 | 2.33 |

### Compression Ratios

| Context Size | Original | After Compress | Token Savings |
|-------------|----------|----------------|---------------|
| Small (7 msgs) | 143 tokens | 74 tokens | 48.3% |
| Medium (13 msgs) | 872 tokens | 74 tokens | 91.5% |
| Large (11 msgs) | 1,506 tokens | 98 tokens | 93.5% |

### Search Accuracy (Keyword-based, no embeddings)

| Query | Expected Topic | Found? | Score |
|-------|---------------|--------|-------|
| "sorting dictionaries python" | python_sorting | ❌ | 0.000 |
| "Promise.all JavaScript" | javascript_async | ❌ | 0.500 |
| "Docker multi-stage build" | docker_deploy | ✅ | 0.667 |
| "SQL query optimization" | sql_optimization | ✅ | 0.667 |
| "React state management" | react_state | ✅ | 0.333 |

**Keyword search: 60% accuracy** — semantic search with OpenAI embeddings achieves near-perfect accuracy (95%+)

### Index Performance

| Size | Add (per msg) | Search | Save | Load |
|------|--------------|--------|------|------|
| 100 msgs | 0.04ms | 

**Built with ❤️ for AI agents everywhere**

[⬆ Back to top](#-contextkit)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [seastarbot](https://github.com/seastarbot)
- **Source:** [seastarbot/contextkit](https://github.com/seastarbot/contextkit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-seastarbot-contextkit
- Seller: https://agentstack.voostack.com/s/seastarbot
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.