Universal AI chat history database. Aggregates conversations from multiple AI tools (ChatGPT, Claude, Gemini, Cursor, Claude Code, etc.) into a single searchable SQLite database.
- Import chat history from multiple sources via pluggable TypeScript adapters
- One-off imports from files or directories with auto-detection
- Full-text search with separate indexes for natural language and code
- Filter by source, workspace, role, and local/remote scope
- Remote sync and search over SSH
- Background service for automatic syncing
- Optional terminal UI (
hstry-tui) for interactive browsing - Incremental adapter parsing with cursor-based batching
- Export conversations to adapter formats (markdown/json, pi, opencode, codex, claude-code, etc.)
- Resume past sessions in any coding agent with cross-format conversion
- Deduplicate conversations and export memories to mmry
- JSON output for scripting and MCP integration
brew tap byteowlz/tap
brew install hstry# Using yay (recommended)
yay -S hstry
# Using paru
paru -S hstry
# Using makepkg (manual)
git clone https://aur.archlinux.org/hstry.git
cd hstry
makepkg -sicargo install --path crates/hstry-cliDownload pre-built binaries from the GitHub Releases page.
Available platforms:
- Linux x86_64 and ARM64
- macOS Intel and Apple Silicon
git clone https://github.com/byteowlz/hstry.git
cd hstry
cargo build --release --workspaceTo install all binaries (CLI, TUI, MCP):
cargo install --path .# Quickstart: scan, add sources, and sync
hstry quickstart
# Install Playwright browsers (web automation)
hstry web install
# Login to a web provider (headful for first login)
hstry web login chatgpt
# Sync web providers (uses saved sessions)
hstry web sync --provider chatgpt
# Note: web sync currently supports ChatGPT (including multiple workspaces).# Claude and Gemini sync support is planned.# Scan for supported chat history sources
hstry scan
# Add a source (auto-detects adapter)
hstry source add ~/.codex/sessions
# Sync all sources
hstry sync
# Control sync concurrency
hstry sync --parallel 2
# Import a one-off export directory
hstry import ~/Downloads/chatgpt-export
# Search your history
hstry search "how to parse JSON"# List recent conversations
hstry list --limit 10
# View a specific conversation
hstry show <conversation-id># Export a conversation to markdown
hstry export --format markdown --conversations <conversation-id> --output ./conversation.md
# Resume a past session in your preferred coding agent
hstry resume --search "JSON parser" --agent pi
# Resume with time filter
hstry resume --after "yesterday" --workspace myproject
# Browse recent and pick interactively
hstry resume --limit 10| Command | Description |
|---|---|
quickstart | Scan known paths, add sources, and sync everything |
web install | Install Playwright browsers for web automation |
web login | Login to a web provider and store session state |
web sync | Sync web providers and import chats |
web status | Show web login and sync status |
scan | Detect chat history sources on the system |
sync | Import conversations from all configured sources in parallel (resets cursor if source is empty) |
import <path> | One-off import with auto-detected adapter |
search <query> | Full-text search across all messages |
index | Build or refresh the search index |
list | List conversations with optional filters (workspace uses substring match) |
show <id> | Display a conversation with all messages |
export | Export conversations to markdown/json or adapter format |
resume | Resume a past session in a coding agent (pi, claude-code, codex, etc.) |
dedup | Deduplicate conversations in the database |
source add/list/remove | Manage import sources |
adapters list/add/enable/disable | Manage adapters |
adapters repo ... | Manage adapter repositories (git/archive/local) |
remote add/list/remove/test/fetch/sync/status | Manage remote hosts and sync |
Adapter installs are version-pinned to the hstry binary. Run hstry adapters update
whenever you upgrade, and the CLI will refuse to sync if adapter manifests do not
match the current hstry version.
| service enable/disable/start/run/restart/stop/status | Control background sync service |
| config show/path/edit | Manage configuration |
| stats | Show database statistics |
| mmry extract | Export memories to mmry |
The search command auto-detects query type:
- Natural language: Uses porter stemming for English text
- Code: Preserves underscores, dots, and path separators
Force a mode with --mode natural or --mode code.
Scope and filters:
--scope local|remote|all(default: local)--remote <name>to target specific remotes--source,--workspace,--rolefilters--no-toolsto exclude tool calls--dedupto collapse similar results--include-systemto include system context (AGENTS.md, etc.)
The resume command opens a past session in your preferred coding agent. It handles
cross-agent format conversion automatically -- a Codex session can be resumed in pi,
a Claude Code session in Codex, etc.
# Direct resume by conversation ID
hstry resume <conversation-id># Search for a session
hstry resume --search "async runtime refactor"# Browse recent sessions and pick interactively
hstry resume --limit 10
# Filter by time
hstry resume --after "yesterday"
hstry resume --after "2 days ago" --before "today"
hstry resume --after "2026-02-01" --before "2026-03-01"# Filter by source or workspace
hstry resume --source codex-main --workspace myproject
# Target a specific agent (overrides default_agent from config)
hstry resume --search "refactor" --agent claude-code
# Dry run (show what would happen without writing or launching)
hstry resume --dry-run --search "query"# JSON output for automation
hstry resume --json --search "query"How it works:
- If the session already belongs to the target agent and the original file exists on disk, it launches directly (zero conversion overhead).
- Otherwise, it exports the session via the target adapter, places the converted file in the agent's native session directory, and launches the agent.
Time filter formats: ISO dates (2026-03-01), relative dates (yesterday, today, last week, last month), duration expressions (2 days ago, 3 weeks ago, 1 month ago).
Configure the default agent and per-agent launch commands in config.toml:
[resume]
default_agent = "pi"
[resume.agents.pi]
format = "pi"command = "pi --session {session_path}"session_dir = "~/.pi/agent/sessions"
[resume.agents.claude-code]
format = "claude-code"command = "claude --resume {session_id}"session_dir = "~/.claude/projects"Command templates support these placeholders: {session_path}, {session_id}, {workspace}.
hstry follows XDG Base Directory specifications:
| Directory | Default | Environment Override |
|---|---|---|
| Config | ~/.config/hstry/ | $XDG_CONFIG_HOME/hstry/ |
| Data | ~/.local/share/hstry/ | $XDG_DATA_HOME/hstry/ |
| State | ~/.local/state/hstry/ | $XDG_STATE_HOME/hstry/ |
Default config: ~/.config/hstry/config.toml
"$schema" = "https://raw.githubusercontent.com/byteowlz/schemas/refs/heads/main/hstry/hstry.config.schema.json"database = "~/.local/share/hstry/hstry.db"adapter_paths = ["~/.config/hstry/adapters"]
js_runtime = "auto"# bun, deno, or node
[[adapters]]
name = "codex"enabled = true
[service]
enabled = falsepoll_interval_secs = 30search_api = true
[search]
index_batch_size = 500
[resume]
default_agent = "pi"
[resume.agents.pi]
format = "pi"command = "pi --session {session_path}"session_dir = "~/.pi/agent/sessions"See examples/config.toml for all options. Use hstry config show/path/edit for config management.
hstry service runs a local daemon that keeps the search index warm and exposes a
local-only gRPC search endpoint. The CLI prefers the service when it is running.
Use hstry service enable/disable/start/run/restart/stop/status to manage it.
The optional hstry-api binary serves a local HTTP API (default http://127.0.0.1:3000)
for external integrations (e.g., Octo).
Override service usage with HSTRY_NO_SERVICE=1. Override the API URL with
HSTRY_API_URL or disable API usage with HSTRY_NO_API=1.
hstry can sync and search remote databases over SSH. Remotes require hstry to
be installed on the host.
# Add a remote host
hstry remote add laptop user@laptop
# Verify connectivity
hstry remote test laptop
# Fetch the remote database into the local cache
hstry remote fetch --remote laptop
# Search only remote results
hstry search "auth error" --scope remote --remote laptop
# Sync (merge) remote history into the local database
hstry remote sync --remote laptop --direction pullSee Remote sync for device namespaces, hub safety checks, and concurrency guidance.
Use the optional hstry-tui binary for an interactive, three-pane browser.
cargo install --path crates/hstry-tui
hstry-tui| Adapter | Default Path | Description |
|---|---|---|
claude-code | ~/.claude/projects | Claude Code CLI |
codex | ~/.codex/sessions | OpenAI Codex CLI |
cursor | Cursor workspaceStorage (platform-specific) | Cursor (state.vscdb) |
opencode | ~/.local/share/opencode | OpenCode |
pi | ~/.pi/agent/sessions | Pi coding agent |
gemini-cli | ~/.gemini/tmp | Gemini CLI sessions |
workbuddy | ~/.workbuddy/projects | WorkBuddy project sessions |
aider | Project directories | Aider (finds .aider.chat.history.md) |
goose | ~/.local/share/goose/sessions | Goose (SQLite/JSONL) |
jan | ~/jan/threads | Jan.ai |
lmstudio | ~/.cache/lm-studio/conversations | LM Studio |
openwebui | ~/.open-webui/data (or /app/backend/data) | Open WebUI |
| Adapter | Source | Export Location |
|---|---|---|
chatgpt | ChatGPT | Settings > Data controls > Export |
claude-web | Claude.ai | Settings > Export data |
gemini | Gemini | google.com/takeout > Gemini Apps |
Point these adapters at the extracted export directory (e.g., ~/Downloads/chatgpt-export).
Adapters are TypeScript modules that parse chat history from specific tools. Each adapter implements:
detect(path)- Check if a path contains valid dataparse(path, options)- Extract conversations and messages
Add custom adapters by placing them in adapter_paths, or manage repositories with:
hstry adapters repo add-git community https://example.com/adapters.git
hstry adapters updatecrates/
hstry-core/ # Database, config, models
hstry-runtime/ # TypeScript adapter execution
hstry-cli/ # Command-line interface
hstry-tui/ # Terminal UI (ratatui)
hstry-mcp/ # MCP server
hstry-api/ # HTTP API (axum)
just check-all # Format, lint, and test
just test# Run tests only
just clippy # Lint only
just update-adapters # Copy latest adapters to ~/.config/hstry/adaptersContributions are welcome! Please see docs/RELEASE.md for information about the release process.
See CHANGELOG.md for the full list of changes.
The release process is fully automated via GitHub Actions:
- GitHub Releases: Automatic builds for Linux (x86_64/ARM64) and macOS (Intel/Apple Silicon)
- Homebrew: Automatic formula updates in
byteowlz/homebrew-tap - AUR: Automatic PKGBUILD updates
See docs/RELEASE.md for detailed release instructions.
This project is inspired by and references ideas from cross-agent-session-search (cass) by Jeffrey Emanuel. Source: https://github.com/Dicklesworthstone/coding_agent_session_search (MIT License).
MIT