关键词

个人知识管理文档智能助手AI文件搜索邮件归档检索本地RAG

项目简介

Ragdex是一个个人知识管理系统，能够自动索引您电脑上的文档（PDF、Word、EPUB等）和电子邮件（Apple Mail、Outlook），并将其转化为一个可供AI助手（如Claude Desktop）进行语义搜索、问答、总结和比较的知识库。它通过Model Context Protocol (MCP) 与AI客户端通信，提供结构化的上下文信息和工具。所有数据处理均在本地进行，确保您的隐私安全。

主要功能点

  • 通用文档支持: 自动处理多种文档格式，包括PDF (支持OCR识别扫描文档)、Word、PowerPoint、Excel、EPUB、MOBI、AZW、纯文本和Markdown文件，无需手动分类。
  • 智能邮件处理: 支持索引Apple Mail和Outlook邮箱存档，智能过滤营销邮件和垃圾邮件，处理附件，并重建邮件线程。此功能默认禁用，需手动开启以保护隐私。
  • 高级搜索与RAG: 利用先进的向量嵌入技术实现语义搜索，提供跨文档的深入洞察，并生成上下文感知的准确响应。
  • 丰富的AI工具: 提供超过17个专用MCP工具，允许AI助手执行如语义搜索、文档视角比较、图书馆统计、书籍总结、引文提取、问答等多种操作。
  • 实时监控仪表盘: 提供一个本地的Web仪表盘 (默认地址为'http://localhost:8888')，用于实时监控索引进度、查看文档和邮件统计、管理处理失败的文档，并提供搜索界面。
  • 本地隐私保护: 所有文档和邮件数据都在您的本地计算机上进行处理和存储，不会上传到任何云服务，最大限度地保护您的个人数据隐私。

安装步骤

  1. 环境准备:

    • 操作系统: macOS 10.15+ 或 Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)。Windows目前不支持。
    • Python: 3.10-3.12 版本 (不兼容3.13)。
    • 内存: 至少8GB RAM (推荐16GB)。
    • 存储空间: 至少5GB可用磁盘空间。
    • MCP客户端: 需要安装Claude Desktop（免费或付费）。
    • macOS用户额外工具: 需要安装 Xcode Command Line Tools ('xcode-select --install') 和 Homebrew ('/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"')。
    • Python包管理器 (推荐): 安装 'uv'，它比 'pip' 更快更可靠。打开终端并运行： 
      curl -LsSf https://astral.sh/uv/install.sh | sh
      安装完成后，请关闭并重新打开终端。

  2. 安装Ragdex:

    • 在终端中执行以下命令（推荐使用'uv'）： 
      uv venv ~/ragdex_env
uv pip install --python ~/ragdex_env/bin/python ragdex
    • 注意: 首次运行会下载约2GB的AI模型，此过程可能需要5-10分钟，具体取决于您的网络速度。

  3. 设置后台服务:

    • 运行交互式安装脚本： 
      curl -O https://raw.githubusercontent.com/hpoliset/ragdex/main/install_ragdex_services.sh
chmod +x install_ragdex_services.sh
./install_ragdex_services.sh
    • 此脚本会引导您配置文档路径、设置后台索引进程和Web仪表盘，并最终显示一段JSON格式的MCP配置信息。请务必复制此JSON配置，它将用于下一步配置Claude Desktop。

服务器配置

MCP客户端（如Claude Desktop）需要以下JSON格式配置来连接Ragdex服务器。请将安装步骤中获得的配置信息填入您的Claude Desktop配置文件。

{
  "mcpServers": {
    "ragdex": {
      "command": "/Users/yourname/ragdex_env/bin/ragdex-mcp",
      "env": {
        "PYTHONUNBUFFERED": "1",
        "CHROMA_TELEMETRY": "false",
        "PERSONAL_LIBRARY_DOC_PATH": "/Users/yourname/Documents",
        "PERSONAL_LIBRARY_DB_PATH": "/Users/yourname/.ragdex/chroma_db",
        "PERSONAL_LIBRARY_LOGS_PATH": "/Users/yourname/.ragdex/logs",
        "PERSONAL_LIBRARY_INDEX_EMAILS": "true",
        "PERSONAL_LIBRARY_EMAIL_SOURCES": "apple_mail,outlook_local",
        "PERSONAL_LIBRARY_EMAIL_MAX_AGE_DAYS": "365",
        "PERSONAL_LIBRARY_EMAIL_EXCLUDED_FOLDERS": "Spam,Junk,Trash"
      }
    }
  }
}

