ChatGPT History to Markdown

When to use it

Find earlier decisions, code examples, and ideas across your exported conversations. Browse readable Markdown and retrieve matching conversation chunks with hybrid search.

Get started

Requirements

Python with venv and SQLite FTS5 support, Git, and a ChatGPT export. The vector helper installs sentence-transformers and downloads an embedding model. Use a current Python version supported by those dependencies.

git clone --branch feature/hybrid-search https://github.com/taylorparsons/chatgpt-history-to-markdown.git
cd chatgpt-history-to-markdown
# Extract your export here first:
# chatgpt-history-source/conversations.json
bash run_with_vectors.sh --no-mermaid --serve --open

How to use

1. Export your ChatGPT data and extract conversations.json and its attachments into chatgpt-history-source/.
2. Run the vector helper above. It creates a virtual environment, installs dependencies, converts the archive, and builds the search index.
3. Open the local viewer at http://127.0.0.1:8000. Search in hybrid, keyword, or vector mode; filter by role, date, and title or body.
4. Open a matching conversation and browse its Markdown and attachments. To browse an existing archive later, run bash serve.sh --open.
5. Keep exports, generated Markdown, and search indexes private. The viewer renders PlantUML through a configurable external server; diagram content is sent there.

Under the hood

Taylor contributed vector search to this fork of rawpurplesmurf/chatgpt-history-to-markdown. The contribution is on feature/hybrid-search; main contains the original converter without the search viewer. The branch combines SQLite FTS5 keyword retrieval with optional sentence-transformers vectors, uses overlapping text chunks, and falls back to a hashing embedder when the transformer backend is unavailable. Index files are search.sqlite, search_meta.json, and search_embeddings.bin in markdown/. Indexing is opt-in; run_with_vectors.sh enables it. The first transformer model load can take time.

Open source recognition

Meet the maintainers and contributors, view dependency sources, and read original license notices ↗

Source documentation

• README.md
• search_index.py
• run_with_vectors.sh
• serve.py
• Original project by rawpurplesmurf

Setup instructions are taken from the public repository. Dependencies, API availability, and scripts can change; check the source README for updates.