Metadata-Version: 2.4
Name: enhanced-mcp-memory
Version: 2.5.1
Summary: Enterprise-grade MCP server with sequential thinking, project convention learning, and intelligent memory management
Author-email: cbunting99 <cbunting99@users.noreply.github.com>
Maintainer-email: cbunting99 <cbunting99@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/cbuntingde/enhanced-mcp-memory
Project-URL: Repository, https://github.com/cbuntingde/enhanced-mcp-memory
Project-URL: Issues, https://github.com/cbuntingde/enhanced-mcp-memory/issues
Project-URL: Documentation, https://github.com/cbuntingde/enhanced-mcp-memory#readme
Project-URL: Changelog, https://github.com/cbuntingde/enhanced-mcp-memory/blob/main/CHANGELOG.md
Keywords: mcp,memory,ai,task-management,knowledge-graph,semantic-search,sequential-thinking,project-conventions,token-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<4.0.0,>=2.10.5
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: sentence-transformers<4.0.0,>=2.2.0
Requires-Dist: numpy<3.0.0,>=1.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: license-file

# 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:

```python
# 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."
    ),
)
```

```python
# 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):

```bash
uvx enhanced-mcp-memory
```

## ⚙️ MCP Configuration

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

```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):

```json
{
  "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`:

```json
{
  "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:

```bash
# 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](CONTRIBUTING.md).
MIT License — see [LICENSE](LICENSE).
