Cluster similar memories for potential consolidation or find duplicates.

Groups similar memories based on semantic similarity (if embeddings are enabled) or other strategies. Useful for identifying redundant memories.

Args: strategy: Clustering strategy (default: "similarity"). threshold: Similarity threshold for linking (0.0-1.0, uses config default if not specified). max_cluster_size: Maximum memories per cluster (1-100, uses config default if not specified). find_duplicates: Find likely duplicate pairs instead of clustering. duplicate_threshold: Similarity threshold for duplicates (0.0-1.0, uses config default).

Returns: List of clusters or duplicate pairs with scores and suggested actions.

Raises: ValueError: If any input fails validation.

Consolidate similar memories using algorithmic merging.

This tool intelligently merges similar memories by:

1. Combining content (preserving unique information)

2. Merging tags and entities (union)

3. Calculating appropriate strength based on cohesion

4. Preserving earliest created_at and latest last_used timestamps

Modes:

• "preview": Generate merge preview without making changes

• "apply": Execute the consolidation (requires cluster_id)

Args: cluster_id: Specific cluster ID to consolidate (valid UUID, required for apply mode). mode: Operation mode - "preview" or "apply". auto_detect: If True, automatically find high-cohesion clusters. cohesion_threshold: Minimum cohesion for auto-detection (0.0-1.0, default: 0.75).

Returns: Consolidation preview or execution results.

Raises: ValueError: If cluster_id is invalid or cohesion_threshold is out of range.

Create an explicit relation between two memories.

Links two memories with a typed relationship.

Args: from_memory_id: Source memory ID (valid UUID). to_memory_id: Target memory ID (valid UUID). relation_type: Type of relation (must be one of: related, causes, supports, contradicts, has_decision, consolidated_from). strength: Strength of the relation (0.0-1.0). metadata: Additional metadata about the relation.

Returns: Created relation ID and confirmation.

Raises: ValueError: If any input fails validation.

Perform garbage collection on low-scoring memories.

Removes or archives memories whose decay score has fallen below the forget threshold. This prevents the database from growing indefinitely with unused memories.

Args: dry_run: Preview what would be removed without actually removing. archive_instead: Archive memories instead of deleting. limit: Maximum number of memories to process (1-10,000).

Returns: Statistics about removed/archived memories.

Raises: ValueError: If limit is out of valid range.

Retrieve specific memories by their IDs.

Similar to the reference MCP memory server's open_nodes functionality. Returns detailed information about the requested memories including their relations to other memories.

Pagination: When retrieving many memories by ID, results are paginated. Use page and page_size to navigate through the list of requested memories.

Args: memory_ids: Single memory ID or list of memory IDs to retrieve (max 100 IDs). include_relations: Include relations from/to these memories. include_scores: Include decay scores and age. page: Page number to retrieve (1-indexed, default: 1). page_size: Number of memories per page (default: 10, max: 100).

Returns: Dictionary with paginated results including: - memories: Detailed memory information for current page - not_found: List of IDs that weren't found - pagination: Metadata (page, page_size, total_count, total_pages, has_more)

Examples: # Get first page of memories open_memories(["id1", "id2", "id3", ...], page=1, page_size=10)

# Get next page
open_memories(["id1", "id2", "id3", ...], page=2, page_size=10)

Raises: ValueError: If any memory ID is invalid or list exceeds maximum length.

Promote high-value memories to long-term storage.

Memories with high scores or frequent usage are promoted to the Obsidian vault (or other long-term storage) where they become permanent.

Args: memory_id: Specific memory ID to promote (valid UUID). auto_detect: Automatically detect promotion candidates. dry_run: Preview what would be promoted without promoting. target: Storage backend for promotion. Default: "obsidian" (Obsidian-compatible markdown). Note: This is a storage format, not a file path. Path configured via LTM_VAULT_PATH. force: Force promotion even if criteria not met.

Returns: List of promoted memories and promotion statistics.

Raises: ValueError: If memory_id is invalid or target is not supported.

Read the entire knowledge graph of memories and relations.

Returns the complete graph structure including all memories (with decay scores), all relations between memories, and statistics about the graph.

Pagination: Results are paginated to help you navigate large knowledge graphs. Use page and page_size to retrieve specific portions of the graph. If searching for specific memories or patterns, increment page to see more results.

