Repository avatar
Search & Data Extraction
v0.9.0
active

hot-memory-mcp

io.github.michael-denyer/hot-memory-mcp

Two-tier memory: hot cache (0ms) + semantic search. Self-organizing.

Documentation

๐Ÿง  Memory MCP

Give your AI assistant a persistent second brain

License: MIT Python 3.11+ MCP 1.0 Claude Code PyPI CI


Stop re-explaining your project every session.

Memory MCP learns what matters and keeps it ready โ€” instant recall for the stuff you use most, semantic search for everything else.


The Problem

Every new chat starts from scratch. You explain your architecture again. You paste the same patterns again. Your context window bloats with repetition.

Other memory solutions help, but they still require tool calls for every lookup โ€” adding latency and eating into Claude's thinking budget.

Memory MCP fixes this with a two-tier architecture:

  1. Hot cache (0ms) โ€” Frequently-used knowledge printed into context by the plugin's SessionStart and UserPromptSubmit hooks before Claude even starts thinking. Claude Code adds a hook's stdout to the conversation, so no tool call is needed.
  2. Cold storage (~50ms) โ€” Everything else, searchable by meaning via semantic similarity.

The system learns what you use and promotes it automatically. Your most valuable knowledge becomes instantly available. No manual curation required.

Before & After

๐Ÿ˜ค Without Memory MCP๐ŸŽฏ With Memory MCP
"Let me explain our architecture again..."Project facts persist and isolate per repo
Copy-paste the same patterns every sessionPatterns auto-promoted to instant access
500k+ token context windowsHot cache keeps it lean (~20 items)
Tool call latency on every memory lookupHot cache: 0ms โ€” a hook already put it in context
Stale information lingers foreverTrust scoring demotes outdated facts
Flat list of disconnected factsKnowledge graph connects related concepts

Install

# Install package
uv tool install hot-memory-mcp   # or: pip install hot-memory-mcp

# Add plugin (recommended)
claude plugins add michael-denyer/memory-mcp

The plugin gives you auto-configured hooks and slash commands. Embeddings run on sentence-transformers on every platform, including Apple Silicon.

Manual config (no plugin)

Add to ~/.claude.json:

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp"
    }
  }
}

See Reference for full configuration options.

Restart Claude Code. Run memory-mcp-cli bootstrap once to seed memories from your project docs; the hooks inject whatever is promoted, but nothing seeds itself.

First run: Embedding model (~90MB) downloads automatically. Takes 30-60 seconds once.

How It Works

flowchart LR
    subgraph LLM["Claude"]
        REQ((Request))
    end

    subgraph Hot["HOT CACHE ยท 0ms"]
        HC[Session context]
        PM[(Promoted memories)]
    end

    subgraph Cold["COLD STORAGE ยท ~50ms"]
        VS[(Vector search)]
        KG[(Knowledge graph)]
    end

    REQ -->|"hook stdout"| HC
    HC -.->|"draws from"| PM
    REQ -->|"recall()"| VS
    VS <-->|"related"| KG

The hot cache (~10 items) reaches Claude through two plugin hooks. SessionStart runs memory-mcp-cli hot-cache --force and UserPromptSubmit runs memory-mcp-cli hot-cache, and Claude Code adds each command's stdout to the conversation. The command prints only when the text differs from what the session last saw, which is cheap while the set is stable and reprints in full when it shifts. The set combines recent recalls, predicted next memories, and top promoted items. Promoted memories (~20 items) is the backing store of frequently-used memories. Memories used 3+ times auto-promote; unused ones demote after 14 days.

What Makes It Different

Most memory systems make you pay a tool-call tax on every lookup. Memory MCP's hot cache bypasses this entirely โ€” a hook prints your most-used knowledge into the conversation before Claude starts thinking.

Memory MCPGeneric Memory Servers
Hot cacheInjected by a hook at 0msEvery lookup = tool call
Self-organizingLearns and promotes automaticallyManual curation required
Project-awareAuto-isolates by git repoOne big pile of memories
Knowledge graphMulti-hop recall across conceptsFlat list of facts
Trust scoringOutdated info decays and sinksAll memories equal
SetupOne command, local SQLiteOften needs cloud setup

The Engram Insight: Human memory doesn't search โ€” frequently-used patterns are already there. That's what hot cache does for Claude.

Quick Reference

Slash CommandToolDescription
/memory-mcp:rememberrememberStore a memory with semantic embedding
/memory-mcp:recallrecallSearch memories by meaning
/memory-mcp:hot-cachepromote / demoteManage promoted memories
/memory-mcp:statsmemory_statsShow statistics
/memory-mcp:bootstrapbootstrap_projectSeed from project docs
โ€”link_memoriesKnowledge graph connections

See Reference for all 10 slash commands and full tool API.

Dashboard

memory-mcp-cli dashboard    # Opens at http://localhost:8765

Dashboard

Browse memories, hot cache, injection history, sessions, and the knowledge graph.

How to Use

Memory MCP is designed to run as three complementary components:

ComponentPurpose
Claude Code PluginHooks that inject the hot cache, plus the /memory-mcp:* slash commands
MCP ServerCore memory tools available to Claude via Model Context Protocol
DashboardWeb UI to browse, manage, and debug your memory database

The plugin is recommended for most users โ€” it auto-configures the MCP server and adds productivity features. Run the dashboard alongside when you want visibility into what's being stored.

Documentation

DocumentDescription
ReferenceFull API, CLI, configuration, MCP resources
TroubleshootingCommon issues and solutions

License

MIT

PYPI
hot-memory-mcp
Install Command
pip install hot-memory-mcp