Project Mind MCP

Persistent Intelligence for AI Development

Transform Claude from a stateless assistant into a persistent, project-aware intelligence system that never loses context and learns across projects.

🎯 What is Project Mind?

Project Mind is an MCP (Model Context Protocol) server that eliminates three core problems with AI assistants:

1. Context Loss - Claude crashes on operations >8 minutes → Session recovery with auto-checkpoints
2. Stateless Intelligence - Complete memory loss between sessions → Persistent project state and memory
3. Isolated Learning - Knowledge doesn't transfer between projects → Cross-project pattern recognition

The Result

Generic intelligence is commodity. Contextual intelligence is monopoly.

With Project Mind, Claude becomes a persistent intelligence that:

• Remembers project context across sessions
• Recovers automatically from crashes
• Learns patterns and applies them across projects
• Maintains comprehensive project knowledge
• Provides semantic search across your entire codebase

✨ Key Features

🧠 Persistent Intelligence

• Session State Management - Auto-checkpoint every 5-10 tool calls
• Crash Recovery - Automatic resume from last checkpoint
• Project Memory - Maintains context across conversations
• Cross-Project Learning - Patterns discovered in one project help others

📁 Advanced Filesystem

• Binary Format Support - Images, archives, videos, PDFs, Excel
• Streaming Operations - Handle files >1GB without OOM
• File Watching - Auto-reload and reindex on changes
• Semantic Search - Find files by meaning, not just keywords

🎯 Intelligence Systems

• Relevance Tuning - Multi-factor scoring for better search
• Query Expansion - Synonym and abbreviation support
• Pattern Recognition - Similarity algorithms for cross-project learning
• Confidence Scoring - Quantify pattern applicability

📊 Project Management

• Backlog System - EPIC tracking with JSON index
• Git Integration - Smart commits with auto-generated messages
• Research History - Progressive research with source tracking
• Status Tracking - Real-time project metrics

🔬 Diagnostics

• Performance Profiling - Track operation timing and memory
• Metrics Collection - Aggregate performance data
• Stress Testing - Validate under extreme conditions
• Test Coverage - Comprehensive test suite

🚀 Quick Start

Prerequisites

• Node.js 18+ (for MCP server)
• Claude Desktop app
• Windows, macOS, or Linux

Installation

1. Clone and install

git clone https://github.com/yourusername/project-mind-mcp.git
cd project-mind-mcp
npm install
npm run build

2. Configure Claude Desktop

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "project-mind": {
      "command": "node",
      "args": [
        "D:/Project Mind/project-mind-mcp/dist/index.js"
      ]
    }
  }
}

3. Restart Claude Desktop

4. Verify connection

In Claude Desktop, type:

Use Project Mind to check if we're connected

Claude should respond confirming the connection and listing available tools.

📖 Core Concepts

Projects

Projects are the fundamental unit in Project Mind. Each project has:

• Unique ID - Identifies the project (e.g., "gregore", "project-mind")
• File System - Direct access to project files
• Session State - Persistent context across conversations
• Backlog - EPIC tracking and management
• Patterns - Learned solutions from this project

Session Management

Every conversation can be checkpointed:

// Automatically called every 5-10 tool calls
auto_checkpoint({
  project: "my-project",
  operation: "Building authentication",
  progress: 0.6,
  currentStep: "Implementing JWT validation",
  decisions: ["Use RS256", "30min token expiry"],
  nextSteps: ["Add refresh tokens", "Implement logout"],
  activeFiles: ["src/auth/jwt.ts", "src/auth/middleware.ts"]
});

Crash Recovery

If Claude crashes mid-operation:

// Next session automatically detects incomplete work
check_resume_needed({ project: "my-project" });

// Returns resume prompt with full context:
// "Last session was building authentication (60% complete).
//  Current step: Implementing JWT validation
//  Decisions made: Use RS256, 30min token expiry
//  Next: Add refresh tokens, implement logout
//  Continue from here?"

Cross-Project Learning

Patterns discovered in one project help others:

// Record a successful pattern
record_pattern({
  name: "Hybrid Source of Truth",
  problem: "Large markdown files slow to query",
  solution: "JSON index + split files",
  implementation: "200-line JSON vs 4900-line markdown",
  metrics: { before: "5 tool calls", after: "1 tool call" }
});

// Later, in a different project
suggest_patterns({
  currentProject: "other-project",
  problem: "Backlog file is too large"
});
// Returns: "Hybrid Source of Truth pattern (85% confidence)"

🛠️ Tool Categories

Project Mind provides 41 tools across 7 categories:

Session Management (5 tools)

• check_resume_needed - Detect interrupted work
• auto_checkpoint - Periodic state saves
• mark_complete - Clear resume state
• get_session_state - Manual state check
• save_session_state - Manual checkpoint

Project Management (4 tools)

• pm_register_project - Add new project
• pm_list_projects - List all projects
• pm_get_project - Get project details
• pm_update_project - Update configuration

Filesystem (8 tools)

• pm_read_file - Read with format detection
• pm_write_file - Write with format conversion
• pm_list_files - Directory listing
• pm_batch_read - Multiple file reads
• pm_index_files - Semantic indexing
• pm_index_status - Check index status
• search_semantic - Semantic search
• read_semantic - Read with related files

Intelligence (2 tools)

• search_semantic - Natural language file search
• suggest_patterns - Cross-project recommendations

Backlog Management (4 tools)

• query_backlog - Filter EPICs
• add_epic - Create new EPIC
• complete_epic - Mark EPIC done
• get_project_status - Overview metrics

Git Operations (2 tools)

