Backstory: search your data exports locally

Backstory

在一个地方搜索所有数据导出文件。它完全在你自己的电脑上运行，你的任何数据都不会离开电脑。

你可以从 Google、Telegram 和大多数其他服务下载自己的数据。问题在于下载得到的内容：一堆几乎无法阅读的 JSON 和 CSV 文件。Backstory 会将这些导出文件导入一个本地数据库，让你一次搜索所有数据。你可以通过命令行搜索，也可以通过 MCP 将它连接到 AI 助手。

数据不会发送到云端。你的数据会保存在自己电脑上的 SQLite 文件中。这正是这个工具存在的主要原因，因为这些是你最私人的数据。

目录

• 功能介绍
• 数据来源
• 快速开始
• 通过 AI Agent 使用
• 工作原理
• 命令
• 搜索质量
• MCP 工具
• 隐私
• 许可证

功能介绍

• 导入来自 Google、Telegram、Spotify 和 Instagram 的数据导出文件。
• 将所有内容作为一条时间线，按含义或关键词搜索。
• 在不同数据来源中匹配同一个人或地点。
• 回答 AI Agent 的问题，例如“我上次什么时候给 Sarah 发消息聊晚餐的？”。
• 展示如何导出数据，并在下载完成后自动导入。
• 生成基准测试报告，让你了解搜索的实际效果。

数据来源

每种数据来源都由一个小型适配器负责将导出文件转换为事件。以下是目前支持的来源及其导入内容。

来源	导入内容	导出方式
Google Takeout	搜索记录、YouTube 历史记录、已保存地点、位置记录	backstory fetch google
Telegram	消息、联系人	backstory fetch telegram
Spotify	收听记录、播客、搜索记录	backstory fetch spotify
Instagram	私信、帖子、评论、搜索记录	backstory fetch instagram

添加新来源只需编写一个适配器，其他部分无需更改。

快速开始

你需要 .NET 10 SDK。它可在 Linux、macOS 和 Windows 上运行。

安装为全局工具：

dotnet tool install -g Backstory

或者现在就从源代码构建：

git clone https://github.com/magna-nz/backstory && cd backstory
dotnet build Backstory.slnx -c Release

导入你的数据。Backstory 会告诉你如何导出数据，并在文件下载到 Downloads 文件夹后为你导入：

backstory fetch google      # or: telegram
backstory watch

你也可以自行指定文件或 zip 文件。Takeout 压缩包会自动解压，包括多部分压缩包：

backstory import ~/Downloads/takeout-20240101.zip
backstory import ~/Downloads/telegram-export/result.json

然后进行搜索：

backstory search "dinner plans with sarah"
backstory search "trip to japan" --from 2023-01-01

通过 AI Agent 使用

Backstory 支持 MCP，因此任何 MCP 客户端（Claude 等）都能查询你的时间线。启动服务：

backstory serve

用一条命令注册：

claude mcp add backstory -- backstory serve

或者直接将其添加到 MCP 配置中：

{
  "mcpServers": {
    "backstory": { "command": "backstory", "args": ["serve"] }
  }
}

现在，你可以向 Agent 提问，例如“我在东京查过的那家拉面店叫什么？”，它会搜索你的 Google 和 Telegram 数据并给出答案。

工作原理

每种导出格式都有各自的问题，因此我们为每种格式编写了一个小型适配器，将其转换为统一的数据结构：时间线上的事件，以及事件中提到的人物和地点。此后，所有操作都以相同方式进行。数据存储在 SQLite 中，并使用全文索引搜索关键词、使用向量索引搜索语义。搜索会同时运行这两种索引并合并结果。

flowchart TD
    TG["Telegram<br/>result.json"]:::src
    GT["Google Takeout<br/>JSON / CSV"]:::src

    TG --> AD
    GT --> AD

    AD["Adapters<br/><i>parse and normalize</i>"]:::ingest
    NR["Normalizer<br/><i>events and entities</i>"]:::ingest
    ER["Entity resolution<br/><i>link people and places</i>"]:::ingest
    AD --> NR --> ER

    ER --> FTS[("SQLite + FTS5<br/>timeline, keyword")]:::store
    ER --> VEC[("Vector index<br/>meaning")]:::store

    FTS --> HQ
    VEC --> HQ
    HQ["Search<br/><i>keyword + meaning</i>"]:::query

    HQ --> CLI["CLI"]:::iface
    HQ --> MCP["MCP server"]:::iface

    classDef src fill:#FAECE7,stroke:#993C1D,color:#4A1B0C;
    classDef ingest fill:#EEEDFE,stroke:#534AB7,color:#26215C;
    classDef store fill:#E1F5EE,stroke:#0F6E56,color:#04342C;
    classDef query fill:#E1F5EE,stroke:#0F6E56,color:#04342C;
    classDef iface fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A;

完整的技术说明见 magna-nz.github.io/backstory 和 SPEC.md。

命令

命令	功能
fetch google|telegram|spotify|instagram	说明如何导出数据，并打开相应页面
watch [--dir <path>]	在导出文件下载到 ~/Downloads 时自动导入
import <path>	导入导出文件（文件、文件夹或 Takeout zip）
search "<query>"	搜索时间线。筛选条件：--from --to --source --limit
timeline	按时间顺序列出事件，支持相同的筛选条件
entity "<name>"	查找人物或地点
stats	按来源和类型统计数量，并显示正在使用的嵌入器
serve	运行 MCP 服务
model fetch	下载语义搜索模型（可选，只需下载一次）
eval	运行基准测试

数据库位于 $BACKSTORY_DB，默认路径为 ~/.backstory/backstory.db。

搜索质量

有两种将文本转换为向量的方式，你可以在两者之间切换：

• 哈希（默认）。无需设置，完全离线，根据出现的词语进行匹配。足以满足入门使用。
• ONNX MiniLM。真正的语义搜索，可根据含义进行匹配。运行一次 backstory model fetch（约 90 MB），Backstory 就会自动使用该模型。这样，搜索“日本度假”就能找到提到“飞往东京”的消息。

你可以通过 backstory eval 自行衡量差异。它会加载示例数据并报告两个数字：解析了多少数据，以及正确事件出现在搜索结果前 5 条中的频率。

嵌入器	已解析数据	前 5 条中有正确结果
哈希（默认）	100%	87.5%
ONNX MiniLM	100%	100%

MCP 工具

工具	返回内容
search_timeline	针对自然语言查询排序后的事件
get_events	按 ID 返回完整事件记录，包括指向来源的引用
lookup_entity	按名称查找人物或地点
summarize_period	指定日期范围内的所有事件，供 Agent 总结
list_sources	已导入的来源及各自的事件数量

隐私

所有操作都在本地运行，不会收集遥测数据。Backstory 只有在你运行 backstory model fetch 下载搜索模型时才会连接网络，而且这一步是可选的。你的数据不会离开本机。.gitignore 已配置好，避免数据库或导出文件被意外提交。

许可证

MIT。详见 LICENSE。基于 ModelContextProtocol SDK、ONNX Runtime 和 all-MiniLM-L6-v2 构建。