mcp-memory-keeper 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -7,8 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
@@ -53,7 +87,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added recipes for common patterns in RECIPES.md
 - Added troubleshooting tips for new features
 
-## [0.10.0] - 2025-01-26
+## [0.10.0] - 2025-06-26
 
 ### Added
 
@@ -92,7 +126,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhanced validation for channel names
 - Backward compatible - existing items default to 'default' channel
 
-## [0.9.0] - 2025-01-20
+## [0.9.0] - 2025-06-21
 
 ### Changed (BREAKING)
 
@@ -115,7 +149,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `context_get_shared` tool (use `context_get` instead)
 - Complex sharing mechanism that was causing inconsistencies
 
-## [0.8.4] - 2025-01-19
+## [0.8.4] - 2025-06-19
 
 ### Fixed
 
@@ -129,7 +163,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Feature flags system (planned)
 - Database migration system (planned)
 
-## [0.8.3] - 2025-01-19
+## [0.8.3] - 2025-06-19
 
 ### Added
 
@@ -150,7 +184,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Automatic schema migration for existing databases to add the `working_directory` column
 
-## [0.8.0] - 2024-01-18
+## [0.8.0] - 2025-06-18
 
 ### Added
 
@@ -190,7 +224,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New tables: `journal_entries`, `compressed_context`, `tool_events`
 - All 255 tests passing
 
-## [0.7.0] - 2024-01-18
+## [0.7.0] - 2025-06-18
 
 ### Added
 
@@ -214,7 +248,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added comprehensive test coverage (30 new tests)
 - All 236 tests passing
 
-## [0.6.0] - 2024-01-17
+## [0.6.0] - 2025-06-17
 
 ### Added
 
@@ -237,7 +271,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive test coverage for semantic search
 - All 206 tests passing
 
-## [0.5.0] - 2024-01-17
+## [0.5.0] - 2025-06-17
 
 ### Added
 
@@ -260,7 +294,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added `knowledge-graph.ts` utility module
 - Comprehensive test coverage for graph operations
 
-## [0.4.2] - 2024-01-16
+## [0.4.2] - 2025-06-17
 
 ### Added
 
@@ -274,7 +308,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Git integration error handling
 - Session list date filtering
 
-## [0.4.1] - 2024-01-16
+## [0.4.1] - 2025-06-17
 
 ### Fixed
 
@@ -287,7 +321,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Improved error messages for better debugging
 - Enhanced validation for file paths
 
-## [0.4.0] - 2024-01-15
+## [0.4.0] - 2025-06-17
 
 ### Added
 
@@ -308,7 +342,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Created `git.ts` utility module
 - 97% test coverage maintained
 
-## [0.3.0] - 2024-01-14
+## [0.3.0] - 2025-06-17
 
 ### Added
 
@@ -337,7 +371,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implemented streaming for large exports
 - Transaction support for atomic operations
 
-## [0.2.0] - 2024-01-13
+## [0.2.0] - 2025-06-17
 
 ### Added
 
@@ -367,7 +401,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Memory leak in file cache operations
 - Session switching race condition
 
-## [0.1.0] - 2024-01-12
+## [0.1.0] - 2025-06-17
 
 ### Added
 
@@ -395,12 +429,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Development Releases
 
-### [0.1.0-beta.2] - 2024-01-11
+### [0.1.0-beta.2] - 2025-06-17
 
 - Fixed Windows path handling
 - Added Node.js 18+ compatibility
 
-### [0.1.0-beta.1] - 2024-01-10
+### [0.1.0-beta.1] - 2025-06-17
 
 - Initial beta release
 - Basic functionality testing

package/README.md

@@ -1,11 +1,106 @@
 # MCP Memory Keeper - Claude Code Context Management
 
