Devmind MCP

DevMind MCP

[](https://www.npmjs.com/package/devmind-mcp) [](https://opensource.org/licenses/MIT) [](https://nodejs.org) [](https://www.npmjs.com/package/devmind-mcp)

Intelligent context-aware memory system for AI assistants

[English](README.md) | [中文](docs/zh/README.md) | [📋 Changelog](CHANGELOG.md) | 🚀 Latest Release

---

Why DevMind MCP?

• Pure MCP Tool - Seamless integration with AI assistants through Model Context Protocol
• Hybrid Search - Semantic 40% + Keyword 30% + Quality 20% + Freshness 10%
• 100% Private - All data stored locally in SQLite, zero cloud transmission
• 15 MCP Tools - Complete toolkit for memory management and codebase indexing
• Cross-Platform - Works with Claude Code, Cursor, and all MCP-compatible clients

---

Table of Contents

• [Overview](#overview)
• [Quick Start](#quick-start)
• [Usage Guide](#usage-guide)
• [Configuration](#configuration)
• [API Reference](#api-reference)
• [Use Cases](#use-cases)
• [Development](#development)
• [Contributing](#contributing)
• [License](#license)

---

Overview

What is DevMind MCP?

DevMind MCP provides persistent memory capabilities for AI assistants through the Model Context Protocol (MCP). It enables AI to remember context across conversations, automatically track development activities, and retrieve relevant information intelligently.

Key Features

Core Capabilities

• Type-Based Auto-Memory - Simplified intelligent recording based on context type
• Tier 1: Auto-record technical execution (bugfix, featureadd, code_modify) - silent
• Tier 2: Auto-record with notice (solution, design, documentation) - can delete
• Tier 3: No auto-record (conversation, error) - unless force_remember=true
• Intelligent Memory - AI-driven context recording through MCP protocol
• Semantic Search - AI-powered vector embedding search for finding related contexts
• Codebase Indexing - Index project files for semantic search and code discovery
• Persistent Storage - SQLite-based local storage with complete privacy
• Hybrid Search - Combines keyword and semantic search for best results
• Real-time Response - Records during development, retrieves instantly
• Cross-tool Support - Compatible with multiple MCP clients and development environments
• Unified Sessions - One main session per project for consistent context

Technical Features

• Full MCP protocol compliance
• Unified session management (one main session per project)
• Automatic session reactivation
• Customizable storage paths and behavior
• Efficient handling of thousands of contexts
• Automatic cleanup and memory optimization
• Robust error handling and recovery

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      AI Assistant                            │
│               (Claude Code / Cursor / etc.)                  │
└────────────────────────┬─────────────────────────────────────┘
                         │ MCP Protocol (stdio)
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                   DevMind MCP Server                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐  │
│  │  15 MCP Tools   │  │ Type-Based      │  │ Hybrid Search│  │
│  │                 │  │ Auto-Memory     │  │              │  │
│  │ • Session (4)   │  │                 │  │ • Semantic   │  │
│  │ • Context (6)   │  │                 │  │ • Keyword    │  │
│  │ • Project (3)   │  │ • 3 Tiers       │  │ • Quality    │  │
│  │ • Codebase (2)  │  │ • Smart Types   │  │ • Freshness  │  │
│  │ • Visualize (1) │  │ • Lazy Scoring  │  │              │  │
│  └─────────────────┘  └─────────────────┘  └──────────────┘  │
└────────────────────────┬─────────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────────┐
│                  SQLite Local Storage                        │
│  Projects • Sessions • Contexts • Relationships • Embeddings │
│  + Auto-generated quality scores (lazy update every 24h)     │
└──────────────────────────────────────────────────────────────┘

Key Components:

• 15 MCP Tools - Session management (4), context operations (6), project features (3), codebase indexing (2), visualization (1)
• Type-Based Auto-Memory - Simplified 3-tier strategy based on context type
• Hybrid Search - Multi-dimensional scoring: Semantic 40% + Keyword 30% + Quality 20% + Freshness 10%
• Local Storage - SQLite database with vector embeddings and full-text search indexes

Project Structure

devmind-mcp/
├── src/
│   ├── mcp-server.ts                # MCP protocol server
│   ├── database.ts                  # SQLite storage engine
│   ├── vector-search.ts             # Semantic search with embeddings
│   ├── session-manager.ts           # Session & context management
│   ├── pending-memory-tracker.ts    # Unrecorded file tracking (v2.2.6+)
│   ├── content-extractor.ts         # Code analysis & extraction
│   ├── content-quality-assessor.ts  # Content quality scoring
│   ├── quality-score-calculator.ts  # Multi-dimensional quality scoring
│   ├── auto-record-filter.ts        # Smart deduplication
│   ├── context-file-manager.ts      # File change tracking
│   ├── performance-optimizer.ts     # Performance optimizer (v2.2.0+)
│   ├── search-cache.ts              # Search cache
│   ├── smart-confirmation-system.ts # Smart confirmation system
│   ├── types.ts                     # Type definitions
│   ├── index.ts                     # Main entry point
│   │
│   ├── memory-graph/                # Memory graph visualization
│   │   ├── index.ts                 # Main graph generator
│   │   ├── types.ts                 # Graph type definitions
│   │   ├── data/
│   │   │   ├── GraphDataExtractor.ts  # Data extraction from database
│   │   │   ├── NodeBuilder.ts         # Node construction & labeling
│   │   │   └── EdgeBuilder.ts         # Edge/relationship building
│   │   └── templates/
│   │       ├── HTMLGenerator.ts       # HTML visualization generator
│   │       └── HTMLGeneratorCytoscape.ts  # Cytoscape graph generator
│   │
│   ├── context-engine/              # Codebase indexing engine
│   │   ├── index.ts                 # ContextEngine main entry
│   │   ├── FileScanner.ts           # File scanning and filtering
│   │   ├── IgnoreProcessor.ts       # .gitignore and .augmentignore rules
│   │   └── types.ts                 # Type definitions
│   │
│   ├── utils/
│   │   ├── file-path-detector.ts    # Intelligent file detection
│   │   ├── git-diff-parser.ts       # Git diff parsing
│   │   ├── path-normalizer.ts       # Cross-platform path handling
│   │   ├── project-root-finder.ts   # Project root finder (v2.1.11+)
│   │   ├── language-detector.ts     # Programming language detection
│   │   ├── query-enhancer.ts        # Search query enhancement (v2.2.0+)
│   │   ├── auto-memory-classifier.ts # Auto memory classification (v2.2.0+)
│   │   ├── context-enricher.ts      # Context enrichment (v2.2.0+)
│   │   ├── batch-processor.ts       # Batch processor (v2.2.0+)
│   │   └── performance-optimizer.ts # Performance optimization (v2.2.0+)
│
├── dist/                            # Compiled output
├── scripts/                         # Maintenance scripts
├── docs/zh/                         # Chinese documentation
└── tests/                           # Test files

---

Quick Start

Prerequisites

• Node.js ≥ 20.0.0
• MCP-compatible client (Claude Code, Cursor, etc.)

Installation

Choose the method that fits your needs:

| Method | Command | Best For | Auto-update | |:-------------------|:-----------------------------|:------------------------------|:-----------:| | NPX | npx -y devmind-mcp@latest | Quick testing, first-time use | Yes | | Global Install | npm install -g devmind-mcp | Daily development | No | | From Source | git clone + npm install | Contributing, customization | No |

Step-by-Step Setup

Step 1: Add to MCP Client

Option A: Using Claude Code CLI (Easiest)

# Install latest version
claude add mcp npx -y devmind-mcp@latest

# Or install specific version
claude add mcp npx -y devmind-mcp@2.4.1

Option B: Manual Configuration

Edit your MCP client configuration file:

Configuration File Locations:

• Windows: C:\Users\\.claude.json or %USERPROFILE%\.claude.json
• macOS: ~/.claude.json
• Linux: ~/.claude.json

Add this configuration:

{
  "mcpServers": {
    "devmind": {
      "command": "npx",
      "args": ["-y", "devmind-mcp@latest"]
    }
  }
}

Using Global Install? Replace with: {"command": "devmind-mcp"}

Step 2: Restart Your MCP Client

Restart Claude Code or your MCP client to load DevMind.

Step 3: Try Your First Command

In your AI assistant, try:

> "Use semantic_search to find information about authentication"

Done! DevMind is now enhancing your AI with persistent memory.

Next Steps

• Read [Usage Guide](#usage-guide) for available tools
• Check [Configuration](#configuration) for smart recording rules
• Explore [Use Cases](#use-cases) for inspiration

---

How AI Should Use DevMind

Follow these steps for each development session:

1. Session Initialization

• Start by calling get_current_session or let it auto-create
• Say "Checking memory..." and call list_contexts(limit: 5)

1. During Development

• CRITICAL: Call record_context IMMEDIATELY after editing files
• Use type: bugfix, featureadd, code_modify based on work type
• Content MUST be in project's language (Chinese/English)

1. Before Completing Tasks

• Record before saying "done" or "complete"
• Use files_changed for multi-file modifications

1. When User Asks About History

• Use semantic_search for intelligent queries
• Use list_contexts for chronological browsing
• Use get_context to view full details

---

Usage Guide

MCP Tools Quick Reference

DevMind provides 15 powerful tools for your AI assistant:

Codebase Indexing

| Tool | Purpose | Example Use | |--------------------------|--------------------------------------------|-------------------------------| | codebase | Index project files for semantic search | Index entire codebase | | delete_codebase_index | Remove codebase index for a project | Clean up indexed files |

Note: The codebase tool supports .gitignore and .augmentignore exclusion patterns. It also includes built-in defaults that automatically exclude common directories like node_modules/, dist/, build/, .git/, and many more.

Project Management

| Tool | Purpose | Example Use | |--------------------------|--------------------------------------------|-------------------------------| | list_projects | [RECOMMENDED] List all projects with stats | Overview tracked projects | | cleanup_empty_projects | Clean up empty projects with no memories | Remove unused project records |

Session Management

| Tool | Purpose | Example Use | |-----------------------|---------------------------------|-------------------------| | create_session | Start new development session | Beginning a new feature | | get_current_session | Get active session info | Check current context | | end_session | End development session | Finishing work | | delete_session | Delete session and all contexts | Clean up old sessions |

Note: DevMind automatically manages one main session per project. Sessions are created automatically when needed and reactivated across conversations.

Context Operations

|| Tool | Purpose | Example Use | ||------------------|-----------------------------|------------------------| || record_context | Store development context | Save bug fix solution | || list_contexts | List all contexts | Review project history | || delete_context | Delete specific context | Remove outdated info | || update_context | Update context content/tags | Refine documentation |

Search & Discovery

|| Tool | Purpose | Example Use | ||-------------------|-------------------------------|------------------------------| || semantic_search | AI-powered semantic search | Find related implementations | || get_context | Get context(s) by ID(s) | View full memory content |

Note: Embeddings are auto-generated on record_context. Quality scores auto-update every 24h during searches (lazy loading).

Visualization

| Tool | Purpose | Example Use | |-----------------------|-------------------------------------------|-----------------------------------------------------------| | export_memory_graph | Export interactive timeline graph (v1.19) | Visualize memory in vertical timeline with 6 type columns |

New in v1.19: Memory graph features a clean vertical timeline layout with fixed node positioning and optimized performance.

ContextEngine (New in v2.4.9)

ContextEngine is a powerful codebase indexing system that automatically scans and indexes your entire project for intelligent search and code discovery.

Key Features

• Comprehensive File Scanning - Recursively scans all project files with support for 20+ programming languages
• Smart Filtering - Automatically applies ignore rules to exclude irrelevant files and directories
• Incremental Indexing - Only re-indexes changed files based on SHA-256 hashes for efficiency
• Independent Storage - Uses separate file_index table to avoid polluting development memory
• Binary File Detection - Automatically skips binary files (images, executables, etc.)
• Language Detection - Automatically detects and categorizes programming languages

How It Works

Project Directory
    │
    ▼
┌─────────────────────┐
│   FileScanner       │  1. Recursively scan all files
│                     │  2. Apply ignore rules
│   - Recursive scan  │  3. Detect file types
│   - File filtering  │  4. Skip binaries
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  IgnoreProcessor    │  1. Apply ignore rules
│                     │  2. Filter files
│   - Smart filtering │
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Database Storage   │  1. Store in file_index table
│                     │  2. Generate file hashes
│   - file_index      │  3. Index for search
│   - SHA-256 hashes  │
└─────────────────────┘

Default Exclusions

ContextEngine automatically excludes common directories and files:

• Version Control: .git/, .svn/, .hg/
• Dependencies: node_modules/, vendor/, .composer/
• Build Outputs: dist/, build/, out/, .next/, .vite/, target/
• Logs & Temp: *.log, *.tmp, *.temp, .DS_Store, Thumbs.db
• IDE Files: .vscode/, .idea/, *.swp
• Coverage: coverage/, .nyc_output/, .pytest_cache/

Usage Example

// Index your entire codebase
await codebase({
  project_path: "/path/to/my-project"
});

// Force re-index all files
await codebase({
  project_path: "/path/to/my-project",
  force_reindex: true
});

// After indexing, use semantic_search t

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JochenYang](https://github.com/JochenYang)
- **Source:** [JochenYang/Devmind-MCP](https://github.com/JochenYang/Devmind-MCP)
- **License:** MIT
- **Homepage:** https://jochenyang.github.io/devmind-docs/

Install and usage instructions live in the source repository linked above.