# mcp-context-manager

<p align="center">
  <img src="https://img.shields.io/badge/MCP-Server-blue?style=for-the-badge" alt="MCP Server"/>
  <img src="https://img.shields.io/badge/Python-3.10%2B-green?style=for-the-badge" alt="Python"/>
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="MIT"/>
  <img src="https://img.shields.io/badge/Local--First-Yes-brightgreen?style=for-the-badge" alt="Local First"/>
  <img src="https://img.shields.io/badge/API%20Keys-Zero-red?style=for-the-badge" alt="Zero API Keys"/>
</p>

<p align="center">
  <strong>Keep your AI agents focused, cheap, and in control of their own memory.</strong><br>
  Free • Local-first • Pure Python • Ready in 30 seconds
</p>

---

## 1. Value Proposition

Long conversations make AI agents forget important things and burn money on old messages.

**mcp-context-manager** gives any AI agent simple tools to:

- Score which messages matter
- Compress and prune context
- Search past conversations intelligently
- Traverse conversation graphs
- Produce clean, token-budget-ready context

All of this happens **locally**, with **zero API keys** and **zero cost**.

---

## 2. Why this project exists

| Problem | Result |
|---------|--------|
| Context windows fill up | Agents lose focus and make mistakes |
| Every extra token costs money | Bills grow fast on long sessions |
| Most memory tools are heavy | Need databases, embeddings, cloud APIs |
| Cloud memory tools raise privacy issues | Sensitive data leaves your machine |

This project was built to solve those problems with the simplest possible approach:

- Pure Python
- Heuristic scoring (no LLM needed for scoring)
- Local JSON storage
- Works with any MCP-compatible client (Claude Desktop, Cursor, etc.)

---

## 3. Features

| Feature | Description |
|---------|-------------|
| **Message Logging** | Track every user, assistant, system and tool message |
| **Importance Scoring** | Automatic 0–1 score based on role, keywords and length |
| **Context Health** | 0–100 health score with warnings and suggestions |
| **Smart Compression** | Keep high-importance + recent messages, drop the rest |
| **Token Savings Preview** | See how many tokens you will save before compressing |
| **AI Context Query** | Ask a natural language question and get relevant past messages |
| **Hybrid Search** | Keyword + importance + recency ranking |
| **Graph Traversal** | Walk the conversation as a graph of related messages |
| **Token-ready Context** | Produce a clean string that fits exactly inside a token budget |
| **Session Management** | Multiple independent sessions, clear anytime |

---

## 4. Architecture

```mermaid
flowchart TD
    A[AI Agent / MCP Client] -->|calls tools| B[MCP Server<br/>server.py]
    B --> C[Analyzer<br/>analyzer.py]
    B --> D[Storage<br/>storage.py]
    C --> E[Importance Scoring]
    C --> F[Hybrid Search]
    C --> G[Graph Traversal]
    C --> H[Token-ready Packer]
    D --> I[(Local JSON<br/>data/contexts.json)]
    E --> C
    F --> C
    G --> C
    H --> C
```

**Simple flow:**
1. Agent sends a message → `add_message`
2. When context gets large → `get_context_health` or `estimate_token_savings`
3. Need focus → `compress_context` or `get_token_ready_context`
4. Need specific info → `ai_context_query` / `hybrid_search_context` / `graph_traverse_context`

---

## 5. Installation

```bash
# Clone the repo
git clone https://github.com/princeruhulofficial/mcp-context-manager.git
cd mcp-context-manager

# Install in editable mode
pip install -e .

# Run the server
python -m src.server
```

Requirements:
- Python 3.10+
- `mcp` and `pydantic` (installed automatically)

---

## 6. MCP Client Configuration

### Claude Desktop / Cursor / any MCP client

```json
{
  "mcpServers": {
    "context-manager": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/absolute/path/to/mcp-context-manager"
    }
  }
}
```

Replace `/absolute/path/to/mcp-context-manager` with the real path on your machine.

---

## 7. All Tools

### 7.1 `add_message`

