Promem-MCP

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

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

pip install promem-mcp

Then register ContextMCP with your AI coding client:

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

{
  "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

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

CLI

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

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

promem privacy

Storage Location

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

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

# 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

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

License

MIT