Memory MCP

Local, persistent memory for Claude Desktop and MCP-compatible AI assistants.

A lightweight MCP server that gives your AI durable, searchable memory — entirely on your machine. Built with TypeScript, SQLite + FTS5, and minimal dependencies.

Quick Start

Choose your installation method below based on your platform and preference.

Option 1: Direct from GitHub (Always Latest)

This method fetches directly from GitHub, bypassing npm cache issues.

macOS / Linux:

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "github:whenmoon-afk/claude-memory-mcp"]
    }
  }
}

Windows (Command Prompt wrapper):

Add to your Claude Desktop config (%APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "github:whenmoon-afk/claude-memory-mcp"]
    }
  }
}

Windows (Full npx.cmd path - alternative):

{
  "mcpServers": {
    "memory": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "github:whenmoon-afk/claude-memory-mcp"]
    }
  }
}

WSL Users: Use the macOS/Linux config above.

Option 2: Global Install (Most Reliable)

Install globally for offline support and faster startup:

npm install -g @whenmoon-afk/memory-mcp

Find your global npm path:

npm root -g

Then add to Claude Desktop config:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["YOUR_GLOBAL_PATH/node_modules/@whenmoon-afk/memory-mcp/dist/index.js"]
    }
  }
}

Replace YOUR_GLOBAL_PATH with the output from npm root -g.

Option 3: Automatic Installer

For first-time setup, the installer configures Claude Desktop automatically:

npx @whenmoon-afk/memory-mcp-install

After any installation method, restart Claude Desktop completely (quit and reopen).

Custom Database Location

By default, memories are stored at ~/.memory-mcp/memory.db on all platforms.

To use a custom location, add the env field to your config:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "github:whenmoon-afk/claude-memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/your/memory.db"
      }
    }
  }
}

The database is a single portable SQLite file. Back it up by copying the file.

Tools

| Tool | Description | |------|-------------| | memory_store | Store a memory with auto-summarization and entity extraction | | memory_recall | Search memories with token-aware loading | | memory_forget | Soft-delete a memory (preserves audit trail) |

Features

• FTS5 full-text search (fast, no embeddings needed)
• Token budgeting for context-aware responses
• Automatic entity extraction and summarization
• Soft deletes with provenance tracking
• Hybrid relevance scoring (recency + importance + frequency)

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MEMORY_DB_PATH | Platform-specific | Database file location | | DEFAULT_TTL_DAYS | 90 | Default memory expiration |

Troubleshooting

Tools not appearing in Claude Desktop?

1. Restart Claude Desktop completely (quit and reopen)
2. Verify config file syntax is valid JSON
3. Check that Node.js 18+ is installed: node --version

"Connection closed" on Windows?

Windows requires either:

• The cmd /c wrapper method (see Windows config above), OR
• The full path to npx.cmd (e.g., C:\Program Files\nodejs\npx.cmd)

Getting stale cached versions?

The npx github: method bypasses npm cache. Alternatively:

• Clear npm cache: npm cache clean --force
• Use global install for version control

Slow startup with github: method?

First run requires downloading and installing dependencies (can take 30+ seconds). Subsequent runs are faster but still fetch from GitHub. For faster startup, use the global install method.

Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• better-sqlite3 - Fast native SQLite with FTS5

Links

• npm: https://www.npmjs.com/package/@whenmoon-afk/memory-mcp
• GitHub: https://github.com/WhenMoon-afk/claude-memory-mcp
• Issues: https://github.com/WhenMoon-afk/claude-memory-mcp/issues

Disclaimer

This project is provided as-is. It is actively maintained but may have breaking changes between minor versions.

License

MIT