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

Get learned access patterns for predictive caching. When memory_id is provided, shows patterns from that specific memory. Otherwise, shows all learned patterns across all memories. Requires MEMORY_MCP_PREDICTIVE_CACHE_ENABLED=true.

Approve a mined pattern, storing it as a memory and optionally promoting to hot cache.

Get recent audit log entries for destructive operations. Shows history of operations like delete_memory, demote, maintenance, unlink_memories, etc. Useful for understanding what changed and when.

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

Bulk reject multiple mining candidates at once. Provide either pattern_ids (list of specific IDs) OR pattern_type_prefix (e.g., 'entity_' to reject all entity extractions).

Find content patterns appearing across multiple conversation sessions. Useful for identifying frequently-discussed topics that might warrant promotion to hot cache. Patterns appearing in many sessions are likely important project knowledge. Returns patterns sorted by session count and total accesses.

Get database information including schema version and size.

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

Rebuild all memory vectors with the current embedding model. Use this when: - Switching to a different embedding model - Fixing dimension mismatch errors - Recovering from corrupted vector data This operation: 1. Clears all existing vectors (memories are preserved) 2. Re-embeds every memory with the current model 3. Updates stored model info Warning: This can take time for large databases. Progress is logged.

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

Get embedding provider and cache information.

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.

Find memories that may contradict a given memory. Searches for semantically similar memories that could contain conflicting information. High similarity means same topic area, which is where contradictions are likely. Use this after storing a new memory or when validating existing ones.

Delete a memory permanently.

Get all memory pairs marked as contradictions. Returns pairs that have been flagged as containing conflicting information. Use resolve_contradiction to handle these.

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.

Get details for a specific session.

Get all memories from a specific conversation session. Use this to explore what was learned during a particular conversation.

Get recent conversation sessions. Sessions track which conversations memories originated from. Use this to see conversation history and navigate to specific sessions.

Get the trust adjustment history for a memory. Shows all trust changes with reasons, timestamps, and context. Useful for understanding why a memory's trust score evolved.

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)

Mark a memory as incorrect or outdated. Decreases the memory's trust score and records the reason in the trust history. Use this when you discover that a recalled memory contains inaccurate or outdated information. Reasons and their default penalties: - outdated: -0.10 (information is stale but was once correct) - partially_incorrect: -0.15 (some details are wrong) - factually_wrong: -0.30 (fundamentally incorrect) - superseded: -0.05 (replaced by newer information) - low_utility: -0.05 (not useful in practice) Trust score is floored at 0.0. Memories with very low trust will rank lower in recall results due to trust-weighted scoring.

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)

List stored memories with pagination.

Log an output for pattern mining. Called automatically or manually.

Mark two memories as contradicting each other. Creates a CONTRADICTS relationship. Use this when you discover that two memories contain conflicting information about the same topic.

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.

Get memory statistics.

Get observability metrics for monitoring and debugging. Returns counters and gauges for key operations: - recall: queries, results returned/gated, hot hits, empty results - store: total stores, by type, merges, contradictions - mining: runs, patterns found/new/updated - hot_cache: promotions, demotions, evictions, utilization Useful for debugging performance issues, monitoring usage patterns, and understanding system behavior.

Show pattern mining statistics.

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.

Predict which memories might be needed next based on access patterns. Uses learned Markov chain of access sequences to predict what memories typically follow after accessing the given memory. Requires MEMORY_MCP_PREDICTIVE_CACHE_ENABLED=true.

Get status of the predictive hot cache system. Shows whether predictive caching is enabled, configuration, and learned pattern statistics.

Preview memory consolidation without making changes. Shows clusters of similar memories that could be merged. Use this before running actual consolidation to review changes.

Manually promote a memory to hot cache for instant recall.

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.

Get memories with a specific tag.

Recall with automatic fallback through memory types. Tries searching in order: patterns -> project facts -> all types. Stops when min_results are found with medium+ confidence. Use this when you're unsure which memory type contains the answer.

Reject a mined pattern, removing it from candidates.

Get statistics about memory relationships in the knowledge graph.

Store a new memory. Returns the memory ID.

Resolve a contradiction by keeping one memory and handling the other. After resolving: - 'supersedes': Creates SUPERSEDES relationship, weakens trust in discarded - 'delete': Removes the discarded memory entirely - 'weaken': Reduces trust in discarded memory but keeps it

Get retrieval quality statistics. Shows which memories are frequently retrieved and actually used. Helps identify high-value and low-utility memories.

Review mined patterns that are ready for promotion.

Run comprehensive cleanup of stale data. Performs all cleanup operations in one call: - Demotes stale hot memories (not accessed in demotion_days) - Expires old pending mining patterns (30+ days without activity) - Deletes old output logs (based on log_retention_days) - Deletes stale memories by type-specific retention policies Use this periodically to keep the database lean. For just database compaction, use db_maintenance() instead.

Consolidate similar memories by merging near-duplicates. Finds clusters of semantically similar memories and merges them, keeping the most accessed/valuable one as representative.

Run pattern mining on recent output logs. Extracts patterns (imports, facts, commands, code) from logged outputs and updates the mined_patterns table with occurrence counts. Mining is project-scoped: only logs from the current project are processed.

Seed memories from a file. Reads the file and extracts memories based on content structure. Supports markdown files (splits on headers and lists) and plain text. Common use: Import from project CLAUDE.md or documentation files.

Seed memories from text content. Parses the content into individual memories (one per paragraph or list item) and stores them. Useful for initial setup or bulk import. Content is split on: - Double newlines (paragraphs) - Lines starting with '- ' or '* ' (list items) - Lines starting with numbers like '1. ' (numbered lists)

Set or update the topic for a conversation session. Topics help identify what conversations were about when reviewing session history. Can be auto-detected or manually set.