+[![npm version](https://img.shields.io/npm/v/mcp-memory-keeper.svg)](https://www.npmjs.com/package/mcp-memory-keeper)
+[![npm downloads](https://img.shields.io/npm/dm/mcp-memory-keeper.svg)](https://www.npmjs.com/package/mcp-memory-keeper)
 [![CI](https://github.com/mkreyman/mcp-memory-keeper/actions/workflows/ci.yml/badge.svg)](https://github.com/mkreyman/mcp-memory-keeper/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/mkreyman/mcp-memory-keeper/branch/main/graph/badge.svg)](https://codecov.io/gh/mkreyman/mcp-memory-keeper)
-[![npm version](https://badge.fury.io/js/mcp-memory-keeper.svg)](https://badge.fury.io/js/mcp-memory-keeper)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 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:
+
+```bash
+# 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)
+
+```markdown
+# 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`**
+
+```markdown
+# 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.
@@ -39,31 +134,33 @@ Claude Code users often face context loss when the conversation window fills up.
 
 ## Installation
 
-### Method 1: NPX (Recommended)
-
-The simplest way to use memory-keeper with Claude:
+### Recommended: NPX Installation
 
 ```bash
 claude mcp add memory-keeper npx mcp-memory-keeper
 ```
 
-That's it! This will:
+This single command:
 
-- Always use the latest version
-- Handle all dependencies automatically
-- Create the data directory at `~/mcp-data/memory-keeper/`
-- Work across different platforms
+- ✅ Always uses the latest version
+- ✅ Handles all dependencies automatically
+- ✅ Works across macOS, Linux, and Windows
+- ✅ No manual building or native module issues
 
-### Method 2: Global Installation
+### Alternative Installation Methods
 
-If you prefer a global installation:
+<details>
+<summary>Global Installation</summary>
 
 ```bash
 npm install -g mcp-memory-keeper
 claude mcp add memory-keeper mcp-memory-keeper
 ```
 
-### Method 3: From Source
+</details>
+
+<details>
+<summary>From Source (for development)</summary>
 
 ```bash
 # 1. Clone the repository
@@ -80,14 +177,42 @@ npm run build
 claude mcp add memory-keeper node /absolute/path/to/mcp-memory-keeper/dist/index.js
 ```
 
+</details>
+
 ## 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:
+
+```bash
+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)
+```
+
 ### Claude Code (CLI)
 
 #### Configuration Scopes
@@ -96,13 +221,13 @@ Choose where to save the configuration:
 
 ```bash
 # Project-specific (default) - only for you in this project
-claude mcp add memory-keeper node /path/to/mcp-memory-keeper/dist/index.js
+claude mcp add memory-keeper npx mcp-memory-keeper
 
 # Shared with team via .mcp.json
-claude mcp add --scope project memory-keeper node /path/to/mcp-memory-keeper/dist/index.js
+claude mcp add --scope project memory-keeper npx mcp-memory-keeper
 
 # Available across all your projects
-claude mcp add --scope user memory-keeper node /path/to/mcp-memory-keeper/dist/index.js
+claude mcp add --scope user memory-keeper npx mcp-memory-keeper
 ```
 
 #### Verify Configuration
@@ -126,20 +251,14 @@ claude mcp get memory-keeper
 {
   "mcpServers": {
     "memory-keeper": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-memory-keeper/dist/index.js"]
+      "command": "npx",
+      "args": ["mcp-memory-keeper"]
     }
   }
 }
 ```
 
-**Important**: Replace `/absolute/path/to/mcp-memory-keeper` with the actual path where you cloned/installed the project.
-
-### Example paths:
-
-- macOS: `/Users/username/projects/mcp-memory-keeper/dist/index.js`
-- Windows: `C:\\Users\\username\\projects\\mcp-memory-keeper\\dist\\index.js`
-- Linux: `/home/username/projects/mcp-memory-keeper/dist/index.js`
+That's it! No paths needed - npx automatically handles everything.
 
 ### Verify Installation
 
@@ -166,7 +285,7 @@ If Memory Keeper isn't working:
 ```bash
 # Remove and re-add the server
 claude mcp remove memory-keeper
-claude mcp add memory-keeper node /absolute/path/to/mcp-memory-keeper/dist/index.js
+claude mcp add memory-keeper npx mcp-memory-keeper
 
 # Check logs for errors
 # The server output will appear in Claude Code's output panel
@@ -174,26 +293,19 @@ claude mcp add memory-keeper node /absolute/path/to/mcp-memory-keeper/dist/index
 
 ### Updating to Latest Version
 
-To get the latest features and bug fixes:
-
-```bash
-# 1. Navigate to your Memory Keeper directory
-cd /path/to/mcp-memory-keeper
+With the npx installation method, you automatically get the latest version every time! No manual updates needed.
 
-# 2. Pull the latest changes
-git pull
+If you're using the global installation method:
 
-# 3. Install any new dependencies (if package.json changed)
-npm install
-
-# 4. Rebuild the project
-npm run build
+```bash
+# Update to latest version
+npm update -g mcp-memory-keeper
 
-# 5. Start a new Claude session
+# 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 pull, build, and start a new session!
+**Note**: You don't need to reconfigure the MCP server in Claude after updating. Just start a new session!
 
 ## Usage
 

package/bin/mcp-memory-keeper

@@ -27,7 +27,9 @@ const serverPath = path.join(__dirname, '..', 'dist', 'index.js');
 // Check if the server is built
 if (!fs.existsSync(serverPath)) {
   console.error('Error: Server not built. This should not happen with the npm package.');
-  console.error('Please report this issue at: https://github.com/mkreyman/mcp-memory-keeper/issues');
+  console.error(
+    'Please report this issue at: https://github.com/mkreyman/mcp-memory-keeper/issues'
+  );
   process.exit(1);
 }
 
@@ -37,16 +39,16 @@ process.chdir(DATA_DIR);
 // Spawn the server
 const child = spawn(process.execPath, [serverPath, ...process.argv.slice(2)], {
   stdio: 'inherit',
-  env: process.env
+  env: process.env,
 });
 
 // Handle exit
-child.on('exit', (code) => {
+child.on('exit', code => {
   process.exit(code);
 });
 
 // Handle errors
-child.on('error', (err) => {
+child.on('error', err => {
   console.error('Failed to start memory-keeper server:', err);
   process.exit(1);
-});
+});