Mem0 Dify Plugin v0.1.8

A comprehensive Dify plugin that integrates Mem0 AI's intelligent memory layer, providing self-hosted mode tools with a unified client for self-hosted setups.

🌟 Features

Complete Memory Management (8 Tools)

✅ Add Memory - Intelligently add, update, or delete memories based on user interactions
✅ Search Memory - Search with advanced filters (AND/OR logic) and top_k limiting, returns timestamp field (most recent created_at/updated_at)
✅ Get All Memories - List memories with pagination
✅ Get Memory - Fetch specific memory details
✅ Update Memory - Modify existing memories
✅ Delete Memory - Remove individual memories
✅ Delete All Memories - Batch delete with filters
✅ Get Memory History - View change history

Advanced Capabilities

🖥️ Self-Hosted Mode - Run with Local Mem0 (JSON-based config)
🧱 Simplified Local Config - 5 JSON blocks: LLM, Embedder, Vector DB, Graph DB (optional), Reranker (optional)
🎯 Entity Scoping - user_id (required for add), agent_id, run_id
📊 Metadata System - Custom JSON metadata for rich context
🔍 Filters - JSON filters supported by Mem0 self-hosted mode
🌍 Internationalized - 中英双语 (Chinese/English)
⚙️ Async Mode Switch - async_mode is enabled by default; Write ops (Add/Update/Delete) are non-blocking in async mode, Read ops (Search/Get/History) always wait; in sync mode all operations block until completion.

What's New (v0.1.8)

Dynamic Log Level Configuration: Added runtime log level control without redeployment
- New log_level credential field (INFO/DEBUG/WARNING/ERROR) for online adjustment
- Thread-safe log level updates apply to all existing loggers immediately
- Default log level is INFO; can be changed to DEBUG for detailed troubleshooting
Timeout Optimization: Unified and optimized operation timeouts for better performance
- Read operations (Search/Get/Get_All/History): unified timeout reduced to 15 seconds (from 30s)
- Write operations (Add/Update/Delete): timeout set to 30 seconds for persistence operations
- Improved responsiveness while maintaining reliability
Request Tracing Enhancement: Added run_id parameter to all tools for call chain tracking
- Recommended to use Dify's workflow_run_id to link multiple memory operations in the same workflow
- Important: run_id is only used for request tracing and logging; it is NOT used as a condition for memory layering or filtering
- All tools now include request ID in logs for better traceability
Configuration Cleanup: Removed deprecated configuration fields from UI
- Legacy *_json fields (e.g., local_llm_json) are no longer shown in configuration UI
- Only *_secret fields (e.g., local_llm_json_secret) are available for new installations
- Important: If you encounter configuration issues after upgrade, please delete old credentials and reconfigure using the new *_secret fields
Code Quality Improvements:
- Improved logging with request ID tracking across all operations
- Better error messages with context information
- Optimized timeout handling with unified constants

Previous Updates (v0.1.7)

CPU Overload Protection: Implemented comprehensive task queue monitoring and overload protection
- Background task tracking prevents task accumulation causing CPU 99% utilization
- Automatic rejection of new write operations when queue exceeds 5x concurrency limit
- Enhanced logging with pending task counts for better observability
Seamless Upgrade Compatibility: Resolved upgrade errors from v0.1.3 to v0.1.7. See Upgrade Guide for details.
Installation Time Optimization: Removed transformers and torch dependencies to restore fast installation (~22 seconds). See Upgrade Guide for local reranker installation instructions.
Configuration Validation: Added validation to catch common configuration errors
- Detects when LLM providers are mistakenly used in vector database configuration
- Provides clear error messages before Mem0 validation fails
Code Quality Improvements:
- Fixed recurring indentation errors in multiple tool files
- Optimized code formatting and removed line length violations
- Changed _max_ops from private to public attribute (max_ops)
- Used MAX_PENDING_TASKS_MULTIPLIER constant instead of hardcoded values

Previous Updates (v0.1.6)

Security Enhancement: All sensitive configuration fields now use secret-input type to protect API keys and credentials in the Dify UI
- All JSON configuration fields (local_llm_json, local_embedder_json, local_vector_db_json, local_graph_db_json, local_reranker_json) are now hidden in the UI
User-Configurable Performance Parameters: Added three new optional configuration parameters for production environments
- max_concurrent_memory_operations - Control maximum concurrent async operations (default: 40, recommended > 20 for production)
- pgvector_min_connections - Set PGVector connection pool minimum size (default: 10)
- pgvector_max_connections - Set PGVector connection pool maximum size (default: 40, recommended to match max_concurrent_memory_operations)

Previous Updates (v0.1.5)