配置说明:

  • '"ragdex"': 这是您的MCP服务器的名称，您可以根据需要自定义。
  • '"command"': 启动Ragdex MCP服务器的可执行文件路径。
    • 重要提示: 请务必将其替换为您系统中'ragdex-mcp'的实际绝对路径。通常位于您的Python虚拟环境的'bin'目录下，例如 '/Users/yourname/ragdex_env/bin/ragdex-mcp'。
  • '"env"': 环境变量配置，用于控制Ragdex的行为。请根据您的需求调整这些值：
    • '"PYTHONUNBUFFERED": "1"': 确保Python的输出是不缓冲的，这有助于实时日志查看。
    • '"CHROMA_TELEMETRY": "false"': 禁用Ragdex内部使用的向量数据库ChromaDB的遥测数据收集。
    • '"PERSONAL_LIBRARY_DOC_PATH"': 您的个人文档库所在目录的绝对路径。Ragdex将扫描此目录及其子目录以索引文件。例如：'/Users/yourname/Documents'。
    • '"PERSONAL_LIBRARY_DB_PATH"': Ragdex存储其数据库文件（如向量数据库和索引状态）的目录路径。例如：'/Users/yourname/.ragdex/chroma_db'。
    • '"PERSONAL_LIBRARY_LOGS_PATH"': Ragdex存储其日志文件的目录路径。例如：'/Users/yourname/.ragdex/logs'。
    • '"PERSONAL_LIBRARY_INDEX_EMAILS": "true"': (可选) 如果您希望Ragdex索引您的邮件，请将此值设置为'"true"'。默认是禁用状态。
    • '"PERSONAL_LIBRARY_EMAIL_SOURCES": "apple_mail,outlook_local"': (可选) 当邮件索引启用时，指定要索引的邮件来源。可选项包括'apple_mail'和/或'outlook_local'。
    • '"PERSONAL_LIBRARY_EMAIL_MAX_AGE_DAYS": "365"': (可选) 邮件索引时，仅索引过去指定天数内的邮件。
    • '"PERSONAL_LIBRARY_EMAIL_EXCLUDED_FOLDERS": "Spam,Junk,Trash"': (可选) 邮件索引时，要排除的邮件文件夹列表，多个文件夹用逗号分隔。

如何配置到Claude Desktop:

  1. 复制您通过Ragdex安装脚本获得的JSON配置（或参照上述示例并修改路径）。
  2. 打开Claude Desktop的配置文件。在macOS上，通常位于 '~/Library/Application Support/Claude/claude_desktop_config.json'。
  3. 将配置粘贴到现有的'"mcpServers"'部分。如果您已经配置了其他MCP服务器，请确保将Ragdex的配置合并到现有结构中，避免覆盖。
  4. 重启Claude Desktop（在macOS上，务必按'Cmd+Q'完全退出应用程序，然后重新打开）。

基本使用方法

  1. 验证Ragdex安装和运行:

    • 在终端中运行 '~/ragdex_env/bin/ragdex --version'，检查Ragdex的版本信息。
    • 运行 'launchctl list | grep ragdex' (macOS) 或 'systemctl status ragdex' (Linux，如果配置为systemd服务) 检查Ragdex的后台服务是否正在运行。
    • 在浏览器中访问 'http://localhost:8888'，查看Ragdex的Web仪表盘，监控索引进度和文档统计。
    • 在重启Claude Desktop后，尝试询问：“Can you check my library stats?” (你能帮我检查图书馆统计数据吗？) 如果Claude能回复您的文档和邮件统计信息，则表示连接成功。

  2. 向Claude提问，查询您的知识库: 一旦Ragdex配置并成功运行，您就可以在Claude Desktop中直接使用自然语言向您的个人知识库提问。Claude将自动利用Ragdex提供的工具和上下文信息来回答您的问题。

    以下是一些您可以尝试的例子：

    • "Search my library for information about machine learning" (搜索我的图书馆中关于机器学习的信息)
    • "Compare perspectives on climate change across my documents" (比较我的文档中关于气候变化的观点)
    • "Summarize the main themes in my recent emails" (总结我最近邮件中的主要主题)
    • "Find all documents mentioning Python programming" (找到所有提及Python编程的文档)
    • "What meetings did I have last month?" (我上个月有什么会议？- 如果启用了邮件索引，此功能将从您的邮件中提取信息。)

Ragdex将自动处理您的请求，通过其索引的文档和邮件提供相关信息，极大地扩展了AI助手获取和理解您本地上下文的能力。

信息

分类

数据库与文件

访问项目