Memory Keeper
STDIOMCP server providing persistent context management for Claude AI coding sessions
MCP server providing persistent context management for Claude AI coding sessions
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.
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.
# 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
/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
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:
🎯 Key Feature: Memory Keeper is a shared board! You can:
This enables powerful workflows like having one Claude session doing research while another implements code, both sharing discoveries through 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.
claude mcp add memory-keeper npx mcp-memory-keeper
This single command:
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 node /absolute/path/to/mcp-memory-keeper/dist/index.js
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-updatesChoose where to save the configuration:
# Project-specific (default) - only for you in this project claude mcp add memory-keeper npx mcp-memory-keeper # Shared with team via .mcp.json claude mcp add --scope project memory-keeper npx mcp-memory-keeper # Available across all your projects claude mcp add --scope user memory-keeper npx mcp-memory-keeper
# List all configured servers claude mcp list # Get details for Memory Keeper claude mcp get memory-keeper
{ "mcpServers": { "memory-keeper": { "command": "npx", "args": ["mcp-memory-keeper"] } } }
That's it! No paths needed - npx automatically handles everything.
mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" })claude mcp list # Should show memory-keeper as "running"
If Memory Keeper isn't working:
# Remove and re-add the server claude mcp remove memory-keeper claude mcp add memory-keeper npx mcp-memory-keeper # Check logs for errors # The server output will appear in Claude Code's output panel
With the npx installation method, you automatically get the latest version every time! No manual updates needed.
If you're using the global installation method:
# Update to latest version npm update -g mcp-memory-keeper # Start a new Claude session # The updated features will be available immediately
Note: You don't need to reconfigure the MCP server in Claude after updating. Just start a new session!
// Start a new session mcp_context_session_start({ name: 'Feature Development', description: 'Working on user authentication', }); // Start a session with project directory for git tracking mcp_context_session_start({ name: 'Feature Development', description: 'Working on user authentication', projectDir: '/path/to/your/project', }); // Start a session with a default channel mcp_context_session_start({ name: 'Feature Development', description: 'Working on user authentication', projectDir: '/path/to/your/project', defaultChannel: 'auth-feature', // Will auto-derive from git branch if not specified }); // Set project directory for current session mcp_context_set_project_dir({ projectDir: '/path/to/your/project', }); // List recent sessions mcp_context_session_list({ limit: 5 }); // Continue from a previous session mcp_context_session_start({ name: 'Feature Dev Continued', continueFrom: 'previous-session-id', });
Channels provide persistent topic-based organization that survives session crashes and restarts:
// Channels are auto-derived from git branch (if projectDir is set) // Branch "feature/auth-system" becomes channel "feature-auth-system" (20 chars max) // Save to a specific channel mcp_context_save({ key: 'auth_design', value: 'Using JWT with refresh tokens', category: 'decision', priority: 'high', channel: 'auth-feature', // Explicitly set channel }); // Get items from a specific channel mcp_context_get({ channel: 'auth-feature' }); // Get items across all channels (default behavior) mcp_context_get({ category: 'task' }); // Channels persist across sessions - perfect for: // - Multi-branch development // - Feature-specific context // - Team collaboration on different topics
// Save with categories and priorities mcp_context_save({ key: 'current_task', value: 'Implement OAuth integration', category: 'task', priority: 'high', }); // Save decisions mcp_context_save({ key: 'auth_strategy', value: 'Using JWT tokens with 24h expiry', category: 'decision', priority: 'high', }); // Save progress notes mcp_context_save({ key: 'progress_auth', value: 'Completed user model, working on token generation', category: 'progress', priority: 'normal', }); // Retrieve by category mcp_context_get({ category: 'task' }); // Retrieve specific item mcp_context_get({ key: 'current_task' }); // Get context from specific session mcp_context_get({ sessionId: 'session-id-here', category: 'decision', }); // Enhanced filtering (NEW in v0.10.0) mcp_context_get({ category: 'task', priorities: ['high', 'normal'], includeMetadata: true, // Get timestamps, size info sort: 'created_desc', // created_asc/desc, updated_asc/desc, priority limit: 10, // Pagination offset: 0, }); // Time-based queries (NEW in v0.10.0) mcp_context_get({ createdAfter: '2025-01-20T00:00:00Z', createdBefore: '2025-01-26T23:59:59Z', includeMetadata: true, }); // Pattern matching (NEW in v0.10.0) mcp_context_get({ keyPattern: 'auth_.*', // Regex to match keys category: 'decision', });
// Cache file content for change detection mcp_context_cache_file({ filePath: '/src/auth/user.model.ts', content: fileContent, }); // Check if file has changed mcp_context_file_changed({ filePath: '/src/auth/user.model.ts', currentContent: newFileContent, }); // Get current session status mcp_context_status();
// 1. Start a new session mcp_context_session_start({ name: 'Settings Refactor', description: 'Refactoring settings module for better performance', }); // 2. Save high-priority task mcp_context_save({ key: 'main_task', value: 'Refactor Settings.Context to use behaviors', category: 'task', priority: 'high', }); // 3. Cache important files mcp_context_cache_file({ filePath: 'lib/settings/context.ex', content: originalFileContent, }); // 4. Save decisions as you work mcp_context_save({ key: 'architecture_decision', value: 'Split settings into read/write modules', category: 'decision', priority: 'high', }); // 5. Track progress mcp_context_save({ key: 'progress_1', value: 'Completed behavior definition, 5 modules remaining', category: 'progress', priority: 'normal', }); // 6. Before context window fills up mcp_context_status(); // Check what's saved // 7. After Claude Code restart mcp_context_get({ category: 'task', priority: 'high' }); // Get high priority tasks mcp_context_get({ key: 'architecture_decision' }); // Get specific decisions mcp_context_file_changed({ filePath: 'lib/settings/context.ex' }); // Check for changes
Create named snapshots of your entire context that can be restored later:
// Create a checkpoint before major changes mcp_context_checkpoint({ name: 'before-refactor', description: 'State before major settings refactor', includeFiles: true, // Include cached files includeGitStatus: true, // Capture git status }); // Continue working... // If something goes wrong, restore from checkpoint mcp_context_restore_checkpoint({ name: 'before-refactor', restoreFiles: true, // Restore cached files too }); // Or restore the latest checkpoint mcp_context_restore_checkpoint({});
Get AI-friendly summaries of your saved context:
// Get a summary of all context mcp_context_summarize(); // Get summary of specific categories mcp_context_summarize({ categories: ['task', 'decision'], maxLength: 2000, }); // Summarize a specific session mcp_context_summarize({ sessionId: 'session-id-here', categories: ['progress'], });
Example summary output:
# Context Summary ## High Priority Items - **main_task**: Refactor Settings.Context to use behaviors - **critical_bug**: Fix memory leak in subscription handler ## Task - implement_auth: Add OAuth2 authentication flow - update_tests: Update test suite for new API ## Decision - architecture_decision: Split settings into read/write modules - db_choice: Use PostgreSQL for better JSON support
Perform multiple operations atomically:
// Save multiple items at once mcp_context_batch_save({ items: [ { key: 'config_api_url', value: 'https://api.example.com', category: 'note' }, { key: 'config_timeout', value: '30000', category: 'note' }, { key: 'config_retries', value: '3', category: 'note' }, ], }); // Update multiple items mcp_context_batch_update({ updates: [ { key: 'task_1', priority: 'high' }, { key: 'task_2', priority: 'high' }, { key: 'task_3', value: 'Updated task description' }, ], }); // Delete by pattern mcp_context_batch_delete({ keyPattern: 'temp_*', dryRun: true, // Preview first });
Reorganize context items between channels:
// Move items to a new channel mcp_context_reassign_channel({ keyPattern: 'auth_*', toChannel: 'feature-authentication', }); // Move from one channel to another mcp_context_reassign_channel({ fromChannel: 'sprint-14', toChannel: 'sprint-15', category: 'task', priorities: ['high'], });
Build a graph of related items:
// Link related items mcp_context_link({ sourceKey: 'epic_user_management', targetKey: 'task_create_user_api', relationship: 'contains', }); // Find related items mcp_context_get_related({ key: 'epic_user_management', relationship: 'contains', depth: 2, });
Watch for context changes:
// Create a watcher const watcher = await mcp_context_watch({ action: 'create', filters: { categories: ['task'], priorities: ['high'], }, }); // Poll for changes const changes = await mcp_context_watch({ action: 'poll', watcherId: watcher.watcherId, });
Never lose critical context when Claude's window fills up:
// Before context window fills mcp_context_prepare_compaction(); // This automatically: // - Creates a checkpoint // - Identifies high-priority items // - Captures unfinished tasks // - Saves all decisions // - Generates a summary // - Prepares restoration instructions
Track git changes in your project directory and save context with commits:
// First, set your project directory (if not done during session start) mcp_context_set_project_dir({ projectDir: '/path/to/your/project', }); // Commit with auto-save mcp_context_git_commit({ message: 'feat: Add user authentication', autoSave: true, // Creates checkpoint with commit }); // Context is automatically linked to the commit // Note: If no project directory is set, you'll see a helpful message // explaining how to enable git tracking for your project
Find anything in your saved context:
// Search in keys and values mcp_context_search({ query: 'authentication' }); // Search only in keys mcp_context_search({ query: 'config', searchIn: ['key'], }); // Search in specific session mcp_context_search({ query: 'bug', sessionId: 'session-id', });
Share context or backup your work:
// Export current session mcp_context_export(); // Creates memory-keeper-export-xxx.json // Export specific session mcp_context_export({ sessionId: 'session-id', format: 'json', }); // Import from file mcp_context_import({ filePath: 'memory-keeper-export-xxx.json', }); // Merge into current session mcp_context_import({ filePath: 'backup.json', merge: true, });
Automatically extract entities and relationships from your context:
// Analyze context to build knowledge graph mcp_context_analyze(); // Or analyze specific categories mcp_context_analyze({ categories: ['task', 'decision'], }); // Find related entities mcp_context_find_related({ key: 'AuthService', maxDepth: 2, }); // Generate visualization data mcp_context_visualize({ type: 'graph', }); // Timeline view mcp_context_visualize({ type: 'timeline', }); // Category/priority heatmap mcp_context_visualize({ type: 'heatmap', });
Find context using natural language queries:
// Search with natural language mcp_context_semantic_search({ query: 'how are we handling user authentication?', topK: 5, }); // Find the most relevant security decisions mcp_context_semantic_search({ query: 'security concerns and decisions', minSimilarity: 0.5, }); // Search with specific similarity threshold mcp_context_semantic_search({ query: 'database performance optimization', topK: 10, minSimilarity: 0.3, });
Delegate complex analysis tasks to specialized agents:
// Analyze patterns in your context mcp_context_delegate({ taskType: 'analyze', input: { analysisType: 'patterns', categories: ['task', 'decision'], }, }); // Get comprehensive analysis mcp_context_delegate({ taskType: 'analyze', input: { analysisType: 'comprehensive', }, }); // Analyze relationships between entities mcp_context_delegate({ taskType: 'analyze', input: { analysisType: 'relationships', maxDepth: 3, }, }); // Create intelligent summaries mcp_context_delegate({ taskType: 'synthesize', input: { synthesisType: 'summary', maxLength: 1000, }, }); // Get actionable recommendations mcp_context_delegate({ taskType: 'synthesize', input: { synthesisType: 'recommendations', analysisResults: {}, // Can pass previous analysis results }, }); // Chain multiple agent tasks mcp_context_delegate({ chain: true, taskType: ['analyze', 'synthesize'], input: [{ analysisType: 'comprehensive' }, { synthesisType: 'recommendations' }], });
Agent Types:
Explore alternatives without losing your original work:
// Create a branch to try something new mcp_context_branch_session({ branchName: 'experimental-refactor', copyDepth: 'shallow', // Only copy high-priority items }); // Or create a full copy mcp_context_branch_session({ branchName: 'feature-complete-copy', copyDepth: 'deep', // Copy everything }); // Later, merge changes back mcp_context_merge_sessions({ sourceSessionId: 'branch-session-id', conflictResolution: 'keep_newest', // or "keep_current", "keep_source" });
Track your thoughts and progress with timestamped journal entries:
// Add a journal entry mcp_context_journal_entry({ entry: 'Completed the authentication module. Tests are passing!', tags: ['milestone', 'authentication'], mood: 'accomplished', }); // Entries are included in timeline views mcp_context_timeline({ groupBy: 'day', });
Visualize your work patterns over time:
// Get activity timeline mcp_context_timeline({ startDate: '2024-01-01', endDate: '2024-01-31', groupBy: 'day', // or "hour", "week" }); // Enhanced timeline (NEW in v0.10.0) mcp_context_timeline({ groupBy: 'hour', includeItems: true, // Show actual items, not just counts categories: ['task', 'progress'], // Filter by categories relativeTime: true, // Show "2 hours ago" format itemsPerPeriod: 10, // Limit items shown per time period }); // Shows: // - Context items created per day/hour // - Category distribution over time // - Journal entries with moods and tags // - Actual item details when includeItems: true
Save space by intelligently compressing old context:
// Compress items older than 30 days mcp_context_compress({ olderThan: '2024-01-01', preserveCategories: ['decision', 'critical'], // Keep these targetSize: 1000, // Target size in KB (optional) }); // Compression summary shows: // - Items compressed // - Space saved // - Compression ratio // - Categories affected
Track events from other MCP tools:
// Record events from other tools mcp_context_integrate_tool({ toolName: 'code-analyzer', eventType: 'security-scan-complete', data: { vulnerabilities: 0, filesScanned: 150, important: true, // Creates high-priority context item }, });
# Install dependencies npm install # Run tests npm test # Run tests with coverage npm run test:coverage # Run with auto-reload npm run dev # Build for production npm run build # Start production server npm start
mcp-memory-keeper/
├── src/
│ ├── index.ts # Main MCP server implementation
│ ├── utils/ # Utility modules
│ │ ├── database.ts # Database management
│ │ ├── validation.ts # Input validation
│ │ ├── git.ts # Git operations
│ │ ├── knowledge-graph.ts # Knowledge graph management
│ │ ├── vector-store.ts # Vector embeddings
│ │ └── agents.ts # Multi-agent system
│ └── __tests__/ # Test files
├── dist/ # Compiled JavaScript (generated)
├── context.db # SQLite database (auto-created)
├── EXAMPLES.md # Quick start examples
├── TROUBLESHOOTING.md # Common issues and solutions
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── jest.config.js # Test configuration
└── README.md # This file
The project includes comprehensive test coverage:
# Run all tests npm test # Run tests in watch mode npm run test:watch # Generate coverage report npm run test:coverage # Run specific test file npm test -- summarization.test.ts
Test categories:
| Feature | Maturity | Version | Use Case |
|---|---|---|---|
| Basic Save/Get | ✅ Stable | v0.1+ | Daily context management |
| Sessions | ✅ Stable | v0.2+ | Multi-project work |
| File Caching | ✅ Stable | v0.2+ | Track file changes |
| Checkpoints | ✅ Stable | v0.3+ | Context preservation |
| Smart Compaction | ✅ Stable | v0.3+ | Pre-compaction prep |
| Git Integration | ✅ Stable | v0.3+ | Commit context tracking |
| Search | ✅ Stable | v0.3+ | Find saved items |
| Export/Import | ✅ Stable | v0.3+ | Backup & sharing |
| Knowledge Graph | ✅ Stable | v0.5+ | Code relationship analysis |
| Visualization | ✅ Stable | v0.5+ | Context exploration |
| Semantic Search | ✅ Stable | v0.6+ | Natural language queries |
| Multi-Agent | ✅ Stable | v0.7+ | Intelligent processing |
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/AmazingFeature)git commit -m 'Add some AmazingFeature')git push origin feature/AmazingFeature)This project is licensed under the MIT License - see the LICENSE file for details.
Mark Kreyman
If you encounter any issues or have questions:
Claude Code context management, MCP server, Claude AI memory, persistent context, Model Context Protocol, Claude assistant memory, AI coding context, Claude Code MCP, context preservation, Claude AI tools