# 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)
```bash
npm install @gsxrchris/claude-memory
```

Configure in `.mcp.json` (project or global at `~/.claude/`):
```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@gsxrchris/claude-memory"]
    }
  }
}
```

## Running Without npm

For local development:
```bash
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:

```yaml
---
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:
```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["@gsxrchris/claude-memory"]
    }
  }
}
```

### Team/Shared Deployment

For teams sharing a memory store:
```json
{
  "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

```bash
# 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:

```json
{
  "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

```bash
# 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

```bash
# 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.