# MeshDB

**Distributed full-text search engine with LLM conversation indexing.**

Part of [MeshPOP](https://mpop.dev) — Layer 4 (Search)

## Features

- **Full-text search** with SQLite FTS5 across all servers (BM25 ranking, snippets)
- **LLM Conversation Indexing** — indexes Q&A from Claude Code, Cowork, Cursor, ChatGPT, Gemini across all 14 servers
- **Multi-server discovery** — automatically finds and indexes conversations on remote servers via vssh protocol
- **MCP-driven discover** — connected AIs can register their own conversation storage paths
- **Semantic search** with vector embeddings (ChromaDB)
- **Auto-indexing** with file change detection (hash-based skip)

## Install

```bash
pip install meshpop-db
```

## Usage

### Document Search
```bash
meshdb search "nginx config"         # Full-text search across all servers
meshdb find "config.json"            # Find files by name
meshdb semantic "how to deploy"      # Semantic vector search
meshdb status                        # Database status
```

### Conversation Search
```bash
# Index local conversations (Claude Code, Cursor, ChatGPT, Gemini)
meshdb-conv index

# Index local + all remote servers (d1, d2, g1, g2, g3)
meshdb-conv index --remote

# Search across all indexed AI conversations
meshdb-conv search "wireguard setup"
meshdb-conv search "PyPI upload" --source claude --project MeshPOP

# Show what conversation files exist on this machine
meshdb-conv discover

# Status — shows chunks by source, server, project
meshdb-conv status
```

### JSON Agent Protocol (for remote vssh calls)
```bash
meshdb-conv json discover           # List discovered session files as JSON
meshdb-conv json chunks <filepath>  # Parse file into Q&A chunks as JSON
meshdb-conv json search <query>     # Search and return JSON
meshdb-conv json status             # Stats as JSON
```

## MCP Tools

Add to Claude Desktop / Claude Code config:

```json
{
  "mcpServers": {
    "meshdb": {
      "command": "python3",
      "args": ["/path/to/meshdb-mcp-server.py"]
    }
  }
}
```

Available tools:

| Tool | Description |
|------|-------------|
| `meshdb_search` | Full-text search across all servers (244K+ files) |
| `meshdb_find` | Find files by filename |
| `meshdb_read` | Read indexed file content |
| `meshdb_conversations` | Search LLM conversations (Claude, Cursor, ChatGPT, Gemini) |
| `meshdb_conv_read` | Read full Q&A chunk |
| `meshdb_conv_discover` | Discover/register conversation sources; trigger indexing |
| `meshdb_semantic` | Semantic code search via ChromaDB |
| `meshdb_status` | Database status across all servers |

## Architecture

```
m1 (macOS) ─── direct SQLite ─── meshdb.db (central)
  │
  ├── vssh ──→ d2: json discover → json chunks → insert
  ├── vssh ──→ g1: json discover → json chunks → insert
  ├── vssh ──→ g2: json discover → json chunks → insert
  ├── vssh ──→ g3: json discover → json chunks → insert
  └── vssh ──→ d1: json discover → json chunks → insert
```

**Conversation sources discovered automatically:**

| Source | Format | Path |
|--------|--------|------|
| Claude Code | JSONL | `~/.claude/projects/**/*.jsonl` |
| Cowork | JSONL | `~/Library/.../local-agent-mode-sessions/**/*.jsonl` |
| Cursor | SQLite | `~/.config/Cursor/User/workspaceStorage/*/state.vscdb` |
| ChatGPT | JSON | `~/Downloads/chatgpt_export/conversations.json` |
| Gemini | JSONL/JSON | `~/.gemini/history/**/*` |

**MCP-driven discovery:** Connected AIs can register new sources via `meshdb_conv_discover` tool — no code changes needed.

## Current Stats

- **34,500+ Q&A chunks** indexed across 7 servers
- **1,589 unique sessions** from Claude Code, Cowork, Cursor
- **Coverage:** 2025-12 to 2026-03
- **Indexing speed:** ~17s for 231 remote files across 5 servers

## Links

- Main project: [github.com/meshpop/mpop](https://github.com/meshpop/mpop)
- Website: [mpop.dev](https://mpop.dev)
- PyPI: [pypi.org/project/meshpop-db](https://pypi.org/project/meshpop-db/)

## License

Apache-2.0
