Telegram Private Search

电报私人搜索

将您的Telegram历史记录转化为您和您的AI工具的可搜索内存。

telegram-private-search 是本地第一个Kotlin/JVM工具和MCP服务器，它将多年的私人Telegram聊天变成了一个结构化的、可搜索的知识源。

它是为一种非常具体的感觉而构建的：你知道发生了一次对话，你记得它的意思，但你不记得确切的措辞，无法通过正常搜索找到它。

通过这个项目，你的助手可以停止猜测，直接开始查询你当地的Telegram档案。

快速开始

cp .env.example .env
./gradlew test
./gradlew run --console=plain --args='index --limit-per-chat 500'
./gradlew run --args='mcp'

然后将兼容MCP的客户端连接到服务器，并用自然语言查询您的Telegram历史记录。

为什么这很有趣

您的Telegram历史记录通常包含：

• 从未在其他地方写下来的决定
• 非正式项目更新
• 协议、承诺和后续行动
• 旅行计划、地址、链接和建议
• 仅存在于聊天线程内的上下文

这个项目将混乱的、记忆形状的信息转化为MCP兼容客户端可以实际使用的东西。

与其滚动浏览多年的聊天记录并尝试随机关键字，您可以问更高级别的问题，例如：

• “查找我们上次讨论Readian进度的时间”
• “她什么时候提到寄发票的？”
• “显示他在后端被阻止的消息”
• “找到我们比较公寓选择的对话”

它将您的私人Telegram聊天记录索引到本地SQLite数据库中，然后结合本地关键字搜索、近因感知排名和线程扩展，因此模糊的、记忆形状的查询仍然有很好的机会找到正确的信息。

这个MCP服务器是什么

此项目通过MCP服务器公开您的Telegram搜索索引 stdio.

这意味着支持MCP的AI工具可以作为一种功能调用此服务器，而不是手动复制文本。在实践中，这让你的助手可以作为一个结构化的工具搜索你当地的Telegram历史记录，当你用自然语言提问时，返回相关的消息和上下文。

将其视为以下两者之间的桥梁：

• 您本地的Telegram存档
• 为会话回忆而调整的搜索引擎
• MCP兼容助手或客户端

为什么MCP在这里很重要

如果没有MCP，这个项目已经可以作为CLI搜索工具使用。

有了MCP，它就成为了更大的助理工作流程的一部分。您的客户可以将Telegram搜索视为一个真正的工具调用，而不是手动的辅助任务。这使得可以：

• 用自然语言提问，得到有根据的结果
• 在同一助手会话中将Telegram搜索与其他工具结合使用
• 减少幻觉记忆重建
• 保持消息索引在本地，同时仍使其可供AI工具使用

建筑概览

Telegram account
      |
      v
   TDLight client
      |
      v
Message ingestion
      |
      v
Local SQLite index (Room)
      |
      +--> keyword search
      |
      +--> local lexical retrieval
      |
      v
Ranking and result shaping
      |
      +--> CLI search
      |
      +--> MCP server over stdio
              |
              v
      MCP-compatible assistant or client

简而言之：电报消息进来，建立本地索引，本地检索找到相关结果，MCP服务器将该功能暴露给可以说MCP的工具。

为什么它存在

人们很少记得聊天中使用的确切单词。他们记住意图、背景和片段：

• “他最终同意的信息”
• “那次我们计划了这次旅行”
• “关于功能推出的最新更新”

当你记住确切的文本时，传统搜索非常有用。当你记住意义时，它就没那么有帮助了。

telegram-private-search 是为第二种情况而设计的。它有助于从模糊记忆、长时间对话和跨多个聊天的主题转换中恢复消息。

它能做什么

• 使用您自己的Telegram帐户进行身份验证
• 将私人聊天消息索引到本地SQLite数据库中
• 使用本地全文检索和线程扩展进行搜索
• 使用近因感知启发式方法对结果进行排名
• 通过MCP兼容服务器公开搜索
• 作为本地CLI运行，用于索引和直接查询

运作原理

1. 该应用程序使用您自己的API凭据对Telegram进行身份验证。
2. 它从您的帐户读取私人聊天消息。
3. 消息通过Room本地存储在SQLite中。
4. 搜索使用本地关键字匹配、近因感知排名和线程扩展。
5. MCP服务器向外部AI客户端公开该搜索功能。

当前的接收路径侧重于来自主聊天和存档私人聊天的文本消息。

隐私和数据流

此项目将索引、搜索和上下文重建保持在本地，并且只返回您实际要求的对话片段。

• 电报数据被索引到本地数据库中 data/
• 你的 .env 留在当地，永远不应该承诺
• MCP服务器在本地运行 stdio
• search_messages 在返回结果之前，在本地重建扩展的线程上下文
• search_messages 刷新面向最新查询的本地索引，并重用最近的刷新以避免重复导入
• 查询解释仅使用局部启发式方法
• 服务器不调用任何外部LLM或嵌入API
• 您当前的Copilot/AI代理应在调用MCP工具后进行推理

如果你想对模糊内存风格的查询进行更深入的推理，让MCP客户端要求更广泛的本地上下文，并让当前的AI代理分析返回的线程切片。服务器本身保持在本地。

示例用例

当您想要：

• 从队友或朋友那里恢复最后一次具体进度更新
• 在聊天中找到一个非正式的决定
• 追踪某人承诺、推迟、确认或拒绝某事的时间
• 从模糊记忆中搜索对话，而不依赖于精确的措辞
• 允许启用MCP的助手作为工具访问您的Telegram内存

堆栈

• Kotlin/JVM
• 具有MVVM风格表示状态的干净架构
• 带捆绑SQLite的3号房间
• TDLight用于Telegram用户帐户访问
• MCP服务器 stdio

设置

1. 复制 .env.example 到 .env.
2. 从中填写您的Telegram API凭证 https://my.telegram.org.
3. 如果尚未安装OpenSSL 3，请在macOS上安装。
4. 跑 ./gradlew test.
5. 可选设置 TELEGRAM_PHONE_NUMBER 在 .env 跳过第一个登录模式提示。

本地配置示例：

TELEGRAM_API_ID=
TELEGRAM_API_HASH=
TELEGRAM_PHONE_NUMBER=
TELEGRAM_USE_CONSOLE_LOGIN=true
TELEGRAM_SESSION_DIR=data/telegram-session
DATABASE_PATH=data/telegram-search.db

CLI使用情况

构建本地索引：

./gradlew run --console=plain --args='index --limit-per-chat 500'

安装可运行的分发：

./gradlew installDist
./build/install/telegram-private-search/bin/telegram-private-search index --limit-per-chat 500

运行直接搜索：

./gradlew run --args='search "find last message where he reported progress on Readian" --context-before-messages 12 --context-after-messages 12'

MCP使用

启动MCP服务器：

./gradlew run --args='mcp'

运行后，兼容MCP的客户端可以使用服务器的搜索工具查询您的索引电报历史记录。

捆绑的Kotlin MCP stdio传输每行使用一条JSON-RPC消息。它不使用 Content-Length 框架，因此手动烟雾测试应该将换行符分隔的JSON对象写入stdin，并从stdout读取换行符定界的JSON对象。

快速烟雾测试：

python3 - <<'PY'
import json, subprocess

proc = subprocess.Popen(
  ['./build/install/telegram-private-search/bin/telegram-private-search', 'mcp'],
  stdin=subprocess.PIPE,
  stdout=subprocess.PIPE,
  text=True,
  bufsize=1,
)

for message in [
  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}},
  {"jsonrpc":"2.0","method":"notifications/initialized","params":{}},
  {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}},
]:
  proc.stdin.write(json.dumps(message) + "\n")
  proc.stdin.flush()

print(proc.stdout.readline().strip())
print(proc.stdout.readline().strip())

proc.terminate()
proc.wait(timeout=5)
PY

预期的架构是：

• MCP服务器：本地索引、本地搜索、本地线程扩展
• 当前人工智能代理：推理、重新排序、总结、后续调查

search_messages 接受以下可选上下文控件：

• context_before_messages：在每个匹配的锚点周围包含多少条早期消息
• context_after_messages：每个匹配的锚点周围要包含多少条后续消息

两者均默认为 12，因此该工具返回一个本地会话切片，而不是一个孤立的块。将它们设置为 0 如果你只想要锚结果。

当查询要求 最新 消息，MCP服务器在搜索之前刷新本地Telegram索引，以便答案反映最近的聊天活动。重复的最新样式查询会重用最近的刷新，而不是立即启动另一个完整的Telegram导入。

备注

• 第一 index 运行是交互式的，如果 TELEGRAM_USE_CONSOLE_LOGIN=true.
• TDLight日志被减少，以保持登录提示可见。
• 搜索结合了本地关键字过滤、本地启发式、近因感知排名和本地线程扩展。