enhanced-mcp-memory 2.5.0

Enterprise-grade MCP server with sequential thinking, project convention learning, and intelligent memory management

Enhanced MCP Memory

An enhanced MCP (Model Context Protocol) server for intelligent memory and task management, designed for AI assistants and development workflows. Features semantic search, automatic task extraction, knowledge graphs, and comprehensive project management.

⚠️ Heavy Dependencies — Read Before Installing

The semantic-search feature is built on sentence-transformers, which transitively installs PyTorch (torch), transformers, huggingface-hub, tokenizers, numpy, and safetensors. On Windows and Linux, the stock torch wheel ships with bundled CUDA runtime libraries (cublas, cudnn, nccl, …) even for CPU-only installs.

Approximate footprint (cold install, CPU-only):

Asset	Size
pip install download + disk	1.0 – 1.8 GB
First-run model (all-MiniLM-L6-v2 from Hugging Face Hub)	~90 MB
Venv on disk after first run	~1.2 – 2.0 GB

On macOS Apple Silicon the install is much smaller (~150 MB for torch, no bundled CUDA).

NVIDIA GPU drivers are NOT installed automatically. The bundled CUDA libs are enough for CPU inference; install real NVIDIA drivers only if you want GPU acceleration.

If you want a lightweight MCP server that does not pull in PyTorch, this is not it. Semantic search is a core feature and the dependency cannot be skipped. If disk space, download size, or a hostile network policy is a concern, pick a lighter memory server.

✨ Key Features

🧠 Intelligent Memory Management

• Semantic search using sentence-transformers for natural language queries
• Automatic memory classification with importance scoring
• Duplicate detection and content deduplication (normalized hash on (project_id, content_hash) plus optional embedding-based near-duplicate collapse via MEMORY_NEAR_DUP_THRESHOLD)
• Live status notifications — every memory write/recall pushes a short status message through the response (💾 Saved memory …, ♻️ Memory already exists …, 🔍 Found N similar memories …, 📋 Loaded N memories + M tasks …). Visible in chat on every MCP client.
• File path associations for code-memory relationships
• Knowledge graph relationships with automatic similarity detection

🧬 Sequential Thinking Engine

• Structured reasoning chains with 5-stage process (analysis, planning, execution, validation, reflection)
• Context management with automatic token optimization
• Conversation continuity across sessions with intelligent summarization
• Real-time token estimation and compression (30-70% reduction)
• Auto-extraction of key points, decisions, and action items

📋 Advanced Task Management

• Auto-task extraction from conversations and code comments
• Priority and category management with validation
• Status tracking (pending, in_progress, completed, cancelled)
• Task-memory relationships in knowledge graph
• Project-based organization
• Complex task decomposition into manageable subtasks

🏗️ Project Convention Learning

• Automatic environment detection - OS, shell, tools, and runtime versions
• Project type recognition - Node.js, Python, Rust, Go, Java, MCP servers, etc.
• Command pattern learning - Extracts npm scripts, Makefile targets, and project commands
• Tool configuration detection - IDEs, linters, CI/CD, build tools, and testing frameworks
• Dependency management - Package managers, lock files, and installation commands
• Smart command suggestions - Corrects user commands based on project conventions
• Windows-specific optimizations - Proper path separators and command formats
• Memory integration - Stores learned conventions for AI context and future reference

📊 Performance Monitoring

• Performance monitoring with detailed metrics
• Health checks and system diagnostics
• Automatic cleanup of old data and duplicates
• Database optimization tools
• Comprehensive logging and error tracking
• Token usage analytics and optimization recommendations

🚀 Easy Deployment

• uvx compatible for one-command installation
• Automatic private venv launcher (run_in_venv.py) for users who want full isolation without python -m venv setup
• Zero-configuration startup with sensible defaults
• Environment variable configuration
• Cross-platform support (Windows, macOS, Linux)

🏗️ Project Structure