Args: status: Filter memories by status - "active", "promoted", "archived", or "all". include_scores: Include decay scores and age in results. limit: Maximum number of memories to return (1-10,000). page: Page number to retrieve (1-indexed, default: 1). page_size: Number of memories per page (default: 10, max: 100).

Returns: Dictionary with paginated graph including: - memories: List of memories for current page - relations: All relations (not paginated, for graph structure) - stats: Graph statistics - pagination: Metadata (page, page_size, total_count, total_pages, has_more)

Examples: # Get first page of active memories read_graph(status="active", page=1, page_size=10)

# Get next page
read_graph(status="active", page=2, page_size=10)

# Larger page for overview
read_graph(status="active", page=1, page_size=50)

Raises: ValueError: If status is invalid or limit is out of range.

Save a new memory to short-term storage.

The memory will have temporal decay applied and will be forgotten if not used regularly. Frequently accessed memories may be promoted to long-term storage automatically.

Args: content: The content to remember (max 50,000 chars). tags: Tags for categorization (max 50 tags, each max 100 chars). entities: Named entities in this memory (max 100 entities). source: Source of the memory (max 500 chars). context: Context when memory was created (max 1,000 chars). meta: Additional custom metadata.

Raises: ValueError: If any input fails validation.

Search for memories with optional filters and scoring.

This tool implements natural spaced repetition by blending memories due for review into results when they're relevant. This creates the "Maslow effect" - natural reinforcement through conversation.

Pagination: Results are paginated to help you find specific memories across large result sets. Use page and page_size to navigate through results. If a search term isn't found on the first page, increment page to see more results.

Args: query: Text query to search for (max 50,000 chars). tags: Filter by tags (max 50 tags). top_k: Maximum number of results before pagination (1-100). window_days: Only search memories from last N days (1-3650). min_score: Minimum decay score threshold (0.0-1.0). use_embeddings: Use semantic search with embeddings. include_review_candidates: Blend in memories due for review (default True). page: Page number to retrieve (1-indexed, default: 1). page_size: Number of memories per page (default: 10, max: 100).

Returns: Dictionary with paginated results including: - results: List of matching memories with scores for current page - pagination: Metadata (page, page_size, total_count, total_pages, has_more)

Some results may be review candidates that benefit from reinforcement.

Examples: # Get first page (10 results) search_memory(query="authentication", page=1, page_size=10)

# Get next page
search_memory(query="authentication", page=2, page_size=10)

# Larger page size
search_memory(query="authentication", page=1, page_size=25)

Raises: ValueError: If any input fails validation.

Search across both STM and LTM with unified ranking.

Pagination: Results are paginated to help you find specific memories across large result sets from both short-term and long-term memory. Use page and page_size to navigate through results. If a search term isn't found on the first page, increment page to see more results.

Args: query: Text query to search for (max 50,000 chars). tags: Filter by tags (max 50 tags). limit: Maximum total results before pagination (1-100). stm_weight: Weight multiplier for STM results (0.0-2.0). ltm_weight: Weight multiplier for LTM results (0.0-2.0). window_days: Only include STM memories from last N days (1-3650). min_score: Minimum score threshold for STM memories (0.0-1.0). page: Page number to retrieve (1-indexed, default: 1). page_size: Number of memories per page (default: 10, max: 100).

Returns: Dictionary with paginated results including: - results: List of matching memories from STM and LTM for current page - pagination: Metadata (page, page_size, total_count, total_pages, has_more)

Examples: # Get first page (10 results) search_unified(query="architecture", page=1, page_size=10)

# Get next page
search_unified(query="architecture", page=2, page_size=10)

Raises: ValueError: If any input fails validation.

Reinforce a memory by updating its last accessed time and use count.

This resets the temporal decay and increases the memory's resistance to being forgotten. Optionally can boost the memory's base strength.

Args: memory_id: ID of the memory to reinforce (valid UUID). boost_strength: Whether to boost the base strength.

Returns: Updated memory statistics including old and new scores.

Raises: ValueError: If memory_id is invalid.

Get current performance metrics and statistics.

Returns: Dictionary containing performance statistics for various operations.

Reset all performance metrics and return confirmation.

Returns: Dictionary confirming metrics have been reset.