**Purpose:** Log a new message into a session so the manager can track history.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Any string that identifies the conversation |
| `role` | string | Yes | `user` \| `assistant` \| `system` \| `tool` |
| `content` | string | Yes | The message text |

**Returns:**  
`"Added message abc123 (importance=0.75, ~42 tokens)"`

**Example:**
```json
{
  "session_id": "project-alpha",
  "role": "user",
  "content": "Remember our goal is to launch by Friday"
}
```

---

### 7.2 `get_context_health`

**Purpose:** Check how healthy the current context is (0–100 score).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `session_id` | string | Yes | Session to inspect |

**Returns (JSON):**
```json
{
  "session_id": "project-alpha",
  "message_count": 27,
  "estimated_tokens": 4820,
  "health_score": 68.5,
  "warnings": ["Context is getting large (>8k tokens). Consider compression."],
  "suggestions": ["Call compress_context to free space."]
}
```

---

### 7.3 `compress_context`

**Purpose:** Keep high-importance + recent messages and drop the rest.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `session_id` | string | Yes | – | Session to compress |
| `target_ratio` | float | No | 0.4 | How much of original to keep (0.3–0.6 recommended) |

**Returns (JSON):**
```json
{
  "original_tokens": 8200,
  "compressed_tokens": 3100,
  "tokens_saved": 5100,
  "savings_percent": 62.2,
  "summary": "Compressed history highlights:\n...",
  "kept_message_ids": ["a1b2", "c3d4", ...]
}
```

---

### 7.4 `estimate_token_savings`

**Purpose:** Preview savings without changing anything.

| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `session_id` | string | Yes | – |
| `target_ratio` | float | No | 0.4 |

**Returns:**  
```
Original: ~8200 tokens
After compression: ~3100 tokens
Saved: 5100 tokens (62.2%)
```

---

### 7.5 `score_message_importance`

**Purpose:** Re-calculate importance of one specific message.

| Parameter | Type | Required |
|-----------|------|----------|
| `session_id` | string | Yes |
| `message_id` | string | Yes |

**Returns:**  
`"Message a1b2 importance = 0.82"`

---

### 7.6 `list_sessions`

**Purpose:** See all tracked sessions.

**Returns:**  
```
Sessions:
- project-alpha
- support-chat-42
```

---

### 7.7 `clear_session`

**Purpose:** Delete all context for a session.

| Parameter | Type | Required |
|-----------|------|----------|
| `session_id` | string | Yes |

**Returns:**  
`"Cleared session project-alpha"`

---

### 7.8 `ai_context_query`

**Purpose:** Ask a natural language question and get the most relevant past messages.

| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `session_id` | string | Yes | – |
| `question` | string | Yes | – |
| `top_k` | int | No | 5 |

**Returns:** Ranked list of relevant messages with scores.

---

### 7.9 `hybrid_search_context`

**Purpose:** Built-in Hybrid Search (keyword + importance + recency).

| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `session_id` | string | Yes | – |
| `query` | string | Yes | – |
| `top_k` | int | No | 5 |

**Returns (JSON):** List of matches with `message_id`, `role`, `content`, `score`, `reason`.

---

### 7.10 `graph_traverse_context`

**Purpose:** Walk the conversation graph starting from a message (or the most important one).

| Parameter | Type | Required | Default |
|-----------|------|----------|---------|
| `session_id` | string | Yes | – |
| `start_message_id` | string | No | most important |
| `max_nodes` | int | No | 8 |

**Returns:** List of related messages in traversal order.

---

### 7.11 `get_token_ready_context`

**Purpose:** Create a clean context string that fits inside a token budget (ready to paste into an LLM).

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `session_id` | string | Yes | – | Session |
| `token_budget` | int | No | 2000 | Max tokens allowed |
| `mode` | string | No | `"hybrid"` | `hybrid` \| `graph` \| `importance` |
| `query` | string | No | null | Used when mode=`hybrid` |

**Returns (JSON):**
```json
{
  "session_id": "project-alpha",
  "token_budget": 2000,
  "used_tokens": 1874,
  "message_count": 9,
  "context_text": "[USER] ...\n\n[ASSISTANT] ...",
  "source": "hybrid"
}
```

