How do I use Claude Memory MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Claude Memory MCP Server search for my notes about the project requirements from last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Memory MCP

npm version License: MIT

Identity persistence for AI agents. An MCP server that helps AI maintain a coherent sense of self across sessions.

What It Does

Three tools that help an AI agent build and maintain identity over time:

Tool	Description
`reflect`	End-of-session concept extraction. Records observed patterns, runs promotion scoring, optionally updates self-state. Set `auto_promote: true` to automatically anchor mature patterns.
`anchor`	Explicit identity writing. Write to soul (core truths), self-state (current state), or anchors (grown patterns).
`self`	Query current identity. Returns all identity files and top observed patterns with scores.

Plus an MCP prompt for automatic context loading:

Prompt	Description
`identity`	Loads persistent identity at session start — soul, self-state, anchors, observed patterns.

Related MCP server: ClaudeKeep

How It Works

The server manages three identity files and an observation store:

soul.md — Core truths, carved by the LLM. "Who I am."
self-state.md — Current state, updated each session. "Where I am now."
identity-anchors.md — Patterns grown from repeated observations. "What I've become."
observations.json — Concept frequency tracking with promotion math.

When a concept appears consistently across enough sessions and contexts, it crosses a promotion threshold and gets added to identity-anchors.md automatically.

Promotion formula: score = total_recalls * log2(distinct_days + 1) * context_diversity * recency_weight

Quick Start

Claude Code

claude mcp add memory-mcp -- npx -y @whenmoon-afk/memory-mcp

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

After installation, restart Claude Desktop.

Auto-Reflect Hook (Claude Code)

Add a Stop hook to .claude/settings.json to automatically reflect at session end:

{ "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "npx -y @whenmoon-afk/memory-mcp reflect '{\"concepts\":[], \"session_summary\":\"Session ended.\", \"auto_promote\": true}'" } ] } ] } }

For richer reflection, use a custom script that extracts concepts from the session transcript.

CLI Commands

# Start the MCP server (default) npx @whenmoon-afk/memory-mcp # Print setup instructions npx @whenmoon-afk/memory-mcp setup # Record concepts from CLI (for hooks/scripts) npx @whenmoon-afk/memory-mcp reflect '{"concepts":[{"name":"pattern","context":"ctx"}]}'

Data Storage

All data is local. Stored at $XDG_DATA_HOME/claude-memory/ (defaults to ~/.local/share/claude-memory/).

claude-memory/ observations.json # Concept frequency tracking identity/ soul.md # Core identity truths self-state.md # Current session state identity-anchors.md # Promoted patterns

Dependencies

@modelcontextprotocol/sdk — MCP protocol
zod — Input validation

No database. No embeddings. No external services.

Privacy

Local-only: All data stays on your machine. Zero telemetry. Zero network calls.

License

MIT

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Claude Memory MCP Server