Project Memory MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Project Memory MCP review my changes before I commit this feature"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.gitSetup
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 structureAnalyze 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 --cachedRead 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/filesReplace verbose sections with minimal references in CLAUDE.md
Example migration:
Architecture (75 lines) →
.project-memory/architecture.mdConventions (60 lines) →
.project-memory/conventions.mdCommands (30 lines) →
.project-memory/useful-commands.mdTasks →
.project-memory/tasks/tasks-active.jsonSpecs →
.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 commitsTask 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 formatTesting
Run the test suite:
npm testTests 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
Support
For issues, questions, or feedback:
Note: This MCP server requires Claude Desktop, Claude Code CLI, or another MCP-compatible client to function.
Available Tools
7 toolscreate-specA
Create detailed specification from user requirements. Use this tool when: (1) user asks to create/write a spec, (2) user describes a feature they want to build, (3) user says "spec this" or "write a spec for". Clarifies ambiguity, validates against codebase, considers security/edge cases/tests, and writes spec to .project-memory/specs/.
Inputs: no named parameters.
initA
Initialize project memory system. Creates folder structure, generates project-specific prompts, and sets up claude.md instructions. Only run once per project.
Inputs: no named parameters.
organizeA
Organize existing CLAUDE.md into project-memory structure. Migrates architecture, conventions, commands, tasks, and specs from CLAUDE.md to .project-memory/ files while keeping minimal references. Requires user approval.
Inputs: no named parameters.
parse-tasksA
Parse tasks from spec files or implementation plans. Extracts tasks with IDs, descriptions, acceptance criteria, dependencies, and adds them to tasks-active.json after user approval.
Inputs: no named parameters.
refresh-promptsA
Refresh project-specific prompts with latest template improvements while preserving customizations. Backs up existing prompts, compares with new templates, identifies customizations, and merges them into updated templates. Requires user approval before modifications.
Inputs: no named parameters.
reviewB
Review uncommitted code changes. Analyzes git diff, checks against current tasks and architecture, identifies issues, and proposes task/architecture updates for user approval.
Inputs: no named parameters.
syncB
Sync project memory with recent commits. Updates tasks (marks completed), prunes commit log to last 20 commits, updates architecture if needed, and extracts new commands.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose with no overlap: create-spec generates specifications, init sets up the system, organize migrates existing content, parse-tasks extracts tasks, refresh-prompts updates templates, review analyzes code changes, and sync integrates commits. The descriptions provide specific use cases and actions, making misselection unlikely.
All tool names follow a consistent verb-based pattern (e.g., create-spec, init, organize, parse-tasks, refresh-prompts, review, sync), using lowercase with hyphens for multi-word names. This uniformity makes the set predictable and easy to navigate, with no deviations in style.
With 7 tools, this server is well-scoped for managing project memory, covering initialization, organization, task parsing, prompt refreshing, code review, and synchronization. Each tool earns its place by addressing a specific aspect of the workflow without being excessive or insufficient.
The tool set provides complete coverage for the project memory domain, including setup (init, organize), content creation (create-spec, parse-tasks), maintenance (refresh-prompts, sync), and quality assurance (review). There are no obvious gaps, and the tools support a full lifecycle from initialization to ongoing updates.
Related MCP Connectors
Shared work memory for Claude Code, Codex, Cursor and chat, scoped to each repository.
Project memory, documentation and controlled secret access for AI coding agents.
Shared project memory that keeps teammates and AI agents aligned across sessions.
Project memory for every AI. Pick up where you left off in Claude, ChatGPT or Cursor, with a team.