# michael-denyer/memory-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/michael-denyer/memory-mcp  
**GitHub Stars:** 7  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/michael-denyer-memory-mcp

## Description
Two-tier memory with hot cache (instant injection) and cold semantic search. Auto-promotes frequently-used patterns, extracts knowledge from Claude outputs, and organizes via knowledge graph relationships.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "memory-mcp": {
    "command": "uvx",
    "args": ["hot-memory-mcp"]
  }
}
```

## Documentation & README

<!-- mcp-name: io.github.michael-denyer/hot-memory-mcp -->
<div align="center">

# 🧠 Memory MCP

### Give your AI assistant a persistent second brain

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP 1.0](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io)
[![Claude Code](https://img.shields.io/badge/Claude%20Code-2.1+-blueviolet.svg)](https://claude.ai/code)
[![PyPI](https://img.shields.io/pypi/v/hot-memory-mcp.svg)](https://pypi.org/project/hot-memory-mcp/)
[![CI](https://github.com/michael-denyer/memory-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/michael-denyer/memory-mcp/actions)

<br />

**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.

</div>

---

## 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 session | Patterns auto-promoted to instant access |
| 500k+ token context windows | Hot cache keeps it lean (~20 items) |
| Tool call latency on every memory lookup | Hot cache: **0ms** — a hook already put it in context |
| Stale information lingers forever | Trust scoring demotes outdated facts |
| Flat list of disconnected facts | Knowledge graph connects related concepts |

## Install

```bash
# 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.

<details>
<summary>Manual config (no plugin)</summary>

Add to `~/.claude.json`:

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

See [Reference](https://github.com/michael-denyer/memory-mcp/blob/HEAD/docs/REFERENCE.md) for full configuration options.
</details>

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

```mermaid
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 MCP | Generic Memory Servers |
|---|------------|------------------------|
| **Hot cache** | Injected by a hook at 0ms | Every lookup = tool call |
| **Self-organizing** | Learns and promotes automatically | Manual curation required |
| **Project-aware** | Auto-isolates by git repo | One big pile of memories |
| **Knowledge graph** | Multi-hop recall across concepts | Flat list of facts |
| **Trust scoring** | Outdated info decays and sinks | All memories equal |
| **Setup** | One command, local SQLite | Often 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 Command | Tool | Description |
|---------------|------|-------------|
| `/memory-mcp:remember` | `remember` | Store a memory with semantic embedding |
| `/memory-mcp:recall` | `recall` | Search memories by meaning |
| `/memory-mcp:hot-cache` | `promote` / `demote` | Manage promoted memories |
| `/memory-mcp:stats` | `memory_stats` | Show statistics |
| `/memory-mcp:bootstrap` | `bootstrap_project` | Seed from project docs |
| — | `link_memories` | Knowledge graph connections |

See [Reference](https://github.com/michael-denyer/memory-mcp/blob/HEAD/docs/REFERENCE.md) for all 10 slash commands and full tool API.

### Dashboard

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

![Dashboard](https://raw.githubusercontent.com/michael-denyer/memory-mcp/HEAD/docs/images/dashboard.png)

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

## How to Use

Memory MCP is designed to run as three complementary components:

| Component | Purpose |
|-----------|---------|
| **Claude Code Plugin** | Hooks that inject the hot cache, plus the `/memory-mcp:*` slash commands |
| **MCP Server** | Core memory tools available to Claude via Model Context Protocol |
| **Dashboard** | Web 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

| Document | Description |
|----------|-------------|
| [Reference](https://github.com/michael-denyer/memory-mcp/blob/HEAD/docs/REFERENCE.md) | Full API, CLI, configuration, MCP resources |
| [Troubleshooting](https://github.com/michael-denyer/memory-mcp/blob/HEAD/docs/TROUBLESHOOTING.md) | Common issues and solutions |

## License

MIT