ChatLab: A Local-First SQL and AI Query Layer for Personal Chat Archives

The Problem: Chat History Is Trapped in Export Files

Most messaging apps give you an export function, but the result is a folder of JSON, HTML, or text files that are painful to search, filter, or analyze. ChatLab addresses this by providing a unified pipeline: it detects the format, streams the data, stores it locally, and then lets you query it with SQL or natural language through AI agents. The intended user is someone with a large personal archive, possibly spanning multiple apps, who wants to find patterns like response times, conversation frequency, or keyword trends. The project explicitly mentions million-message scale, so it targets heavy users, not casual phone owners. The value proposition is that you do not need to write custom parsers for each platform or send your private conversations to a third-party service.

Architecture: Stream Parsing and Shared Core Packages

ChatLab is a pnpm monorepo built on Electron, Vue 3, Nuxt UI, and Tailwind CSS. The core logic lives in shared packages: @openchatlab/core, @openchatlab/node-runtime, and @openchatlab/tools. These are consumed by both the desktop app and the CLI service, which means the command-line interface and the GUI stay in sync. The data flow is described in five stages: format detection, stream parsing, local persistence, SQL + AI query, and visualization. The stream-first approach is a deliberate design choice to keep memory usage low during imports. Instead of loading an entire export into RAM, the parser processes records incrementally. This is important for the million-message claim, because buffering everything would crash most consumer machines. The architecture principles also mention schema-first evolution, meaning all stages share a consistent data model, which should make adding new platforms or features less disruptive.

Getting Started: Desktop Installer or CLI

The easiest path is to download an installer from the official website or GitHub Releases and double-click it. For scripted or headless use, there is a CLI. It requires Node.js 20 or newer. Install it with: npm i chatlab-cli -g. Then start the service with clb web, which launches both an API and a Web UI and auto-opens the browser. Useful flags include --no-open to skip the browser, --headless for API-only mode, and --port to change the default port 3110. You can also set --host and --token for network access control. For persistent operation, clb web --daemon installs a system service on macOS or Linux that auto-starts on login and restarts after crashes. clb status and clb stop manage the service. The README also notes that if Electron throws exceptions during startup, you can try electron-fix with npm install electron-fix -g and then electron-fix start. This is a concrete troubleshooting step, but the README does not explain what kind of exceptions it fixes.

The AI Layer: Agent and Function Calling, Not Hard-Coded Prompts

ChatLab's AI features are built around an agent with function calling. The README mentions 24+ tools that can search, summarize, and analyze chat records with context. The architecture principle is 'composable intelligence': AI is assembled from agent and tool calling, rather than being a single model path. This means the AI can execute SQL queries, retrieve specific messages, or compute statistics, and then use the results to answer a question. For example, you could ask 'How often do I message this contact after midnight?' and the agent would run the appropriate SQL and summarize the output. The local-first principle applies here too: the tool calls operate on the local database. However, the README does not specify which AI models are supported, whether they run locally or require an API key, or how the agent is configured. That is a gap in the documentation. If you plan to use the AI features, you should check the docs for model requirements and privacy implications.

Supported Platforms and the Normalization Challenge

Currently supported platforms are WhatsApp, LINE, QQ, Discord, Instagram, Telegram, iMessage, and Google Chat. Messenger and KakaoTalk are listed as coming next. The key design element is cross-platform normalization: different export formats are mapped into a unified data model. That is what allows you to run the same SQL query across histories from different apps. The hard part is that each platform exports different fields, timestamps, and media references. ChatLab's approach is schema-first, meaning the unified model is defined upfront and each importer translates into it. This is a pragmatic way to handle the mess, but it also means that if a platform changes its export format, the importer must be updated. The README points to a standardized format specification, which is good for reproducibility, but it also means that if your export is not in a recognized format, you may need to convert it manually.

Limitations and Failure Modes

The most obvious limitation is platform coverage. If you use Messenger or KakaoTalk, you are out of luck until those are added. Even for supported platforms, export formats vary by app version and operating system. The README does not list which export variants are accepted, so you might hit an error if your export is not recognized. Another limitation is the AGPL-3.0 license. This is a strong copyleft license. If you modify ChatLab and distribute it, you must release your changes under the same license. That is fine for personal use, but it is a barrier for companies that want to embed it in proprietary products. The README also notes that PRs for new features without prior discussion will be closed, which is a governance constraint if you plan to contribute. On the technical side, while stream parsing is memory-efficient, it still requires local processing power. A million-message import will take time, and the README does not give performance benchmarks. For someone with a modest laptop, the import phase might be slow, and the AI agent queries could also be resource-intensive.

Alternative: Export and Query with Plain SQLite

If you do not need the AI layer or the multi-platform normalization, a simpler alternative is to write your own import script that loads chat exports into SQLite. You would use tools like sqlite3 or a language-specific driver to create tables for messages, senders, and timestamps, then run SQL queries directly. This approach gives you full control over the schema and avoids the AGPL license. The trade-off is that you have to write and maintain parsers for each platform, handle encoding issues, and deal with media files. You also lose the built-in visualization and the AI agent. Another alternative is to use a general-purpose data analysis tool like Jupyter Notebook with pandas, which can handle JSON exports but requires more manual work for large files. The key difference is that ChatLab provides a ready-made pipeline and a consistent query interface across platforms, whereas the DIY route is more flexible but more time-consuming. For someone who only needs to analyze a single platform once, the DIY route might be sufficient. For ongoing analysis of multiple platforms, ChatLab's normalization saves significant effort.

Maintenance and Upgrade Costs

ChatLab is under active development, with releases v0.37.0, v0.36.2, and v0.36.1 pushed in August 2026. The version numbers suggest a pre-1.0 project, so you should expect API changes and potential breaking changes between releases. The monorepo structure with shared packages means that the CLI and desktop app are updated together, which reduces drift but also means that an update to the core could affect both. The README does not describe a migration path for existing databases when upgrading. You will need to check the release notes for each version. The license is AGPL-3.0, which is a legal consideration for anyone who wants to redistribute modified versions. The project also has a clear contribution policy: bug fixes are welcome, but new features require an issue discussion first. This is a signal that the maintainers want to control scope, which can be good for stability but might slow down feature requests. Before adopting ChatLab, verify that the current version supports your platform's export format and that you are comfortable with the upgrade cadence.

Editorial conclusion

Adopt ChatLab if you have large, multi-platform chat exports and want to run SQL queries and AI analysis without uploading data to a cloud service. Skip it if you need Messenger or KakaoTalk support today, or if you require a permissive license for embedding in proprietary software. Before committing, verify that your exact export formats are supported and review the AGPL-3.0 obligations, especially if you plan to modify or redistribute the tool. Confirm that your Node.js version meets the CLI requirement (>= 20) and that your hardware can handle million-message imports, as stream parsing still needs a local machine with enough memory and CPU.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes