# Changelog
All notable changes to MCP Memory Keeper will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.11.0] - 2025-12-10
### Breaking Changes
- **Node.js 18 support dropped** - Minimum required Node.js version is now 20.0.0
- Node.js 18 reached End-of-Life on April 30, 2025
- Users on Node.js 18 must upgrade to Node.js 20 or later
- Existing installations will continue working until updated
### Fixed
- **Installation fails on Node.js 24 (#28)** - Updated `better-sqlite3` dependency
- Upgraded from `^11.10.0` to `^12.1.0` to support Node.js 24 (LTS "Krypton")
- Prebuilt binaries now available for Node.js 20, 22, and 24
- Resolves `gyp ERR!` build failures on Node.js 24
## [0.10.2] - 2025-09-16
### Fixed
- **Critical Token Limit Issue (#24)** - Fixed token overflow with includeMetadata
- Implemented dynamic token limit calculation based on actual content size
- Automatically adjusts item limits based on average item size in session
- More accurate token estimation (3.5 chars/token vs 4)
- Configurable via environment variables (MCP_MAX_TOKENS, MCP_TOKEN_SAFETY_BUFFER)
- Added tokenInfo to response metadata for transparency
- Resolves "MCP tool context_get response exceeds maximum allowed tokens" errors
### Added
- **Token Limit Management Module** (`utils/token-limits.ts`)
- Dynamic calculation of safe item limits
- Response overhead estimation
- Configurable token limits via environment
- Better visibility into token usage
- Proper TypeScript interfaces for context items
- Environment variable validation with bounds checking
- Safe JSON parsing with error handling
- Well-documented constants replacing magic numbers
## [0.10.1] - 2025-07-11
### Fixed
- **Token Limit Enforcement** - Fixed MCP protocol token limit errors
- Added automatic response truncation when approaching 25,000 token limit
- Implemented `calculateSafeItemCount()` helper to determine safe result size
- Enhanced pagination metadata with `truncated` and `truncatedCount` fields
- Improved warning messages with specific pagination instructions
- Prevents "response exceeds maximum allowed tokens" errors from MCP clients
- **Pagination Defaults in context_get** - Improved consistency
- Added proper validation of pagination parameters at handler level
- Default limit of 100 items now properly applied when not specified
- Invalid limit/offset values are validated and fallback to defaults
- Response includes `defaultsApplied` metadata to indicate when defaults were used
- Consistent behavior with `context_search_all` and other paginated endpoints
### Added
- **Batch Operations** - Atomic multi-item operations
- `context_batch_save` - Save multiple items in one transaction
- `context_batch_delete` - Delete multiple items by keys or pattern
- `context_batch_update` - Update multiple items with partial changes
- Ensures data consistency with all-or-nothing transactions
- **Channel Reassignment** - Reorganize context items
- `context_reassign_channel` - Move items between channels
- Support for key patterns, specific keys, or entire channels
- Filter by category and priority during moves
- Dry run option to preview changes
- **Context Relationships** - Build knowledge graphs
- `context_link` - Create typed relationships between items
- `context_get_related` - Find related items with traversal
- 14 relationship types (contains, depends_on, references, etc.)
- Multi-level depth traversal support
- Directional queries (incoming/outgoing/both)
- **Real-time Monitoring** - Watch for context changes
- `context_watch` - Create filtered watchers for changes
- Support for long polling and immediate returns
- Filter by keys, categories, channels, priorities
- Track added vs updated items
### Documentation
- Added comprehensive documentation for all new features in API.md
- Added practical examples in EXAMPLES.md
- Added recipes for common patterns in RECIPES.md
- Added troubleshooting tips for new features
## [0.10.0] - 2025-06-26
### Added
- **Channels** - Persistent topic-based organization (#22)
- Auto-derived from git branch names (20 chars max)
- Survives session crashes and restarts
- `defaultChannel` parameter in `context_session_start`
- `channel` parameter in `context_save` and `context_get`
- Perfect for multi-branch development and team collaboration
- **Enhanced Filtering** in `context_get` (#21)
- `includeMetadata` - Get timestamps and size information
- `sort` - Sort by created/updated time (asc/desc) or priority
- `limit` and `offset` - Pagination support
- `createdAfter` and `createdBefore` - Time-based filtering
- `keyPattern` - Regex pattern matching for keys
- `priorities` - Filter by multiple priority levels
- **Enhanced Timeline** (#21)
- `includeItems` - Show actual items, not just counts
- `categories` - Filter timeline by specific categories
- `relativeTime` - Display "2 hours ago" format
- `itemsPerPeriod` - Limit items shown per time period
### Changed
- Database schema updated with `channel` column in context_items table
- Improved query performance with channel indexing
- Better support for cross-branch context queries
### Technical
- Added channels migration (003_add_channels.ts)
- Enhanced validation for channel names
- Backward compatible - existing items default to 'default' channel
## [0.9.0] - 2025-06-21
### Changed (BREAKING)
- **Simplified Sharing Model** (#19)
- Context items are now shared across all sessions by default (public)
- Removed broken `context_share` and `context_get_shared` commands
- Added `private` flag to `context_save` for session-specific items
- Database schema updated: replaced `shared` and `shared_with_sessions` columns with `is_private`
- Migration included to make ALL existing items public (accessible across sessions)
### Fixed
- Cross-session collaboration now works reliably
- Context accessibility is consistent across all retrieval methods
- Search operations properly respect privacy settings
### Removed
- `context_share` tool (sharing is now automatic)
- `context_get_shared` tool (use `context_get` instead)
- Complex sharing mechanism that was causing inconsistencies
## [0.8.4] - 2025-06-19
### Fixed
- Critical fix for "table sessions has no column named working_directory" error
- Added defensive checks before using working_directory column
- Gracefully handles existing databases without the new column
### Added
- Tiered storage and retention policies (planned)
- Feature flags system (planned)
- Database migration system (planned)
## [0.8.3] - 2025-06-19
### Added
- **Smart Project Directory Management**
- `context_session_start` provides intelligent suggestions when no project directory is set
- Detects git repositories in current directory and subdirectories
- Suggests appropriate project paths based on directory structure
- Working directory is stored in the sessions table when explicitly provided
- Git-dependent tools now prompt for project directory setup when needed
### Changed
- Sessions table now includes a `working_directory` column
- Improved user guidance for setting up git tracking
- More helpful messages when project directory is not set
### Fixed
- Automatic schema migration for existing databases to add the `working_directory` column
## [0.8.0] - 2025-06-18
### Added
- **Session Branching & Merging** (#14)
- `context_branch_session` tool for creating session branches
- Support for shallow (high-priority only) and deep (full copy) branching
- `context_merge_sessions` tool with three conflict resolution strategies
- Parent-child relationship tracking in sessions table
- **Journal Entries** (#16)
- `context_journal_entry` tool for time-stamped reflections
- Support for tags and mood tracking
- Integration with timeline visualization
- **Timeline View** (#16)
- `context_timeline` tool to visualize activity patterns
- Grouping by hour, day, or week
- Category distribution over time
- Journal entry integration
- **Progressive Compression** (#17)
- `context_compress` tool for intelligent space management
- Preserve important categories while compressing old data
- Automatic compression ratio calculation
- Target size optimization support
- **Cross-Tool Integration** (#18)
- `context_integrate_tool` to record events from other MCP tools
- Automatic high-priority context item creation for important events
- Support for tool event metadata storage
### Changed
- Updated database schema to support new features
- Enhanced documentation with comprehensive examples
- Improved test coverage with 19 new test cases
### Technical
- Added `parent_id` column to sessions table
- New tables: `journal_entries`, `compressed_context`, `tool_events`
- All 255 tests passing
## [0.7.0] - 2025-06-18
### Added
- **Multi-Agent System** (#9)
- Agent framework with specialized roles
- `AnalyzerAgent` for pattern detection and relationship analysis
- `SynthesizerAgent` for summarization and recommendations
- `AgentCoordinator` for managing agent workflows
- `context_delegate` tool for intelligent task delegation
- Agent chaining capability for complex workflows
- Confidence scoring for agent outputs
### Changed
- Improved documentation with multi-agent examples
- Enhanced EXAMPLES.md with agent usage patterns
### Technical
- Created `src/utils/agents.ts` with complete agent implementation
- Added comprehensive test coverage (30 new tests)
- All 236 tests passing
## [0.6.0] - 2025-06-17
### Added
- **Semantic Search** (#4)
- `context_semantic_search` tool for natural language queries
- Lightweight vector embeddings using character n-grams
- No external dependencies required
- Similarity threshold filtering
- Integration with existing search infrastructure
### Changed
- Updated examples with semantic search patterns
- Enhanced documentation for natural language queries
### Technical
- Implemented `VectorStore` class for embedding management
- Added `vector_embeddings` table to database schema
- Comprehensive test coverage for semantic search
- All 206 tests passing
## [0.5.0] - 2025-06-17
### Added
- **Knowledge Graph Integration** (#3)
- Automatic entity extraction from context
- Relationship detection between entities
- `context_analyze` tool for building knowledge graph
- `context_find_related` tool for exploring connections
- `context_visualize` tool with graph/timeline/heatmap views
- Confidence scoring for relationships
### Changed
- Enhanced database schema for knowledge graph support
- Improved context analysis capabilities
### Technical
- New tables: `entities`, `relations`, `observations`
- Added `knowledge-graph.ts` utility module
- Comprehensive test coverage for graph operations
## [0.4.2] - 2025-06-17
### Added
- **Documentation Improvements**
- Comprehensive TROUBLESHOOTING.md guide
- Enhanced EXAMPLES.md with real-world scenarios
- Started RECIPES.md for common patterns
### Fixed
- Git integration error handling
- Session list date filtering
## [0.4.1] - 2025-06-17
### Fixed
- Database initialization race condition
- Checkpoint restoration with missing files
- Search result ranking accuracy
### Changed
- Improved error messages for better debugging
- Enhanced validation for file paths
## [0.4.0] - 2025-06-17
### Added
- **Git Integration** (#2)
- `context_git_commit` tool with auto-save
- Automatic context correlation with commits
- Git status capture in checkpoints
- Branch tracking
### Changed
- Checkpoint system now includes git information
- Enhanced session metadata with git branch
### Technical
- Added `simple-git` dependency
- Created `git.ts` utility module
- 97% test coverage maintained
## [0.3.0] - 2025-06-17
### Added
- **Smart Compaction** (#1)
- `context_prepare_compaction` tool
- Automatic identification of critical items
- Unfinished task preservation
- Restoration instructions generation
- **Search Functionality**
- `context_search` tool with full-text search
- Search in keys and values
- Category and session filtering
- **Export/Import**
- `context_export` tool for JSON/CSV export
- `context_import` tool with merge strategies
- Session backup and restore capability
### Changed
- Improved checkpoint metadata
- Enhanced error handling across all tools
### Technical
- Added search indexes for performance
- Implemented streaming for large exports
- Transaction support for atomic operations
## [0.2.0] - 2025-06-17
### Added
- **Checkpoint System**
- `context_checkpoint` tool for complete snapshots
- `context_restore_checkpoint` for state restoration
- File cache inclusion in checkpoints
- Git status integration
- **Context Summarization**
- `context_summarize` tool
- AI-friendly markdown summaries
- Category and priority grouping
- Session statistics
- **Enhanced File Management**
- SHA-256 hash-based change detection
- File size tracking
- Automatic cache invalidation
### Changed
- Improved session management with metadata
- Better error messages with error codes
- Enhanced validation for all inputs
### Fixed
- Memory leak in file cache operations
- Session switching race condition
## [0.1.0] - 2025-06-17
### Added
- Initial release
- **Core Features**
- `context_save` and `context_get` tools
- `context_delete` for item removal
- Session management with `context_session_start` and `context_session_list`
- File caching with `context_cache_file` and `context_file_changed`
- Status monitoring with `context_status`
- **Database Setup**
- SQLite with WAL mode
- Automatic database creation
- Size tracking and limits
- **MCP Integration**
- Full MCP protocol implementation
- Tool discovery and schema validation
- Error handling and reporting
### Technical
- TypeScript implementation
- Comprehensive test suite
- Zero runtime dependencies (except MCP SDK and SQLite)
## Development Releases
### [0.1.0-beta.2] - 2025-06-17
- Fixed Windows path handling
- Added Node.js 18+ compatibility
### [0.1.0-beta.1] - 2025-06-17
- Initial beta release
- Basic functionality testing
- Community feedback integration
## Legend
- **Added**: New features
- **Changed**: Changes in existing functionality
- **Deprecated**: Soon-to-be removed features
- **Removed**: Removed features
- **Fixed**: Bug fixes
- **Security**: Security updates
- **Technical**: Internal improvements
[Unreleased]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.10.0...HEAD
[0.10.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.9.0...v0.10.0
[0.9.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.8.4...v0.9.0
[0.8.4]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.8.3...v0.8.4
[0.8.3]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.8.0...v0.8.3
[0.8.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.7.0...v0.8.0
[0.7.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.6.0...v0.7.0
[0.6.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.5.0...v0.6.0
[0.5.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.4.2...v0.5.0
[0.4.2]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.4.1...v0.4.2
[0.4.1]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/mkreyman/mcp-memory-keeper/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/mkreyman/mcp-memory-keeper/releases/tag/v0.1.0
