DevMind MCP

Intelligent context-aware memory system for AI assistants

English | 中文 | 📋 Changelog | 🚀 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
• Quick Start
• Usage Guide
• Configuration
• API Reference
• Use Cases
• Development
• Contributing
• 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

┌──────────────────────────────────────────────────────────────┐
│                      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\<YourUsername>\.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 for available tools
• Check Configuration for smart recording rules
• Explore 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

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

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

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

Update Existing Context

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

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

{
  "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):

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

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

With Global Installation:

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

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:

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

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

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:

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:

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

# 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 file for details.

---

🔗 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• NPM Package: devmind-mcp

---

DevMind MCP - Intelligent context-aware memory for AI assistants

Made with ❤️ by Jochen