enhanced-mcp-memory/
├── mcp_server_enhanced.py              # Main MCP server with FastMCP integration
├── run_in_venv.py                      # Cross-platform venv launcher (--uninstall, --venv-path)
├── memory_manager.py                   # Core memory/task logic and embeddings
├── sequential_thinking.py              # Thinking chains and context optimization
├── project_conventions.py              # Project convention learning
├── secret_filter.py                    # Credential redaction (default-on)
├── enhanced_automation_middleware.py   # FastMCP request middleware
├── database.py                         # SQLite layer with WAL + write locking
├── __init__.py                         # Package entry (lazy main/mcp)
├── pyproject.toml                      # Build + project metadata
├── setup.py                            # setuptools shim
├── requirements.txt                    # Python dependencies
├── INSTALLATION.md                     # Detailed install guide
├── CHANGELOG.md                        # Release history
├── SECURITY.md                         # Security policy
├── CONTRIBUTING.md                     # Contribution guide
├── tests/                              # pytest suite (secret filter, launcher, tasks, search)
├── data/                               # SQLite database (created on first run)
└── logs/                               # Daily-rotated log files (created on first run)

🚀 Quick Start

Option 1: Using uvx (Recommended)

# Install and run with uvx
uvx enhanced-mcp-memory

Option 2: Manual Installation

# Clone and install
git clone https://github.com/cbuntingde/enhanced-mcp-memory.git
cd enhanced-mcp-memory
pip install -e .

# Run the server
enhanced-mcp-memory

Option 3: Development Setup

# Clone repository
git clone https://github.com/cbuntingde/enhanced-mcp-memory.git
cd enhanced-mcp-memory

# Install dependencies
pip install -r requirements.txt

# Run directly
python mcp_server_enhanced.py

Option 4: Automatic Private Venv (Cross-Platform — Recommended for Local Installs)

If you want a fully isolated install without manually creating a virtualenv, this repo ships run_in_venv.py. On Windows, macOS, and Linux it will:

1. Create a stable per-user venv on first run:
   • Windows: %LOCALAPPDATA%\enhanced-mcp-memory\venv
   • macOS / Linux: ~/.enhanced-mcp-memory/venv
   • Override with ENHANCED_MCP_MEMORY_VENV=/some/path.
2. Install the package into that venv — editable from the current source checkout if pyproject.toml is present, otherwise from PyPI.
3. Re-exec the server's console script inside the venv.

Subsequent runs reuse the cached venv. The MCP config then looks like:

{
  "mcpServers": {
    "memory-manager": {
      "command": "python",
      "args": ["run_in_venv.py"],
      "cwd": "/path/to/enhanced-mcp-memory",
      "env": {
        "LOG_LEVEL": "INFO",
      }
    }
  }
}

The first launch takes a few minutes (downloading torch etc.). After that it is a near-instant sub-process handoff. Use uvx (Option 1) if you'd rather not manage a venv at all.

The launcher also supports --uninstall, --venv-path, and --purge-data — see 🗑️ Uninstall below.

⚙️ MCP Configuration

Add to your MCP client configuration:

For uvx installation:

{
  "mcpServers": {
    "memory-manager": {
      "command": "uvx",
      "args": ["enhanced-mcp-memory"],
      "env": {
        "LOG_LEVEL": "INFO",
      }
    }
  }
}

For local installation:

{
  "mcpServers": {
    "memory-manager": {
      "command": "python",
      "args": ["mcp_server_enhanced.py"],
      "cwd": "/path/to/enhanced-mcp-memory",
      "env": {
        "LOG_LEVEL": "INFO",
      }
    }
  }
}

For auto-venv launcher (recommended for local installs):

{
  "mcpServers": {
    "memory-manager": {
      "command": "python",
      "args": ["run_in_venv.py"],
      "cwd": "/path/to/enhanced-mcp-memory",
      "env": {
        "LOG_LEVEL": "INFO",
      }
    }
  }
}

The launcher creates and reuses a private venv at %LOCALAPPDATA%\enhanced-mcp-memory\venv on Windows or ~/.enhanced-mcp-memory/venv on macOS/Linux. See run_in_venv.py for details, or set ENHANCED_MCP_MEMORY_VENV=/custom/path to override the location.

🗑️ Uninstall

The command depends on how you installed:

Install method	Uninstall command	What it removes
uvx enhanced-mcp-memory (transient)	uv cache clean enhanced-mcp-memory (or delete ~/.cache/uv/environments/enhanced-mcp-memory-* on Linux/macOS / %LOCALAPPDATA%\uv\environments\enhanced-mcp-memory-* on Windows)	The cached venv in uv's cache. Data dir preserved.
uv tool install enhanced-mcp-memory	uv tool uninstall enhanced-mcp-memory	The named tool venv. Data dir preserved.
pip install enhanced-mcp-memory	pip uninstall enhanced-mcp-memory	The system / user-site install. Data dir preserved.
python run_in_venv.py	python run_in_venv.py --uninstall	The managed venv. Add --purge-data to also drop ~/.enhanced_mcp_memory.

The SQLite database and logs live in ~/.enhanced_mcp_memory/ by default (set DATA_DIR to override). They survive uninstall — wipe them manually if you want a fully clean state. The Hugging Face model cache (~/.cache/huggingface/ on Linux/macOS, %USERPROFILE%\.cache\huggingface\ on Windows) is also separate; clear the sentence-transformers/all-MiniLM-L6-v2 directory there to reclaim the ~90 MB model.

For the auto-venv launcher specifically:

python run_in_venv.py --help                # show all flags
python run_in_venv.py --venv-path           # print the venv path
python run_in_venv.py --uninstall           # remove the venv (asks first)
python run_in_venv.py --uninstall --yes     # remove the venv, no prompt
python run_in_venv.py --uninstall --yes --purge-data
                                            # also drop ~/.enhanced_mcp_memory

--uninstall refuses to run without a TTY or --yes, so it is safe to wire into scripted cleanup.

🛠️ Available Tools

Core Memory Tools

• get_memory_context(query) - Get relevant memories and context
• list_memories(project_id?, memory_type?, limit=20) - List memories with optional filters, rendered as a markdown table
• update_memory(memory_id, content?, title?, importance?, tags_csv?) - Partial update of an existing memory; only the fields you pass are written
• delete_memory(memory_id) - Delete a single memory by id (idempotent — no error on missing id)
• create_task(title, description, priority, category) - Create new tasks
• get_tasks(status, limit) - Retrieve tasks with filtering
• get_project_summary() - Get comprehensive project overview

Project Management Tools

• list_projects() - List every project in the database, most-recently-updated first
• add_global_memory(content, importance=0.7) - Write a memory to the cross-project "global" project; surfaced by get_memory_context in every project

Sequential Thinking Tools

• start_thinking_chain(objective) - Begin structured reasoning process
• add_thinking_step(chain_id, stage, title, content, reasoning) - Add reasoning steps
• get_thinking_chain(chain_id) - Retrieve complete thinking chain
• list_thinking_chains(limit) - List recent thinking chains

Context Management Tools

• create_context_summary(content, key_points, decisions, actions) - Compress context for token optimization
• start_new_chat_session(title, objective, continue_from) - Begin new conversation with optional continuation
• consolidate_current_session() - Compress current session for handoff
• get_optimized_context(max_tokens) - Get token-optimized context
• estimate_token_usage(text) - Estimate token count for planning

Enterprise Auto-Processing

• auto_process_conversation(content, interaction_type) - Extract memories and tasks automatically
• decompose_task(prompt) - Break complex tasks into subtasks

Project Convention Tools

• auto_learn_project_conventions() - Automatically detect and learn project patterns
• get_project_conventions_summary() - Get formatted summary of learned conventions
• suggest_correct_command(user_command) - Suggest project-appropriate command corrections
• remember_project_pattern(pattern_type, pattern_name, pattern_content, importance) - Manually store project patterns
• update_memory_context(query) - Refresh memory context with latest project conventions

System Management Tools

• health_check() - Check server health and connectivity
• get_performance_stats() - Get detailed performance metrics
• cleanup_old_data(days_old) - Clean up old memories and tasks
• optimize_memories() - Remove duplicates and optimize storage
• get_database_stats() - Get comprehensive database statistics

🏗️ Project Convention Learning

The Enhanced MCP Memory Server automatically learns and remembers project-specific conventions to prevent AI assistants from suggesting incorrect commands or approaches:

Automatic Detection

• Operating System: Windows vs Unix, preferred shell and commands
• Project Type: Node.js, Python, Rust, Go, Java, MCP servers, FastAPI, Django
• Development Tools: IDEs, linters, formatters, CI/CD configurations
• Package Management: npm, yarn, pip, poetry, cargo, go modules
• Build Systems: Vite, Webpack, Make, batch scripts, shell scripts

