hstry

One searchable SQLite database for your AI chat history. Imports conversations from coding agents (Claude Code, Codex, Pi, Cursor, Aider, ...) and web apps (ChatGPT, Claude, Gemini, Perplexity), with full-text search, export, and cross-agent session resume.

# Homebrew (macOS and Linux)
brew tap byteowlz/tap
brew install hstry

# Arch Linux
yay -S hstry

# Cargo
cargo install --path crates/hstry-cli

# Optional binaries
cargo install --path .        # all binaries (CLI, TUI, MCP, API)
cargo install --path crates/hstry-tui

Pre-built binaries for Linux (x86_64/ARM64) and macOS (Intel/Apple Silicon) are on the Releases page.

hstry quickstart                      # scan known paths, add sources, sync

hstry source add ~/.codex/sessions    # add a source (adapter auto-detected)
hstry sync --parallel 2               # import from all sources
hstry import ~/Downloads/chatgpt-export  # one-off import

hstry search "how to parse JSON"      # full-text search
hstry list --limit 10                 # recent conversations
hstry show <conversation-id>

hstry resume --search "JSON parser" --agent pi   # reopen a session in any agent

Adapter installs are version-pinned to the hstry binary. Run hstry adapters update after upgrading; sync refuses to run if adapter manifests do not match.

extension/ contains hstry sync, a Chrome MV3 extension that background-syncs conversations from ChatGPT, Claude, Gemini, and Perplexity into your local database. It POSTs new conversations to a running hstry-api instance (http://127.0.0.1:3000/ingest, token-authenticated).

hstry-api --port 3000   # start the API, optionally with --token <secret>

Load it from chrome://extensions with Developer mode enabled (Load unpacked, select extension/). Provider toggles, port, and token are configured on the extension's options page. The hstry web Playwright commands are the headless alternative to the extension.

The query type is auto-detected: natural-language queries use porter stemming, code queries preserve underscores, dots, and path separators. Force with --mode natural|code.

Useful flags: --scope local|remote|all, --remote <name>, --source, --workspace, --role, --no-tools, --dedup, --json.

resume reopens a past session in any supported agent, converting formats when needed (a Codex session can resume in Claude Code and vice versa).

hstry resume <conversation-id>
hstry resume --search "async runtime refactor" --agent claude-code
hstry resume --after "2 days ago" --workspace myproject
hstry resume --limit 10                # browse and pick interactively

Time filters accept ISO dates, relative dates (yesterday, last week), and durations (3 weeks ago). Defaults come from config:

[resume]
default_agent = "pi"

[resume.agents.pi]
format = "pi"
command = "pi --session {session_path}"
session_dir = "~/.pi/agent/sessions"

Placeholders: {session_path}, {session_id}, {workspace}.

Sync and search other machines' databases over SSH. Remotes need hstry installed.

hstry remote add laptop user@laptop
hstry remote test laptop
hstry remote fetch --remote laptop
hstry search "auth error" --scope remote --remote laptop
hstry remote sync --remote laptop --direction pull

See docs/remote-sync.md for device namespaces and concurrency guidance.

hstry service runs a daemon that keeps the search index warm and exposes a local-only gRPC search endpoint; the CLI prefers it when running. hstry-api serves a local HTTP API (default 127.0.0.1:3000) for external integrations, including the browser extension.

Environment overrides: HSTRY_NO_SERVICE=1, HSTRY_API_URL, HSTRY_NO_API=1.

• Browser extension (extension/): ChatGPT, Claude, Gemini, Perplexity
• Manual exports: chatgpt (Settings > Data controls > Export), claude-web (Settings > Export data), gemini (Google Takeout)

Adapters are TypeScript modules that implement detect(path) and parse(path, options). They run via Bun/Deno/Node and are loaded from adapter_paths. Repositories (git, archive, local) can be managed with hstry adapters repo.

hstry adapters repo add-git community https://example.com/adapters.git
hstry adapters update

XDG paths: config in ~/.config/hstry/, data in ~/.local/share/hstry/, state in ~/.local/state/hstry/ (overridable via XDG_*). Default config is ~/.config/hstry/config.toml:

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 = false
poll_interval_secs = 30

[resume]
default_agent = "pi"

See examples/config.toml for all options.

just check-all        # format, lint, test
just update-adapters  # copy adapters to ~/.config/hstry/adapters

Workspace layout: hstry-core (database, config, models), hstry-runtime (adapter execution), hstry-cli, hstry-tui (ratatui), hstry-mcp, hstry-api (axum). Releases are automated via GitHub Actions; see docs/RELEASE.md and CHANGELOG.md.

Inspired by cross-agent-session-search (cass) by Jeffrey Emanuel (MIT).

MIT