v0.3.0

Upgrading — read this before you sync

This release is mostly about not losing turns, and getting there needs a schema change.

Opening your archive with v0.3.0 runs 8 migrations (005 and 007–013) automatically. One of them matters operationally:

Migration 012 rebuilds the turns table. It holds the old and new copies at once, so it needs free disk space roughly equal to your turns table, plus room for the write-ahead log. On a large archive that is gigabytes, and the database file stays that much larger afterward until you run ccvault vacuum.

It is wrapped in a transaction and ends with a strict FTS integrity check, so a failure — including running out of disk — rolls the whole thing back rather than leaving a half-rebuilt table. But migrations do not take a backup for you (only sync --full and --rebuild do). So before upgrading, with nothing else running:

cp ~/.ccvault/ccvault.db ~/.ccvault/ccvault.db.bak

Two further cautions:

• Don't run an older ccvault against an upgraded archive. Older binaries open a newer schema without complaint, write with the wrong connection pragmas, and their sync --full wipes the archive instead of re-parsing it. Upgrade every copy on your PATH.
• Timing on a million-row archive is extrapolated, not measured — expect minutes, not seconds, and don't interrupt it.

What this fixes

• Turns lost to uuid collisions between resumed transcripts. A resumed session copies the earlier session's lines verbatim, uuids included, and turns was keyed on the uuid alone — so the later parse deleted the earlier session's rows. Migration 012 re-keys on (session_id, id) and un-marks the affected transcripts so the next sync recovers them. Measured on one real set: 23,905 turns stored before, 25,003 after.
• sync --full destroying the archive. It no longer resets the database; re-parsing is now a separate --rebuild, it backs up first, confirms interactively, and refuses to run unattended.
• Full-text index orphans, which made searches miss turns that were present.
• Failed tool calls are now searchable — is_error is stored, so you can find the calls that didn't work.
• stats gained --json, search reaches tool inputs and results, and date-filtered searches no longer scan the whole index.

