enhanced-mcp-memory 2.5.1

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, persistent memory across AI sessions — semantic search, knowledge graphs, and project convention learning for AI assistants and development workflows.

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

The uvx install uses its own virtual environment (uv cache venv) that is auto-created, activated, and used by uvx — you don't manage it yourself. Remove it with uv cache clean enhanced-mcp-memory or uv tool uninstall enhanced-mcp-memory. For a project-local install, the launcher in run_in_venv.py auto-creates, activates, and runs the server inside a private venv (%LOCALAPPDATA%\enhanced-mcp-memory\venv on Windows, ~/.enhanced-mcp-memory/venv on macOS/Linux) and tears it down with python run_in_venv.py --uninstall.

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

• 🧠 Persistent semantic memory — sentence-transformers embeddings with automatic importance scoring, hash + near-duplicate collapse, knowledge-graph relationships, and live status notifications on every read/write.
• 🌐 Cross-project global memories — preferences and conventions stored in a sentinel "global" project that get_memory_context merges into every active project.
• 🏗️ Project convention learning — auto-detects OS, shell, project type (Node, Python, Rust, Go, Java, MCP, FastAPI, …), command patterns (npm scripts, Makefile targets), and tooling; corrects the model's own suggestions and persists conventions as high-importance memories.
• 🔒 Built-in secret redaction — SecretFilter scrubs AWS keys, GitHub/GitLab PATs, OpenAI/Anthropic/Google keys, Stripe/Slack tokens, JWTs, private keys, and credentialed URLs from every write path. Default-on; strict mode via MEMORY_STRICT_SECRET_MODE=true.
• 🚀 Zero-friction deployment — uvx install uses uv's auto-managed venv with one command; local installs use run_in_venv.py which auto-creates, activates, and tears down a private venv (%LOCALAPPDATA%\enhanced-mcp-memory\venv on Windows, ~/.enhanced-mcp-memory/venv on macOS/Linux) via --uninstall.

🧠 Automatic Memory + Manual Overrides

Memory capture is automatic by default — you don't have to call any tool to teach the server about a project:

• On session start — project type, OS, shell, and tooling are detected and persisted as high-importance convention memories (auto_learn_project_conventions).
• On every tools/call / chat/send — incoming content is auto-extracted as a memory (add_context_memory) and, when action verbs are detected, a task is auto-created (auto_create_task_from_context).
• On every AI turn — get_memory_context runs first, merging semantically-relevant project memories with cross-project global memories before the model starts thinking.

Anything you add manually is stored the same way and read the same way when it's semantically related to the current query. There is no "manual vs auto" tier — the recall pipeline (search_memories / search_memories_semantic) ranks every row by importance + similarity regardless of who wrote it. The two paths share storage, dedup, the knowledge-graph relationship generator, and the secret-redaction filter.

Manual writes that flow straight back into recall:

Call	Stored as	Surfaced when
add_global_memory("Always use snake_case for Python variables")	Global preference (importance 0.7)	Any Python task in any project
remember_project_pattern("api", "auth middleware", "JWT in Authorization header")	Project pattern (importance 0.8)	Auth / API work in this project
create_task(title="Refactor login flow")	Project task	Task reminders + context block
start_thinking_chain("Diagnose failing test")	Thinking chain	Follow-up add_thinking_step calls in the same session
auto_process_conversation("TODO: … need to …")	Manual trigger of the same extract path	Identical to the auto path
update_memory(memory_id, importance=0.95)	Existing row, importance bumped	Anything that previously matched it

In short: you can ignore every memory tool and the server still learns as you work, or you can seed it with explicit preferences, patterns, and tasks — those become part of the recall pool the instant they're related to the model's current work.

Real examples — project memory vs. global memory

The same recall pipeline serves both scopes. Here are two rules you might seed on day one, one project-scoped and one global:

# Project memory — applies only inside this repo.
# Surfaced whenever the model is working on issues / debugging here.
remember_project_pattern(
    pattern_type="workflow",
    pattern_name="expert-persona-on-new-issues",
    pattern_content=(
        "When tackling new issues, always use the proper expert persona "
        "for the domain before starting work."
    ),
)

# Global memory — applies across every project, in every editor.
# Surfaced whenever the model is mid-plan / mid-implementation, anywhere.
add_global_memory(
    content=(
        "After each phase or task when implementing a plan, run a code, "
        "bug, and security analysis and fix any issues found before "
        "moving on."
    ),
    importance=0.9,
)

