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

$3

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

``bash


Run directly with npx (recommended)

npx @asd412id/mcp-context-manager

Or install globally

npm install -g @asd412id/mcp-context-manager
`

Configuration by Client

$3

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

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

$3

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

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

Option 2: User settings - settings.json

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

$3

Config file location:
- Windows: %APPDATA%\Cursor\mcp.json
- macOS: ~/Library/Application Support/Cursor/mcp.json
- Linux: ~/.config/Cursor/mcp.json

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

$3

Config file location:
- Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
- macOS: ~/.codeium/windsurf/mcp_config.json
- Linux: ~/.codeium/windsurf/mcp_config.json

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

$3

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

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

$3

Config file: ~/.continue/config.json

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

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

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

$3

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

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

$3

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

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

$3

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

Claude Desktop / Cursor / Windsurf / Cline:
`json
{
"mcpServers": {
"context-manager": {
"command": "npx",
"args": ["-y", "@asd412id/mcp-context-manager"],
"env": {
"MCP_CONTEXT_PATH": "/path/to/your/project/.context"
}
}
}
}
`

OpenCode:
`jsonc
{
"$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:
`json
{
"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 (31 tools)

$3

| 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) |

$3

| 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 |

$3

| 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 |
| store_health | Check store integrity and recommendations |

$3

| 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 |

$3

| 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 |

$3

| 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

$3

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

$3

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

$3

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

$3

`
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

$3

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

$3

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

$3

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