Mem0 Dify Plugin v0.3.1

Last updated: 2026-05-16

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. View on GitHub

---

🌟 Features

Complete Memory Management (12 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
• ✅ Extract Long-Term Memory - Automatically extract semantic/episodic/procedural memories from Dify conversation history
• ✅ Check Extraction Status - Check the status and progress of async extraction tasks
• ✅ Get User Checkpoint - Inspect extraction checkpoint state for a user/app
• ✅ Forget Memories - Periodically forget low-retention memories and clean up stale extraction checkpoints

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
• 📈 Score Normalization - Automatically adapts to distance/similarity backends and returns unified 0-1 similarity
• 🧠 Memory Lifecycle - Access-log-driven forgetting curve with optional hard TTL for controlled memory retention
• 🌍 Internationalized - Chinese/English
• ⚙️ Async Mode Switch - 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.3.1) - Windows Compatibility & Write Timeout Fix ✅

• Windows debugging environment support (PR #47, credit: sususweet):
  • Fixed psycopg3 connection errors on Windows (gevent selector conflict with ProactorEventLoop)
  • Added on Windows at plugin startup
  • Conditional psycopg dependency: psycopg3 on Linux/macOS (production), psycopg2 on Windows (local debugging)
• Write operation timeout (PR #47):
  • Raised from 15 s to 45 s to reduce silent write failures on slower LLM providers
• Ollama provider fix (PR #46, credit: sususweet):
  • Added missing dependency so the API-key validation screen no longer hangs when Ollama is selected

Previous Updates (v0.3.0) - Checkpoint & Lock Reliability ✅

• Checkpoint and distributed lock reliability (PR #44):
  • Improved checkpoint write/read sequencing to eliminate rare race conditions under concurrent extraction tasks
  • Strengthened distributed lock acquisition and release paths for more predictable behavior under load
• Async checkpoint test isolation:
  • Isolated async checkpoint tests from pytest-asyncio event loop pollution for more deterministic CI
• Provider compatibility gate & registry validation:
  • Added validation tests for LLMs, embedders, vector DBs, and rerankers to catch unsupported provider configurations early
  • Removed the invalid provider entry that caused silent failures during credential validation

Previous Updates (v0.2.12) - Dynamic Extract Params & Cohere SDK ✅

• Dynamic extraction tool inputs:
  • Changed all parameters to so Dify can bind system variables and upstream values more consistently
• Built-in Cohere reranker dependency:
  • Added the runtime dependency and clarified SDK expectations for cloud rerankers in the docs

Previous Updates (v0.2.11) - AsyncMemory Compatibility & Release Docs ✅

• AsyncMemory initialization compatibility:
  • Added a compatibility shim around so async mode now works whether mem0 exposes it as a coroutine-returning API or a regular classmethod
  • Preserved the existing async credential validation flow in the provider, avoiding behavioral changes outside the initialization fix
• Supported mem0 version range:
  • Documented and aligned the supported dependency range to
  • Kept the current lockfile on while allowing explicit future validation within the supported range
• Regression coverage & release docs:
  • Added unit coverage for both async/sync semantics and async provider credential validation
  • Refreshed top-level docs, testing notes, privacy metadata, and submission template for this release

These changes fix the async-mode startup regression against newer mem0 releases while keeping installation and release documentation aligned.

Previous Updates (v0.2.10) - Score Adaptation & Memory Evolution ✅

• Cross-backend score semantics:
  • Added automatic score mode inference ( vs ) by vector provider/metric and normalized search outputs to stable 0-1 similarity
  • results now consistently expose (similarity), , and
• Access-log-driven forgetting:
  • Search now updates per-user/per-app access logs from raw recall results (sync and async paths)
  • Forgetting uses EWMA quality + Ebbinghaus-style retention curve, with subtype-aware base stability
• Operational cleanup controls:
  • Added new tool with preview support
  • Added credentials: (optional hard memory TTL) and (checkpoint cleanup TTL, default 90)

These changes improve cross-backend retrieval consistency and establish a controllable memory lifecycle for long-term operation.

Previous Updates (v0.2.9) - Extraction Worker Pool Optimization ✅

• Sliding-window concurrency:
  • Extraction uses with a true Semaphore sliding window; a slow user no longer blocks the next one from starting (straggler problem eliminated)
• Precise time budget enforcement:
  • Time budget is checked after acquiring the Semaphore slot, preventing new work from starting past the deadline at user granularity
• Cleaner error handling:
  • User-level exceptions are captured inside each coroutine and returned as ERROR results; progress updates flush every N completions

These changes improve extraction throughput and resource utilization for large user batches; the global concurrency ceiling across multiple concurrent extraction tasks remains unchanged.

For full historical details, see CHANGELOG.md.

---

🚀 Quick Start

Installation

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

1. In Dify Dashboard
   • Go to →
   • Click or upload the plugin package
   • Enter your repository URL or select the file
   • Click

Configuration

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

After installation, you need to configure:

1. Operation Mode: Choose between async (default, recommended for production) or sync mode (for testing)
2. Required JSON Configs: , ,
3. Optional Configs: ,
4. Performance Parameters (optional):
   • Note: PGVector connection pool settings (, ) are configured in the vector store JSON config, not as separate credential fields
5. Connection Keep-Alive (optional): (default: 120 seconds, minimum: 30 seconds) - configurable heartbeat interval for connection keep-alive mechanism
6. Log Level (optional): (INFO/DEBUG/WARNING/ERROR, default: INFO) - can be changed online without redeployment

Recommended configuration choices (brief):

• LLM: Prefer for stricter schema handling and more reliable structured parsing
• Vector DB: Prefer with + psycopg3 pool for stability (TCP keepalive + pool lifecycle)
• Details: See CONFIG.md for full examples and placeholders

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

Long-Term Memory Extraction Modes (Extract Tool)

• Async mode (): Recommended for production and batch jobs; returns and runs in background.
• Sync mode (): Recommended for testing or small runs; sequential and blocking.

Details (including batch processing behavior) are in under Extract Long-Term Memory.

Start Using

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

---

📖 Quick Examples

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

Add Memory

In Dify workflow, add the tool and configure the following parameters:

[Image blocked: Add Memory Tool Configuration]

Required Parameters:

• : User message (e.g., "I love Italian food")
• : User identifier (e.g., "alex")

Optional Parameters:

• : Assistant response (e.g., "Great! I'll remember that.")
• : Agent identifier for scoping
• : Workflow run ID for tracing (recommended to use Dify's )
• : Custom JSON metadata string

Search Memories

In Dify workflow, add the tool and configure the following parameters:

[Image blocked: Search Memory Tool Configuration]

Required Parameters:

• : Search query (e.g., "What food does alex like?")
• : User identifier (e.g., "alex")

Optional Parameters:

• : Maximum number of results (default: 5)
• : JSON filter string for advanced filtering
• : Agent identifier for scoping
• : Workflow run ID for tracing

Key Points:

• is required for , , and
• and must be valid JSON strings when provided
• defaults to 5 if not specified for
• (optional): Recommended to use Dify's 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

Note: uses as the per-user total conversation cap within the configured time range.

---

📚 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

---

⚠️ Upgrade Guide

⚠️ CRITICAL: Credentials Configuration Incompatibility

🔴 IMPORTANT: The plugin has undergone breaking changes in credentials configuration that make old and new configurations incompatible. You MUST delete old credentials before upgrading to avoid configuration errors.

Configuration Field Changes

Version History:

• v0.1.9+: Removed and credential fields (now configured in vector store JSON)
• v0.1.8+: Removed legacy fields completely, only fields are available
• v0.1.6: Changed to type fields (e.g., , , )
• v0.1.6: Added and as separate credential fields
• v0.1.3 and earlier: Used type fields (e.g., , , )

Why This Causes Issues:

• Dify framework cannot automatically migrate credentials from to type
• Old credentials with type will cause Internal Server Error or configuration errors when upgrading
• The field names changed (e.g., → ), making them incompatible
• Removed and fields will cause configuration errors if still present

Required Upgrade Steps

⚠️ BEFORE UPGRADING, YOU MUST:

1. Backup Your Configuration (Optional but Recommended)

   • Copy your current configuration values from Dify UI
   • Save them in a secure location (they contain sensitive API keys and passwords)

2. Delete Old Credentials

   • Go to Dify UI: → →
   • Click or remove all existing credential values
   • This step is mandatory - old credentials will cause errors after upgrade

3. Upgrade the Plugin

   • Install the new plugin version (v0.1.6 or later)
   • Wait for installation to complete

4. Reconfigure Credentials

   • Go to → →
   • Fill in all required fields using the new field names:
     • (was )
     • (was )
     • (was )
     • (was , optional)
     • (was , optional)
   • Important: If you previously used and credential fields, you must now configure them in the JSON config:
     • Add and to your pgvector config JSON (or set to match your , default: 20). See CONFIG.md for examples.
     • These fields are no longer available as separate credential fields
   • Use the same configuration values you backed up in step 1
   • Save the configuration

⚠️ If You Skip Deleting Old Credentials:

• Plugin may fail to start
• You may see "Internal Server Error" when accessing plugin settings
• Tools may not work correctly
• You will need to delete credentials and reconfigure anyway

Upgrading to v0.1.8+

⚠️ Important Configuration Changes:

• Deprecated Fields Removed: Legacy configuration fields (e.g., , ) are completely removed from the configuration UI
• New Fields Required: Only fields (e.g., , ) are available
• Mandatory Action: You MUST delete old credentials and reconfigure using fields

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 parameter for better call chain tracking (recommended to use Dify's )
• Timeout Optimization: Read operation timeout is tuned for responsiveness (current default: 5s, configurable per tool)

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 type for credential fields (e.g., )
• v0.1.6+ changed to type with different field names (e.g., )
• Dify framework cannot handle this type and name change on existing credentials

Required Steps:

1. ✅ Delete Old Credentials First (MANDATORY)

   • Go to Dify UI: → → →
   • Do this BEFORE upgrading to avoid errors

2. Upgrade the Plugin

   • Install v0.1.6 or later version
   • Wait for installation to complete

3. Reconfigure Using New Fields

   • Go to → →
   • Configure using the new fields:
     • (replaces )
     • (replaces )
     • (replaces )
     • (replaces , optional)
     • (replaces , optional)
   • Use the same configuration values as before (just different field names)

Note: v0.1.7 provides backward compatibility in code (can read old field names), but the UI only shows new fields. For cleanest upgrade, always delete old credentials and reconfigure.

Installation Time Optimization

v0.1.6 Installation Time Issue:

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

v0.1.7 Solution:

• Removed and 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:

Note:

• This only affects users who want to use local reranker models
• For Cohere reranker, install the Cohere SDK dependency () in the plugin runtime environment
• Other cloud rerankers may also require their own provider SDKs depending on the selected backend
• 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

1. Clone the repository

2. Install dependencies

3. Run locally

Testing

Run YAML validation:

---

📊 Version History

See CHANGELOG.md for detailed changes.

---

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch ()
3. Commit your changes ()
4. Push to the branch ()
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License - see the LICENSE [blocked] 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.