Project Memory MCP

# Project Memory MCP A Model Context Protocol (MCP) server that provides AI-driven project memory management through structured prompts. This server acts as a **pure prompt provider** - it never touches your files directly. Instead, it returns instructions for Claude to execute using its standard tools. ## What is This? `project-memory-mcp` helps Claude manage your project context by: - **Parsing tasks** from specs and implementation plans - **Reviewing code** before commits - **Syncing project memory** with commit history - **Maintaining project documentation** (architecture, conventions, commands) All operations are performed by Claude using its Read, Write, Edit, and Bash tools after getting your approval. ## Key Features ✅ **Pure prompt provider** - No file access, only returns instructions ✅ **Interface-agnostic** - Works with Claude Desktop, Claude Code CLI, or custom clients ✅ **No API costs** - Uses your existing Claude subscription ✅ **User approval required** - Claude asks before making any changes ✅ **Project-specific prompts** - Customized during initialization for your stack ✅ **200-line limit** - Prevents context bloat ## Installation Install globally from GitHub: ```bash npm install -g git+https://github.com/misaamane21j/project-memory-mcp.git ``` ## Setup ### Configure MCP in Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "project-memory": { "command": "project-memory-mcp" } } } ``` ### Configure MCP in Claude Code CLI Add to your MCP settings (`~/.config/claude/mcp_settings.json`): ```json { "mcpServers": { "project-memory": { "command": "project-memory-mcp" } } } ``` ### Restart Claude Restart Claude Desktop or Claude Code CLI to load the MCP server. ## Usage ### Initialize Project Memory In your project directory, ask Claude: ``` "Initialize project memory" ``` Claude will: 1. Create `.project-memory/` folder structure 2. Analyze your project (language, frameworks, structure, conventions) 3. Generate and customize project-specific prompts (base.md, parse-tasks.md, review.md, sync.md) 4. Populate initial documentation files (architecture.md, conventions.md, useful-commands.md) with detected project info 5. Add minimal IMPORTANT reference to `claude.md` **Important:** Each prompt file is limited to ≤ 200 lines to prevent context bloat. ### Parse Tasks from Specs Add a spec file to `.project-memory/specs/feature-name.md`, then ask Claude: ``` "Parse tasks from the spec" ``` Claude will: 1. Read the spec file 2. Extract tasks with IDs, descriptions, acceptance criteria, dependencies 3. Show you the parsed tasks 4. After approval, add them to `.project-memory/tasks/tasks-active.json` ### Review Code Before Committing Before committing, ask Claude: ``` "Review my changes" ``` Claude will: 1. Get `git diff` and `git diff --cached` 2. Read current tasks and architecture 3. Analyze code for issues 4. Propose task status updates 5. After approval, update project memory ### Sync After Commits After committing, ask Claude: ``` "Sync project memory" ``` Claude will: 1. Get recent commit history 2. Determine completed tasks 3. Update commit log (last 20 commits) 4. Update architecture if changed 5. After approval, apply updates ### Organize Existing CLAUDE.md For existing projects with verbose CLAUDE.md files, ask Claude: ``` "Organize my CLAUDE.md into project memory" ``` Claude will: 1. Read and analyze your CLAUDE.md 2. Identify sections: architecture, conventions, commands, tasks, specs 3. Show migration plan with line numbers 4. After approval, migrate content to `.project-memory/` files 5. Replace verbose sections with minimal references in CLAUDE.md **Example migration:** - Architecture (75 lines) → `.project-memory/architecture.md` - Conventions (60 lines) → `.project-memory/conventions.md` - Commands (30 lines) → `.project-memory/useful-commands.md` - Tasks → `.project-memory/tasks/tasks-active.json` - Specs → `.project-memory/specs/*.md` **Result:** CLAUDE.md stays clean with just references, detailed content lives in organized files. ### Proactive Prompting After initialization, Claude will automatically prompt you: - **When you provide a spec:** "Would you like me to parse tasks?" - **Before commits:** "Would you like me to review your changes?" - **After commits:** "Would you like me to sync project memory?" - **Session start:** Check for pending reviews/syncs ## Project Structure After initialization, your project will have: ``` .project-memory/ ├── tasks/ │ ├── tasks-active.json # Active and in-progress tasks │ └── tasks-completed.json # Completed tasks ├── specs/ │ └── *.md # Immutable spec files (you create these) ├── prompts/ │ ├── base.md # Core instructions (≤200 lines) │ ├── parse-tasks.md # Task parsing workflow (≤200 lines) │ ├── review.md # Code review workflow (≤200 lines) │ ├── sync.md # Post-commit sync workflow (≤200 lines) │ └── languages/ # Optional language-specific extensions ├── architecture.md # Project architecture docs ├── conventions.md # Coding conventions ├── useful-commands.md # Common commands └── commit-log.md # Last 20 commits ``` ## Task Schema Tasks follow this structure: ```json { "id": "TASK-001", "title": "Brief description", "description": "Detailed description", "status": "pending | in_progress | completed", "priority": "low | medium | high | critical", "acceptanceCriteria": ["criterion 1", "criterion 2"], "dependencies": ["TASK-000"], "subtasks": [ { "id": "TASK-001-1", "title": "Sub-task title", "status": "pending", "acceptanceCriteria": ["optional"] } ], "specReference": "specs/feature-auth.md", "complexity": "simple | moderate | complex", "createdAt": "2025-01-15T10:00:00Z", "updatedAt": "2025-01-16T14:30:00Z", "completedAt": null } ``` ## MCP Tools The server exposes 5 tools (all return prompts only): ### `init` Initialize project memory system. Run once per project. ### `parse-tasks` Parse tasks from spec files or implementation plans. ### `review` Review uncommitted code changes against project context. ### `sync` Sync project memory with recent commits. ### `organize` Organize existing CLAUDE.md into project-memory structure. Migrates architecture, conventions, commands, tasks, and specs from verbose CLAUDE.md to organized files. ## How It Works ``` ┌─────────────────────────────────────┐ │ Claude (your subscription) │ │ - Analyzes prompts │ │ - Uses Read/Write/Edit/Bash tools │ │ - Asks for user approval │ └──────────────┬──────────────────────┘ │ MCP protocol ▼ ┌─────────────────────────────────────┐ │ project-memory-mcp Server │ │ - Returns prompt text only │ │ - NO file operations │ │ - NO git commands │ └─────────────────────────────────────┘ ``` ## Architecture Principles 1. **MCP is a pure prompt provider** - Only returns text instructions - Never reads/writes project files - Never executes git commands 2. **Claude does all the work** - Uses standard tools (Read, Write, Edit, Bash) - User sees all operations - Requires approval via AskUserQuestion 3. **Project-specific customization** - Prompts tailored to your tech stack - Language-specific guidelines - Framework conventions 4. **200-line limit per prompt** - Prevents context bloat - Keeps prompts focused - Enforced during init ## Development ```bash # Install dependencies npm install # Build npm run build # Watch mode npm run watch # Run tests npm test # Lint npm run lint # Format npm run format ``` ## Testing Run the test suite: ```bash npm test ``` Tests cover: - Prompt length validation (200-line limit) - Prompt composition - Edge cases ## Contributing Contributions welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests 5. Submit a pull request ## License MIT ## Links - [Spec](./spec.md) - Detailed specification - [MCP Documentation](https://modelcontextprotocol.io/) - [GitHub Repository](https://github.com/misaamane21j/project-memory-mcp) ## Support For issues, questions, or feedback: - [GitHub Issues](https://github.com/misaamane21j/project-memory-mcp/issues) --- **Note:** This MCP server requires Claude Desktop, Claude Code CLI, or another MCP-compatible client to function.