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 (uses config default).
    max_cluster_size: Maximum memories per cluster (uses config default).
    find_duplicates: Find likely duplicate pairs instead of clustering.
    duplicate_threshold: Similarity threshold for duplicates (uses config default).

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

Consolidate similar memories using LLM-driven merging (NOT YET IMPLEMENTED).

This tool will use an LLM to intelligently merge similar memories,
resolve conflicts, and create consolidated notes. Currently returns
a placeholder message.

Args:
    cluster_id: Cluster ID to consolidate.
    mode: Operation mode - "dry_run" or "apply".

Returns:
    Consolidation results (when implemented).

Create an explicit relation between two memories.

Links two memories with a typed relationship (e.g., "references",
"follows_from", "similar_to").

Args:
    from_memory_id: Source memory ID.
    to_memory_id: Target memory ID.
    relation_type: Type of relation.
    strength: Strength of the relation (0.0-1.0).
    metadata: Additional metadata about the relation.

Returns:
    Created relation ID and confirmation.

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.

Returns:
    Statistics about removed/archived memories.

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.

Args:
    memory_ids: Single memory ID or list of memory IDs to retrieve.
    include_relations: Include relations from/to these memories.
    include_scores: Include decay scores and age.

Returns:
    Detailed information about the requested memories with relations.

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.
    auto_detect: Automatically detect promotion candidates.
    dry_run: Preview what would be promoted without promoting.
    target: Target for promotion (default: "obsidian").
    force: Force promotion even if criteria not met.

Returns:
    List of promoted memories and promotion statistics.

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.

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.

Returns:
    Complete knowledge graph with memories, relations, and statistics.

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.
    tags: Tags for categorization.
    entities: Named entities in this memory.
    source: Source of the memory.
    context: Context when memory was created.
    meta: Additional custom metadata.

Search for memories with optional filters and scoring.

Args:
    query: Text query to search for.
    tags: Filter by tags.
    top_k: Maximum number of results.
    window_days: Only search memories from last N days.
    min_score: Minimum decay score threshold.
    use_embeddings: Use semantic search with embeddings.

Returns:
    List of matching memories with scores.

Search across both STM and LTM with unified ranking.

Args:
    query: Text query to search for.
    tags: Filter by tags.
    limit: Maximum total results.
    stm_weight: Weight multiplier for STM results.
    ltm_weight: Weight multiplier for LTM results.
    window_days: Only include STM memories from last N days.
    min_score: Minimum score threshold for STM memories.

Returns:
    A dictionary containing the search results.

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.
    boost_strength: Whether to boost the base strength.

Returns:
    Updated memory statistics including old and new scores.