# Claude Continuity MCP Server

A Model Context Protocol (MCP) server that provides persistent memory and conversation continuity for Claude Desktop and Claude Code. Never lose your project context again when threads hit token limits.

## Features

- 🔄 **Automatic State Persistence** - Saves project context and conversation state
- ⚡ **Seamless Restoration** - Instantly restore full context when starting new threads  
- 🔒 **Privacy First** - All data stored locally in `~/.claude_states`
- 📊 **Multi-Project Support** - Manage multiple concurrent projects
- 🗂️ **Smart Organization** - Automatic backup rotation and state management
- 🎯 **Zero Configuration** - Works immediately after setup

## Installation

### 1. Clone or Download

```bash
# Clone to your home directory
cd ~
git clone https://github.com/yourusername/claude-continuity.git

# Or download and extract the files
```

### 2. Install Dependencies

```bash
cd ~/claude-continuity
pip3 install mcp
```

### 3. Configure Claude Desktop

Edit your Claude Desktop configuration:
- **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:

```json
{
  "mcpServers": {
    "claude-continuity": {
      "command": "/opt/homebrew/bin/python3.11",
      "args": ["/Users/yourusername/claude-continuity/server.py"],
      "env": {}
    }
  }
}
```

### 4. Configure Claude Code

Run this command to add globally:

```bash
claude mcp add --scope user claude-continuity python3 ~/claude-continuity/server.py
```

## Usage

### Available Tools

| Tool | Description |
|------|-------------|
| `save_project_state` | Save current project context and state |
| `load_project_state` | Restore saved project context |
| `list_active_projects` | View all tracked projects |
| `get_project_summary` | Get quick overview without loading full state |
| `delete_project_state` | Remove project (with safety confirmation) |
| `update_project_context` | Update just context/metadata |

### Example Usage

**Save Project State:**
```
save_project_state: 
  project_name="my-web-app"
  state={current work and context}
  summary="Setting up authentication system"
  context={files_modified, issues, next_steps}
```

**Load Project State:**
```
load_project_state: project_name="my-web-app"
```

**List All Projects:**
```
list_active_projects
```

## Data Storage

All project states are stored locally at:
```
~/.claude_states/
├── project-name-1/
│   ├── state.json
│   ├── summary.txt
│   └── state.backup.*.json
└── project-name-2/
    ├── state.json
    ├── summary.txt
    └── state.backup.*.json
```

### State Structure

Each saved state includes:
```json
{
  "project_name": "my-project",
  "state": {
    // Your custom state object
  },
  "summary": "Human-readable summary",
  "context": {
    "files_modified": [],
    "issues": [],
    "next_steps": [],
    "dependencies": []
  },
  "updated_at": "2025-08-05T22:48:00Z",
  "version": 1
}
```

## Troubleshooting

### Server Not Connecting

1. Check Python installation:
```bash
python3 --version
# Should be 3.8 or higher
```

2. Test server directly:
```bash
python3 ~/claude-continuity/server.py
# Should show: "Claude Continuity Server initialized..."
```

3. Check Claude Desktop logs for errors

### Permission Issues

```bash
chmod +x ~/claude-continuity/server.py
```

### Python Path Issues

Update config to use full Python path:
```json
{
  "command": "/usr/bin/python3",
  "args": ["/Users/yourusername/claude-continuity/server.py"]
}
```

## Requirements

- Python 3.8+
- MCP SDK (`pip install mcp`)
- Claude Desktop or Claude Code

## Project Structure

```
claude-continuity/
├── server.py           # Main MCP server
├── requirements.txt    # Python dependencies
├── README.md          # This file
├── LICENSE            # MIT License
└── .gitignore         # Git ignore file
```

## How It Works

1. **Automatic Detection**: Server monitors conversation for project-related activities
2. **Smart Saving**: Automatically creates backups before overwriting states
3. **Context Preservation**: Maintains files, decisions, issues, and next steps
4. **Seamless Recovery**: Load entire project context with one command

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Test your changes
4. Submit a pull request

## License

MIT License - see LICENSE file for details

## Author

Created for the Claude community to solve the context loss problem once and for all.

## Support

For issues or questions:
- Open an issue on GitHub
- Check existing issues for solutions

---

**Before**: 😫 Hit token limit → Lose all context → Re-explain everything  
**After**: 😎 Hit token limit → Start new thread → `load_project_state` → Continue seamlessly