Known issue: a transcript that repeats a uuid within itself still stores fewer turns than it reports (#121). That case is narrower than the cross-session one fixed here, and tracked separately.

---

Changelog

Features

• ccc4c67: feat(mcp): list_sessions/list_projects paginate by offset like search (@detour1999)
• ec09bf2: feat: --data-dir / --config make the whole CLI runnable against a fixture (@detour1999)
• 586b0b7: feat: --full sync backs up, confirms, and refuses non-interactive wipes (@detour1999)
• cbeb94c: feat: add GetToolNamesLike for tool-name suggestions (@harperreed)
• 1eb0be2: feat: add empty-result hints and has_more to MCP search and list tools (@harperreed)
• a45dc45: feat: add nanoclaw source adapter with subagent sidechain support (@detour1999)
• 6c098a9: feat: archive subagent transcripts from ~/.claude as their own sessions (@detour1999)
• 2885b2b: feat: bound a date-filtered search's index scan to the window it asks for (@detour1999)
• 6ef9fab: feat: bounded line reader for parser (defense against pathological input) (@detour1999)
• 257776f: feat: cap line reads at 200 MB and truncate raw_json above 1 MB (@detour1999)
• 5e50e82: feat: ccvault stats gains --json flag for machine-parseable output (@detour1999)
• a2572ab: feat: ccvault sync reports sessions whose transcript was rewritten upstream (@detour1999)
• b6ebb4a: feat: count and surface JSONL lines skipped during parse (@detour1999)
• 9d28aee: feat: get_turns resumes from an ordinal, and the summary reports the cursor (@detour1999)
• 684ccb7: feat: index a day and month token beside the searchable text (@detour1999)
• 533380c: feat: internal/compact width-aware compaction + TUI layout tiers (follow-up 8) (@detour1999)
• 7d84ebe: feat: introduce projectref discipline + AST allowlist (follow-ups 4-8) (@detour1999)
• 36faa55: feat: migration 005 normalizes display_name to basename for existing rows (@detour1999)
• 24c7a1c: feat: migration 009 stores and indexes tool payloads, backfilled from raw_json (@detour1999)
• cbbe01c: feat: ordering reads off ordinal, and get_turns reports it as a cursor (@detour1999)
• b355b02: feat: raw_json placeholder for oversized parsed turns (@detour1999)
• be00190: feat: reclaim dead space with verified copy-and-swap compaction (@detour1999)
• 6480a01: feat: search reaches tool inputs and results, and says when it did (@detour1999)
• 0f480a3: feat: sessions.parent_session_id, with a backfill for ids that carried the link (@detour1999)
• 1b47068: feat: stats reports turns whose stored payload is not JSON (@detour1999)
• b32ffe9: feat: store the tool-result is_error flag, so failed calls are findable (@detour1999)
• 4868423: feat: subagent sessions are hidden from listings, never unreachable (@detour1999)
• cae3d5a: feat: surface raw_json truncation counts in sync stats (@detour1999)
• 202c1c0: feat: the parser and all five adapters carry tool payloads instead of dropping them (@detour1999)
• 167824f: feat: tool-payload storage policy as a shared package (@detour1999)
• e8ef709: feat: turns carry a gapless per-session ordinal, backfilled from rowid (@detour1999)

Bug fixes

• 2f964a4: fix(search): parse dates in local time and tolerate bad timestamps (@MrBeldum)
• 04d8aad: fix: --full re-parses the archive instead of destroying it (@detour1999)
• a05efae: fix: --full sync invalidates analytics parquet cache (@detour1999)
• 601b7f9: fix: CLI errors print once, not twice (#69) (@detour1999)
• 6dba7df: fix: GetTurns drops invalid raw_json so downstream json.Marshal doesn't crash (@detour1999)
• 41ac166: fix: MCP answers every request, and says which turns it could not read (@detour1999)
• 633f8d1: fix: MCP initialize advertises the real build version, not a literal 0.1.0 (@detour1999)
• 8176186: fix: ResetAll runs inside a transaction so mid-reset failure rolls back (@detour1999)
• 5eefac0: fix: SQLite DSN options were never applied; put the archive in real WAL (@detour1999)
• 119988f: fix: TUI startup stall, swallowed search keys, and the dead '?' binding (@detour1999)
• b173ec1: fix: UpsertSession follows a session file that moved on disk (@detour1999)
• c075ee3: fix: a NULL in any nullable session column no longer fails the scan (@detour1999)
• 7666542: fix: a NULL token column no longer zeroes a project's whole total (@detour1999)
• 3e5c9f8: fix: a focused text input owns printable runes; footers match the key map (@detour1999)
• 12b2852: fix: a payload hit resolves to the turn in its own session (@detour1999)
• be25ed4: fix: a replaced turn no longer leaves a ghost entry in turns_fts (@detour1999)
• aaf9edf: fix: a turn's identity is its session and its uuid, not the uuid alone (@detour1999)
• cc5b0f8: fix: address 5 blocking findings from adversarial review (@detour1999)
• c741307: fix: address code review feedback on #12 (@detour1999)
• c2cc18f: fix: an upsert carrying no source_file keeps the path already on the row (@detour1999)
• fc35304: fix: cancel the TUI sync goroutine on navigate-away and ctrl+c (@detour1999)
• 020b65f: fix: collect orient stat-query errors into warnings (@harperreed)
• 7478302: fix: get_session folds the large-session notice into warnings[] (@detour1999)
• b147a17: fix: give tool_uses a key, and clean up what its absence left behind (@detour1999)
• 9053c9c: fix: guard against duplicate migration versions, match tool fragments literally (@detour1999)
• 0f70cbe: fix: make tool: search filter case-insensitive and correct tool-name docs (@harperreed)
• 68027f8: fix: nanoclaw adapter propagates non-notfound errors from ScanClaudeHome (@detour1999)
• ba37739: fix: notifications must not receive JSON-RPC responses (#7) (@detour1999)
• 35839c6:...

v0.2.0

Changelog

Features

• 48bf18a: feat: add --source flag to sync command and source filter to orient help (@detour1999)
• 8aca35e: feat: add Claude Code adapter wrapping existing parser and scanner (@detour1999)
• eaa622f: feat: add Codex source adapter for OpenAI Codex CLI sessions (@detour1999)
• a0809be: feat: add Hex source adapter for agentic loop sessions (@detour1999)
• c7d96e3: feat: add Jeff source adapter for GSuite agentic loop sessions (@detour1999)
• 56630b7: feat: add Source row to markdown export metadata table (@detour1999)
• d653911: feat: add SourceAdapter interface and adapter registry (@detour1999)
• 17064cd: feat: add end-to-end integration test for multi-source sync and search (@detour1999)
• c37e487: feat: add multi-source config with backward compatibility (@detour1999)
• 75fd682: feat: add source column to sessions, projects, and source_files (migration 003) (@detour1999)
• 7e2cbd8: feat: add source field to MCP search results and tool parameters (@detour1999)
• 796b7e2: feat: add source field to analytics SessionRecord and Parquet schema (@detour1999)
• 1dcdbc9: feat: add source: search filter for multi-source queries (@detour1999)
• a9e189b: feat: add versioned migration system for database schema evolution (@detour1999)
• 6a77131: feat: register Claude Code adapter via blank import in main (@detour1999)
• 4e99fb8: feat: thread source display through all TUI views (@detour1999)
• c2963b8: feat: wire Jeff and Hex adapters, add scenario patterns (@detour1999)
• 11a4f1d: feat: wire source field through all DB operations (@detour1999)

Bug fixes

• f8d8565: fix: address PR #6 review feedback and shore up adapter tests (@detour1999)
• 08b7618: fix: address code review findings from PR #6 (@detour1999)

Other

• 34b5e37: refactor: sync layer uses adapter interface instead of direct parser calls (@detour1999)
• eed623e: revert: remove unrelated fmt.Fprintf changes from migration commit (@detour1999)

v0.1.8

Changelog

Features

• bb4245e: feat: add interactive TUI sync, optimize incremental sync, wire has:error/has:subagent search (@harperreed)

Bug fixes

• 7c3ec91: fix: auto-build analytics cache when parquet file is missing (@harperreed)
• 518ea3f: fix: extract CWD from JSONL for correct project path decoding (@harperreed)

Other

• 375674f: Add MIT License to the project (@harperreed)
• 18b3db0: Refactor index.html for a bright and clean design 🌟💥 (@harperreed)
• e231694: Update README with image and feature details (@harperreed)

v0.1.7

What's New

Claude Code Skill

Ship a 4-file skill (skills/ccvault/) that teaches AI agents how to effectively mine conversation history:

• SKILL.md — Strategy guide with search playbook, decision flowchart, five search patterns, and anti-patterns
• reference.md — Full tool/query reference card with all 8 MCP tools, query syntax, and copy-paste recipes
• orient-prompt.md — Session-start orientation workflow (4 steps)
• recall-prompt.md — On-demand recall workflow with search narrowing waterfall

New CLI Commands

• ccvault quickstart — Interactive setup guide for new users
• ccvault orient — Database state summary for AI agents (--json for programmatic use)

Improvements

• list-sessions --json now includes project_path per session, eliminating N+1 CLI calls for consumers that need project context (closes #1)
• Expanded installation docs (Homebrew, go install, build from source)

v0.1.6

Changelog

Features

• a6f13cf: feat: add DuckDB analytics view, copy/paste support, and tests (@harperreed)
• 2299eb0: feat: add auto-sync detection and fix FTS5 hyphenated term search (@harperreed)

v0.1.5

Changelog

Features

• e3223f8: feat: add get_session_summary and get_turns MCP tools (@harperreed)

v0.1.4

Changelog

Features

• d4b2845: feat: add pagination to MCP search, return compact results (@harperreed)

Bug fixes

• adea718: fix: limit test-coverage to packages with tests (@harperreed)

v0.1.3

Changelog

Bug fixes

• a070e59: fix: remove Linux ARM64 build (CGO cross-compile issues with DuckDB) (@harperreed)

v0.1.2

Changelog

Bug fixes

• 8ae401b: fix: apply De Morgan's law and add test-race target (@harperreed)

v0.1.1

Changelog

Features

• 160bf8b: feat: add CLI entry point and fix gitignore (Harper Reed harper@nata2.org)
• 572250c: feat: add data models and JSONL parser (Harper Reed harper@nata2.org)
• 6fe1e2b: feat: add database layer with SQLite and FTS5 (Harper Reed harper@nata2.org)
• 1d09ae9: feat: add markdown export, MCP prompts, and CI/CD configuration (Harper Reed harper@nata2.org)
• 477a7d4: feat: implement Bubble Tea TUI for interactive browsing (Harper Reed harper@nata2.org)
• 653a6e7: feat: implement search, stats, list, and show commands (Harper Reed harper@nata2.org)
• 0ed2213: feat: implement sync command for indexing conversations (Harper Reed harper@nata2.org)
• 0665986: feat: initialize project scaffolding with CLI structure (Harper Reed harper@nata2.org)

Bug fixes

• 5b2a95d: fix: update homebrew tap to 2389-research/homebrew-tap (Harper Reed harper@nata2.org)