Mem0 Dify Plugin v0.2.10

Last updated: 2026-03-23

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

Previous Updates (v0.2.8) - Stability & Latency Safeguards ✅

Pre-enqueue overload guard: Async operations reject early when pending tasks exceed threshold
Conservative defaults for production: Read timeout 5s, write timeout 15s, aligned concurrency and pgvector pool sizing
PGVector connection reliability: Hardened connection string encoding; defaults match overload controls

Previous Updates (v0.2.7) - Checkpoint Windowing & Resume Accuracy ✅

Windowed checkpoint scanning: Incremental scans process only conversations within
Stronger resume guarantees: Resume cursors set only when more pages exist
Consistent checkpoint updates: Normalized values reduce reprocessing on empty/filtered conversations

Previous Updates (v0.2.6) - Extraction Status & Resume Refinements! 🛠️

For full historical details, see CHANGELOG.md.

🚀 Quick Start

Installation

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

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:

Operation Mode: Choose between async (default, recommended for production) or sync mode (for testing)
Required JSON Configs: , ,
Optional Configs: ,
Performance Parameters (optional):
- Note: PGVector connection pool settings (, ) are configured in the vector store JSON config, not as separate credential fields
Connection Keep-Alive (optional): (default: 120 seconds, minimum: 30 seconds) - configurable heartbeat interval for connection keep-alive mechanism
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:

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:

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

Tool	Description
	Add new memories (user_id required)
	Search with filters and top_k, returns timestamp field
	List all memories
	Get specific memory
	Update memory content
	Delete single memory
	Batch delete memories
	View change history
	Extract semantic/episodic/procedural memories from Dify conversation history
	Check the status and progress of async extraction tasks
	Inspect extraction checkpoint state for a user/app
	Forget stale memories and clean old checkpoints (supports dry_run)

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:

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)
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
Upgrade the Plugin
- Install the new plugin version (v0.1.6 or later)
- Wait for installation to complete
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:

✅ Delete Old Credentials First (MANDATORY)
- Go to Dify UI: → → →
- Do this BEFORE upgrading to avoid errors
Upgrade the Plugin
- Install v0.1.6 or later version
- Wait for installation to complete
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
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
Install dependencies
Run locally

Testing

Run YAML validation:

📊 Version History

Version	Date	Changes
v0.2.10	2026-03-23	Score semantics unification, memory evolution lifecycle, and new forget_memories maintenance controls
v0.2.9	2026-03-04	Extraction worker-pool sliding-window optimization with tighter time-budget and progress flushing behavior
v0.2.8	2026-02-12	Stability under load: pre-enqueue overload guard, conservative defaults, pgvector pool/DSN hardening
v0.2.7	2026-02-08	Checkpoint windowing, resume cursor accuracy, normalized message timestamps
v0.2.6	2026-02-07	Extraction resume safeguards, richer status metrics, local-time task timestamps
v0.2.5	2026-02-04	Documentation refresh: recommended config choices and placeholder-safe examples
v0.2.4	2026-02-03	Resource isolation optimization: Connection pool sharing for long-term memory tool (67% reduction in database connections)
v0.2.3	2026-01-31	Documentation updates: Comprehensive documentation synchronization, merged design documents, improved consistency
v0.2.2	2026-01-30	Performance optimizations: Smart memory classification (33% LLM call reduction), token-aware processing with tiktoken, code quality improvements
v0.2.1	2026-01-29	Critical bug fix: Data loss prevention when time range expands backward, enhanced checkpoint with time range awareness
v0.2.0	2026-01-22	New tool: Long-term memory consolidation, automatic retry mechanism, distributed lock, enhanced checkpoint, atomic save
v0.1.9	2025-01-11	Connection stability & resource management: TCP silent timeout prevention, connection pool memory leak prevention, PGVector configuration enhancement
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 ()
Commit your changes ()
Push to the branch ()
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.