Claude Memory MCP Server

Enterprise-grade MCP server for persistent, intelligent memory management across Claude Code sessions.

Overview

Claude Memory is an MCP server that provides persistent memory capabilities with enterprise features: concurrent multi-writer access, intelligent search, versioning, backup/restore, and more. Designed for teams and individuals who need reliable, scalable memory management.

Features

Core Capabilities

• Persistent Memory - Store and recall memories across sessions
• Semantic Search - TF-IDF powered similarity search
• Multi-Scope - User, project, and session-specific memories
• Auto-Tagging - Intelligent tag inference from content
• Importance Scoring - Automatic relevance weighting (1-10)

Enterprise Features

• Concurrent Access - File locking for multi-writer scenarios
• Versioning - Full memory version history
• Transaction Support - Atomic batch operations
• Append-Only Logging - Crash recovery audit trail
• Backup/Restore - Point-in-time recovery
• Memory Consolidation - Deduplication and merge
• GC - Automatic expired memory cleanup

Installation

Quick Start (npm)

npm install @gsxrchris/claude-memory

Configure in .mcp.json (project or global at ~/.claude/):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@gsxrchris/claude-memory"]
    }
  }
}

Running Without npm

For local development:

npx tsx src/index.ts

MCP Tools (22 Tools)

Core Memory Operations

| Tool | Description | |------|-------------| | memory_remember | Store memory with auto-importance, tags, expiration | | memory_recall | Search with semantic/exact/hybrid, filters, cross-project | | memory_search_similar | Find similar memories using vector search | | memory_load | Load memories sorted by importance | | memory_save | Save session context with summarization | | memory_list | List memories with metadata | | memory_clear | Clear memories for a scope |

Intelligence

| Tool | Description | |------|-------------| | memory_consolidate | Find and merge similar memories | | memory_query_expand | Expand queries with synonyms |

Transactions (Enterprise)

| Tool | Description | |------|-------------| | memory_transaction_begin | Start atomic batch operation | | memory_transaction_commit | Commit all pending changes | | memory_transaction_rollback | Rollback all pending changes |

Versioning & Audit

| Tool | Description | |------|-------------| | memory_version_history | Get memory version history | | memory_version_restore | Restore specific version | | memory_audit_log | Query operation history |

Backup & Recovery

| Tool | Description | |------|-------------| | memory_backup_create | Create point-in-time backup | | memory_backup_list | List available backups | | memory_backup_restore | Restore from backup | | memory_backup_delete | Delete backup |

Maintenance

| Tool | Description | |------|-------------| | memory_gc | Clean expired memories | | memory_rebuild_index | Force search index rebuild | | memory_check_save_suggestion | Periodic save reminders |

Skills & Profile

| Tool | Description | |------|-------------| | memory_create_skill | Create Claude Code skill | | memory_list_skills | List created skills | | memory_get_user_profile | Get learned user preferences | | memory_update_user_preference | Update user profile |

Search Modes

| Mode | Description | |------|-------------| | semantic | TF-IDF similarity via vector index | | exact | Plain text substring match | | hybrid | Combined scoring (recommended) |

Scopes

| Scope | Location | Usage | |-------|----------|-------| | user | ~/.claude/memories/user/ | Persistent across projects | | project | ./memory/ | Project-specific | | session | ./memory/ | Temporary (7 day TTL) | | all | Cross-project | Federated search |

Memory Schema

Memories are stored as markdown with YAML frontmatter:

---
scope: user
type: preference
created: 2025-05-22T10:00:00Z
modified: 2025-05-22T12:00:00Z
version: 2
importance: 8
tags: [language, typescript, enterprise]
expires-at: 2025-05-29T10:00:00Z
project-id: myproject
user-id: [email protected]
---

Your memory content here...

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MEMORY_DATA_DIR | Custom memory storage path (for team shared storage) | ~/.claude/memories | | MEMORY_LOCK_TIMEOUT | Lock acquisition timeout (ms) | 5000 | | MEMORY_LOG_ROTATE_SIZE | Log rotation threshold (bytes) | 100MB | | MEMORY_MAX_VERSIONS | Max versions per memory | 3 |

Or via Settings

Add to your Claude Code settings:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@gsxrchris/claude-memory"]
    }
  }
}

Team/Shared Deployment

For teams sharing a memory store:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@gsxrchris/claude-memory"],
      "env": {
        "MEMORY_DATA_DIR": "//server/share/memories"
      }
    }
  }
}

Architecture

┌─────────────────────────────────────────────┐
│           MCP Server Layer                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Tools    │ │ Request  │ │Response  │ │
│  │ Router   │ │ Validator│ │Formatter │ │
│  └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│         Core Services Layer                │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Memory   │ │ Search  │ │ Session  │ │
│  │ Service  │ │ Engine  │ │ Manager  │ │
│  └──────────┘ └──────────┘ └──────────┘ │
├─────────────────────────────────────────────┤
│        Persistence Layer                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ FileMgr │ │ Vector  │ │ Log      │ │
│  │ +Lock   │ │ Index   │ │ Manager  │ │
│  └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────┘

Concurrency

The server supports concurrent multi-writer access through:

• File-level locking - Exclusive (write) and shared (read) locks
• Atomic writes - Temp-file-then-rename pattern
• Append-only log - Crash recovery via replay

Backup Strategy

Backups include:

• All memory files (.memories/)
• Transaction log (memory.log)
• Vector index (.index/)
• User profile

Security

• Memories stored locally (no cloud)
• No encryption (plaintext)
• User-specific isolation via filesystem permissions

Migration from v1.x

The server is a drop-in replacement. All v1.x tools work unchanged.

New users: Memory directory is created automatically at first use.

Development

# Clone
git clone https://github.com/gsxrchris/claude-memory.git
cd claude-memory

# Install
npm install

# Build
npm run build

# Test
npm test

# Run
npm start

License

MIT - See LICENSE file

Author

Developed by Chris Bunting [email protected]

Support

• Issues: https://github.com/cbuntingde/claude-memory/issues
• Changelog: See RELEASE-NOTES.md

Hooks (Automation)

This package includes hooks for automatic memory capture. Add to your Claude Code settings.json using the official hook format:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx @gsxrchris/claude-memory hooks tool"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "command": "npx @gsxrchris/claude-memory hooks pre-tool"
          }
        ]
      }
    ]
  }
}

Available Hooks

| Hook | Purpose | Event | |------|---------|------| | tool | Capture Edit/Write/Bash usage | PostToolUse | | pre-tool | Show conventions before Bash | PreToolUse | | prompt | Capture user requests | PostUserPromptSubmit |

NPM Hook Commands

# Capture tool use
npx @gsxrchris/claude-memory hooks tool

# Pre-tool suggestions
npx @gsxrchris/claude-memory hooks pre-tool

# Capture prompt
npx @gsxrchris/claude-memory hooks prompt

CLI Commands

# Recall memories
npx @gsxrchris/claude-memory cli recall --scope user --limit 5

# Remember something
npx @gsxrchris/claude-memory cli remember --content "remember this" --scope user

# List memories
npx @gsxrchris/claude-memory cli list --scope user

# Clear session memories
npx @gsxrchris/claude-memory cli clear --scope session

# Garbage collect expired
npx @gsxrchris/claude-memory cli gc

See HOOKS.md for full details.