Skip to content

CHANGELOG.md

Latest commit

 

History

History
575 lines (424 loc) · 24.1 KB

CHANGELOG.md

File metadata and controls

575 lines (424 loc) · 24.1 KB
Raw

Changelog

All notable changes to MCP Memory Keeper will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

[0.14.0] - 2026-06-05

Added

  • Checkpoints now survive an export → import round trip (#37, follow-up to #36)
    • context_export writes a new 0.5.0 format that includes the checkpointItems and checkpointFiles join rows (previously only the bare checkpoints rows were exported, which made imported checkpoints empty/useless).
    • context_import restores checkpoints and rewires their links: each checkpoint gets a fresh id, and its item/file links are remapped onto the freshly-imported context-item and file-cache ids. Links pointing at a skipped or absent row are dropped rather than aborting the import. The whole restore happens inside the existing atomic transaction.
    • The import summary now reports Checkpoints: N (skipped M malformed), links restored: K.
    • Backward compatible: importing a pre-0.5.0 export (no join-row arrays) does not error and reports the checkpoints as not imported, preserving the prior explicit-not-imported behaviour.
    • The entry-count cap from #36 now also bounds checkpoint and join-row arrays.
    • Merge safety: on a key/path collision during merge import, the existing row is now UPDATED in place (its id preserved) instead of INSERT OR REPLACE, so a pre-existing checkpoint's links to that row are no longer cascade-deleted. Both context_items and file_cache (which have UNIQUE constraints) are handled this way.
    • Fidelity & observability: file_cache.size is restored on import; duplicate-key/path rows that collapse during import are reported (collapsed N duplicate-key); dropped dangling checkpoint links are surfaced (links restored: K (dropped N dangling)); and metadata.totalSize now accounts for the checkpoint join arrays.

[0.13.0] - 2026-06-05

Fixed

  • Server-reported version is now read from package.json at runtime instead of a hardcoded string, which had drifted to 0.10.0. Added an E2E test asserting the reported version matches package.json so it can't fall out of sync again.

Security

  • Arbitrary local file read via unvalidated context_import filePath (#35)
    • context_import passed the caller-supplied filePath straight to fs.readFileSync, with no path confinement. A malicious MCP client — or a prompt-injected agent — could point it at any file the server process could read: full contents for any JSON file (imported into the session, then retrievable via context_get/context_export), and the leading bytes of any other file (echoed back inside the JSON.parse error message)
    • Imports are now confined to a server-owned exports directory (<DATA_DIR>/exports, overridable via MEMORY_KEEPER_EXPORT_DIR). Relative paths resolve against that directory; absolute paths are accepted only if they resolve — after following symlinks via realpath — to a location inside it. Traversal (../) and absolute paths outside the directory are rejected
    • context_export now writes to that same exports directory (previously the OS temp dir), so the export → import round trip stays within the confined location
    • Import failures no longer echo raw exception messages — at every stage (read, JSON parse, and the database write) a generic message is returned and the detail is logged server-side, so no file bytes or inserted values can leak back to the caller
    • Import is hardened further: the resolved path must be a regular file (directories are rejected), capped at 50 MB and 100k entries to avoid memory/CPU exhaustion, and the whole import runs in a single transaction so a malformed row can never leave an orphaned or partially-populated session. Per-item and session-name shape are validated; merge only merges when a current session actually exists (and the result is reported honestly)
    • The "not found" and "outside the exports directory" cases now return an identical generic message, removing a file-existence oracle, and the resolved absolute path is never echoed back to the caller
    • context_export's tool description and the import path resolution now guard the exports-directory startup (graceful FATAL on an unreadable directory)
    • Round-trip fidelity fixes surfaced by review of the above: imported items now restore their channel, is_private, and metadata columns (previously dropped); file-cache rows with NULL content are preserved (previously dropped); a stored size of 0 is no longer wrongly recomputed; skipped-malformed counts and "checkpoints present but not imported" are reported instead of being silently lost; and context_export warns when a produced file is too large to be re-imported. The new current session is published only after the import transaction commits, so a failed import can no longer leave currentSessionId pointing at a rolled-back session
    • Added an E2E security regression test suite that reproduces the issue #35 PoC (arbitrary JSON read, /etc/passwd byte leak, .. traversal) and covers symlink escape, the exports-dir-prefix sibling boundary, the no-existence-oracle guarantee, empty/non-string paths, directory paths, valid-JSON-but-not-an-export, malformed-item skipping, and a data-preserving round trip
    • Reported by Zhihao Zhang (@mcfly-zzh)

0.12.2 - 2026-04-07

Fixed

  • full tool profile breaks OpenAI-compatible providers (#33)
    • context_delegate.input.insights array property was missing required items declaration
    • Stricter providers rejected the schema with invalid_function_parameters
    • Added items: { type: 'object', properties: {...} } to the insights property with proper patterns, relationships, trends, and themes fields
    • Added properties: {} to context_link.metadata bare object schema for strict validator compatibility
    • Added regression test that validates all array properties across all tool schemas have items declared
    • Added comprehensive E2E test suite that spawns the actual MCP server and validates tool schemas, tool calls, and error handling over stdio

0.12.1 - 2026-03-24

Fixed

  • Server crashes with SQLITE_CANTOPEN when parent process CWD changes (#31)
    • Server now resolves database path to an absolute location ($DATA_DIR or ~/mcp-data/memory-keeper/) instead of relying on CWD
    • Added try/catch around data directory creation with actionable error message
    • Startup warning with exact cp command when legacy context.db detected in CWD
    • README "from source" install command now points to bin/mcp-memory-keeper instead of node dist/index.js
    • Added Upgrading section documenting database path change and migration steps

Technical

  • Fixed integration tests to use DATA_DIR instead of dead MCP_DB_PATH environment variable
  • Fixed git.init() in tests to use --initial-branch=master for deterministic behavior

0.12.0 - 2026-02-06

Added

  • Selective Tool Filtering via Profiles (#29)
    • Control which tools are exposed to reduce context window usage (~10-15K tokens saved with minimal profile)
    • Three built-in profiles: minimal (8 tools), standard (22 tools), full (38 tools, default)
    • TOOL_PROFILE environment variable to select active profile at startup
    • TOOL_PROFILE_CONFIG environment variable to specify custom config file path
    • Custom profile definitions via ~/.mcp-memory-keeper/config.json
    • Config file profiles take precedence over built-in defaults
    • Helpful error messages when disabled tools are called, with guidance on enabling them
    • Startup logging shows active profile, tool count, and source
    • Example config file included in examples/config.json

Technical

  • New src/utils/tool-profiles.ts module with ALL_TOOL_NAMES source of truth
  • ToolName union type for compile-time safety
  • Deep config validation (guards against malformed JSON, null values, non-array profiles, non-string elements)
  • Drift-detection integration test verifies ALL_TOOL_NAMES stays in sync with index.ts tool definitions
  • Defense-in-depth: both ListTools filtering and CallTool guard for disabled tools
  • 100% backwards compatible — no env var + no config = all 38 tools (existing behavior unchanged)
  • All 1185 tests passing across Node.js 20, 22, and 24

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