# 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

# Project Configuration

## Development Rules

- Always use memory-keeper to track progress
- Save architectural decisions and test results
- Create checkpoints before context limits

## Quality Standards

- All tests must pass before marking complete
- Document actual vs claimed results

# My Development Workflow

When working on the provided project:

- Use memory-keeper with channel: <project_name>
- Save progress at every major milestone
- Document all decisions with category: "decision"
- Track implementation status with category: "progress"
- Before claiming anything is complete, save test results

## Workflow Steps

1. Initialize session with project name as channel
2. Save findings during investigation
3. Create checkpoint before major changes
4. Document what actually works vs what should work

User: /my-dev-workflow authentication-service

AI: Setting up workflow for authentication-service.
[Uses memory-keeper with channel "authentication-service"]

[... AI works, automatically saving context ...]

User: "Getting close to context limit. Create checkpoint and give me a key"

AI: "Checkpoint created: authentication-service-checkpoint-20250126-143026"

[Continue working until context reset or compact manually]

User: "Restore from key: authentication-service-checkpoint-20250126-143026"

AI: "Restored! Continuing OAuth implementation. We completed the token validation, working on refresh logic..."

claude mcp add memory-keeper npx mcp-memory-keeper

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)

# Essential tools only (8 tools)
TOOL_PROFILE=minimal npx mcp-memory-keeper

# Standard workflow set (22 tools)
TOOL_PROFILE=standard npx mcp-memory-keeper

# All tools (default)
TOOL_PROFILE=full npx mcp-memory-keeper

{
  "profiles": {
    "my_workflow": [
      "context_session_start",
      "context_save",
      "context_get",
      "context_search",
      "context_checkpoint",
      "context_restore_checkpoint",
      "context_diff",
      "context_timeline"
    ]
  }
}

{
  "mcpServers": {
    "memory-keeper": {
      "command": "npx",
      "args": ["mcp-memory-keeper"],
      "env": {
        "TOOL_PROFILE": "minimal"
      }
    }
  }
}

# Project-specific (default) - only for you in this project
claude mcp add memory-keeper npx mcp-memory-keeper

# Shared with team via .mcp.json
claude mcp add --scope project memory-keeper npx mcp-memory-keeper

# Available across all your projects
claude mcp add --scope user memory-keeper npx mcp-memory-keeper

# List all configured servers
claude mcp list

# Get details for Memory Keeper
claude mcp get memory-keeper

{
  "mcpServers": {
    "memory-keeper": {
      "command": "npx",
      "args": ["mcp-memory-keeper"]
    }
  }
}

# Remove and re-add the server
claude mcp remove memory-keeper
claude mcp add memory-keeper npx mcp-memory-keeper

# Check logs for errors
# The server output will appear in Claude Code's output panel

# Update to latest version
npm update -g mcp-memory-keeper

# Start a new Claude session
# The updated features will be available immediately

// Start a new session
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
});

// Start a session with project directory for git tracking
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
  projectDir: '/path/to/your/project',
});

// Start a session with a default channel
mcp_context_session_start({
  name: 'Feature Development',
  description: 'Working on user authentication',
  projectDir: '/path/to/your/project',
  defaultChannel: 'auth-feature', // Will auto-derive from git branch if not specified
});

// Set project directory for current session
mcp_context_set_project_dir({
  projectDir: '/path/to/your/project',
});

// List recent sessions
mcp_context_session_list({ limit: 5 });

// Continue from a previous session
mcp_context_session_start({
  name: 'Feature Dev Continued',
  continueFrom: 'previous-session-id',
});

// Channels are auto-derived from git branch (if projectDir is set)
// Branch "feature/auth-system" becomes channel "feature-auth-system" (20 chars max)

// Save to a specific channel
mcp_context_save({
  key: 'auth_design',
  value: 'Using JWT with refresh tokens',
  category: 'decision',
  priority: 'high',
  channel: 'auth-feature', // Explicitly set channel
});

// Get items from a specific channel
mcp_context_get({ channel: 'auth-feature' });

// Get items across all channels (default behavior)
mcp_context_get({ category: 'task' });