Smart Command Suggestions

# Instead of generic commands, suggests project-specific ones:
User types: "node server.js"
AI suggests: "Use 'npm run dev' instead for this project"

User types: "python main.py" 
AI suggests: "Use 'uvicorn main:app --reload' for this FastAPI project"

Windows Optimization

• Automatically detects Windows environment
• Uses cmd.exe and Windows-appropriate path separators
• Suggests Windows-compatible commands (e.g., dir instead of ls)
• Handles Windows-specific Python and Node.js patterns

Memory Integration

All learned conventions are stored as high-importance memories that:

• Appear in AI context for every interaction
• Persist across sessions and project switches
• Include environment warnings and project-specific guidance
• Prevent repeated incorrect command suggestions

🔧 Configuration Options

Configure via environment variables:

Variable	Default	Description
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
MEMORY_ENABLE_SECRET_FILTER	true	Redact detected credentials (AWS keys, GitHub tokens, JWTs, etc.) before any DB write. Set false to disable.
MEMORY_STRICT_SECRET_MODE	false	When true, refuse to persist any content containing a detected secret instead of saving the redacted version.
MEMORY_NEAR_DUP_THRESHOLD	0.0 (disabled)	Cosine-similarity threshold (0.0–1.0) for collapsing semantically near-duplicate memories. 0.0 keeps only hash-based dedup; 0.92 collapses true paraphrases; 0.85 is more aggressive. Bypassed automatically when embeddings are unavailable.
MEMORY_EAGER_EMBEDDINGS	false	When true, load the sentence-transformers model eagerly in MemoryManager.__init__ (pre-2.5.0 behaviour). Off by default — the model is lazy-loaded on first embedding use so cold start is ~5s faster.
DATA_DIR	~/.enhanced_mcp_memory	Where to store data and logs
ENHANCED_MCP_MEMORY_VENV	OS-dependent	Override the venv path used by run_in_venv.py. Defaults to %LOCALAPPDATA%\enhanced-mcp-memory\venv on Windows and ~/.enhanced-mcp-memory/venv on macOS/Linux.

🧪 Testing

The package ships with a pytest suite covering the secret filter, the venv launcher, the task status update path, memory deduplication, and basic search. To run it:

pip install -e ".[dev]"
pytest

The suite is safe to run anywhere — every test uses tmp_path and never touches the production data/ directory. Add new tests under tests/ next to any change in behaviour.

📊 Performance & Monitoring

The server includes built-in performance tracking:

• Response time monitoring for all tools
• Success rate tracking with error counts
• Memory usage statistics
• Database performance metrics
• Automatic health checks

Access via the get_performance_stats() and health_check() tools.

🗄️ Database

• SQLite for reliable, file-based storage
• Automatic schema migrations for updates
• Comprehensive indexing for fast queries
• Built-in backup and optimization tools
• Cross-platform compatibility

Default location: ~/.enhanced_mcp_memory/data/mcp_memory.db (override with DATA_DIR).

🔍 Semantic Search

Powered by sentence-transformers for intelligent memory retrieval:

• Natural language queries — "Find memories about database optimization"
• Similarity-based matching using embeddings
• Configurable similarity thresholds
• Automatic model downloading (~90 MB on first run)

90-day pre-filter (important behaviour change)

search_memories_semantic and add_context_memory's auto-relationship sweep pre-filter the candidate set to memories created within the last 90 days:

SELECT ... FROM memories
WHERE project_id = ?
  AND embedding_vector IS NOT NULL
  AND created_at >= datetime('now', '-90 days')

Cosine similarity is then computed against that pre-filtered set with a single vectorised numpy matmul, not a Python loop. At 1 000 candidate memories this drops the per-query cost from a ~1 000-iteration loop to one matrix multiply.

Implication: a memory older than 90 days will not surface from a semantic-search query, even if its embedding exists and it is the best match. This is intentional — it keeps the hot path fast and biases results toward recent context — but if you depend on long-tail recall, run cleanup_old_data(days_old=0) to bump the created_at of important rows, or back the date window off by editing memory_manager.search_memories_semantic. Plain-text search_memories(query, ...) (the LIKE-based scan) has no such pre-filter and will see the full table.

Scaling and the ANN-index question

