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

Show current hot cache contents, stats, and observability metrics. Returns items sorted by hot_score (highest first), along with: - metrics.hits: Times hot cache resource was read with content - metrics.misses: Times hot cache resource was empty - metrics.evictions: Items removed to make space for new ones - metrics.promotions: Items added to hot cache - effectiveness: Value metrics (hit rate, tool calls saved, most/least used) - avg_hot_score: Average hot score of items (for LRU ranking)

Manually promote a memory to hot cache for instant recall.

Remove a memory from hot cache (keeps in cold storage).

Pin a hot cache memory to prevent auto-eviction. Pinned memories stay in hot cache even when space is needed for new items. Only works on memories already in hot cache.

Unpin a memory, making it eligible for auto-eviction from hot cache.

Run database maintenance (vacuum, analyze, auto-demote stale). Compacts the database to reclaim unused space, updates query planner statistics, and demotes stale hot memories (if auto_demote is enabled).

Mark a memory as actually used/helpful after recall. Call this when a recalled memory was useful in your response. Helps improve ranking by tracking which memories are valuable. Args: memory_id: ID of the memory that was useful feedback: Optional feedback (e.g., "helpful", "partially_helpful") Returns: Success response with update count

Create a typed relationship between two memories. Use this to build a knowledge graph connecting related concepts. Relationships are directional: from_memory -[relation_type]-> to_memory. Examples: - "Python 3.12 features" -[supersedes]-> "Python 3.11 features" - "Auth implementation" -[depends_on]-> "Database schema" - "API endpoint details" -[elaborates]-> "API overview" - "Project notes" -[mentions]-> "PostgreSQL" (entity extraction)

Get memories related to a given memory. Returns related memories along with their relationship information. Use this to explore the knowledge graph around a specific concept.

Bootstrap hot cache from project documentation files. Scans for common project documentation files (README.md, CLAUDE.md, etc.), parses them into memories, and optionally promotes to hot cache. This is ideal for quickly populating the hot cache when starting work on a new codebase. Edge cases handled gracefully: - Empty repo: Returns success with files_found=0 and helpful message - No markdown files: Returns success with message - File read errors: Logged in errors list, continues with other files - Empty files: Skipped silently - Binary files: Skipped with warning - All content already exists: Returns memories_skipped count

End a session and consolidate episodic memories. Mirrors human memory consolidation: short-term (episodic) memories that prove valuable get promoted to long-term (semantic) storage. Top episodic memories are selected by salience score (combining importance, trust, access count, and recency). Only memories above the threshold are promoted. Use this at the end of a conversation to preserve valuable learnings.

Store a new memory. Returns the memory ID.

Semantic search with confidence gating and composite ranking. Modes: - 'precision': High threshold (0.8), few results (3), prioritizes similarity - 'balanced': Default settings, good for general use - 'exploratory': Low threshold (0.5), more results (10), diverse ranking Returns memories with confidence level and hallucination-prevention guidance.

Delete a memory permanently.

List stored memories with pagination.

Get memory statistics.