{
"markdown": "# Backstory\n\nSearch all your data exports in one place. It runs entirely on your own computer, and nothing ever leaves your PC.\n\n\n\n[](https://github.com/magna-nz/backstory/actions/workflows/ci.yml)\n[](https://www.nuget.org/packages/Backstory)\n[](https://www.nuget.org/packages/Backstory)\n[](https://dotnet.microsoft.com/)\n[](https://modelcontextprotocol.io/)\n[](https://glama.ai/mcp/servers/magna-nz/backstory)\n[](#quick-start)\n[](LICENSE)\n[](https://magna-nz.github.io/backstory/)\n\nYou 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.\n\nNothing 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.\n\n## Contents\n\n- [What it can do](#what-it-can-do)\n- [Sources](#sources)\n- [Quick start](#quick-start)\n- [Use it from an AI agent](#use-it-from-an-ai-agent)\n- [How it works](#how-it-works)\n- [Commands](#commands)\n- [Search quality](#search-quality)\n- [MCP tools](#mcp-tools)\n- [Privacy](#privacy)\n- [License](#license)\n\n## What it can do\n\n- Import exports from Google, Telegram, Spotify, and Instagram.\n- Search everything as one timeline, by meaning or by keyword.\n- Match the same person or place across different sources.\n- Answer questions from an AI agent, like \"when did I last message Sarah about dinner?\".\n- Show you how to export your data, then import it automatically when it finishes downloading.\n- Report a benchmark so you can see how well the search actually works.\n\n## Sources\n\nEach source is a small adapter that turns an export into events. Here is what works today and what each one pulls in.\n\n| Source | What it imports | How to export it |\n|---|---|---|\n| Google Takeout | Search history, YouTube history, saved places, location history | `backstory fetch google` |\n| Telegram | Messages, contacts | `backstory fetch telegram` |\n| Spotify | Listening history, podcasts, searches | `backstory fetch spotify` |\n| Instagram | Direct messages, posts, comments, searches | `backstory fetch instagram` |\n\nAdding a new source means writing one adapter. Nothing else changes.\n\n## Quick start\n\nYou need the .NET 10 SDK. It runs on Linux, macOS, and Windows.\n\nInstall as a global tool:\n\n```bash\ndotnet tool install -g Backstory\n```\n\nOr build from source today:\n\n```bash\ngit clone https://github.com/magna-nz/backstory && cd backstory\ndotnet build Backstory.slnx -c Release\n```\n\nGet your data in. Backstory shows you how to export it, then imports it for you when it lands in your Downloads folder:\n\n```bash\nbackstory fetch google # or: telegram\nbackstory watch\n```\n\nYou can also point it at a file or zip yourself. Takeout zips are unpacked for you, including the multi-part ones:\n\n```bash\nbackstory import ~/Downloads/takeout-20240101.zip\nbackstory import ~/Downloads/telegram-export/result.json\n```\n\nThen search:\n\n```bash\nbackstory search \"dinner plans with sarah\"\nbackstory search \"trip to japan\" --from 2023-01-01\n```\n\n## Use it from an AI agent\n\nBackstory speaks MCP, so any MCP client (Claude and others) can query your timeline. Start the server:\n\n```bash\nbackstory serve\n```\n\nRegister it with one command:\n\n```bash\nclaude mcp add backstory -- backstory serve\n```\n\nOr add it to your MCP config directly:\n\n```json\n{\n \"mcpServers\": {\n \"backstory\": { \"command\": \"backstory\", \"args\": [\"serve\"] }\n }\n}\n```\n\nNow 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.\n\n## How it works\n\nEvery 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.\n\n```mermaid\nflowchart TD\n TG[\"Telegram
result.json\"]:::src\n GT[\"Google Takeout
JSON / CSV\"]:::src\n\n TG --> AD\n GT --> AD\n\n AD[\"Adapters
parse and normalize\"]:::ingest\n NR[\"Normalizer
events and entities\"]:::ingest\n ER[\"Entity resolution
link people and places\"]:::ingest\n AD --> NR --> ER\n\n ER --> FTS[(\"SQLite + FTS5
timeline, keyword\")]:::store\n ER --> VEC[(\"Vector index
meaning\")]:::store\n\n FTS --> HQ\n VEC --> HQ\n HQ[\"Search
keyword + meaning\"]:::query\n\n HQ --> CLI[\"CLI\"]:::iface\n HQ --> MCP[\"MCP server\"]:::iface\n\n classDef src fill:#FAECE7,stroke:#993C1D,color:#4A1B0C;\n classDef ingest fill:#EEEDFE,stroke:#534AB7,color:#26215C;\n classDef store fill:#E1F5EE,stroke:#0F6E56,color:#04342C;\n classDef query fill:#E1F5EE,stroke:#0F6E56,color:#04342C;\n classDef iface fill:#F1EFE8,stroke:#5F5E5A,color:#2C2C2A;\n```\n\nThere is a full technical writeup at [magna-nz.github.io/backstory](https://magna-nz.github.io/backstory/) and in [SPEC.md](SPEC.md).\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `fetch google\\|telegram\\|spotify\\|instagram` | Show how to export your data, and open the page |\n| `watch [--dir ]` | Import exports automatically as they download to `~/Downloads` |\n| `import ` | Import an export (file, folder, or Takeout zip) |\n| `search \"\"` | Search the timeline. Filters: `--from --to --source --limit` |\n| `timeline` | List events in time order, with the same filters |\n| `entity \"\"` | Look up a person or place |\n| `stats` | Counts by source and type, and the embedder in use |\n| `serve` | Run the MCP server |\n| `model fetch` | Download the semantic search model (optional, one time) |\n| `eval` | Run the benchmark |\n\nThe database lives at `$BACKSTORY_DB`, or `~/.backstory/backstory.db` by default.\n\n## Search quality\n\nThere are two ways to turn text into vectors, and you can switch between them:\n\n- Hashing (default). No setup, fully offline, matches on the words that appear. Good enough to get started.\n- 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\".\n\nYou 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.\n\n| Embedder | Data parsed | Right answer in top 5 |\n|---|---|---|\n| Hashing (default) | 100% | 87.5% |\n| ONNX MiniLM | 100% | 100% |\n\n## MCP tools\n\n| Tool | What it returns |\n|---|---|\n| `search_timeline` | Ranked events for a natural-language query |\n| `get_events` | Full event records by id, including a pointer to the source |\n| `lookup_entity` | A person or place by name |\n| `summarize_period` | Every event in a date range, for the agent to summarize |\n| `list_sources` | The sources imported and how many events each has |\n\n## Privacy\n\nEverything 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.\n\n## License\n\nMIT. See [LICENSE](LICENSE). Built on the [ModelContextProtocol SDK](https://github.com/modelcontextprotocol/csharp-sdk), [ONNX Runtime](https://github.com/microsoft/onnxruntime), and [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2).\n",
"bytes": 8531,
"sha": "acb876cd5ba68953f3d5d6b99d9574bee3e63e005af369632696a3d2b2c09ef0",
"repo_slug": "magna-nz/backstory",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_magna_nz_backstory_83f9d74c/readme"
}