@yavdaanalytics/context-optimiser

A context window optimizer and session rotator MCP server for agentic workflows. It prevents LLMs/coding agents from running out of context window space by estimating token usage, compacting chat history using semantic failure clustering (Topic Attempt Graph - TAG), and rotating chat sessions dynamically while preserving session continuity links.

Features

1. Token Estimation: Heuristically counts and budgets tokens for a conversation.
2. Context Compaction: Uses semantic failure clustering (TAG) and heuristic offloading to shrink conversational history, offloading large code dumps/logs to disk or local ChromaDB.
3. Session Auto-Rotation: Dynamically rotates chat sessions when context limit thresholds are reached, updating next/previous session pointers for linked context history.
4. Local Vector Search: Stores offloaded messages in ChromaDB and retrieves them via semantic similarity search.

---

Quick Start

1. Installation

Install globally via npm:

npm install -g @yavdaanalytics/context-optimiser

2. Setup

Run the setup utility to configure the MCP server globally for Gemini, Cursor, and Claude Desktop, and copy the agent loading skills:

context-optimiser-setup

This will automatically configure:

• Gemini: ~/.gemini/settings.json
• Cursor: ~/.cursor/mcp.json
• Claude Desktop: ~/.claude/settings.json and %APPDATA%/Claude/claude_desktop_config.json
• Loader Skills: Copies SKILL.md to ~/.cursor/skills/context-optimiser/SKILL.md, ~/.claude/skills/context-optimiser/SKILL.md, and ~/.gemini/config/skills/context-optimiser/SKILL.md.

---

MCP Tools API

The server registers the following MCP tools for client use:

• estimate_tokens(conversation): Returns estimated token usage, capacity limits, and percentage used.
• compact_context(conversation, strategy, keep_last_n_turns): Returns compacted message history.
• rotate_session(conversation, origin_prompt, token_limit, threshold_pct): Returns rotated session metadata and compacted history.
• get_current_session(): Returns active session JSON metadata.
• query_vector_store(query_text, n_results): Performs semantic vector similarity queries on offloaded history.

Development & Local Testing

If you are developing locally, run setup in local mode to link the configuration to your checkout directory:

node bin/setup.js --local

Run Tests

To verify all tool integrations and ChromaDB vector queries:

python scratch/test_tools.py