• smart_commit - Auto-generated commit messages
• session_package - Package work for commit

Research (2 tools)

• research_progressive - Streaming research
• search_research - Search history

📚 Usage Examples

Basic Project Setup

// Register your project
pm_register_project({
  id: "my-app",
  name: "My Application",
  path: "C:/Projects/my-app",
  config: {
    fileScanning: { mode: "auto" },
    git: { enabled: true, autoCommit: false }
  }
});

// Index files for semantic search
pm_index_files({ project: "my-app" });

// Check status
get_project_status({ project: "my-app" });

Semantic Search

// Find files by meaning
search_semantic({
  project: "my-app",
  query: "authentication logic",
  topN: 5
});

// Returns:
// - src/auth/jwt.ts (0.92 relevance)
// - src/middleware/auth.ts (0.87 relevance)
// - src/routes/login.ts (0.81 relevance)

Session Checkpoints

// Start work
auto_checkpoint({
  project: "my-app",
  operation: "Refactoring authentication",
  progress: 0.0,
  currentStep: "Analyzing current implementation",
  decisions: [],
  nextSteps: ["Extract JWT logic", "Add refresh tokens"],
  activeFiles: ["src/auth/jwt.ts"]
});

// ... work happens ...

// Checkpoint progress
auto_checkpoint({
  project: "my-app",
  operation: "Refactoring authentication",
  progress: 0.5,
  currentStep: "Extracting JWT logic",
  decisions: ["Keep existing token structure"],
  nextSteps: ["Add refresh tokens", "Update tests"],
  activeFiles: ["src/auth/jwt.ts", "src/auth/tokens.ts"]
});

// Complete
mark_complete({
  project: "my-app",
  summary: "Refactored auth to use refresh tokens"
});

Pattern Learning

// Record a pattern
record_pattern({
  name: "Streaming File Operations",
  problem: "Large files cause OOM errors",
  solution: "Chunk-based streaming with progress",
  implementation: "ReadStream and WriteStream classes",
  project: "my-app",
  metrics: {
    before: { maxSize: "10MB" },
    after: { maxSize: "unlimited" },
    improvement: "100x larger files"
  }
});

// Find similar patterns
suggest_patterns({
  currentProject: "other-app",
  problem: "Memory errors when processing large datasets"
});

🔧 Configuration

Project Configuration

{
  fileScanning: {
    enabled: true,
    mode: "auto",           // "manual" | "auto" | "watcher"
    excludes: [
      "**/node_modules/**",
      "**/.git/**",
      "**/dist/**"
    ]
  },
  git: {
    enabled: true,
    autoCommit: false,
    messageTemplate: "{{type}}({{scope}}): {{message}}"
  },
  backlog: {
    indexPath: "BACKLOG_INDEX.json",
    overviewPath: "BACKLOG_OVERVIEW.md",
    epicsDir: "docs/epics"
  }
}

MCP Server Options

Environment variables:

PROJECT_MIND_DB_PATH=./data/project-mind.db
PROJECT_MIND_LOG_LEVEL=info
PROJECT_MIND_PROFILE=false

📊 Performance

Benchmarks

• File Search: <100ms for 10,000 files
• Semantic Search: <500ms with full indexing
• Checkpoint Save: <50ms
• Pattern Matching: <200ms for 100 patterns
• Large Files: 1GB+ with streaming (constant memory)

Scalability

• Projects: Tested with 50+ simultaneous projects
• Files: 100,000+ files per project
• Patterns: 1,000+ patterns with clustering
• Session State: Unlimited size (compression)

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run stress tests
npm run test:stress

# Run specific test file
npm test filesystem

# Watch mode
npm run test:watch

Test Coverage

• Filesystem: 95% coverage
• Intelligence: 92% coverage
• Session Management: 98% coverage
• Overall: 94% coverage

🐛 Troubleshooting

MCP Connection Issues

Problem: Claude Desktop doesn't see Project Mind tools

Solutions:

1. Check configuration file path
2. Verify Node.js installation: node --version
3. Rebuild MCP server: npm run build
4. Check logs: %APPDATA%\Claude\logs\mcp.log
5. Restart Claude Desktop completely

Performance Issues

Problem: Slow semantic search

Solutions:

1. Check index status: pm_index_status({ project: "my-project" })
2. Reindex files: pm_index_files({ project: "my-project", reindex: true })
3. Reduce file count with excludes in config

Session Recovery Not Working

Problem: Check_resume_needed returns false when it shouldn't

Solutions:

1. Verify checkpoint was saved: Check database timestamps
2. Ensure mark_complete wasn't called prematurely
3. Check for database corruption: Restart MCP server

🗺️ Roadmap

v1.1 (Q1 2026)

• [ ] Web UI for project management
• [ ] Real-time collaboration features
• [ ] Enhanced pattern visualization
• [ ] Additional file format support

v1.2 (Q2 2026)

• [ ] Cloud sync for session state
• [ ] Team collaboration features
• [ ] Advanced analytics dashboard
• [ ] Plugin system for extensions

v2.0 (Q3 2026)

• [ ] Multi-LLM support (GPT, Gemini, etc.)
• [ ] Distributed pattern learning
• [ ] Enterprise features (SSO, audit logs)
• [ ] Advanced security features

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/yourusername/project-mind-mcp.git
cd project-mind-mcp
npm install
npm run dev  # Watch mode

Running Tests

npm test           # All tests
npm run test:unit  # Unit tests only
npm run test:integration  # Integration tests

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Built with:

• Model Context Protocol
• TypeScript
• Vitest

Inspired by the need for truly persistent AI intelligence.

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by developers who believe AI assistants should remember