// Channels persist across sessions - perfect for:
// - Multi-branch development
// - Feature-specific context
// - Team collaboration on different topics

// Save with categories and priorities
mcp_context_save({
  key: 'current_task',
  value: 'Implement OAuth integration',
  category: 'task',
  priority: 'high',
});

// Save decisions
mcp_context_save({
  key: 'auth_strategy',
  value: 'Using JWT tokens with 24h expiry',
  category: 'decision',
  priority: 'high',
});

// Save progress notes
mcp_context_save({
  key: 'progress_auth',
  value: 'Completed user model, working on token generation',
  category: 'progress',
  priority: 'normal',
});

// Retrieve by category
mcp_context_get({ category: 'task' });

// Retrieve specific item
mcp_context_get({ key: 'current_task' });

// Get context from specific session
mcp_context_get({
  sessionId: 'session-id-here',
  category: 'decision',
});

// Enhanced filtering (NEW in v0.10.0)
mcp_context_get({
  category: 'task',
  priorities: ['high', 'normal'],
  includeMetadata: true, // Get timestamps, size info
  sort: 'created_desc', // created_asc/desc, updated_asc/desc, priority
  limit: 10, // Pagination
  offset: 0,
});

// Time-based queries (NEW in v0.10.0)
mcp_context_get({
  createdAfter: '2025-01-20T00:00:00Z',
  createdBefore: '2025-01-26T23:59:59Z',
  includeMetadata: true,
});

// Pattern matching (NEW in v0.10.0)
mcp_context_get({
  keyPattern: 'auth_.*', // Regex to match keys
  category: 'decision',
});

// Cache file content for change detection
mcp_context_cache_file({
  filePath: '/src/auth/user.model.ts',
  content: fileContent,
});

// Check if file has changed
mcp_context_file_changed({
  filePath: '/src/auth/user.model.ts',
  currentContent: newFileContent,
});

// Get current session status
mcp_context_status();

// 1. Start a new session
mcp_context_session_start({
  name: 'Settings Refactor',
  description: 'Refactoring settings module for better performance',
});

// 2. Save high-priority task
mcp_context_save({
  key: 'main_task',
  value: 'Refactor Settings.Context to use behaviors',
  category: 'task',
  priority: 'high',
});

// 3. Cache important files
mcp_context_cache_file({
  filePath: 'lib/settings/context.ex',
  content: originalFileContent,
});

// 4. Save decisions as you work
mcp_context_save({
  key: 'architecture_decision',
  value: 'Split settings into read/write modules',
  category: 'decision',
  priority: 'high',
});

// 5. Track progress
mcp_context_save({
  key: 'progress_1',
  value: 'Completed behavior definition, 5 modules remaining',
  category: 'progress',
  priority: 'normal',
});

// 6. Before context window fills up
mcp_context_status(); // Check what's saved

// 7. After Claude Code restart
mcp_context_get({ category: 'task', priority: 'high' }); // Get high priority tasks
mcp_context_get({ key: 'architecture_decision' }); // Get specific decisions
mcp_context_file_changed({ filePath: 'lib/settings/context.ex' }); // Check for changes

// Create a checkpoint before major changes
mcp_context_checkpoint({
  name: 'before-refactor',
  description: 'State before major settings refactor',
  includeFiles: true, // Include cached files
  includeGitStatus: true, // Capture git status
});

// Continue working...
// If something goes wrong, restore from checkpoint
mcp_context_restore_checkpoint({
  name: 'before-refactor',
  restoreFiles: true, // Restore cached files too
});

// Or restore the latest checkpoint
mcp_context_restore_checkpoint({});

// Get a summary of all context
mcp_context_summarize();

// Get summary of specific categories
mcp_context_summarize({
  categories: ['task', 'decision'],
  maxLength: 2000,
});

// Summarize a specific session
mcp_context_summarize({
  sessionId: 'session-id-here',
  categories: ['progress'],
});

# Context Summary

## High Priority Items

- **main_task**: Refactor Settings.Context to use behaviors
- **critical_bug**: Fix memory leak in subscription handler

## Task

- implement_auth: Add OAuth2 authentication flow
- update_tests: Update test suite for new API

