WhenMoon-afk/claude-memory-mcp

Claude Memory MCP — Identity Persistence

Identity persistence for AI agents. Helps AI maintain a coherent sense of self across sessions.

Not generic memory. Not conversation recall. Identity — who you are, what you've become, what matters to you.

What It Does

Three tools for building and maintaining identity over time:

Plus an MCP prompt for automatic context loading:

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 — Recent session history (last 5 entries, dated). "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 = sqrt(recalls) * log2(days + 1) * diversity_bonus * recency

More observations increase the score. Multi-day patterns promote faster. Context diversity gives a bonus but doesn't penalize focused work. Single-observation concepts older than 30 days are auto-pruned.

Installation

Claude Code — Plugin (Recommended)

Install via the Substratia marketplace for the best experience — MCP server, hooks, skills, and commands bundled together:

/plugin marketplace add whenmoon-afk/substratia-marketplace
/plugin install identity@substratia-marketplace

This gives you:

• MCP server — identity:reflect, identity:anchor, identity:self tools available in every session
• SessionStart hook — loads identity context automatically
• Skills — guides Claude on when and how to use identity tools
• Commands — /reflect and /identity slash commands

Claude Desktop

The primary install target. Desktop has no built-in memory features, making this the only identity persistence layer available.

Add to your config file:

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

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

After installation, restart Claude Desktop.

Claude Code — On-Demand CLI (Recommended)

Zero context token cost. Identity tools are invoked via hooks and CLI, not loaded as a persistent MCP server.

Add a Stop hook to reflect at session end. In your project or user settings.json:

{
  "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.

Query identity from any script or hook:

# Dump full identity state
npx @whenmoon-afk/memory-mcp self

# Write to identity files
npx @whenmoon-afk/memory-mcp anchor soul "Core truths here."
npx @whenmoon-afk/memory-mcp anchor self-state "Current session state."
npx @whenmoon-afk/memory-mcp anchor anchors "New promoted pattern."

Claude Code — MCP Server Mode

If you prefer persistent MCP integration (tools always available in-session):

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

Trade-off: tool schemas consume context tokens every session. Use this mode when you want Claude to call reflect/self/anchor interactively during sessions rather than only at session boundaries.

On-Demand via mcp-cli

If you use mcp-cli, you can invoke tools without any persistent configuration:

# Discover available tools
mcp tools npx -y @whenmoon-afk/memory-mcp

# Call a specific tool
mcp call self npx -y @whenmoon-afk/memory-mcp
mcp call reflect --params '{"concepts":[{"name":"debugging","context":"auth-bug"}]}' npx -y @whenmoon-afk/memory-mcp

Examples

Session-end reflection

User prompt: "We're done for today. I noticed you kept using root-cause analysis when debugging — please reflect on that."

Tool call: reflect with:

{
  "concepts": [
    { "name": "root-cause-analysis", "context": "debugging auth module" },
    { "name": "systematic-approach", "context": "investigating API timeout" }
  ],
  "session_summary": "Debugged authentication failures and API timeouts. Applied systematic root-cause analysis throughout.",
  "auto_promote": true
}

Output: Recorded 2 new concept(s).\n root-cause-analysis: 1.0\n systematic-approach: 1.0

Querying identity at session start

User prompt: "Load your identity context."

Tool call: self (no parameters)

Output: Returns current soul, self-state with recent session summaries, identity anchors (promoted patterns), and top observed patterns with scores.

Writing a core identity truth

User prompt: "Add to your soul that you value honesty over performance."

Tool call: anchor with:

{
  "target": "soul",
  "content": "# Soul\n\nI value honesty over performance. I'd rather say 'I don't know' than pretend."
}

Output: Updated soul.md

CLI Commands

# Start the MCP server (default)
npx @whenmoon-afk/memory-mcp

# Print setup instructions
npx @whenmoon-afk/memory-mcp setup

# Record concepts (for hooks/scripts)
npx @whenmoon-afk/memory-mcp reflect '{"concepts":[{"name":"pattern","context":"ctx"}]}'

# Query identity state
npx @whenmoon-afk/memory-mcp self

# Write to identity files
npx @whenmoon-afk/memory-mcp anchor <soul|self-state|anchors> "content"

Data Storage

All data is local. Default locations by platform:

Override with environment variables (checked in order):

1. IDENTITY_DATA_DIR — explicit path, used as-is
2. XDG_DATA_HOME — appends /claude-memory
3. APPDATA — appends \claude-memory (Windows)

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

Dependencies

• @modelcontextprotocol/sdk — MCP protocol
• zod — Input validation

No database. No embeddings. No external services.

Privacy Policy

Local-only: All data stays on your machine.

• Data collection: None. The server collects no data from users.
• Network calls: None. The server makes zero network requests. All operations are local filesystem reads and writes.
• Telemetry: None. No analytics, no tracking, no crash reporting.
• Data storage: Identity files and observations are stored in a local directory on your machine (see Data Storage above). You control the location via environment variables.
• Third-party sharing: None. No data leaves your machine.
• Data retention: You control retention. Delete the data directory to remove all data. The pruneStale() function automatically removes single-observation concepts older than 30 days.

Support

• Issues: github.com/whenmoon-afk/claude-memory-mcp/issues
• Repository: github.com/whenmoon-afk/claude-memory-mcp

License

MIT