Search Memory Timestamp Support: Added timestamp field to search results, displaying the most recent timestamp (created_at or updated_at) in second precision format (2025-11-03T20:06:27)
Code Refactoring: Created utils/helpers.py to centralize common utility functions
- Abstracted parse_timeout() function for unified timeout parameter parsing across all read operations
- Abstracted format_recent_timestamp() and parse_iso_timestamp() for timestamp handling
Code Quality Improvements:
- Removed unused class imports (LocalClient, AsyncLocalClient) from tool files
- Changed AsyncLocalClient.ensure_bg_loop() to instance method call client.ensure_bg_loop()
- Fixed indentation errors in multiple tool files

Previous Updates (v0.1.4)

Logging Investigation: Documented logging output behavior and investigated potential improvements. Identified that logs may appear twice (JSON format from Dify handler + standard format from Python root logger) and that JSON format uses Unicode encoding for non-ASCII characters.

Previous Updates (v0.1.3)

Unified Logging Configuration: Implemented centralized logging using Dify's official plugin logger handler to ensure all logs are properly output to the Dify plugin container for better debugging and monitoring.
Database Connection Pool Optimization: Added automatic connection pool settings for pgvector (min: 10, max: 40) to align with concurrent operation limits, ensuring sufficient database connections for high-concurrency scenarios.
PGVector Configuration Enhancement: Optimized pgvector configuration handling according to Mem0 official documentation, properly supporting parameter priority (connection_pool > connection_string > individual parameters) and automatically building connection strings from discrete parameters.
Constant Naming Optimization: Renamed MAX_CONCURRENT_MEM_ADDS to MAX_CONCURRENT_MEMORY_OPERATIONS (default: 40) to accurately reflect that it controls concurrency for all async memory operations, not just add operations.

Previous Updates (v0.1.2)

Configurable Timeout Parameters: All read operations (Search/Get/Get_All/History) now support user-configurable timeout values through the Dify plugin configuration interface. Timeout parameters are set as manual input fields (not exposed to LLM), allowing users to customize timeout behavior per tool based on their specific needs.
Optimized Default Timeouts: Reduced default timeout values for better responsiveness - all read operations now default to 30 seconds (previously 60s for Search/Get_All), and MAX_REQUEST_TIMEOUT reduced to 60 seconds (from 120s).
Code Quality: Added missing module and class docstrings, fixed formatting issues to comply with Python best practices.

Previous Updates (v0.1.1)

Timeout & Service Degradation: Added comprehensive timeout mechanisms for all async read operations (Search/Get/Get_All/History) with graceful service degradation. When operations timeout or encounter errors, the plugin logs the event and returns default/empty results to ensure Dify workflow continuity.
Robust Error Handling: Enhanced exception handling across all tools to catch all error types (network errors, connection failures, etc.), ensuring workflows continue even when individual tools fail.
Resource Management: Improved background task cancellation on timeout to prevent resource leaks and hanging tasks.
Production Stability: Fixed production issues where tools would hang indefinitely, ensuring reliable operation in production environments.

Previous Updates (v0.1.0)

Smart Memory Management: add_memory tool description updated to reflect its ability to intelligently add, update, or delete memories based on context.
Robust Error Handling: Enhanced get_memory, update_memory, and delete_memory to gracefully handle non-existent memories and race conditions with clear error messages instead of crashes.
Bug Fixes: Fixed get_all_memories returning empty results by correctly parsing Mem0's dictionary response format.
Documentation: Added important notes about delete_all index reset warnings and vector store connection details.

🚀 Quick Start

Installation

📖 For detailed installation steps, see CONFIG.md - Installation

In Dify Dashboard
- Go to Settings → Plugins
- Click Install from GitHub or upload the plugin package
- Enter your repository URL or select the .difypkg file
- Click Install

Configuration

📖 For detailed configuration steps and examples, see CONFIG.md - Configuration Steps

After installation, you need to configure:

Operation Mode: Choose between async (default, recommended for production) or sync mode (for testing)
Required JSON Configs: local_llm_json_secret, local_embedder_json_secret, local_vector_db_json_secret
Optional Configs: local_graph_db_json_secret, local_reranker_json_secret
Performance Parameters (optional): max_concurrent_memory_operations, pgvector_min_connections, pgvector_max_connections
Log Level (optional): log_level (INFO/DEBUG/WARNING/ERROR, default: INFO) - can be changed online without redeployment

Note: All JSON configuration fields are displayed as password fields (hidden input) in the Dify UI to protect sensitive information. Legacy *_json fields are no longer shown in the UI.

Start Using

Once configured, all 8 tools are available in your workflows!

📖 Usage Examples