---

## 8. Scoring Methodology

Importance score (0.0 – 1.0) is calculated with simple heuristics:

| Factor | Effect |
|--------|--------|
| Role = `system` | +0.30 |
| Role = `user` | +0.20 |
| Role = `tool` | +0.10 |
| Important keywords present | +0.04 each |
| Message longer than 300 chars | +0.10 |
| Message longer than 150 chars | +0.05 |

**Important keywords currently include:**  
`error`, `fail`, `important`, `remember`, `goal`, `must`, `critical`, `decision`, `final`, `priority`, `deadline`, `key`, `summary`, `conclusion`, `action`

Health score (0–100) starts at 100 and is reduced by:
- High total token count
- High message count

---

## 9. Examples

### Example 1 – Basic tracking
```text
add_message(session_id="demo", role="user", content="Our deadline is next Monday")
add_message(session_id="demo", role="assistant", content="Got it. I will prioritise the launch tasks.")
get_context_health(session_id="demo")
```

### Example 2 – Search + Token-ready context
```text
ai_context_query(session_id="demo", question="What is the deadline?")
get_token_ready_context(session_id="demo", token_budget=1500, mode="hybrid", query="deadline")
```

### Example 3 – Compression
```text
estimate_token_savings(session_id="demo", target_ratio=0.4)
compress_context(session_id="demo", target_ratio=0.4)
```

---

## 10. Use Cases

| Use Case | How this helps |
|----------|----------------|
| Long coding sessions | Keep only decisions, errors and current goals |
| Customer support agents | Retrieve relevant past tickets without full history |
| Research / multi-step reasoning | Graph traversal finds related insights |
| Cost control | Token-ready context keeps every LLM call inside budget |
| Privacy-sensitive work | Everything stays on your machine |

---

## 11. Design Principles

1. **Local-first** – No cloud, no external API calls for core logic
2. **Zero API keys** – Works completely offline
3. **Simple heuristics** – Fast, predictable, easy to understand
4. **Token awareness** – Every tool thinks about cost
5. **Agent-friendly** – Tools are small and composable
6. **Safe by default** – Compression does not auto-delete unless you ask

---

## 12. Performance

| Operation | Typical speed | Notes |
|-----------|---------------|-------|
| `add_message` | < 5 ms | In-memory + JSON write |
| `hybrid_search` | < 20 ms | For a few hundred messages |
| `graph_traverse` | < 30 ms | Limited by `max_nodes` |
| `get_token_ready_context` | < 40 ms | Packing is linear |
| `compress_context` | < 50 ms | Pure Python |

Suitable for real-time use inside agent loops.

---

## 13. Security & Privacy

- All data is stored locally in `data/contexts.json`
- No network calls are made by the core logic
- No telemetry, no analytics, no external embeddings
- You fully control when to clear sessions
- MIT licensed – audit the code yourself

---

## 14. FAQ

**Q: Does this need an OpenAI / Anthropic key?**  
A: No. Scoring and search are pure heuristics.

**Q: Can I use it with Claude Desktop?**  
A: Yes. Just add the MCP config shown above.

**Q: Will compression delete my messages forever?**  
A: The current `compress_context` only returns a plan. It does not auto-write the reduced set unless you extend it.

**Q: How accurate is the token estimate?**  
A: It is a fast approximation (words + characters). Good enough for budgeting, not perfect.

**Q: Can I run multiple sessions?**  
A: Yes. Each `session_id` is completely independent.

---

## 15. Roadmap

- [ ] Optional real embedding-based semantic search (still local)
- [ ] Automatic compression when health score drops below threshold
- [ ] Export / import session snapshots
- [ ] Simple web dashboard for inspection
- [ ] Streaming support for very large histories
- [ ] Plugin system for custom scoring rules

---

## 16. Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Add tests if possible
4. Open a Pull Request

Please keep the spirit of the project: simple, local-first, and easy to understand.

---

## 17. License

MIT License © Prince Ruhul

---

<p align="center">
  Daily AI project for Prevalid · Built with ❤️ by Prince Ruhul
</p>