MCP Context Manager

MCP (Model Context Protocol) tools for context management in AI coding agents. Helps prevent out-of-context issues in long conversations.

Features

• Memory Store - Persistent key-value storage across sessions
• Context Summarizer - Summarize chat/text, extract key points, decisions, action items
• Project Tracker - Track decisions, changes, todos, notes, errors
• Session Checkpoint - Save/restore session state
• Smart File Loader - Load files with relevance filtering

Agent Skill (Recommended)

For optimal agent performance, use the included SKILL.md file as agent instructions. This skill teaches agents to:

• Minimize context window usage - Free up RAM by offloading data to persistent storage
• Auto-save progress - Checkpoint every 10-15 messages
• Track decisions & changes - Maintain project history
• Handle long sessions - Seamless handoff to new sessions when context gets full

How to Use the Skill

Option 1: Claude Code / Cline / Cursor Place SKILL.md in your project root or reference it in your agent configuration.

Option 2: Custom Agents Include the content of SKILL.md in your system prompt or agent instructions.

Option 3: Direct Reference Tell your agent: "Load and follow the instructions in SKILL.md"

The skill provides:

• Mandatory triggers for when to use each tool
• Context cleanup strategies to reduce LLM memory usage
• Best practices for minimal context consumption
• Complete tool reference with examples

Installation

Requires Node.js >= 18.0.0

# Run directly with npx (recommended)
npx @asd412id/mcp-context-manager

# Or install globally
npm install -g @asd412id/mcp-context-manager

Configuration by Client

Claude Desktop

Config file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

VS Code (GitHub Copilot / Claude Extension)

Option 1: Workspace config - .vscode/mcp.json

{
  "servers": {
    "context-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

Option 2: User settings - settings.json

{
  "mcp.servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

Cursor

Config file location:

• Windows: %APPDATA%\Cursor\mcp.json
• macOS: ~/Library/Application Support/Cursor/mcp.json
• Linux: ~/.config/Cursor/mcp.json

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

Windsurf

Config file location:

• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
• macOS: ~/.codeium/windsurf/mcp_config.json
• Linux: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  }
}

Cline (VS Code Extension)

Config file location:

• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Continue (VS Code / JetBrains Extension)

Config file: ~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "context-manager",
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"]
    }
  ]
}

Or using YAML (~/.continue/config.yaml):

mcpServers:
  - name: context-manager
    command: npx
    args:
      - "-y"
      - "@asd412id/mcp-context-manager"

OpenCode

Config file: opencode.json in your project root or ~/.config/opencode/config.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context-manager": {
      "type": "local",
      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
      "enabled": true
    }
  }
}

Zed Editor

Config file: ~/.config/zed/settings.json

{
  "context_servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {}
    }
  }
}

Custom Context Path

To specify a custom path for storing context data, add environment variables.

Claude Desktop / Cursor / Windsurf / Cline:

