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:
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):
{
"mcpServers": {
"project-memory": {
"type": "stdio",
"command": "project-memory-mcp"
}
}
}
Configure MCP in Claude Code CLI
Add to your user config at ~/.claude.json:
{
"mcpServers": {
"project-memory": {
"type": "stdio",
"command": "project-memory-mcp"
}
}
}
This will make the mcp available in all your project.
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:
- Create
.project-memory/folder structure - Analyze your project (language, frameworks, structure, conventions)
- Generate and customize project-specific prompts (base.md, parse-tasks.md, review.md, sync.md)
- Populate initial documentation files (architecture.md, conventions.md, useful-commands.md) with detected project info
- Add session-start checklist to CLAUDE.md (ensures project memory is loaded every session)
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:
- Read the spec file
- Extract tasks with IDs, descriptions, acceptance criteria, dependencies
- Show you the parsed tasks
- After approval, add them to
.project-memory/tasks/tasks-active.json
Review Code Before Committing
Before committing, ask Claude:
"Review my changes"
Claude will:
- Get
git diffandgit diff --cached - Read current tasks and architecture
- Analyze code for issues
- Propose task status updates
- After approval, update project memory
Sync After Commits
After committing, ask Claude:
"Sync project memory"
Claude will:
- Get recent commit history
- Determine completed tasks
- Update commit log (last 20 commits)
- Update architecture if changed
- 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:
- Read and analyze your CLAUDE.md
- Identify sections: architecture, conventions, commands, tasks, specs
- Show migration plan with line numbers
- After approval, migrate content to
.project-memory/files - 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.
Create Spec from Requirements
When you have a feature idea or requirements, ask Claude:
"Create a spec for user authentication"
Claude will:
- Clarify ambiguous requirements
- Validate against existing codebase
- Consider security, edge cases, and testing
- Write spec to
.project-memory/specs/
Refresh Prompts
When prompt templates have been updated, ask Claude:
"Refresh project memory prompts"
Claude will:
- Backup existing prompts
- Compare with new templates
- Preserve your customizations
- Merge improvements into updated prompts
Proactive Prompting
After initialization, Claude will automatically:
- Session start: Read project memory files (tasks, architecture, conventions) before working
- When you provide a spec: Offer to parse tasks
- Before commits: Offer to review changes
- After commits: Offer to sync project memory
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:
{
"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 7 tools (all return prompts only):
init
Initialize project memory system. Run once per project.
parse-tasks
Parse tasks from spec files or implementation plans. Checks existing tasks AND codebase to avoid duplicates.
review
Review uncommitted code changes against project context. Uses extended thinking for thorough analysis.
sync
Sync project memory with recent commits. Ensures CLAUDE.md never has outdated references.
organize
Organize existing CLAUDE.md into project-memory structure. Migrates architecture, conventions, commands, tasks, and specs from verbose CLAUDE.md to organized files.
create-spec
Create detailed specification from user requirements. Clarifies ambiguity, validates against codebase, considers security and edge cases.
refresh-prompts
Update project-specific prompts with latest template improvements while preserving customizations. Backs up existing prompts before changes.
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
-
MCP is a pure prompt provider
- Only returns text instructions
- Never reads/writes project files
- Never executes git commands
-
Claude does all the work
- Uses standard tools (Read, Write, Edit, Bash)
- User sees all operations
- Requires approval via AskUserQuestion
-
Project-specific customization
- Prompts tailored to your tech stack
- Language-specific guidelines
- Framework conventions
-
200-line limit per prompt
- Prevents context bloat
- Keeps prompts focused
- Enforced during init
Development
# 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:
npm test
Tests cover:
- Prompt length validation (200-line limit)
- Prompt composition
- Edge cases
Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
License
MIT
Links
- Spec - Detailed specification
- MCP Documentation
- GitHub Repository
Support
For issues, questions, or feedback:
Note: This MCP server requires Claude Desktop, Claude Code CLI, or another MCP-compatible client to function.