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

- **Type:** MCP server
- **Install:** `agentstack add mcp-jochenyang-devmind-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JochenYang](https://agentstack.voostack.com/s/jochenyang)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JochenYang](https://github.com/JochenYang)
- **Source:** https://github.com/JochenYang/Devmind-MCP
- **Website:** https://jochenyang.github.io/devmind-docs/

## Install

```sh
agentstack add mcp-jochenyang-devmind-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/JochenYang/Devmind/releases/latest)

---

## 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 (bug_fix, feature_add, 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

```text
┌──────────────────────────────────────────────────────────────┐
│                      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)**

```bash
# 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:**

```json
{
  "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)`

2. **During Development**
   - **CRITICAL**: Call `record_context` IMMEDIATELY after editing files
   - Use type: bug_fix, feature_add, code_modify based on work type
   - Content MUST be in project's language (Chinese/English)

3. **Before Completing Tasks**
   - Record before saying "done" or "complete"
   - Use `files_changed` for multi-file modifications

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

```text
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

```typescript
// 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jochenyang-devmind-mcp
- Seller: https://agentstack.voostack.com/s/jochenyang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.