📖 For complete usage examples with all 8 tools, see CONFIG.md - Usage Examples

Quick Examples

Add Memory:

{
  "user": "I love Italian food",
  "assistant": "Great! I'll remember that.",
  "user_id": "alex"
}

Search Memories:

{
  "query": "What food does alex like?",
  "user_id": "alex",
  "top_k": 5
}

Key Points:

user_id is required for add_memory, search_memory, and get_all_memories
filters and metadata must be valid JSON strings when provided
top_k defaults to 5 if not specified for search_memory
run_id (optional): Recommended to use Dify's workflow_run_id for call chain tracking. Note: This parameter is only for tracing and is NOT used as a condition for memory layering or filtering

🛠️ Available Tools

Tool	Description
`add_memory`	Add new memories (user_id required)
`search_memory`	Search with filters and top_k, returns timestamp field
`get_all_memories`	List all memories
`get_memory`	Get specific memory
`update_memory`	Update memory content
`delete_memory`	Delete single memory
`delete_all_memories`	Batch delete memories
`get_memory_history`	View change history

📚 Documentation

CONFIG.md - Complete installation and configuration guide
CHANGELOG.md - Detailed changelog and version history
PRIVACY.md - Privacy policy and data handling
Mem0 Official Docs - Full API documentation
Dify Plugin Docs - Dify plugin development guide

🎯 Use Cases

Personal Assistant

# Remember user preferences
add_memory("I prefer morning meetings", user_id="john")
add_memory("I'm vegetarian", user_id="john")

# Query preferences
search("when does john prefer meetings?", user_id="john")

Customer Support

# Track interactions
add_memory("Customer reported login issue", user_id="customer_123")

# Retrieve context
search("previous issues", user_id="customer_123")

Multi-Agent Systems

# Agent-specific memories
add_memory("User likes Italian food", agent_id="food_agent")
add_memory("User prefers Rome", agent_id="travel_agent")

# Search across agents
search(
    "user preferences",
    filters='{"OR": [{"agent_id": "food_agent"}, {"agent_id": "travel_agent"}]}'
)

⚠️ Upgrade Guide

Upgrading to v0.1.8

⚠️ Important Configuration Changes:

Deprecated Fields Removed: Legacy *_json configuration fields (e.g., local_llm_json, local_embedder_json) are no longer shown in the configuration UI
New Fields Required: Only *_secret fields (e.g., local_llm_json_secret, local_embedder_json_secret) are available for new installations
If You Encounter Configuration Issues:
- Delete old credentials in Dify UI (Settings → Plugins → mem0ai → Delete Credentials)
- Reconfigure using the new *_secret fields
- This ensures a clean configuration state without legacy field conflicts

New Features:

Dynamic Log Level: You can now change log level (INFO/DEBUG/WARNING/ERROR) in plugin credentials without redeployment
Request Tracing: All tools now support run_id parameter for better call chain tracking (recommended to use Dify's workflow_run_id)
Timeout Optimization: Read operation timeout reduced to 15 seconds for better responsiveness

Upgrading from v0.1.3

⚠️ Critical Issue: If you upgrade from v0.1.3 directly to v0.1.6, you will encounter an Internal Server Error because:

v0.1.3 used text-input type for credential fields
v0.1.6 changed to secret-input type for the same fields
Dify framework cannot handle this type change on existing credentials

Two Solutions:

✅ Recommended: Upgrade to v0.1.7 (Seamless)
- v0.1.7 supports backward-compatible credential upgrades
- Your old text-input credentials will continue to work automatically
- No action required - just upgrade the plugin to v0.1.7
- Optionally migrate to new encrypted fields (*_secret) for enhanced security later
- This is the recommended approach for all users
Alternative: Delete and Reconfigure (for v0.1.6 upgrade)
- Only needed if upgrading directly to v0.1.6 (not recommended)
- Before upgrading, delete all existing plugin credentials in Dify UI
- Upgrade the plugin to v0.1.6 or v0.1.7
- Reconfigure all credentials using the new encrypted fields (*_secret)

Summary: Always upgrade to v0.1.7 for seamless compatibility. Avoid upgrading directly to v0.1.6 from v0.1.3.

Installation Time Optimization

v0.1.6 Installation Time Issue:

v0.1.6 included transformers and torch dependencies for local reranker support
This significantly increased installation time from ~22 seconds to ~2 minutes 25 seconds

v0.1.7 Solution:

Removed transformers and torch from default dependencies to restore fast installation (~22 seconds)
For Local Reranker Users Only: If you need to use local reranker models (e.g., HuggingFace models), you must manually install these dependencies in the Dify plugin container after plugin installation:

# Access the Dify plugin container
docker exec -it <plugin-container-name> /bin/bash

# Install transformers and torch
pip install transformers torch

Note:

This only affects users who want to use local reranker models
If you use cloud-based rerankers (e.g., Cohere API, OpenAI), no additional installation is needed
Most users do not need local rerankers, so this change benefits the majority of users

📌 Important Notes

📖 For detailed operational notes, runtime behavior, and troubleshooting, see CONFIG.md

Quick Reference

Delete All Memories: Automatically resets vector index (normal behavior)
Async Mode (default): Non-blocking writes, timeout-protected reads
Sync Mode: All operations block until completion (no timeout protection)
Service Degradation: Graceful error handling with default/empty results

🚀 Development

Local Setup

Clone the repository

git clone https://github.com/beersoccer/mem0_dify_plugin.git
cd mem0_dify_plugin

Install dependencies
```
pip install -r requirements.txt
```
Run locally
```
python -m main
```

Testing

Run YAML validation:

for file in tools/*.yaml; do 
  python3 -c "import yaml; yaml.safe_load(open('$file'))" && echo "✅ $(basename $file)"
done

📊 Version History

Version	Date	Changes
v0.1.8	2025-12-25	Dynamic log level configuration, timeout optimization, request tracing with run_id, configuration cleanup
v0.1.7	2025-12-16	CPU overload protection, seamless upgrade compatibility, configuration validation, code quality improvements
v0.1.6	2025-12-08	Security enhancement (secret-input for all configs), user-configurable performance parameters
v0.1.5	2025-11-28	Search memory timestamp support, code refactoring with helpers module
v0.1.4	2025-11-23	Logging investigation and documentation update
v0.1.3	2025-11-22	Unified logging configuration, database connection pool optimization, pgvector config enhancement, constant naming optimization
v0.1.2	2025-11-21	Configurable timeout parameters, optimized default timeouts (30s for all read ops), code quality improvements
v0.1.1	2025-11-20	Timeout & service degradation for async operations, robust error handling, resource management improvements, production stability fixes
v0.1.0	2025-11-19	Smart memory management, robust error handling for non-existent memories, race condition protection, bug fixes
v0.0.9	2025-11-17	Unified return format, enhanced async operations (Update/Delete/Delete_All non-blocking), standardized fields, extended constants, complete documentation
v0.0.8	2025-11-11	async_mode credential (default true), sync/async tool routing, provider validation aligned, docs updated
v0.0.7	2025-11-08	Self-hosted mode refactor, centralized constants, background event loop with graceful shutdown, non-blocking add (queued), search via background loop, normalized outputs
v0.0.4	2025-10-29	Dual-mode (SaaS/Local), unified client, simplified Local JSON config, search top_k, add requires user_id, HTTP→SDK refactor
v0.0.3	2025-10-06	Added 6 new tools, v2 API support, metadata, multi-entity
v0.0.2	2025-02-24	Basic add and retrieve functionality
v0.0.1	Initial	First release

See CHANGELOG.md for detailed changes.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Issues: GitHub Issues
Documentation: Mem0 Docs
Dify Docs: Plugin Development

⭐ Show Your Support

If you find this plugin useful, please give it a ⭐ on GitHub!

🙏 Acknowledgments

Dify - AI application development platform
Mem0 AI - Intelligent memory layer for AI
Dify Plugin SDK - Plugin development framework
Original Project - Original dify-plugin-mem0 repository

This project is a deeply modified and enhanced version of the excellent dify-plugin-mem0 project by yevanchen.

I sincerely appreciate the foundational work and outstanding contribution of the original author, yevanchen. The project provided a solid foundation for my localized, high-performance, and asynchronous plugin.

Key Differences from the Original Project:

The original project primarily supported Mem0 platform (SaaS mode) and synchronous request handling. This project has been fully refactored to include:

Self-Hosted Mode: Supports configuring and running the user's own LLM, embedding models, vector databases (e.g., pgvector/Milvus), graph databases, and more.
Asynchronous Support: Utilizes asynchronous request handling, significantly improving performance and concurrency.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
_assets		_assets
provider		provider
tools		tools
utils		utils
.cursorignore		.cursorignore
.difyignore		.difyignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
COMMIT_MESSAGE.txt		COMMIT_MESSAGE.txt
CONFIG.md		CONFIG.md
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
PR_TEMPLATE.md		PR_TEMPLATE.md
README.md		README.md
__init__.py		__init__.py
build_package.sh		build_package.sh
main.py		main.py
manifest.yaml		manifest.yaml
requirements.txt		requirements.txt

License

beersoccer/mem0_dify_plugin

Folders and files

Latest commit

History

Repository files navigation