Backstory

Search all your data exports in one place. It runs entirely on your own computer, and nothing ever leaves your PC.

<!-- mcp-name: io.github.magna-nz/backstory -->

You can download your data from Google, Telegram, and most other services. The problem is what you get back: a pile of JSON and CSV files that are nearly impossible to read. Backstory pulls those exports into one local database and lets you search across all of them at once. You can search from the command line or connect it to an AI assistant over MCP.

Nothing is sent to the cloud. Your data stays in a SQLite file on your machine. That is the main reason this tool exists, since this is the most personal data you have.

Contents

• What it can do
• Sources
• Quick start
• Use it from an AI agent
• How it works
• Commands
• Search quality
• MCP tools
• Privacy
• License

What it can do

• Import exports from Google, Telegram, Spotify, and Instagram.
• Search everything as one timeline, by meaning or by keyword.
• Match the same person or place across different sources.
• Answer questions from an AI agent, like "when did I last message Sarah about dinner?".
• Show you how to export your data, then import it automatically when it finishes downloading.
• Report a benchmark so you can see how well the search actually works.

Sources

Each source is a small adapter that turns an export into events. Here is what works today and what each one pulls in.

Source	What it imports	How to export it
Google Takeout	Search history, YouTube history, saved places, location history	backstory fetch google
Telegram	Messages, contacts	backstory fetch telegram
Spotify	Listening history, podcasts, searches	backstory fetch spotify
Instagram	Direct messages, posts, comments, searches	backstory fetch instagram

Adding a new source means writing one adapter. Nothing else changes.

Quick start

You need the .NET 10 SDK. It runs on Linux, macOS, and Windows.

Install as a global tool:

dotnet tool install -g Backstory

Or build from source today:

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

Get your data in. Backstory shows you how to export it, then imports it for you when it lands in your Downloads folder:

backstory fetch google      # or: telegram
backstory watch

You can also point it at a file or zip yourself. Takeout zips are unpacked for you, including the multi-part ones:

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

Then search:

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

Use it from an AI agent

Backstory speaks MCP, so any MCP client (Claude and others) can query your timeline. Start the server:

backstory serve

Register it with one command:

claude mcp add backstory -- backstory serve

Or add it to your MCP config directly:

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

Now you can ask the agent things like "what was that ramen place I looked up in Tokyo?" and it searches across both your Google and Telegram data to answer.

How it works

Every export format is messy in its own way, so a small adapter handles each one and converts it into the same shape: events on a timeline, plus the people and places they mention. From there everything works the same. Storage is SQLite with a full-text index for keywords and a vector index for meaning. A search runs both and combines the results.

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;

There is a full technical writeup at magna-nz.github.io/backstory and in SPEC.md.

Commands

Command	What it does
fetch google|telegram|spotify|instagram	Show how to export your data, and open the page
watch [--dir <path>]	Import exports automatically as they download to ~/Downloads
import <path>	Import an export (file, folder, or Takeout zip)
search "<query>"	Search the timeline. Filters: --from --to --source --limit
timeline	List events in time order, with the same filters
entity "<name>"	Look up a person or place
stats	Counts by source and type, and the embedder in use
serve	Run the MCP server
model fetch	Download the semantic search model (optional, one time)
eval	Run the benchmark

The database lives at $BACKSTORY_DB, or ~/.backstory/backstory.db by default.

Search quality

There are two ways to turn text into vectors, and you can switch between them:

• Hashing (default). No setup, fully offline, matches on the words that appear. Good enough to get started.
• ONNX MiniLM. Real semantic search that matches on meaning. Run backstory model fetch once (about 90 MB) and Backstory uses it automatically. This is what lets a search for "japan vacation" find a message about a "flight to Tokyo".

You can measure the difference yourself with backstory eval. It loads sample data and reports two numbers: how much of the data was parsed, and how often the right event shows up in the top five search results.

Embedder	Data parsed	Right answer in top 5
Hashing (default)	100%	87.5%
ONNX MiniLM	100%	100%

MCP tools

Tool	What it returns
search_timeline	Ranked events for a natural-language query
get_events	Full event records by id, including a pointer to the source
lookup_entity	A person or place by name
summarize_period	Every event in a date range, for the agent to summarize
list_sources	The sources imported and how many events each has

Privacy

Everything runs locally and there is no telemetry. The only time Backstory touches the network is when you run backstory model fetch to download the search model, and that step is optional. Your data never leaves your machine. The .gitignore is set up so a database or an export can't be committed by accident.

License

MIT. See LICENSE. Built on the ModelContextProtocol SDK, ONNX Runtime, and all-MiniLM-L6-v2.