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: user@company.com
---

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 cbuntingde@gmail.com

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.