Claude Memory MCP Server

How to use

Install and run memory in your MCP setup to store, recall, and manage memories as you interact with your AI. You can add memories with automatic summaries, run token-aware recalls that fetch relevant items, and soft-delete memories when needed for debugging or rollback. The memory store, recall, and forget tools give you a practical workflow for keeping your AI focused and informed over time.

How to install

Prerequisites: Node.js 18 or newer and an MCP-compatible client (Claude Desktop, Cursor, Windsurf, or similar). Follow one of these installation flows to add memory support to your MCP setup.

# Option 1: Automatic installation with setup (recommended)
npx @whenmoon-afk/memory-mcp

# After automatic setup, restart your MCP client (quit and reopen)
```

```bash
# Optional global install and manual run
npm install -g @whenmoon-afk/memory-mcp
memory-mcp
```

```bash
# Option 2: From source (for development)
git clone https://github.com/WhenMoon-afk/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
```

> Output: `dist/index.js` — your memory server.

Configuration and starting details

Configure your MCP client to connect to the local memory server. The recommended approach is to use the automatic installer, which adjusts settings for your platform. If you prefer manual configuration, you can point your MCP client to run the memory server via the provided command and environment variable.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@whenmoon-afk/memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}
```

```json
{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@whenmoon-afk/memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

Using the MCP tools

The server exposes simple tools to manage memory within your MCP workflow: store memories, recall memories, and forget memories. Each tool is designed to work within your token budgets and provide provenance and summarization to keep your AI’s memory useful and auditable.

# Store a memory with automatic summary
{
  "tool": "memory_store",
  "input": {
    "content": "User works best in focused 90-minute blocks with 15-minute breaks.",
    "type": "fact",
    "importance": 8
  }
}
```

```json
# Smart recall with a token budget
{
  "tool": "memory_recall",
  "input": {
    "query": "work habits",
    "max_tokens": 1200
  }
}
```

```json
# Forget a memory by id
{
  "tool": "memory_forget",
  "input": {
    "id": "mem_8b1",
    "reason": "Information no longer relevant"
  }
}

Security and data portability

This is a local MCP server. Data is stored in a plain SQLite file named memory.db, giving you full control over backups, encryption, and portability. Regularly copy memory.db to a safe location to back up memories. For extra security, store memory.db on an encrypted drive.

Best practices

• Start with max_tokens around 1000 and adjust per task.
• Filter by memory type to improve relevance.
• Use entity filtering to narrow recalls to topics of interest.
• Reference provenance to maintain an audit trail.
• Back up memory.db regularly.

memory_store

Store or update memory with auto-summary

memory_recall

Search memories with token-aware loading

memory_forget

Soft-delete memory while preserving provenance