Skip to content
Back to search

mcp-memory-keeper

MCP server for persistent context management in AI coding assistants

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mkreyman--mcp-memory-keeper/badge.svg)](/listings/mkreyman--mcp-memory-keeper)

HTML

<a href="/listings/mkreyman--mcp-memory-keeper"><img src="/api/listings/mkreyman--mcp-memory-keeper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,295 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Memory Keeper - Claude Code Context Management
  2. [![npm version](https://img.shields.io/npm/v/mcp-memory-keeper.svg)](https://www.npmjs.com/package/mcp-memory-keeper)
  3. [![npm downloads](https://img.shields.io/npm/dm/mcp-memory-keeper.svg)](https://www.npmjs.com/package/mcp-memory-keeper)
  4. [![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)
  5. [![codecov](https://codecov.io/gh/mkreyman/mcp-memory-keeper/branch/main/graph/badge.svg)](https://codecov.io/gh/mkreyman/mcp-memory-keeper)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. 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.
  8. ## 🚀 Quick Start
  9. Get started in under 30 seconds:
  10. ```bash
  11. # Add memory-keeper to Claude
  12. claude mcp add memory-keeper npx mcp-memory-keeper
  13. # Start a new Claude session and use it!
  14. # Try: Analyze the current repo and save your analysis in memory-keeper
  15. ```
  16. 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.
  17. ## 🚀 Practical Memory Keeper Workflow Example
  18. ### **Custom Command + CLAUDE.md = Automatic Context Management**
  19. #### **CLAUDE.md** (condensed example)
  20. ```markdown
  21. # Project Configuration
  22. ## Development Rules
  23. - Always use memory-keeper to track progress
  24. - Save architectural decisions and test results
  25. - Create checkpoints before context limits
  26. ## Quality Standards
  27. - All tests must pass before marking complete
  28. - Document actual vs claimed results
  29. ```
  30. #### **Custom Command Example: `/my-dev-workflow`**
  31. ```markdown
  32. # My Development Workflow
  33. When working on the provided project:
  34. - Use memory-keeper with channel: <project_name>
  35. - Save progress at every major milestone
  36. - Document all decisions with category: "decision"
  37. - Track implementation status with category: "progress"
  38. - Before claiming anything is complete, save test results
  39. ## Workflow Steps
  40. 1. Initialize session with project name as channel
  41. 2. Save findings during investigation
  42. 3. Create checkpoint before major changes
  43. 4. Document what actually works vs what should work
  44. ```
  45. #### **Usage Example**
  46. ```
  47. User: /my-dev-workflow authentication-service
  48. AI: Setting up workflow for authentication-service.
  49. [Uses memory-keeper with channel "authentication-service"]
  50. [... AI works, automatically saving context ...]
  51. User: "Getting close to context limit. Create checkpoint and give me a key"
  52. AI: "Checkpoint created: authentication-service-checkpoint-20250126-143026"
  53. [Continue working until context reset or compact manually]
  54. User: "Restore from key: authentication-service-checkpoint-20250126-143026"
  55. AI: "Restored! Continuing OAuth implementation. We completed the token validation, working on refresh logic..."
  56. ```
  57. **The Pattern:**
  58. 1. Custom command includes instructions to use memory-keeper
  59. 2. AI follows those instructions automatically
  60. 3. **When you notice the conversation getting long, YOU ask Claude to save a checkpoint** (like saving your game before a boss fight!)
  61. 4. **When Claude runs out of space and starts fresh, YOU tell it to restore using the checkpoint key**
  62. **🎯 Key Feature:** Memory Keeper is a shared board! You can:
  63. - Continue in the same session after reset
  64. - Start a completely new session and restore
  65. - Have multiple Claude sessions running in parallel, all sharing the same memory
  66. - One session can save context that another session retrieves
  67. This enables powerful workflows like having one Claude session doing research while another implements code, both sharing discoveries through Memory Keeper!
  68. ## Why MCP Memory Keeper?
  69. 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.
  70. ### Perfect for:
  71. - Long coding sessions with Claude Code
  72. - Complex projects requiring context preservation
  73. - Teams using Claude AI for collaborative development
  74. - Developers who want persistent context across Claude sessions
  75. ## Features
  76. - 🔄 Save and restore context between Claude Code sessions
  77. - 📁 File content caching with change detection
  78. - 🏷️ Organize context with categories and priorities
  79. - 📺 **Channels** - Persistent topic-based organization (auto-derived from git branch)
  80. - 📸 Checkpoint system for complete context snapshots
  81. - 🤖 Smart compaction helper that never loses critical info
  82. - 🔍 Full-text search across all saved context
  83. - 🕐 **Enhanced filtering** - Time-based queries, regex patterns, pagination
  84. - 📊 **Change tracking** - See what's been added, modified, or deleted since any point
  85. - 💾 Export/import for backup and sharing
  86. - 🌿 Git integration with automatic context correlation
  87. - 📊 AI-friendly summarization with priority awareness
  88. - 🚀 Fast SQLite-based storage optimized for Claude
  89. - 🔁 **Batch operations** - Save, update, or delete multiple items atomically
  90. - 🔄 **Channel reassignment** - Move items between channels based on patterns
  91. - 🔗 **Context relationships** - Link related items with typed relationships
  92. - 👁️ **Real-time monitoring** - Watch for context changes with filters
  93. ## Installation
  94. ### Recommended: NPX Installation
  95. ```bash
  96. claude mcp add memory-keeper npx mcp-memory-keeper
  97. ```
  98. This single command:
  99. - ✅ Always uses the latest version
  100. - ✅ Handles all dependencies automatically
  101. - ✅ Works across macOS, Linux, and Windows
  102. - ✅ No manual building or native module issues
  103. ### Alternative Installation Methods
  104. <details>
  105. <summary>Global Installation</summary>
  106. ```bash
  107. npm install -g mcp-memory-keeper
  108. claude mcp add memory-keeper mcp-memory-keeper
  109. ```
  110. </details>
  111. <details>
  112. <summary>From Source (for development)</summary>
  113. ```bash
  114. # 1. Clone the repository
  115. git clone https://github.com/mkreyman/mcp-memory-keeper.git
  116. cd mcp-memory-keeper
  117. # 2. Install dependencies
  118. npm install
  119. # 3. Build the project
  120. npm run build
  121. # 4. Add to Claude
  122. claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper
  123. ```
  124. </details>
  125. ## Configuration
  126. ### Environment Variables
  127. #### Storage and Installation
  128. - `DATA_DIR` - Directory for database storage (default: `~/mcp-data/memory-keeper/`)
  129. - `MEMORY_KEEPER_INSTALL_DIR` - Installation directory (default: `~/.local/mcp-servers/memory-keeper/`)
  130. - `MEMORY_KEEPER_AUTO_UPDATE` - Set to `1` to enable auto-updates
  131. #### Token Limit Configuration
  132. - `MCP_MAX_TOKENS` - Maximum tokens allowed in responses (default: `25000`, range: `1000-100000`)
  133. - Adjust this if your MCP client has different limits
  134. - `MCP_TOKEN_SAFETY_BUFFER` - Safety buffer percentage (default: `0.8`, range: `0.1-1.0`)
  135. - Uses only this fraction of the max tokens to prevent overflows
  136. - `MCP_MIN_ITEMS` - Minimum items to return even if exceeding limits (default: `1`, range: `1-100`)
  137. - Ensures at least some results are returned
  138. - `MCP_MAX_ITEMS` - Maximum items allowed per response (default: `100`, range: `10-1000`)
  139. - Upper bound for result sets regardless of token limits
  140. - `MCP_CHARS_PER_TOKEN` - Characters per token ratio (default: `3.5`, range: `2.5-5.0`) **[Advanced]**
  141. - Adjusts token estimation accuracy for different content types
  142. - Lower values = more conservative (safer but returns fewer items)
  143. - Higher values = more aggressive (returns more items but risks overflow)
  144. Example configuration for stricter token limits:
  145. ```bash
  146. export MCP_MAX_TOKENS=20000 # Lower max tokens
  147. export MCP_TOKEN_SAFETY_BUFFER=0.7 # More conservative buffer
  148. export MCP_MAX_ITEMS=50 # Fewer items per response
  149. export MCP_CHARS_PER_TOKEN=3.0 # More conservative estimation (optional)
  150. ```
  151. #### Tool Profiles
  152. 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.
  153. **Quick usage:**
  154. ```bash
  155. # Essential tools only (8 tools)
  156. TOOL_PROFILE=minimal npx mcp-memory-keeper
  157. # Standard workflow set (22 tools)
  158. TOOL_PROFILE=standard npx mcp-memory-keeper
  159. # All tools (default)
  160. TOOL_PROFILE=full npx mcp-memory-keeper
  161. ```
  162. **Built-in profiles:**
  163. | Profile | Tools | Description |
  164. | ---------- | ----- | -------------------------------------------------------------- |
  165. | `minimal` | 8 | Core persistence: save, get, search, status, checkpoint |
  166. | `standard` | 22 | Daily workflow: core + git, batch ops, channels, export/import |
  167. | `full` | 38 | All tools (default, backwards compatible) |
  168. **Custom profiles via config file:**
  169. Create `~/.mcp-memory-keeper/config.json` to define or override profiles:
  170. ```json
  171. {
  172. "profiles": {
  173. "my_workflow": [
  174. "context_session_start",
  175. "context_save",
  176. "context_get",
  177. "context_search",
  178. "context_checkpoint",
  179. "context_restore_checkpoint",
  180. "context_diff",
  181. "context_timeline"
  182. ]
  183. }
  184. }
  185. ```
  186. Then activate it: `TOOL_PROFILE=my_workflow npx mcp-memory-keeper`
  187. Config file profiles take precedence over built-in defaults with the same name.
  188. **Profile resolution precedence:**
  189. | `TOOL_PROFILE` | Config file has profile? | Built-in exists? | Result |
  190. | -------------- | ------------------------ | ---------------- | -------------------------------- |
  191. | Set | Yes | — | Uses config file definition |
  192. | Set | No | Yes | Uses built-in definition |
  193. | Set | No | No | Warning + falls back to `full` |
  194. | Not set | — | — | Uses built-in `full` (all tools) |
  195. **Environment variables:**
  196. | Variable | Description |
  197. | --------------------- | ------------------------------------------------------------------------- |
  198. | `TOOL_PROFILE` | Profile name to activate (e.g., `minimal`, `standard`, `full`, or custom) |
  199. | `TOOL_PROFILE_CONFIG` | Override config file path (default: `~/.mcp-memory-keeper/config.json`) |
  200. > Note: Profile resolution happens once at server startup. Changes to the env var or config file take effect on the next server restart.
  201. **Claude Code / Claude Desktop configuration:**
  202. ```json
  203. {
  204. "mcpServers": {
  205. "memory-keeper": {
  206. "command": "npx",
  207. "args": ["mcp-memory-keeper"],
  208. "env": {
  209. "TOOL_PROFILE": "minimal"
  210. }
  211. }
  212. }
  213. }
  214. ```
  215. See `examples/config.json` for a complete example config file.
  216. ### Claude Code (CLI)
  217. #### Configuration Scopes
  218. Choose where to save the configuration:
  219. ```bash
  220. # Project-specific (default) - only for you in this project
  221. claude mcp add memory-keeper npx mcp-memory-keeper
  222. # Shared with team via .mcp.json
  223. claude mcp add --scope project memory-keeper npx mcp-memory-keeper
  224. # Available across all your projects
  225. claude mcp add --scope user memory-keeper npx mcp-memory-keeper
  226. ```
  227. #### Verify Configuration
  228. ```bash
  229. # List all configured servers
  230. claude mcp list
  231. # Get details for Memory Keeper
  232. claude mcp get memory-keeper
  233. ```
  234. ### Claude Desktop App
  235. 1. Open Claude Desktop settings
  236. 2. Navigate to "Developer" → "Model Context Protocol"
  237. 3. Click "Add MCP Server"
  238. 4. Add the following configuration:
  239. ```json
  240. {
  241. "mcpServers": {
  242. "memory-keeper": {
  243. "command": "npx",
  244. "args": ["mcp-memory-keeper"]
  245. }
  246. }
  247. }
  248. ```
  249. That's it! No paths needed - npx automatically handles everything.
  250. ### Verify Installation
  251. #### For Claude Code:
  252. 1. Restart Claude Code or start a new session
  253. 2. The Memory Keeper tools should be available automatically
  254. 3. Test with: `mcp_memory_save({ key: "test", value: "Hello Memory Keeper!" })`
  255. 4. If not working, check server status:
  256. ```bash
  257. claude mcp list # Should show memory-keeper as "running"
  258. ```
  259. #### For Claude Desktop:
  260. 1. Restart Claude Desktop after adding the configuration
  261. 2. In a new conversation, the Memory Keeper tools should be available
  262. 3. Test with the same command above
  263. ### Troubleshooting
  264. If Memory Keeper isn't working:
  265. ```bash
  266. # Remove and re-add the server
  267. claude mcp remove memory-keeper
  268. claude mcp add memory-keeper npx mcp-memory-keeper
  269. # Check logs for errors
  270. # The server output will appear in Claude Code's output panel
  271. ```
  272. ### Updating to Latest Version
  273. With the npx installation method, you automatically get the latest version every time! No manual updates needed.
  274. If you're using the global installation method:
  275. ```bash
  276. # Update to latest version
  277. npm update -g mcp-memory-keeper
  278. # Start a new Claude session
  279. # The updated features will be available immediately
  280. ```
  281. **Note**: You don't need to reconfigure the MCP server in Claude after updating. Just start a new session!
  282. ## Usage
  283. ### Session Management
  284. ```javascript
  285. // Start a new session
  286. mcp_context_session_start({
  287. name: 'Feature Development',
  288. description: 'Working on user authentication',
  289. });
  290. // Start a session with project directory for git tracking
  291. mcp_context_session_start({
  292. name: 'Feature Development',
  293. description: 'Working on user authentication',
  294. projectDir: '/path/to/your/project',
  295. });
  296. // Start a session with a default channel
  297. mcp_context_session_start({
  298. name: 'Feature Development',
  299. description: 'Working on user authentication',
  300. projectDir: '/path/to/your/project',
  301. defaultChannel: 'auth-feature', // Will auto-derive from git branch if not specified
  302. });
  303. // Set project directory for current session
  304. mcp_context_set_project_dir({
  305. projectDir: '/path/to/your/project',
  306. });
  307. // List recent sessions
  308. mcp_context_session_list({ limit: 5 });
  309. // Continue from a previous session
  310. mcp_context_session_start({
  311. name: 'Feature Dev Continued',
  312. continueFrom: 'previous-session-id',
  313. });
  314. ```
  315. ### Working with Channels (NEW in v0.10.0)
  316. Channels provide persistent topic-based organization that survives session crashes and restarts:
  317. ```javascript
  318. // Channels are auto-derived from git branch (if projectDir is set)
  319. // Branch "feature/auth-system" becomes channel "feature-auth-system" (20 chars max)
  320. // Save to a specific channel
  321. mcp_context_save({
  322. key: 'auth_design',
  323. value: 'Using JWT with refresh tokens',
  324. category: 'decision',
  325. priority: 'high',
  326. channel: 'auth-feature', // Explicitly set channel
  327. });
  328. // Get items from a specific channel
  329. mcp_context_get({ channel: 'auth-feature' });
  330. // Get items across all channels (default behavior)
  331. mcp_context_get({ category: 'task' });
  332. // Channels persist across sessions - perfect for:
  333. // - Multi-branch development
  334. // - Feature-specific context
  335. // - Team collaboration on different topics
  336. ```
  337. ### Enhanced Context Storage
  338. ```javascript
  339. // Save with categories and priorities
  340. mcp_context_save({
  341. key: 'current_task',
  342. value: 'Implement OAuth integration',
  343. category: 'task',
  344. priority: 'high',
  345. });
  346. // Save decisions
  347. mcp_context_save({
  348. key: 'auth_strategy',
  349. value: 'Using JWT tokens with 24h expiry',
  350. category: 'decision',
  351. priority: 'high',
  352. });
  353. // Save progress notes
  354. mcp_context_save({
  355. key: 'progress_auth',
  356. value: 'Completed user model, working on token generation',
  357. category: 'progress',
  358. priority: 'normal',
  359. });
  360. // Retrieve by category
  361. mcp_context_get({ category: 'task' });
  362. // Retrieve specific item
  363. mcp_context_get({ key: 'current_task' });
  364. // Get context from specific session
  365. mcp_context_get({
  366. sessionId: 'session-id-here',
  367. category: 'decision',
  368. });
  369. // Enhanced filtering (NEW in v0.10.0)
  370. mcp_context_get({
  371. category: 'task',
  372. priorities: ['high', 'normal'],
  373. includeMetadata: true, // Get timestamps, size info
  374. sort: 'created_desc', // created_asc/desc, updated_asc/desc, priority
  375. limit: 10, // Pagination
  376. offset: 0,
  377. });
  378. // Time-based queries (NEW in v0.10.0)
  379. mcp_context_get({
  380. createdAfter: '2025-01-20T00:00:00Z',
  381. createdBefore: '2025-01-26T23:59:59Z',
  382. includeMetadata: true,
  383. });
  384. // Pattern matching (NEW in v0.10.0)
  385. mcp_context_get({
  386. keyPattern: 'auth_.*', // Regex to match keys
  387. category: 'decision',
  388. });
  389. ```
  390. ### File Caching
  391. ```javascript
  392. // Cache file content for change detection
  393. mcp_context_cache_file({
  394. filePath: '/src/auth/user.model.ts',
  395. content: fileContent,
  396. });
  397. // Check if file has changed
  398. mcp_context_file_changed({
  399. filePath: '/src/auth/user.model.ts',
  400. currentContent: newFileContent,
  401. });
  402. // Get current session status
  403. mcp_context_status();
  404. ```
  405. ### Complete Workflow Example
  406. ```javascript
  407. // 1. Start a new session
  408. mcp_context_session_start({
  409. name: 'Settings Refactor',
  410. description: 'Refactoring settings module for better performance',
  411. });
  412. // 2. Save high-priority task
  413. mcp_context_save({
  414. key: 'main_task',
  415. value: 'Refactor Settings.Context to use behaviors',
  416. category: 'task',
  417. priority: 'high',
  418. });
  419. // 3. Cache important files
  420. mcp_context_cache_file({
  421. filePath: 'lib/settings/context.ex',
  422. content: originalFileContent,
  423. });
  424. // 4. Save decisions as you work
  425. mcp_context_save({
  426. key: 'architecture_decision',
  427. value: 'Split settings into read/write modules',
  428. category: 'decision',
  429. priority: 'high',
  430. });
  431. // 5. Track progress
  432. mcp_context_save({
  433. key: 'progress_1',
  434. value: 'Completed behavior definition, 5 modules remaining',
  435. category: 'progress',
  436. priority: 'normal',
  437. });
  438. // 6. Before context window fills up
  439. mcp_context_status(); // Check what's saved
  440. // 7. After Claude Code restart
  441. mcp_context_get({ category: 'task', priority: 'high' }); // Get high priority tasks
  442. mcp_context_get({ key: 'architecture_decision' }); // Get specific decisions
  443. mcp_context_file_changed({ filePath: 'lib/settings/context.ex' }); // Check for changes
  444. ```
  445. ### Checkpoints (Phase 2)
  446. Create named snapshots of your entire context that can be restored later:
  447. ```javascript
  448. // Create a checkpoint before major changes
  449. mcp_context_checkpoint({
  450. name: 'before-refactor',
  451. description: 'State before major settings refactor',
  452. includeFiles: true, // Include cached files
  453. includeGitStatus: true, // Capture git status
  454. });
  455. // Continue working...
  456. // If something goes wrong, restore from checkpoint
  457. mcp_context_restore_checkpoint({
  458. name: 'before-refactor',
  459. restoreFiles: true, // Restore cached files too
  460. });
  461. // Or restore the latest checkpoint
  462. mcp_context_restore_checkpoint({});
  463. ```
  464. ### Context Summarization (Phase 2)
  465. Get AI-friendly summaries of your saved context:
  466. ```javascript
  467. // Get a summary of all context
  468. mcp_context_summarize();
  469. // Get summary of specific categories
  470. mcp_context_summarize({
  471. categories: ['task', 'decision'],
  472. maxLength: 2000,
  473. });
  474. // Summarize a specific session
  475. mcp_context_summarize({
  476. sessionId: 'session-id-here',
  477. categories: ['progress'],
  478. });
  479. ```
  480. Example summary output:
  481. ```markdown
  482. # Context Summary
  483. ## High Priority Items
  484. - **main_task**: Refactor Settings.Context to use behaviors
  485. - **critical_bug**: Fix memory leak in subscription handler
  486. ## Task
  487. - implement_auth: Add OAuth2 authentication flow
  488. - update_tests: Update test suite for new API
  489. ## Decision
  490. - architecture_decision: Split settings into read/write modules
  491. - db_choice: Use PostgreSQL for better JSON support
  492. ```
  493. ### Batch Operations
  494. Perform multiple operations atomically:
  495. ```javascript
  496. // Save multiple items at once
  497. mcp_context_batch_save({
  498. items: [
  499. { key: 'config_api_url', value: 'https://api.example.com', category: 'note' },
  500. { key: 'config_timeout', value: '30000', category: 'note' },
  501. { key: 'config_retries', value: '3', category: 'note' },
  502. ],
  503. });
  504. // Update multiple items
  505. mcp_context_batch_update({
  506. updates: [
  507. { key: 'task_1', priority: 'high' },
  508. { key: 'task_2', priority: 'high' },
  509. { key: 'task_3', value: 'Updated task description' },
  510. ],
  511. });
  512. // Delete by pattern
  513. mcp_context_batch_delete({
  514. keyPattern: 'temp_*',
  515. dryRun: true, // Preview first
  516. });
  517. ```
  518. ### Channel Management
  519. Reorganize context items between channels:
  520. ```javascript
  521. // Move items to a new channel
  522. mcp_context_reassign_channel({
  523. keyPattern: 'auth_*',
  524. toChannel: 'feature-authentication',
  525. });
  526. // Move from one channel to another
  527. mcp_context_reassign_channel({
  528. fromChannel: 'sprint-14',
  529. toChannel: 'sprint-15',
  530. category: 'task',
  531. priorities: ['high'],
  532. });
  533. ```
  534. ### Context Relationships
  535. Build a graph of related items:
  536. ```javascript
  537. // Link related items
  538. mcp_context_link({
  539. sourceKey: 'epic_user_management',
  540. targetKey: 'task_create_user_api',
  541. relationship: 'contains',
  542. });
  543. // Find related items
  544. mcp_context_get_related({
  545. key: 'epic_user_management',
  546. relationship: 'contains',
  547. depth: 2,
  548. });
  549. ```
  550. ### Real-time Monitoring
  551. Watch for context changes:
  552. ```javascript
  553. // Create a watcher
  554. const watcher = await mcp_context_watch({
  555. action: 'create',
  556. filters: {
  557. categories: ['task'],
  558. priorities: ['high'],
  559. },
  560. });
  561. // Poll for changes
  562. const changes = await mcp_context_watch({
  563. action: 'poll',
  564. watcherId: watcher.watcherId,
  565. });
  566. ```
  567. ### Smart Compaction (Phase 3)
  568. Never lose critical context when Claude's window fills up:
  569. ```javascript
  570. // Before context window fills
  571. mcp_context_prepare_compaction();
  572. // This automatically:
  573. // - Creates a checkpoint
  574. // - Identifies high-priority items
  575. // - Captures unfinished tasks
  576. // - Saves all decisions
  577. // - Generates a summary
  578. // - Prepares restoration instructions
  579. ```
  580. ### Git Integration (Phase 3)
  581. Track git changes in your project directory and save context with commits:
  582. ```javascript
  583. // First, set your project directory (if not done during session start)
  584. mcp_context_set_project_dir({
  585. projectDir: '/path/to/your/project',
  586. });
  587. // Commit with auto-save
  588. mcp_context_git_commit({
  589. message: 'feat: Add user authentication',
  590. autoSave: true, // Creates checkpoint with commit
  591. });
  592. // Context is automatically linked to the commit
  593. // Note: If no project directory is set, you'll see a helpful message
  594. // explaining how to enable git tracking for your project
  595. ```
  596. ### Context Search (Phase 3)
  597. Find anything in your saved context:
  598. ```javascript
  599. // Search in keys and values
  600. mcp_context_search({ query: 'authentication' });
  601. // Search only in keys
  602. mcp_context_search({
  603. query: 'config',
  604. searchIn: ['key'],
  605. });
  606. // Search in specific session
  607. mcp_context_search({
  608. query: 'bug',
  609. sessionId: 'session-id',
  610. });
  611. ```
  612. ### Export/Import (Phase 3)
  613. Share context or backup your work:
  614. ```javascript
  615. // Export current session — writes into the exports directory
  616. // (<DATA_DIR>/exports/, overridable via MEMORY_KEEPER_EXPORT_DIR)
  617. mcp_context_export(); // Creates memory-keeper-export-xxx.json
  618. // Export specific session
  619. mcp_context_export({
  620. sessionId: 'session-id',
  621. format: 'json',
  622. });
  623. // Import from a file inside the exports directory.
  624. // A bare filename resolves against that directory; the absolute path
  625. // returned by context_export also works.
  626. mcp_context_import({
  627. filePath: 'memory-keeper-export-xxx.json',
  628. });
  629. // Merge into current session
  630. mcp_context_import({
  631. filePath: 'backup.json',
  632. merge: true,
  633. });
  634. ```
  635. > **Security note:** For safety, `context_import` only reads files inside the
  636. > server-owned exports directory (`<DATA_DIR>/exports/`, or
  637. > `MEMORY_KEEPER_EXPORT_DIR` if set). Absolute paths outside that directory and
  638. > `../` traversal are rejected, so the tool cannot be steered at arbitrary
  639. > files on disk. Drop any file you want to import into that directory first.
  640. > Point `MEMORY_KEEPER_EXPORT_DIR` at a dedicated directory — not at a home
  641. > folder or a tree containing secrets — since any JSON file inside it becomes
  642. > importable. (Prior to this change, exports were written to the OS temp
  643. > directory; existing exports there must be moved into the exports directory to
  644. > be re-imported.)
  645. ### Knowledge Graph (Phase 4)
  646. Automatically extract entities and relationships from your context:
  647. ```javascript
  648. // Analyze context to build knowledge graph
  649. mcp_context_analyze();
  650. // Or analyze specific categories
  651. mcp_context_analyze({
  652. categories: ['task', 'decision'],
  653. });
  654. // Find related entities
  655. mcp_context_find_related({
  656. key: 'AuthService',
  657. maxDepth: 2,
  658. });
  659. // Generate visualization data
  660. mcp_context_visualize({
  661. type: 'graph',
  662. });
  663. // Timeline view
  664. mcp_context_visualize({
  665. type: 'timeline',
  666. });
  667. // Category/priority heatmap
  668. mcp_context_visualize({
  669. type: 'heatmap',
  670. });
  671. ```
  672. ### Semantic Search (Phase 4.2)
  673. Find context using natural language queries:
  674. ```javascript
  675. // Search with natural language
  676. mcp_context_semantic_search({
  677. query: 'how are we handling user authentication?',
  678. topK: 5,
  679. });
  680. // Find the most relevant security decisions
  681. mcp_context_semantic_search({
  682. query: 'security concerns and decisions',
  683. minSimilarity: 0.5,
  684. });
  685. // Search with specific similarity threshold
  686. mcp_context_semantic_search({
  687. query: 'database performance optimization',
  688. topK: 10,
  689. minSimilarity: 0.3,
  690. });
  691. ```
  692. ### Multi-Agent System (Phase 4.3)
  693. Delegate complex analysis tasks to specialized agents:
  694. ```javascript
  695. // Analyze patterns in your context
  696. mcp_context_delegate({
  697. taskType: 'analyze',
  698. input: {
  699. analysisType: 'patterns',
  700. categories: ['task', 'decision'],
  701. },
  702. });
  703. // Get comprehensive analysis
  704. mcp_context_delegate({
  705. taskType: 'analyze',
  706. input: {
  707. analysisType: 'comprehensive',
  708. },
  709. });
  710. // Analyze relationships between entities
  711. mcp_context_delegate({
  712. taskType: 'analyze',
  713. input: {
  714. analysisType: 'relationships',
  715. maxDepth: 3,
  716. },
  717. });
  718. // Create intelligent summaries
  719. mcp_context_delegate({
  720. taskType: 'synthesize',
  721. input: {
  722. synthesisType: 'summary',
  723. maxLength: 1000,
  724. },
  725. });
  726. // Get actionable recommendations
  727. mcp_context_delegate({
  728. taskType: 'synthesize',
  729. input: {
  730. synthesisType: 'recommendations',
  731. analysisResults: {}, // Can pass previous analysis results
  732. },
  733. });
  734. // Chain multiple agent tasks
  735. mcp_context_delegate({
  736. chain: true,
  737. taskType: ['analyze', 'synthesize'],
  738. input: [{ analysisType: 'comprehensive' }, { synthesisType: 'recommendations' }],
  739. });
  740. ```
  741. Agent Types:
  742. - **Analyzer Agent**: Detects patterns, analyzes relationships, tracks trends
  743. - **Synthesizer Agent**: Creates summaries, merges insights, generates recommendations
  744. ### Session Branching & Merging (Phase 4.4)
  745. Explore alternatives without losing your original work:
  746. ```javascript
  747. // Create a branch to try something new
  748. mcp_context_branch_session({
  749. branchName: 'experimental-refactor',
  750. copyDepth: 'shallow', // Only copy high-priority items
  751. });
  752. // Or create a full copy
  753. mcp_context_branch_session({
  754. branchName: 'feature-complete-copy',
  755. copyDepth: 'deep', // Copy everything
  756. });
  757. // Later, merge changes back
  758. mcp_context_merge_sessions({
  759. sourceSessionId: 'branch-session-id',
  760. conflictResolution: 'keep_newest', // or "keep_current", "keep_source"
  761. });
  762. ```
  763. ### Journal Entries (Phase 4.4)
  764. Track your thoughts and progress with timestamped journal entries:
  765. ```javascript
  766. // Add a journal entry
  767. mcp_context_journal_entry({
  768. entry: 'Completed the authentication module. Tests are passing!',
  769. tags: ['milestone', 'authentication'],
  770. mood: 'accomplished',
  771. });
  772. // Entries are included in timeline views
  773. mcp_context_timeline({
  774. groupBy: 'day',
  775. });
  776. ```
  777. ### Timeline & Activity Tracking (Phase 4.4)
  778. Visualize your work patterns over time:
  779. ```javascript
  780. // Get activity timeline
  781. mcp_context_timeline({
  782. startDate: '2024-01-01',
  783. endDate: '2024-01-31',
  784. groupBy: 'day', // or "hour", "week"
  785. });
  786. // Enhanced timeline (NEW in v0.10.0)
  787. mcp_context_timeline({
  788. groupBy: 'hour',
  789. includeItems: true, // Show actual items, not just counts
  790. categories: ['task', 'progress'], // Filter by categories
  791. relativeTime: true, // Show "2 hours ago" format
  792. itemsPerPeriod: 10, // Limit items shown per time period
  793. });
  794. // Shows:
  795. // - Context items created per day/hour
  796. // - Category distribution over time
  797. // - Journal entries with moods and tags
  798. // - Actual item details when includeItems: true
  799. ```
  800. ### Progressive Compression (Phase 4.4)
  801. Save space by intelligently compressing old context:
  802. ```javascript
  803. // Compress items older than 30 days
  804. mcp_context_compress({
  805. olderThan: '2024-01-01',
  806. preserveCategories: ['decision', 'critical'], // Keep these
  807. targetSize: 1000, // Target size in KB (optional)
  808. });
  809. // Compression summary shows:
  810. // - Items compressed
  811. // - Space saved
  812. // - Compression ratio
  813. // - Categories affected
  814. ```
  815. ### Cross-Tool Integration (Phase 4.4)
  816. Track events from other MCP tools:
  817. ```javascript
  818. // Record events from other tools
  819. mcp_context_integrate_tool({
  820. toolName: 'code-analyzer',
  821. eventType: 'security-scan-complete',
  822. data: {
  823. vulnerabilities: 0,
  824. filesScanned: 150,
  825. important: true, // Creates high-priority context item
  826. },
  827. });
  828. ```
  829. ## Documentation
  830. - **[Quick Start Examples](./EXAMPLES.md)** - Real-world scenarios and workflows
  831. - **[API Reference](./API.md)** - Complete tool documentation with all parameters and examples
  832. - **[Recipe Book](./RECIPES.md)** - Common patterns and best practices for daily development
  833. - **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Common issues and solutions
  834. - **[Architecture Overview](./ARCHITECTURE.md)** - System design and technical details
  835. - **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
  836. - **[Changelog](./CHANGELOG.md)** - Version history and release notes
  837. ## Development
  838. ### Running in Development Mode
  839. ```bash
  840. # Install dependencies
  841. npm install
  842. # Run tests
  843. npm test
  844. # Run tests with coverage
  845. npm run test:coverage
  846. # Run with auto-reload
  847. npm run dev
  848. # Build for production
  849. npm run build
  850. # Start production server
  851. npm start
  852. ```
  853. ### Project Structure
  854. ```
  855. mcp-memory-keeper/
  856. ├── src/
  857. │ ├── index.ts # Main MCP server implementation
  858. │ ├── utils/ # Utility modules
  859. │ │ ├── database.ts # Database management
  860. │ │ ├── validation.ts # Input validation
  861. │ │ ├── git.ts # Git operations
  862. │ │ ├── knowledge-graph.ts # Knowledge graph management
  863. │ │ ├── vector-store.ts # Vector embeddings
  864. │ │ └── agents.ts # Multi-agent system
  865. │ └── __tests__/ # Test files
  866. ├── dist/ # Compiled JavaScript (generated)
  867. ├── context.db # SQLite database (auto-created)
  868. ├── EXAMPLES.md # Quick start examples
  869. ├── TROUBLESHOOTING.md # Common issues and solutions
  870. ├── package.json # Project configuration
  871. ├── tsconfig.json # TypeScript configuration
  872. ├── jest.config.js # Test configuration
  873. └── README.md # This file
  874. ```
  875. ### Testing
  876. The project includes comprehensive test coverage:
  877. ```bash
  878. # Run all tests
  879. npm test
  880. # Run tests in watch mode
  881. npm run test:watch
  882. # Generate coverage report
  883. npm run test:coverage
  884. # Run specific test file
  885. npm test -- summarization.test.ts
  886. ```
  887. Test categories:
  888. - **Unit Tests**: Input validation, database operations, git integration
  889. - **Integration Tests**: Full tool workflows, error scenarios, edge cases
  890. - **Coverage**: 97%+ coverage on critical modules
  891. ## Feature Status
  892. | Feature | Maturity | Version | Use Case |
  893. | ---------------- | --------- | ------- | -------------------------- |
  894. | Basic Save/Get | ✅ Stable | v0.1+ | Daily context management |
  895. | Sessions | ✅ Stable | v0.2+ | Multi-project work |
  896. | File Caching | ✅ Stable | v0.2+ | Track file changes |
  897. | Checkpoints | ✅ Stable | v0.3+ | Context preservation |
  898. | Smart Compaction | ✅ Stable | v0.3+ | Pre-compaction prep |
  899. | Git Integration | ✅ Stable | v0.3+ | Commit context tracking |
  900. | Search | ✅ Stable | v0.3+ | Find saved items |
  901. | Export/Import | ✅ Stable | v0.3+ | Backup & sharing |
  902. | Knowledge Graph | ✅ Stable | v0.5+ | Code relationship analysis |
  903. | Visualization | ✅ Stable | v0.5+ | Context exploration |
  904. | Semantic Search | ✅ Stable | v0.6+ | Natural language queries |
  905. | Multi-Agent | ✅ Stable | v0.7+ | Intelligent processing |
  906. ### Current Features (v0.10.0)
  907. - ✅ **Session Management**: Create, list, and continue sessions with branching support
  908. - ✅ **Channels**: Persistent topic-based organization (auto-derived from git branch)
  909. - ✅ **Context Storage**: Save/retrieve context with categories (task, decision, progress, note) and priorities
  910. - ✅ **Enhanced Filtering**: Time-based queries, regex patterns, sorting, pagination
  911. - ✅ **File Caching**: Track file changes with SHA-256 hashing
  912. - ✅ **Checkpoints**: Create and restore complete context snapshots
  913. - ✅ **Smart Compaction**: Never lose critical context when hitting limits
  914. - ✅ **Git Integration**: Auto-save context on commits with branch tracking
  915. - ✅ **Search**: Full-text search across all saved context
  916. - ✅ **Export/Import**: Backup and share context as JSON
  917. - ✅ **SQLite Storage**: Persistent, reliable data storage with WAL mode
  918. - ✅ **Knowledge Graph**: Automatic entity and relationship extraction from context
  919. - ✅ **Visualization**: Generate graph, timeline, and heatmap data for context exploration
  920. - ✅ **Semantic Search**: Natural language search using lightweight vector embeddings
  921. - ✅ **Multi-Agent System**: Intelligent analysis with specialized analyzer and synthesizer agents
  922. - ✅ **Session Branching**: Create branches to explore alternatives without losing original context
  923. - ✅ **Session Merging**: Merge branches back with conflict resolution options
  924. - ✅ **Journal Entries**: Time-stamped entries with tags and mood tracking
  925. - ✅ **Enhanced Timeline**: Activity patterns with item details and relative time
  926. - ✅ **Progressive Compression**: Intelligently compress old context to save space
  927. - ✅ **Cross-Tool Integration**: Track events from other MCP tools
  928. ### Roadmap
  929. #### Phase 4: Advanced Features (In Development)
  930. - 🚧 **Knowledge Graph**: Entity-relation tracking for code understanding
  931. - 🚧 **Vector Search**: Semantic search using natural language
  932. - 📋 **Multi-Agent Processing**: Intelligent analysis and synthesis
  933. - 📋 **Time-Aware Context**: Timeline views and journal entries
  934. #### Phase 5: Documentation & Polish
  935. - ✅ **Examples**: Comprehensive quick-start scenarios
  936. - ✅ **Troubleshooting**: Common issues and solutions
  937. - 🚧 **Recipes**: Common patterns and workflows
  938. - 📋 **Video Tutorials**: Visual guides for key features
  939. #### Future Enhancements
  940. - [ ] Web UI for browsing context history
  941. - [ ] Multi-user/team collaboration features
  942. - [ ] Cloud sync and sharing
  943. - [ ] Integration with other AI assistants
  944. - [ ] Advanced analytics and insights
  945. - [ ] Custom context templates
  946. - [ ] Automatic retention policies
  947. ## Upgrading
  948. ### Database path change (v0.12.x+)
  949. Prior to this release, the server resolved `context.db` relative to the process's current working directory. The database now lives at an absolute path:
  950. - **Default:** `~/mcp-data/memory-keeper/context.db`
  951. - **Custom:** set `DATA_DIR=/your/path` — the server will use `$DATA_DIR/context.db`
  952. If you have existing data in a `context.db` in your old working directory, move it to the new location before restarting the server:
  953. ```bash
  954. mkdir -p ~/mcp-data/memory-keeper
  955. cp /path/to/old/context.db ~/mcp-data/memory-keeper/context.db
  956. ```
  957. If `DATA_DIR` is set, use that path as the destination instead of `~/mcp-data/memory-keeper/`.
  958. The server will print a warning to stderr if it detects a `context.db` in the current directory that differs from the configured data directory, including the exact `cp` command to run.
  959. ### From-source install command change
  960. If you registered memory-keeper using `node dist/index.js` directly, update your MCP config to use the bin wrapper instead:
  961. ```bash
  962. # remove the old entry
  963. claude mcp remove memory-keeper
  964. # add the updated entry
  965. claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper
  966. ```
  967. ## Contributing
  968. Contributions are welcome! Please feel free to submit a Pull Request.
  969. 1. Fork the repository
  970. 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
  971. 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
  972. 4. Push to the branch (`git push origin feature/AmazingFeature`)
  973. 5. Open a Pull Request
  974. ## License
  975. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  976. ## Author
  977. Mark Kreyman
  978. ## Acknowledgments
  979. - Built for the Claude Code community
  980. - Inspired by the need for better context management in AI coding sessions
  981. - Thanks to Anthropic for the MCP protocol
  982. ## Support
  983. If you encounter any issues or have questions:
  984. - Open an issue on [GitHub](https://github.com/mkreyman/mcp-memory-keeper/issues)
  985. - Check the [MCP documentation](https://modelcontextprotocol.io/)
  986. - Join the Claude Code community discussions
  987. ## Keywords
  988. 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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.