# Promem-MCP

> Project Memory MCP — persistent project context for AI coding agents. Built by DIP-RO.

[![PyPI version](https://img.shields.io/pypi/v/promem-mcp?color=blue&label=PyPI)](https://pypi.org/project/promem-mcp/)
[![PyPI downloads](https://static.pepy.tech/badge/promem-mcp)](https://pepy.tech/project/promem-mcp)
[![PyPI downloads (month)](https://img.shields.io/pypi/dm/promem-mcp?label=downloads%2Fmonth&color=green)](https://pepy.tech/project/promem-mcp)
[![Python versions](https://img.shields.io/pypi/pyversions/promem-mcp?color=blue)](https://pypi.org/project/promem-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/DIP-RO/MCP_Package/blob/main/LICENSE)
[![CI](https://github.com/DIP-RO/MCP_Package/actions/workflows/ci.yml/badge.svg)](https://github.com/DIP-RO/MCP_Package/actions/workflows/ci.yml)

```bash
pip install promem-mcp
```

**No database setup. No cloud. No daemon. No manual config.**

Promem-MCP is a local-first, MCP-native context runtime that gives AI coding agents persistent project understanding — architecture, rules, decisions, conventions, environment intelligence, and Git context — without repeated explanations or context waste.

## Quick Start

```bash
pip install promem-mcp
```

That's it. On first run, Promem-MCP **auto-detects and auto-configures** all your installed AI coding clients (Cursor, Claude, VS Code, Cline, etc.). Just restart your AI client after install.

**Prefer manual control?**

```bash
# See which clients are detected
promem config

# Auto-configure all detected clients at once
promem config --all

# Configure a specific client
promem config cursor
promem config claude-code
promem config vscode
```

Or manually add to your client's MCP config:

```json
{
  "mcpServers": {
    "promem-mcp": {
      "command": "promem",
      "args": []
    }
  }
}
```

> **VS Code note:** VS Code uses `"servers"` key, not `"mcpServers"`. Run `promem config vscode` for the correct format.

## How It Works

![How It Works](https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgICBBWyJwaXAgaW5zdGFsbCBwcm9tZW0tbWNwIl0gLS0-IEJbIlByb21lbS1NQ1AgUHl0aG9uIFBhY2thZ2UiXQogICAgQiAtLT4gQ1siQXV0b21hdGljIFByb2plY3QgRGV0ZWN0aW9uIl0KICAgIEMgLS0-IERbIlByb2plY3QgQ29udGV4dCJdCiAgICBDIC0tPiBFWyJFbnZpcm9ubWVudCBDb250ZXh0Il0KICAgIEMgLS0-IEZbIkdpdCBDb250ZXh0Il0KICAgIEQgLS0-IEdbIlBlcnNpc3RlbnQgTWVtb3J5IFNRTGl0ZSArIEZUUzUiXQogICAgRSAtLT4gRwogICAgRiAtLT4gRwogICAgRyAtLT4gSFsiSW50ZWxsaWdlbnQgUmV0cmlldmFsIEZUUzUgU2VhcmNoIl0KICAgIEggLS0-IElbIlRva2VuIE9wdGltaXphdGlvbiBCdWRnZXQtYmFzZWQgU2VsZWN0aW9uIl0KICAgIEkgLS0-IEpbIk1DUCBTZXJ2ZXIgc3RkaW8gdHJhbnNwb3J0Il0KICAgIEogLS0-IEtbIkFJIENvZGluZyBBZ2VudCBDbGF1ZGUsIEN1cnNvciwgVlMgQ29kZSwgZXRjLiJdCg==)

## Features

- **Zero-setup storage** — SQLite database created automatically in OS-appropriate directory
- **Automatic project detection** — language, framework, package manager, test framework
- **Persistent memory** — rules, decisions, conventions, environment facts, Git intelligence
- **Token-efficient retrieval** — FTS5 search with token budgeting, returns only relevant context
- **Provenance tracking** — every memory knows where it came from and how confident it is
- **Secret redaction** — API keys, tokens, passwords are never stored or returned
- **Project isolation** — project memories never leak across projects
- **Stale context detection** — flags memories that conflict with current project state
- **Contradiction detection** — identifies conflicting project rules
- **Session continuity** — handoff summaries for switching between agents/sessions
- **Git intelligence** — recent commits, changed files, TODOs/FIXMEs
- **Environment diagnostics** — Python version, venv, .env completeness, Docker
- **Local-first** — no network requests, no cloud, no external services

## MCP Tools

| Tool | Description |
|------|-------------|
| `ctx_search` | Search persistent project context with token budget |
| `ctx_get` | Get a specific memory by ID |
| `ctx_save` | Save a memory, decision, rule, or fact |
| `ctx_update` | Update an existing memory |
| `ctx_delete` | Delete a memory |
| `ctx_project` | Get current project information |
| `ctx_rules` | Get all project rules and conventions |
| `ctx_decisions` | Get all technical/architecture decisions |
| `ctx_recent` | Get recent memories and latest session |
| `ctx_git` | Get Git intelligence |
| `ctx_environment` | Get environment intelligence |
| `ctx_diagnostics` | Run environment diagnostics |
| `ctx_summary` | Get compact project summary for handoff |

## CLI

```bash
contextmcp --version        # Version
promem status           # Project + storage status
promem doctor           # Health checks
promem stats            # Usage statistics
promem search "query"   # Search context
promem memory list      # List memories
promem decision "text"  # Save a decision
promem privacy          # Privacy info
promem config           # Client configuration
promem repair           # Rebuild index, optimize DB
promem reset            # Delete all data (with confirmation)
```

## Client Support

| Client | Auto-config? | Config Key |
|--------|-------------|------------|
| Claude Code | `promem config claude-code` | `mcpServers` |
| Claude Desktop | `promem config claude-desktop` | `mcpServers` |
| Cursor | `promem config cursor` | `mcpServers` |
| VS Code / Copilot | `promem config vscode` | `servers` |
| OpenCode | `promem config opencode` | `mcp` |
| Gemini CLI | `promem config gemini-cli` | `mcpServers` |
| Windsurf | `promem config windsurf` | `mcpServers` |
| Cline | `promem config cline` | `mcpServers` |
| Roo Code | `promem config roo-code` | `mcpServers` |
| Amazon Q | `promem config amazon-q` | `mcpServers` |
| ZCode (GLM/Zhipu) | `promem config zcode` | `mcpServers` |
| Tabnine | `promem config tabnine` | `mcpServers` |

No client supports true zero-config auto-registration. ContextMCP detects installed clients, offers to write config (with backup + merge), and provides exact copy-paste snippets.

## Privacy

- **Local only** — no network requests
- **Project contents not uploaded**
- **Secrets redacted** — never stored or returned
- **No cloud dependencies**

```bash
promem privacy
```

## Storage Location

ContextMCP uses **project-local storage** — no centralized OS directory, no wasted space.

| Location | Path |
|----------|------|
| Project-local (default) | `<project-root>/.contextmcp/` |

Each project gets its own `.contextmcp/contextmcp.db`. Storage travels with the project. No global storage bloat.

Add `.contextmcp/` to your `.gitignore` (already included by default in ContextMCP's ignore patterns).

Override with `CONTEXTMCP_DATA_DIR` environment variable if needed.

## Installation

```bash
# pip
pip install promem-mcp

# uv
uv add promem-mcp

# pipx (global CLI)
pipx install promem-mcp
```

Works in venv, virtualenv, uv, pipx, and system Python.

## Development

```bash
git clone https://github.com/DIP-RO/MCP_Package.git
cd MCP_Package
pip install -e ".[dev]"
pytest
```

## License

MIT