## Decision

- architecture_decision: Split settings into read/write modules
- db_choice: Use PostgreSQL for better JSON support

// Save multiple items at once
mcp_context_batch_save({
  items: [
    { key: 'config_api_url', value: 'https://api.example.com', category: 'note' },
    { key: 'config_timeout', value: '30000', category: 'note' },
    { key: 'config_retries', value: '3', category: 'note' },
  ],
});

// Update multiple items
mcp_context_batch_update({
  updates: [
    { key: 'task_1', priority: 'high' },
    { key: 'task_2', priority: 'high' },
    { key: 'task_3', value: 'Updated task description' },
  ],
});

// Delete by pattern
mcp_context_batch_delete({
  keyPattern: 'temp_*',
  dryRun: true, // Preview first
});

// Move items to a new channel
mcp_context_reassign_channel({
  keyPattern: 'auth_*',
  toChannel: 'feature-authentication',
});

// Move from one channel to another
mcp_context_reassign_channel({
  fromChannel: 'sprint-14',
  toChannel: 'sprint-15',
  category: 'task',
  priorities: ['high'],
});

// Link related items
mcp_context_link({
  sourceKey: 'epic_user_management',
  targetKey: 'task_create_user_api',
  relationship: 'contains',
});

// Find related items
mcp_context_get_related({
  key: 'epic_user_management',
  relationship: 'contains',
  depth: 2,
});

// Create a watcher
const watcher = await mcp_context_watch({
  action: 'create',
  filters: {
    categories: ['task'],
    priorities: ['high'],
  },
});

// Poll for changes
const changes = await mcp_context_watch({
  action: 'poll',
  watcherId: watcher.watcherId,
});

// Before context window fills
mcp_context_prepare_compaction();

// This automatically:
// - Creates a checkpoint
// - Identifies high-priority items
// - Captures unfinished tasks
// - Saves all decisions
// - Generates a summary
// - Prepares restoration instructions

// First, set your project directory (if not done during session start)
mcp_context_set_project_dir({
  projectDir: '/path/to/your/project',
});

// Commit with auto-save
mcp_context_git_commit({
  message: 'feat: Add user authentication',
  autoSave: true, // Creates checkpoint with commit
});

// Context is automatically linked to the commit
// Note: If no project directory is set, you'll see a helpful message
// explaining how to enable git tracking for your project

// Search in keys and values
mcp_context_search({ query: 'authentication' });

// Search only in keys
mcp_context_search({
  query: 'config',
  searchIn: ['key'],
});

// Search in specific session
mcp_context_search({
  query: 'bug',
  sessionId: 'session-id',
});

// Export current session — writes into the exports directory
// (<DATA_DIR>/exports/, overridable via MEMORY_KEEPER_EXPORT_DIR)
mcp_context_export(); // Creates memory-keeper-export-xxx.json

// Export specific session
mcp_context_export({
  sessionId: 'session-id',
  format: 'json',
});

// Import from a file inside the exports directory.
// A bare filename resolves against that directory; the absolute path
// returned by context_export also works.
mcp_context_import({
  filePath: 'memory-keeper-export-xxx.json',
});

// Merge into current session
mcp_context_import({
  filePath: 'backup.json',
  merge: true,
});

// Analyze context to build knowledge graph
mcp_context_analyze();

// Or analyze specific categories
mcp_context_analyze({
  categories: ['task', 'decision'],
});

// Find related entities
mcp_context_find_related({
  key: 'AuthService',
  maxDepth: 2,
});

// Generate visualization data
mcp_context_visualize({
  type: 'graph',
});

// Timeline view
mcp_context_visualize({
  type: 'timeline',
});

// Category/priority heatmap
mcp_context_visualize({
  type: 'heatmap',
});

// Search with natural language
mcp_context_semantic_search({
  query: 'how are we handling user authentication?',
  topK: 5,
});

// Find the most relevant security decisions
mcp_context_semantic_search({
  query: 'security concerns and decisions',
  minSimilarity: 0.5,
});

// Search with specific similarity threshold
mcp_context_semantic_search({
  query: 'database performance optimization',
  topK: 10,
  minSimilarity: 0.3,
});

