# Context Travel MCP
An MCP server that gives Claude agents conscious control over their context lifecycle through "time travel"—the ability to checkpoint their mental state and later reset back to it with a message to their future self.
## Why?
After multiple compactions, agents become confused by fragmented summaries. The "golden window" is right after orientation when understanding is complete and context is clean. This MCP lets agents:
1. **Checkpoint** that golden state
2. Work on complex tasks
3. **Reset** back to the checkpoint with a handoff note
4. Continue fresh, with full fidelity
## Installation
```bash
# Run directly with npx
npx -y github:simen/mcp-memento
# Or install globally
npm install -g github:simen/mcp-memento
```
## Claude Code Configuration
Add to your MCP settings (`~/.claude/settings.json` or project settings):
```json
{
"mcpServers": {
"memento": {
"command": "npx",
"args": ["-y", "github:simen/mcp-memento"]
}
}
}
```
## Tools
### `checkpoint_context`
Save your current context state as a named checkpoint.
```
checkpoint_context(name: "oriented", note?: "Understood the auth system")
```
**When to use:**
- After fully understanding a codebase or task
- Before starting a large, context-heavy operation
- When you feel sharp and well-oriented
### `reset_to_checkpoint`
Reset context to a checkpoint, injecting a handoff message to your future self.
```
reset_to_checkpoint(
name: "oriented",
message_to_self: "Bug fixed in auth/refresh.ts:142. Next: implement caching layer."
)
```
**The message_to_self should include:**
- What was accomplished since the checkpoint
- Key findings and decisions
- Clear next steps
- Critical details (file paths, variable names, gotchas)
### `list_checkpoints`
Show available checkpoints for the current session.
### `get_context_stats`
Get statistics about your current context window health:
- Turn counts
- Estimated tokens
- Compaction events
- Health indicator
### `delete_checkpoint`
Remove a checkpoint you no longer need.
## System Prompt Integration
Add to your agent's system prompt:
```
## Context Time Travel
You have tools for managing your own context window:
- `checkpoint_context(name)` — Save your current mental state
- `reset_to_checkpoint(name, message_to_self)` — Jump back with a note to yourself
- `list_checkpoints()` — See available restore points
- `get_context_stats()` — Check context health
**Good checkpoint moments:**
- After fully understanding a task or codebase
- Before starting a large exploration or refactor
- When you feel well-oriented and productive
**When to reset:**
- Context feels cluttered with old explorations
- You've completed a major task and want fresh space
- You notice confusion from summarized context
**Writing message_to_self:**
Write as if briefing a colleague taking over. Include what you did, key decisions, and specific next steps.
```
## Session Discovery
The MCP discovers the current session via (in order):
1. `CLAUDE_SESSION_ID` environment variable
2. `~/.claude/debug/latest` symlink
3. Most recent `.jsonl` in the PWD-based project directory
## Environment Variables
| Variable | Description |
|----------|-------------|
| `CLAUDE_SESSION_ID` | Explicit session ID |
| `CLAUDE_PROJECTS_DIR` | Override projects directory (default: `~/.claude/projects`) |
| `CLAUDE_CHECKPOINTS_DIR` | Override checkpoints directory (default: `~/.claude/checkpoints`) |
## How It Works
Claude Code stores sessions as JSONL files at `~/.claude/projects/<escaped-cwd>/<session-id>.jsonl`. Each line is a JSON object representing a message, tool use, or summary.
**Checkpoint** = copy the session file
**Reset** = restore the file + append handoff message
**Handoff** = synthetic user message injected after restore
## License
MIT