{
  "mcpServers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context-manager": {
      "type": "local",
      "command": ["npx", "-y", "@asd412id/mcp-context-manager"],
      "environment": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

Zed:

{
  "context_servers": {
    "context-manager": {
      "command": "npx",
      "args": ["-y", "@asd412id/mcp-context-manager"],
      "env": {
        "MCP_CONTEXT_PATH": "/path/to/your/project/.context"
      }
    }
  }
}

Prompts (Shortcut Commands)

| Prompt | Description | |--------|-------------| | ctx-init | Load context from previous session with context management instructions | | ctx-save | Save current state to checkpoint | | ctx-remember | Save important info to memory | | ctx-todo | Add a todo item | | ctx-decide | Log a decision | | ctx-status | Show project status | | ctx-compress | Compress long context | | ctx-recall | Search in memory | | ctx-cleanup | Free up context window space and reduce RAM usage | | ctx-handoff | Generate handoff document for new session |

Available Tools (33 tools)

Session Management

| Tool | Description | |------|-------------| | session_init | Initialize session - loads checkpoint, tracker, memories, detects project in ONE call | | session_handoff | Generate compact markdown handoff document for seamless session continuation | | project_detect | Auto-detect project info (supports 20+ languages: Node, Python, Rust, Go, Java, PHP, Ruby, Elixir, .NET, Swift, Kotlin, Dart, Haskell, Scala, Clojure, Lua, Zig, Nim, V, Deno, Bun) |

Memory Store

| Tool | Description | |------|-------------| | memory_set | Store key-value in memory | | memory_get | Retrieve value from memory | | memory_update | Partially update/merge existing memory value | | memory_search | Search memory by pattern/tags | | memory_delete | Delete memory entry | | memory_list | List all memory keys | | memory_clear | Clear memory (all/by tags) | | memory_cleanup | Remove expired memory entries | | memory_capture_candidates | Extract and optionally persist important memory candidates from text |

Context Summarizer

| Tool | Description | |------|-------------| | context_summarize | Summarize text, extract key points, decisions, action items | | context_get_summary | Get summary by ID | | context_list_summaries | List all summaries | | context_merge_summaries | Merge multiple summaries | | context_status | Get storage stats and token usage estimate | | context_prune_smart | Score context items, keep high-signal, summarize/prune low-signal | | store_health | Check store integrity and recommendations |

Project Tracker

| Tool | Description | |------|-------------| | tracker_log | Log decision/change/todo/note/error | | tracker_status | Get project status overview | | tracker_get | Get specific tracker entry by ID | | tracker_todo_update | Update todo status | | tracker_search | Search tracker entries | | tracker_set_project | Set project name | | tracker_export | Export tracker as markdown | | tracker_cleanup | Clean old entries, keep most recent |

Session Checkpoint

| Tool | Description | |------|-------------| | checkpoint_save | Save session state | | checkpoint_load | Load checkpoint | | checkpoint_list | List all checkpoints | | checkpoint_delete | Delete checkpoint | | checkpoint_compare | Compare 2 checkpoints |

Smart File Loader

| Tool | Description | |------|-------------| | file_smart_read | Read file with smart options (lines, keywords, structure) | | file_info | Get file metadata | | file_search_content | Search pattern in file | | file_list_dir | List directory files |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MCP_CONTEXT_PATH | Path to store context data | {cwd}/.context | | MCP_MAX_CHECKPOINTS | Max checkpoints before auto-cleanup | 50 | | MCP_MAX_SUMMARIES | Max summaries before auto-cleanup | 100 | | MCP_TRACKER_MAX_ENTRIES | Max tracker entries before rotation | 1000 | | MCP_TRACKER_ROTATE_KEEP | Entries to keep after rotation | 800 |

Usage Examples

Session Start Workflow

User: ctx-init
AI: *runs checkpoint_load(), tracker_status(), memory_list()*

Save Important Information

User: ctx-remember what:"API endpoint at https://api.example.com"
AI: *saves to memory with appropriate key and tags*

Before Ending Session

User: ctx-save name:"feature-login-done"
AI: *creates checkpoint with current state*

When Context Gets Long

User: Generate handoff for new session
AI: *runs session_handoff()* -> outputs compact markdown with all context
AI: Start a new conversation and paste this handoff, then run session_init()

Best Practices

1. Session start - Always run session_init() to load previous context
2. Save decisions - Use tracker_log(type:"decision") for important decisions
3. Track todos - Use tracker_log(type:"todo") for tasks to be done
4. Checkpoint regularly - Run checkpoint_save() every ~15-20 messages or after milestones
5. Handoff when long - Use session_handoff() when context >50%, then start new session

Data Storage

All data is stored in .context/ folder (default: working directory):

.context/
├── memory.json          # Memory store
├── tracker.json         # Project tracker
├── checkpoints/         # Session checkpoints
│   ├── index.json
│   └── cp_*.json
└── summaries/           # Context summaries
    └── index.json

Troubleshooting

Server not starting

1. Make sure Node.js >= 18 is installed: node --version
2. Try running manually: npx @asd412id/mcp-context-manager
3. Check if port/process conflicts exist

Tools not appearing

1. Restart your MCP client after configuration changes
2. Check config file syntax (valid JSON)
3. Verify the config file location is correct for your client

Permission issues

1. Ensure write access to the context path
2. Try setting explicit MCP_CONTEXT_PATH in env

License

MIT

Contributing

Issues and PRs welcome at GitHub

Release Notes Automation

This repository includes .github/release.yml to standardize generated release notes.

How to Create a Clean Release Note

Use GitHub auto-generated notes (CLI):

gh release create vX.Y.Z --target master --generate-notes

GitHub will automatically:

• Group changes by category (Features, Fixes, Security, Tests, Maintenance)
• Use a consistent bullet format
• Include contributor list

Safe Release Procedure (Required)

To avoid duplicate/dirty npm versions, follow this strict flow:

# 1) Ensure package version already final in package.json
node -p "require('./package.json').version"

# 2) Push commit first
git push origin master

# 3) Create release tag matching package version exactly
gh release create vX.Y.Z --target master --generate-notes

# 4) WAIT until publish workflow completes
gh run list --workflow publish.yml --limit 5
gh run watch <run-id> --exit-status

# 5) Verify npm registry
npm view @asd412id/mcp-context-manager version --registry=https://registry.npmjs.org
npm view @asd412id/[email protected] version --registry=https://registry.npmjs.org

Rules:

• Never create next release tag before previous publish run is finished
• Tag version must equal package.json version
• If publish run fails, fix root cause first; do not spam patch releases