// Analyze patterns in your context
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'patterns',
    categories: ['task', 'decision'],
  },
});

// Get comprehensive analysis
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'comprehensive',
  },
});

// Analyze relationships between entities
mcp_context_delegate({
  taskType: 'analyze',
  input: {
    analysisType: 'relationships',
    maxDepth: 3,
  },
});

// Create intelligent summaries
mcp_context_delegate({
  taskType: 'synthesize',
  input: {
    synthesisType: 'summary',
    maxLength: 1000,
  },
});

// Get actionable recommendations
mcp_context_delegate({
  taskType: 'synthesize',
  input: {
    synthesisType: 'recommendations',
    analysisResults: {}, // Can pass previous analysis results
  },
});

// Chain multiple agent tasks
mcp_context_delegate({
  chain: true,
  taskType: ['analyze', 'synthesize'],
  input: [{ analysisType: 'comprehensive' }, { synthesisType: 'recommendations' }],
});

// Create a branch to try something new
mcp_context_branch_session({
  branchName: 'experimental-refactor',
  copyDepth: 'shallow', // Only copy high-priority items
});

// Or create a full copy
mcp_context_branch_session({
  branchName: 'feature-complete-copy',
  copyDepth: 'deep', // Copy everything
});

// Later, merge changes back
mcp_context_merge_sessions({
  sourceSessionId: 'branch-session-id',
  conflictResolution: 'keep_newest', // or "keep_current", "keep_source"
});

// Add a journal entry
mcp_context_journal_entry({
  entry: 'Completed the authentication module. Tests are passing!',
  tags: ['milestone', 'authentication'],
  mood: 'accomplished',
});

// Entries are included in timeline views
mcp_context_timeline({
  groupBy: 'day',
});

// Get activity timeline
mcp_context_timeline({
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  groupBy: 'day', // or "hour", "week"
});

// Enhanced timeline (NEW in v0.10.0)
mcp_context_timeline({
  groupBy: 'hour',
  includeItems: true, // Show actual items, not just counts
  categories: ['task', 'progress'], // Filter by categories
  relativeTime: true, // Show "2 hours ago" format
  itemsPerPeriod: 10, // Limit items shown per time period
});

// Shows:
// - Context items created per day/hour
// - Category distribution over time
// - Journal entries with moods and tags
// - Actual item details when includeItems: true

// Compress items older than 30 days
mcp_context_compress({
  olderThan: '2024-01-01',
  preserveCategories: ['decision', 'critical'], // Keep these
  targetSize: 1000, // Target size in KB (optional)
});

// Compression summary shows:
// - Items compressed
// - Space saved
// - Compression ratio
// - Categories affected

// Record events from other tools
mcp_context_integrate_tool({
  toolName: 'code-analyzer',
  eventType: 'security-scan-complete',
  data: {
    vulnerabilities: 0,
    filesScanned: 150,
    important: true, // Creates high-priority context item
  },
});

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run with auto-reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

mcp-memory-keeper/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   ├── utils/             # Utility modules
│   │   ├── database.ts    # Database management
│   │   ├── validation.ts  # Input validation
│   │   ├── git.ts         # Git operations
│   │   ├── knowledge-graph.ts # Knowledge graph management
│   │   ├── vector-store.ts    # Vector embeddings
│   │   └── agents.ts      # Multi-agent system
│   └── __tests__/         # Test files
├── dist/                  # Compiled JavaScript (generated)
├── context.db             # SQLite database (auto-created)
├── EXAMPLES.md            # Quick start examples
├── TROUBLESHOOTING.md     # Common issues and solutions
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript configuration
├── jest.config.js         # Test configuration
└── README.md              # This file

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run specific test file
npm test -- summarization.test.ts

mkdir -p ~/mcp-data/memory-keeper
cp /path/to/old/context.db ~/mcp-data/memory-keeper/context.db

# remove the old entry
claude mcp remove memory-keeper

# add the updated entry
claude mcp add memory-keeper /absolute/path/to/mcp-memory-keeper/bin/mcp-memory-keeper