WeChat 4.x Database Decryptor: Complete Guide to wechat-decrypt

The wechat-decrypt GitHub repository (1.9k stars, 1.3k forks) is a powerful open-source tool that unlocks WeChat 4.x's encrypted local databases across Windows, macOS, and Linux. By scanning live WeChat process memory, it extracts SQLCipher 4 encryption keys and decrypts all 26+ databases including messages, contacts, media, and sessions.

Key Features

• Cross-Platform Support: Windows (admin), Linux (root/CAP_SYS_PTRACE), macOS (Mach VM API)
• Real-Time Monitoring: Web UI with SSE streaming, 100ms latency, inline image previews
• Image Decryption: Supports legacy XOR, V1 (fixed key), V2 (AES-128-ECB from memory)
• Rich Media Parsing: Emoticons, link cards, files, mini-programs, location sharing
• AI Integration: MCP server for Claude AI to query chat history, search messages
• Hidden Message Recovery: Detects truncated session summaries, recovers full threads

How It Works

WeChat 4.x uses SQLCipher 4 (AES-256-CBC + HMAC-SHA512, PBKDF2 256k iterations). Keys are cached in memory as x'<64hex_key><32hex_salt>'. The tool:

1. Scans WeChat process memory for key patterns
2. Validates keys via HMAC on page 1
3. Decrypts all .db files + WAL checkpoints
4. Handles 4MB WAL files via mtime polling

Quick Start

# Windows
python main.py

# Linux
python3 main.py decrypt

Auto-detects WeChat data directory and generates config.json. Web UI launches at http://localhost:5678.

Image Decryption (V2 Format)

For 2025-08+ .dat files (AES-128-ECB + XOR):

# View 2-3 images in WeChat, then:
python find_image_key_monitor.py

AES key auto-saves to config.json. Monitor web UI shows inline previews.

Claude AI Integration

pip install mcp
claude mcp add wechat -- python mcp_server.py

Query tools: get_chat_history(), search_messages(), get_new_messages().

Technical Highlights

• WAL Handling: mtime-based detection, salt-validated frame parsing
• Thread Safety: Per-key locks prevent DB corruption
• Performance: ~70ms decrypt + 30ms poll = 100ms E2E latency
• macOS C Scanner: Compiled binary using Mach VM API

Database Structure

⚠️ Legal Notice

For educational/research use only. Decrypt your own WeChat data and comply with local laws.

This tool represents cutting-edge reverse engineering of modern encrypted messaging apps. Perfect for security researchers, data analysts, and developers building WeChat integrations. Fork, star, and contribute on GitHub!