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.

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.

Get memories with a specific tag.

Delete a memory permanently.

List stored memories with pagination.

Get memory 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.

Consolidate similar memories by merging near-duplicates.

Finds clusters of semantically similar memories and merges them, keeping the most accessed/valuable one as representative.

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 all memory pairs marked as contradictions.

Returns pairs that have been flagged as containing conflicting information. Use resolve_contradiction to handle these.

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

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)

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.

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

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.

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.

Get database information including schema version and size.

Get embedding provider and cache information.

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.

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.

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

Show pattern mining statistics.

Review mined patterns that are ready for promotion.

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

Reject a mined pattern, removing it from 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 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.

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

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.

Get status of the predictive hot cache system.

Shows whether predictive caching is enabled, configuration, and learned pattern statistics.

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)

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 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 statistics about memory relationships in the knowledge graph.

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 retrieval quality statistics.

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

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

Get recent conversation sessions.

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

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.

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

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.

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