The current numpy-vectorised search over the 90-day candidate set keeps the per-query cost well under 20 ms (p99 ≈ 18 ms in the shipped load test, 100 concurrent calls across 10 workers). It is the right algorithm for any project with fewer than roughly 10 000 candidate memories — the matrix multiply is O(n × d) for embedding dimension d = 384 (all-MiniLM-L6-v2) and modern CPUs finish that in microseconds per row.

Two paths exist if you ever outgrow that ceiling:

Option	When to use it	Trade-off
sqlite-vec	You want a SQLite-native ANN index that lives in the same .db file as your data, so backups and the WAL/SHM siblings Just Work. Distributed as a per-platform Python wheel (no system-level SQLite rebuild).	Newer project (~v0.1 at time of writing); the SQL API is its own dialect rather than standard SQL.
hnswlib	You need the absolute lowest query latency at > 100 k vectors and don't mind a native build dep + a separate index file outside SQLite.	Adds a native compile step on install and breaks the "backup = copy one folder" story — the index lives outside the DB file.

No change is made in v2.x because the measured latency is already inside the LLM's patience budget. If you reach for one of the above, keep the 90-day prefilter as a secondary filter so the index only has to cover the hot working set.

Global memories (cross-project)

Every memory in the schema is project-scoped by default. For context that should travel with you between projects — user preferences ("always use snake_case for Python variables"), workflow conventions, tool configurations — write a memory to the built-in "global" project:

add_global_memory(content="...", importance=0.7)

The global project is a sentinel row whose UUID is fixed at 00000000-0000-0000-0000-000000000001. It is created lazily on first use, so existing databases never see it until you opt in. The row is invisible to the per-project list_memories() / list_projects() defaults — it's just another project as far as the DB is concerned.

When get_memory_context is called, the "Relevant Memories" section is now the deduped merge of project-scoped and global memories, ranked by importance. Global memories are flagged with a [global] marker in the rendered bullet list so you can tell where they came from. Adding a global memory does NOT change your active project or session — it writes a parallel row to the sentinel project.

🧠 Sequential Thinking

Structured reasoning system:

• 5-stage thinking process: Analysis → Planning → Execution → Validation → Reflection
• Token optimization: Real-time estimation and compression (30-70% reduction)
• Context continuity: Intelligent session handoffs with preserved context
• Auto-extraction: Automatically identifies key points, decisions, and action items
• Performance tracking: Monitor reasoning chains and optimization metrics

💼 Token Management

Advanced context optimization for high-scale deployments:

• Smart compression: Pattern-based extraction preserves essential information
• Token estimation: Real-time calculation for planning and budgeting
• Context summarization: Automatic conversion of conversations to actionable summaries
• Session consolidation: Seamless handoffs between conversation sessions
• Performance analytics: Detailed metrics on compression ratios and response times

📝 Logging

Comprehensive logging system:

• Daily log rotation in ./logs/ directory
• Structured logging with timestamps and levels
• Performance tracking integrated
• Error tracking with stack traces

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: README
• Discussions: GitHub Discussions

🏷️ Version History

• v2.2.1 - Corrected maintainer identity on the published package metadata, dropped unused scipy and filelock dependencies, removed dead imports, fixed Black target-version, added Python 3.13 classifier, and shipped SECURITY.md / CONTRIBUTING.md / .github/workflows/test.yml.
• v2.2.0 - Secret redaction (SecretFilter) wired into every DB write path. Detects AWS keys, GitHub/GitLab PATs, OpenAI/Anthropic/Google keys, Stripe/Slack/SendGrid/Twilio tokens, JWTs, private keys, bearer headers, credentialed URLs, connection strings, and generic key/password assignments. Default-on; opt into strict mode via MEMORY_STRICT_SECRET_MODE=true.
• v2.1.0 - Production hardening: SQLite WAL + write locking, thread-safe state, structured error envelopes, lazy package imports, real pytest suite, removal of dead call_tool block and circular dependency, typed exception handling throughout.
• v2.0.2 - Updated package build configuration and license compatibility fixes
• v2.0.1 - Enhanced features with sequential thinking and project conventions
• v1.2.0 - Enhanced MCP server with performance monitoring and health checks
• v1.1.0 - Added semantic search and knowledge graph features
• v1.0.0 - Initial release with basic memory and task management