mcp-context-manager

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.

Related MCP server: claw-tsaver

2. Why this project exists

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

4. Architecture

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

# 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

{
  "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.

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

Example:

{
  "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).

Returns (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.

Returns (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.

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.

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.

Returns:
"Cleared session project-alpha"

7.8 ai_context_query

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

Returns: Ranked list of relevant messages with scores.

7.9 hybrid_search_context

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

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).

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).

Returns (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:

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

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

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

estimate_token_savings(session_id="demo", target_ratio=0.4)
compress_context(session_id="demo", target_ratio=0.4)

10. Use Cases

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

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