Context Travel MCP

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

# Run directly with npx
npx github:your-username/context-travel-mcp

# Or install globally
npm install -g github:your-username/context-travel-mcp

Claude Code Configuration

Add to your MCP settings (~/.claude/settings.json or project settings):

{
  "mcpServers": {
    "context-travel": {
      "command": "npx",
      "args": ["github:your-username/context-travel-mcp"]
    }
  }
}

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

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 fileReset = restore the file + append handoff messageHandoff = synthetic user message injected after restore

License

MIT