The first one stays scoped to this repo (so you don't drag an unrelated convention into another project). The second one is global — it travels with you into every repo, every editor, every session. The server picks the right scope automatically based on which tool you called.

📁 Per-Project Auto-Detection

Projects are detected and isolated automatically — you never pick a project by hand:

• On startup — detect_project_name reads the working directory, the nearest .git root, and any pyproject.toml / package.json / Cargo.toml / go.mod manifest to give the project a stable name and description.
• Existing project — get_or_create_project returns the same SQLite row every time an editor opens that repo, so memories, tasks, and conventions accumulate across sessions, restarts, and editor switches.
• New project — the first time the server sees a path, a project row is created on the fly and immediately populated by auto_learn_project_conventions (OS, shell, package manager, build / test / lint commands).
• Cross-project memory — the sentinel "global" project holds preferences that travel everywhere (see above); every other memory stays scoped to the project that wrote it.

Open repo A in any editor, the server loads A's memories. Open repo B, the server loads B's. Switch back to A, A's memories come back — no manual project switching needed.

🚀 Quick Start

Install and run with uvx (recommended — one command, no venv to manage):

uvx enhanced-mcp-memory

⚙️ MCP Configuration

Add this to your MCP client config (e.g. Claude Desktop / Cursor mcp.json):

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

🧩 Multi-Editor Support

The same MCP server can run in multiple editors at the same time. The SQLite database and Hugging Face model cache live on disk at ~/.enhanced_mcp_memory (or wherever DATA_DIR points), so any memory, task, or convention written by one editor is visible to the others on their next query — they share storage, not process. Each editor spawns its own uvx enhanced-mcp-memory process on first tool call.

Wire the same JSON block into every editor you use; only the file location and key name differ.

Claude Code — <repo>/.mcp.json (project, shareable with the team) or ~/.claude.json (user, global across all your projects):

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

Claude Desktop — claude_desktop_config.json in the OS app-data directory (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS, ~/.config/Claude/ on Linux). Same JSON shape as Claude Code.

GitHub Copilot (VS Code) — <repo>/.vscode/mcp.json (workspace) or the user-level MCP config. VS Code uses servers instead of mcpServers:

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

OpenCode — <repo>/opencode.json (project) or ~/.config/opencode/config.json (user). Check OpenCode's docs for the exact key name in your version; the command + args + env shape is the same.

You can run all three side-by-side: ask Claude Code to capture a memory, switch to Copilot in the same repo, and Copilot will already see that memory on its next turn because both editors hit the same SQLite file.

💬 Example Prompts

You don't need to memorise tool names — describe what you want in plain language and the AI picks the right tool. A few that work out of the box:

• "Show me everything you remembered about this project today." → list_memories for the current project, post-filtered to today's created_at.
• "List all memories across every project I've worked on." → list_memories(project_id="") (empty string = all projects).
• "How big is the memory database? How many projects, memories, tasks?" → get_database_stats.
• "Is the server healthy?" → health_check.
• "What conventions do you know about this project?" → get_project_conventions_summary.
• "Drop anything older than 60 days." → cleanup_old_data(days_old=60).
• "Forget memory <id>." → delete_memory(memory_id=...).

Seeding rules — project-scoped vs global. Two starter rules worth adding on day one:

• "When tackling new issues, always use the proper expert persona when doing so." — a regular project memory, applied only inside this repo. The AI will adopt the right expert (security, frontend, DB, …) before starting any new issue in this codebase. → remember_project_pattern(...) (see snippet above).

• "After each phase or task when implementing a plan, run a code, bug and security analysis and fix any issues found before moving on." — a global memory, applied across every project. The AI will pause at the end of each plan phase, run the analysis, and fix anything it finds before continuing. → add_global_memory(...) (see snippet above).

Because every AI turn starts with get_memory_context, the AI already sees the relevant memories before you ask — so even open-ended prompts like "what did we decide about the auth flow last time?" recall the right memory automatically.

🗑️ Uninstall

uvx installs into a cached venv that uv manages for you. Wipe it with:

# If launched via `uvx enhanced-mcp-memory` (transient env in uv cache)
uv cache clean enhanced-mcp-memory

# If installed as a named uv tool
uv tool uninstall enhanced-mcp-memory

# If used the local run_in_venv.py launcher (auto-configured private venv)
python run_in_venv.py --uninstall

Add --purge-data to the launcher uninstall to also drop ~/.enhanced_mcp_memory (the SQLite database and logs). The Hugging Face model cache (~/.cache/huggingface/) is separate and can be cleared independently to reclaim the ~90 MB model.

🤝 Contributing & License

Contributions welcome — see CONTRIBUTING.md. MIT License — see LICENSE.