# DevMind MCP

<div align="center">

[![npm version](https://img.shields.io/npm/v/devmind-mcp.svg)](https://www.npmjs.com/package/devmind-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
[![Downloads](https://img.shields.io/npm/dm/devmind-mcp.svg)](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)

</div>

---

## 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\<YourUsername>\.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 to query
const results = await semantic_search({
  query: "How is authentication implemented?",
  project_path: "/path/to/my-project"
});
```

#### Integration with Semantic Search

Once indexed, ContextEngine files are automatically included in `semantic_search` results alongside development memory contexts. This enables AI assistants to:

- Find specific implementations across your codebase
- Understand how different parts of your project work together
- Retrieve code patterns and examples from your actual files
- Answer questions about your project's architecture

### Usage Examples

#### Store Context Information

```typescript
// Store development context
await record_context({
  content: "Implemented user authentication using JWT tokens with refresh token support",
  type: "implementation",
  tags: ["auth", "jwt", "security", "api"]
});
```

#### Search and Retrieve

```typescript
// Find relevant contexts
const results = await semantic_search({
  query: "How did we implement authentication?",
  limit: 10
});
```

#### Update Existing Context

```typescript
// Update context with new information
await update_context(contextId, {
  content: "Updated authentication to support OAuth2 and SAML",
  tags: ["auth", "jwt", "oauth2", "saml", "security"]
});
```

#### Contextual Search

```typescript
// Search within specific timeframe
const results = await semantic_search({
  query: "database optimization",
  timeRange: { days: 7 }
});
```



---

## Configuration

### Basic Configuration (Optional)

DevMind works out of the box with sensible defaults. Configuration is **completely optional**.

If you want to customize behavior, create `.devmind.json` in your project root:

```json
{
  "database_path": "~/.devmind/memory.db",
  "quality_threshold": 0.3,
  "embedding_model": "local",
  "auto_save_interval": 30000,
  "ignored_patterns": [
    "node_modules/**",
    ".git/**",
    "dist/**",
    "build/**"
  ],
  "included_extensions": [
    ".js",
    ".ts",
    ".py",
    ".go"
  ]
}
```

### Configuration Options

| Option               | Type     | Default                  | Description                              |
|----------------------|----------|--------------------------|------------------------------------------|
| `database_path`      | string   | `~/.devmind/memory.db`   | SQLite database file location            |
| `quality_threshold`  | number   | `0.3`                    | Minimum quality score for context storage|
| `embedding_model`    | string   | `"local"`                | Embedding model for vector search        |
| `auto_save_interval` | number   | `30000` (30 seconds)     | Auto-save interval in milliseconds       |
| `ignored_patterns`   | string[] | See example above        | Glob patterns to ignore                  |
| `included_extensions`| string[] | See example above        | File extensions to include               |

### Recommended System Prompt Configuration

To ensure AI assistants automatically record development context, add this to your system prompt configuration (e.g., Kiro steering files, Claude Desktop config):

```markdown
## Core Responsibility

AI assistants should immediately call the record_context tool after each code edit to ensure all changes are properly recorded in the project memory.
```

**Why This Is Necessary:**
- MCP tools cannot force AI behavior - system prompts are required
- This ensures 100% recording reliability across all development tasks
- Works with any MCP-compatible client (Kiro, Claude code, Cursor, etc.)



### Full MCP Configuration Example

**With NPX (Recommended):**

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

**With Global Installation:**

```json
{
  "mcpServers": {
    "devmind": {
      "command": "devmind-mcp"
    }
  }
}
```

> **Important**: Restart your MCP client after configuration changes.

---

## API Reference

### Core Methods

#### `record_context(context: ContextData): Promise<string>`

Store new context information.

**Parameters:**

- `content` (string) - Main content text
- `type` (string) - Content type: `solution`, `code`, `error`, `documentation`, `test`, `configuration`
- `tags` (string[]) - Associated tags
- `metadata` (object) - Additional metadata

**Returns:** Context ID string

**Example:**

```typescript
const id = await record_context({
  content: "Fixed memory leak in WebSocket connection handler",
  type: "solution",
  tags: ["websocket", "memory-leak", "bug-fix"]
});
```

---

#### `codebase(options: CodebaseOptions): Promise<IndexResult>`

Index project files into memory for semantic search.

**Parameters:**

- `project_path` (string) - Path to the project directory to index
- `force_reindex` (boolean) - Force reindex all files (default: false)

**Returns:** Index result with statistics

**Example:**

```typescript
// Index a project
const result = await codebase({
  project_path: "./my-project",
  force_reindex: true
});
```

---

#### `delete_codebase_index(options: DeleteIndexOptions): Promise<DeleteResult>`

Delete codebase index for a project.

**Parameters:**

- `project_path` (string) - Path to the project directory to delete index for

**Returns:** Delete result with statistics

**Example:**

```typescript
// Delete project index
const result = await delete_codebase_index({
  project_path: "./my-project"
});
```

---

#### `semantic_search(query: SearchQuery): Promise<Context[]>`

Search for relevant contexts using semantic understanding.

**Parameters:**

- `query` (string) - Search query
- `limit` (number) - Maximum results (default: 20)
- `type` (string) - Filter by content type
- `tags` (string[]) - Filter by tags
- `timeRange` (object) - Time range filter: `{ days: 7 }`

**Returns:** Array of matching contexts

**Example:**

```typescript
const results = await semantic_search({
  query: "authentication implementation",
  limit: 10,
  type: "implementation"
});
```

---


#### `update_context(id: string, updates: Partial<ContextData>): Promise<boolean>`

Update existing context.

**Example:**

```typescript
await update_context(contextId, {
  tags: ["websocket", "memory-leak", "bug-fix", "resolved"]
});
```

---

#### `delete_context(id: string): Promise<boolean>`

Delete context by ID.

---

#### `cleanup_empty_projects(options?: CleanupOptions): Promise<CleanupResult>`

Clean up empty project records that have no associated memories.

**Parameters:**

- `dry_run` (boolean) - Preview projects to be deleted without actually deleting (default: true)

**Returns:** Cleanup result object

**Example:**

```typescript
// Preview empty projects to be deleted
const preview = await cleanup_empty_projects({ dry_run: true });
console.log(`Will delete ${preview.deleted_count} empty projects`);

// Actually delete empty projects
const result = await cleanup_empty_projects({ dry_run: false });
console.log(`Deleted ${result.deleted_count} empty projects`);
```

---

### Utility Methods

#### `cleanup(): Promise<void>`
Perform database cleanup and optimization.

#### `stats(): Promise<DatabaseStats>`
Get database statistics and health information.

#### `export(format: 'json' | 'csv'): Promise<string>`
Export all contexts to specified format.

---

## Use Cases

### Software Development
- Track implementation decisions and technical choices
- Maintain context across development sessions
- Store and retrieve code patterns and snippets
- Document architectural decisions with rationale

### Research & Learning
- Accumulate knowledge from multiple sources
- Build connections between related concepts
- Maintain research context over weeks or months
- Create searchable personal knowledge bases

### Project Management
- Track project evolution and key decisions
- Maintain context across team meetings
- Store project-related insights and lessons
- Document post-mortems and retrospectives

### AI Assistant Enhancement
- Provide persistent memory for AI conversations
- Enable context-aware responses based on history
- Maintain user preferences and project specifics
- Support long-term relationship building with AI

---

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/JochenYang/Devmind.git
cd Devmind

# Install dependencies
npm install

# Development mode with watch
npm run dev

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint
```


## Contributing

We welcome contributions to DevMind MCP! Please follow these steps:

### Development Process

1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
3. **Commit** your changes: `git commit -m 'Add amazing feature'`
4. **Push** to branch: `git push origin feature/amazing-feature`
5. **Open** a Pull Request

### Code Standards

- Follow TypeScript best practices
- Maintain test coverage above 80%
- Use conventional commit messages
- Document all public APIs
- Add tests for new features

---

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

## 🔗 Support

- **Issues**: [GitHub Issues](https://github.com/JochenYang/Devmind/issues)
- **Discussions**: [GitHub Discussions](https://github.com/JochenYang/Devmind/discussions)
- **NPM Package**: [devmind-mcp](https://www.npmjs.com/package/devmind-mcp)

---

<div align="center">

**DevMind MCP** - Intelligent context-aware memory for AI assistants

Made with ❤️ by [Jochen](https://github.com/JochenYang)

</div>