io.github.michael-denyer/hot-memory-mcp
Two-tier memory: hot cache (0ms) + semantic search. Self-organizing.
Versions
0.4.1latestTools 56
remember Store a new memory. Returns the memory ID.
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.
recall_with_fallback 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.
recall_by_tag Get memories with a specific tag.
forget Delete a memory permanently.
list_memories List stored memories with pagination.
memory_stats Get memory statistics.
preview_consolidation Preview memory consolidation without making changes. Shows clusters of similar memories that could be merged. Use this before running actual consolidation to review changes. Args: memory_type: Filter by type (project/pattern/reference/conversation) Returns: Preview of clusters and potential space savings
run_consolidation Consolidate similar memories by merging near-duplicates. Finds clusters of semantically similar memories and merges them, keeping the most accessed/valuable one as representative. Args: memory_type: Filter by type (project/pattern/reference/conversation) dry_run: If True (default), only preview without making changes Returns: Consolidation results (clusters processed, memories deleted)
validate_memory Mark a memory as validated/confirmed useful. Increases the memory's trust score and records the reason in the trust history. Use this when you verify that a recalled memory is still accurate and helpful. Reasons and their default boosts: - used_correctly: +0.05 (memory was applied successfully) - explicitly_confirmed: +0.15 (user explicitly confirmed accuracy) - cross_validated: +0.20 (corroborated by multiple sources) Trust score is capped at 1.0.
invalidate_memory 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.
get_trust_history 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.
seed_from_text 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)
seed_from_file 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.
bootstrap_project 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
link_memories 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)
unlink_memories Remove relationship(s) between two memories. If relation_type is specified, only removes that specific relationship. If not specified, removes all relationships between the two memories.
get_related_memories 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.
relationship_stats Get statistics about memory relationships in the knowledge graph.
find_contradictions 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.
get_contradictions Get all memory pairs marked as contradictions. Returns pairs that have been flagged as containing conflicting information. Use resolve_contradiction to handle these.
mark_contradiction 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.
resolve_contradiction 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
mark_memory_used 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
retrieval_quality_stats Get retrieval quality statistics. Shows which memories are frequently retrieved and actually used. Helps identify high-value and low-utility memories. Args: memory_id: Get stats for specific memory (None for global) days: How many days back to analyze (default 30) Returns: Statistics on retrieval and usage patterns
get_sessions Get recent conversation sessions. Sessions track which conversations memories originated from. Use this to see conversation history and navigate to specific sessions.
get_session Get details for a specific session.
get_session_memories Get all memories from a specific conversation session. Use this to explore what was learned during a particular conversation.
cross_session_patterns 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.
set_session_topic 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.
summarize_session Summarize a session's key decisions, insights, and action items. Groups session memories by semantic category to extract structured knowledge: - Decisions: Choices made and their rationale - Insights: Lessons learned, antipatterns, landmines, constraints - Action Items: TODOs, bugs, tasks to complete - Context: Background info, conventions, preferences, architecture Use this before end_session() to review what was captured, or anytime to get a structured view of a conversation's key takeaways.
end_session 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.
log_output Log an output for pattern mining. Called automatically or manually.
mining_status Show pattern mining statistics.
review_candidates Review mined patterns that are ready for promotion.
approve_candidate Approve a mined pattern, storing it as a memory and optionally promoting to hot cache.
reject_candidate Reject a mined pattern, removing it from candidates.
bulk_reject_candidates 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).
run_mining 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.
hot_cache_status 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)
metrics_status 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.
promote Manually promote a memory to hot cache for instant recall.
demote Remove a memory from hot cache (keeps in cold storage).
pin 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 Unpin a memory, making it eligible for auto-eviction from hot cache.
db_maintenance 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).
run_cleanup 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.
validate_embeddings Check if the embedding model has changed since database was created. If the model or dimension has changed, existing embeddings may be incompatible and memories may need re-embedding. Returns validation status and details about any mismatches.
db_info Get database information including schema version and size.
embedding_info Get embedding provider and cache information.
audit_history 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. Args: limit: Maximum entries to return (default 50, max 500). operation: Filter by operation type (e.g., "delete_memory", "demote_memory"). Available types: delete_memory, demote_memory, demote_stale, delete_pattern, expire_patterns, cleanup_memories, maintenance, unlink_memories.
db_rebuild_vectors 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.
access_patterns 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.
predict_next 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.
warm_cache Pre-warm hot cache with predicted next memories. Promotes predicted memories to hot cache for instant recall. Only promotes memories that aren't already in hot cache. Requires MEMORY_MCP_PREDICTIVE_CACHE_ENABLED=true.
predictive_cache_status Get status of the predictive hot cache system. Shows whether predictive caching is enabled, configuration, and learned pattern statistics.
Permissions 4
filesystem low shell high database medium env_vars low