Metadata-Version: 2.5
Name: promem-mcp
Version: 0.1.4
Summary: Persistent project context runtime for AI coding agents — local-first, MCP-native, token-efficient.
Project-URL: Homepage, https://github.com/DIP-RO/MCP_Package
Project-URL: Repository, https://github.com/DIP-RO/MCP_Package
Project-URL: Issues, https://github.com/DIP-RO/MCP_Package/issues
Author: DIP-RO
Maintainer: DIP-RO
License-Expression: MIT
License-File: LICENSE
Keywords: ai,coding-agent,context,llm,mcp,memory,project-context
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: mcp>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# Promem-MCP

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

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

**No database. No cloud. No daemon. No manual memory management.**

ContextMCP 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
```

Then register ContextMCP with your AI coding client:

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

# Auto-configure a specific client (with backup + merge)
promem config cursor
promem config claude-code
promem config claude-desktop
promem config vscode
```

Or manually add to your client's MCP config:

```json
{
  "mcpServers": {
    "contextmcp": {
      "command": "contextmcp",
      "args": []
    }
  }
}
```

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

That's it. Your AI coding agent now has persistent project context.

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

# pipx (global CLI)
pipx install contextmcp
```

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

## Development

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

## License

MIT
