claude-thread-continuity
๐ง Keep your Claude conversations flowing! An MCP server that automatically saves and restores project context when threads hit token limits.
GitHub Stars
22
User Rating
Not Rated
Forks
0
Issues
0
Views
1
Favorites
0
๐ง Claude Thread Continuity MCP Server
Never lose context again! This MCP server automatically saves and restores project state when Claude threads hit token limits, ensuring seamless conversation continuity.
๐ Features
- ๐ Automatic State Persistence - Auto-saves project context during conversations
- โก Seamless Restoration - Instantly restore full context when starting new threads
- ๐ก๏ธ Smart Validation - Prevents project fragmentation with intelligent name checking
- ๐ Privacy First - All data stored locally on your machine
- ๐ฏ Zero Configuration - Works invisibly once set up
- ๐ Smart Triggers - Auto-saves on file changes, decisions, milestones
- ๐๏ธ Multi-Project Support - Manage multiple concurrent projects
โจ NEW: Anti-Fragmentation System
Version 1.1 introduces intelligent project validation to prevent the common issue of accidentally creating multiple similar projects:
- ๐ Fuzzy Name Matching - Detects similar project names (70% similarity threshold)
- โ ๏ธ Validation Warnings - Suggests consolidation when similar projects exist
- ๐ช Force Override - Bypass validation when genuinely different projects needed
- ๐ฏ Configurable Thresholds - Adjust sensitivity for your workflow
Example Validation in Action
โ Project "Hebrew Speaking Evaluation MVP" blocked
โ
Similar project found: "Hebrew Evaluation MVP" (85% similar)
๐ฏ Recommendation: Update existing project or use force=true
โก Quick Start
# 1. Clone the repository
git clone https://github.com/peless/claude-thread-continuity.git
cd claude-thread-continuity
# 2. Install dependencies
pip install -r requirements.txt
# 3. Test the enhanced server
python3 test_server.py
# 4. Add to Claude Desktop config
# See setup instructions below
๐ ๏ธ Installation
1. Install the MCP Server
# Create permanent directory
mkdir -p ~/.mcp-servers/claude-continuity
cd ~/.mcp-servers/claude-continuity
# Copy files (or clone repo to this location)
# Place server.py and requirements.txt here
2. Configure Claude Desktop
Edit your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\\Claude\\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"claude-continuity": {
"command": "python3",
"args": ["~/.mcp-servers/claude-continuity/server.py"],
"env": {}
}
}
}
3. Restart Claude Desktop
Close and reopen Claude Desktop. The continuity tools will now be available automatically.
๐ฏ How It Works
Automatic Context Saving
The server automatically saves project state when:
- โ Files are created or modified
- โ Technical decisions are made
- โ Project milestones are reached
- โ Every 10 messages (fallback)
Smart Validation Process
Before saving, the system:
- Checks for Similar Names - Uses fuzzy matching to find existing projects
- Calculates Similarity - Compares project names with 70% threshold
- Provides Recommendations - Suggests consolidation or renaming
- Allows Override - Use
force: true
for edge cases
Context Restoration
When starting a new thread:
- Load Project:
load_project_state: project_name="your-project"
- Full Context Restored: All technical decisions, files, and progress restored
- Continue Seamlessly: Pick up exactly where you left off
๐ง Available Commands
Command | Description | NEW in v1.1 |
---|---|---|
save_project_state |
Save current project state | โจ Now with validation |
load_project_state |
Restore full project context | |
list_active_projects |
View all tracked projects | |
get_project_summary |
Get quick project overview | |
validate_project_name |
Check for similar project names | โจ NEW |
auto_save_checkpoint |
Triggered automatically |
๐ก Usage Examples
Starting a New Project (with Validation)
save_project_state: project_name="my-web-app", current_focus="Setting up React components", technical_decisions=["Using TypeScript", "Vite for bundling"], next_actions=["Create header component", "Set up routing"]
Checking Name Before Creating
validate_project_name: project_name="my-webapp", similarity_threshold=0.7
Force Override When Needed
save_project_state: project_name="my-web-app-v2", force=true, current_focus="Starting version 2"
Continuing After Token Limit
load_project_state: project_name="my-web-app"
Viewing All Projects
list_active_projects
๐๏ธ Data Storage
Project states are stored locally at:
~/.claude_states/
โโโ project-name-1/
โ โโโ current_state.json
โ โโโ backup_*.json
โโโ project-name-2/
โโโ current_state.json
โโโ backup_*.json
- Privacy: Everything stays on your machine
- Backups: Automatic backup rotation (keeps last 5)
- Format: Human-readable JSON files
- Validation: Metadata tracks validation bypass status
๐๏ธ Project State Structure
Each saved state includes:
{
"project_name": "my-project",
"current_focus": "What you're working on now",
"technical_decisions": ["Key choices made"],
"files_modified": ["List of files created/changed"],
"next_actions": ["Planned next steps"],
"conversation_summary": "Brief context summary",
"last_updated": "2025-06-15T10:30:00Z",
"version": "1.1",
"validation_bypassed": false
}
๐ก๏ธ Validation Configuration
Default Settings
- Similarity Threshold: 70% (0.7)
- Comparison Method: Fuzzy string matching
- Auto-save Behavior: Bypasses validation (uses
force=true
)
Customizing Validation
validate_project_name: project_name="test-project", similarity_threshold=0.8
Higher threshold = stricter matching (0.9 = 90% similar required) Lower threshold = looser matching (0.5 = 50% similar triggers warning)
๐ Troubleshooting
Tools Not Appearing
- Check Claude Desktop logs
- Verify Python 3 is in your PATH:
python3 --version
- Validate JSON config syntax
- Restart Claude Desktop completely
Testing the Enhanced Server
cd ~/.mcp-servers/claude-continuity
python3 test_server.py
The test suite now includes validation testing and will report:
- โ Basic functionality tests
- โ Project validation tests
- โ Fuzzy matching accuracy
- โ Force override functionality
Common Issues
Validation Too Strict:
Lower the similarity threshold or use force=true
Permission Errors:
chmod +x ~/.mcp-servers/claude-continuity/server.py
Python Path Issues: Update the config to use full Python path:
{
"command": "/usr/bin/python3",
"args": ["~/.mcp-servers/claude-continuity/server.py"]
}
๐งช Development
Requirements
- Python 3.8+
- MCP SDK 1.0+
- difflib (built-in, for fuzzy matching)
Running Tests
python3 test_server.py
Enhanced test suite includes:
- Basic functionality validation
- NEW: Project name similarity testing
- NEW: Validation workflow testing
- NEW: Force override testing
- NEW: MCP tool validation
Project Structure
claude-thread-continuity/
โโโ server.py # Main MCP server (enhanced with validation)
โโโ requirements.txt # Python dependencies
โโโ test_server.py # Comprehensive test suite
โโโ README.md # This file
โโโ LICENSE # MIT License
โโโ examples/ # Usage examples
๐ค Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Submit a pull request
Current Development Priorities
- Integration with external project management tools
- Advanced similarity algorithms
- Project merging utilities
- Custom validation rules
๐ License
MIT License - see LICENSE file for details.
๐ Why This Matters
Before v1.1: ๐ซ Hit token limit โ Lose all context โ Re-explain everything โ Lose momentum
Common Problem: ๐ค Create "Hebrew MVP", then "Hebrew Evaluation MVP", then "Hebrew Speaking MVP" โ Context scattered across multiple projects
After v1.1: ๐ Hit token limit โ Start new thread โ load_project_state
โ Continue seamlessly + Smart validation prevents fragmentation
Perfect for:
- ๐๏ธ Complex Development Projects - Keep track of architecture decisions without fragmentation
- ๐ Learning & Research - Maintain context across study sessions with consistent naming
- โ๏ธ Writing Projects - Remember plot points without creating duplicate character projects
- ๐ง Multi-session Debugging - Preserve debugging state with clear project organization
๐ Version History
v1.1.0 (Current)
- โจ Project Validation System - Prevents fragmentation with fuzzy name matching
- โจ validate_project_name tool - Manual name checking
- โจ Force Override capability - Bypass validation when needed
- โจ Enhanced Testing - Comprehensive validation test suite
- ๐ Bug Fixes - Improved error handling and edge cases
v1.0.0
- ๐ Initial release with core continuity functionality
Built with โค๏ธ for the Claude community
Tired of fragmented projects? Version 1.1 keeps your context organized!