Skip to main content
Glama

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:

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

  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.

Create Spec from Requirements

When you have a feature idea or requirements, ask Claude:

"Create a spec for user authentication"

Claude will:

  1. Clarify ambiguous requirements

  2. Validate against existing codebase

  3. Consider security, edge cases, and testing

  4. Write spec to .project-memory/specs/

Refresh Prompts

When prompt templates have been updated, ask Claude:

"Refresh project memory prompts"

Claude will:

  1. Backup existing prompts

  2. Compare with new templates

  3. Preserve your customizations

  4. 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

  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

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

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request

License

MIT

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 tools
create-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

    A4.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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