MCP Memory Keeper - Claude Code Context Management

A Model Context Protocol (MCP) server that provides persistent context management for Claude AI coding assistants. Never lose context during compaction again! This MCP server helps Claude Code maintain context across sessions, preserving your work history, decisions, and progress.

🚀 Quick Start

Get started in under 30 seconds:

# Add memory-keeper to Claude
claude mcp add memory-keeper npx mcp-memory-keeper

# Start a new Claude session and use it!
# Try: Analyze the current repo and save your analysis in memory-keeper

That's it! Memory Keeper is now available in all your Claude sessions. Your context is stored in ~/mcp-data/memory-keeper/ and persists across sessions.

🚀 Practical Memory Keeper Workflow Example

Custom Command + CLAUDE.md = Automatic Context Management

CLAUDE.md (condensed example)

# Project Configuration

## Development Rules

- Always use memory-keeper to track progress
- Save architectural decisions and test results
- Create checkpoints before context limits

## Quality Standards

- All tests must pass before marking complete
- Document actual vs claimed results

Custom Command Example: /my-dev-workflow

# My Development Workflow

When working on the provided project:

- Use memory-keeper with channel: <project_name>
- Save progress at every major milestone
- Document all decisions with category: "decision"
- Track implementation status with category: "progress"
- Before claiming anything is complete, save test results

## Workflow Steps

1. Initialize session with project name as channel
2. Save findings during investigation
3. Create checkpoint before major changes
4. Document what actually works vs what should work

Usage Example

User: /my-dev-workflow authentication-service

AI: Setting up workflow for authentication-service.
[Uses memory-keeper with channel "authentication-service"]

[... AI works, automatically saving context ...]

User: "Getting close to context limit. Create checkpoint and give me a key"

AI: "Checkpoint created: authentication-service-checkpoint-20250126-143026"

[Continue working until context reset or compact manually]

User: "Restore from key: authentication-service-checkpoint-20250126-143026"

AI: "Restored! Continuing OAuth implementation. We completed the token validation, working on refresh logic..."

The Pattern:

1. Custom command includes instructions to use memory-keeper
2. AI follows those instructions automatically
3. When you notice the conversation getting long, YOU ask Claude to save a checkpoint (like saving your game before a boss fight!)
4. When Claude runs out of space and starts fresh, YOU tell it to restore using the checkpoint key

🎯 Key Feature: Memory Keeper is a shared board! You can:

• Continue in the same session after reset
• Start a completely new session and restore
• Have multiple Claude sessions running in parallel, all sharing the same memory
• One session can save context that another session retrieves

This enables powerful workflows like having one Claude session doing research while another implements code, both sharing discoveries through Memory Keeper!

Why MCP Memory Keeper?

Claude Code users often face context loss when the conversation window fills up. This MCP server solves that problem by providing a persistent memory layer for Claude AI. Whether you're working on complex refactoring, multi-file changes, or long debugging sessions, Memory Keeper ensures your Claude assistant remembers important context, decisions, and progress.

Perfect for:

• Long coding sessions with Claude Code
• Complex projects requiring context preservation
• Teams using Claude AI for collaborative development
• Developers who want persistent context across Claude sessions

Features

• 🔄 Save and restore context between Claude Code sessions
• 📁 File content caching with change detection
• 🏷️ Organize context with categories and priorities
• 📺 Channels - Persistent topic-based organization (auto-derived from git branch)
• 📸 Checkpoint system for complete context snapshots
• 🤖 Smart compaction helper that never loses critical info
• 🔍 Full-text search across all saved context
• 🕐 Enhanced filtering - Time-based queries, regex patterns, pagination
• 📊 Change tracking - See what's been added, modified, or deleted since any point
• 💾 Export/import for backup and sharing
• 🌿 Git integration with automatic context correlation
• 📊 AI-friendly summarization with priority awareness
• 🚀 Fast SQLite-based storage optimized for Claude
• 🔁 Batch operations - Save, update, or delete multiple items atomically
• 🔄 Channel reassignment - Move items between channels based on patterns
• 🔗 Context relationships - Link related items with typed relationships
• 👁️ Real-time monitoring - Watch for context changes with filters

Installation

Recommended: NPX Installation

claude mcp add memory-keeper npx mcp-memory-keeper

This single command:

• ✅ Always uses the latest version
• ✅ Handles all dependencies automatically
• ✅ Works across macOS, Linux, and Windows
• ✅ No manual building or native module issues

Alternative Installation Methods

npm install -g mcp-memory-keeper
claude mcp add memory-keeper mcp-memory-keeper

# 1. Clone the repository
git clone https://github.com/mkreyman/mcp-memory-keeper.git
cd mcp-memory-keeper

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Add to Claude
claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper

Configuration

Environment Variables

Storage and Installation

• DATA_DIR - Directory for database storage (default: ~/mcp-data/memory-keeper/)
• MEMORY_KEEPER_INSTALL_DIR - Installation directory (default: ~/.local/mcp-servers/memory-keeper/)
• MEMORY_KEEPER_AUTO_UPDATE - Set to 1 to enable auto-updates

Token Limit Configuration

• MCP_MAX_TOKENS - Maximum tokens allowed in responses (default: 25000, range: 1000-100000)
  • Adjust this if your MCP client has different limits
• MCP_TOKEN_SAFETY_BUFFER - Safety buffer percentage (default: 0.8, range: 0.1-1.0)
  • Uses only this fraction of the max tokens to prevent overflows
• MCP_MIN_ITEMS - Minimum items to return even if exceeding limits (default: 1, range: 1-100)
  • Ensures at least some results are returned
• MCP_MAX_ITEMS - Maximum items allowed per response (default: 100, range: 10-1000)
  • Upper bound for result sets regardless of token limits
• MCP_CHARS_PER_TOKEN - Characters per token ratio (default: 3.5, range: 2.5-5.0) [Advanced]
  • Adjusts token estimation accuracy for different content types
  • Lower values = more conservative (safer but returns fewer items)
  • Higher values = more aggressive (returns more items but risks overflow)

Example configuration for stricter token limits:

export MCP_MAX_TOKENS=20000        # Lower max tokens
export MCP_TOKEN_SAFETY_BUFFER=0.7  # More conservative buffer
export MCP_MAX_ITEMS=50             # Fewer items per response
export MCP_CHARS_PER_TOKEN=3.0      # More conservative estimation (optional)

Tool Profiles

By default, all 38 tools are exposed. To reduce context overhead in your AI assistant, you can activate a tool profile that limits which tools are available.

Quick usage:

# Essential tools only (8 tools)
TOOL_PROFILE=minimal npx mcp-memory-keeper

# Standard workflow set (22 tools)
TOOL_PROFILE=standard npx mcp-memory-keeper

# All tools (default)
TOOL_PROFILE=full npx mcp-memory-keeper

Built-in profiles:

Custom profiles via config file:

Create ~/.mcp-memory-keeper/config.json to define or override profiles:

{
  "profiles": {
    "my_workflow": [
      "context_session_start",
      "context_save",
      "context_get",
      "context_search",
      "context_checkpoint",
      "context_restore_checkpoint",
      "context_diff",
      "context_timeline"
    ]
  }
}

Then activate it: TOOL_PROFILE=my_workflow npx mcp-memory-keeper

Config file profiles take precedence over built-in defaults with the same name.

Profile resolution precedence: