augur

Universal AI chat history manager. Import, encrypt, search, and manage conversation histories across ChatGPT, Claude, Copilot, Z.ai, Gemini, DeepSeek, Perplexity, Grok, and Poe.

Table of Contents

• What is augur?
• Features
• Supported Providers
• Quick Start
• Installation
• Command Reference
• Export Instructions
• Security & Privacy
• Architecture
• Product Map
• Known Issues
• Development
• License

---

What is augur?

augur is a local-first CLI tool for archiving AI conversations. Export your chat histories from ChatGPT, Claude, Copilot, Z.ai, Gemini, DeepSeek, Perplexity, Grok, or Poe, then import them into augur's encrypted local storage. Search across all providers, track conversation changes over time, and own your data permanently.

Core Philosophy: Your conversations are stored as individually encrypted files on your machine. SQLite indexes provide fast search, but encrypted files are the source of truth. If the index breaks, you can rebuild it. If a provider shuts down, you still have your data.

Use Cases:

• Archive conversations before a provider's retention policy expires
• Search across ChatGPT and Claude conversations with one command
• Track how conversations evolve (detects remote edits via content hashing)
• Export before canceling a subscription
• Keep a permanent local backup of irreplaceable conversations

---

Features

Conversation Import & Sync

• Multi-Provider Support: Import from ChatGPT (ZIP), Claude (ZIP), Microsoft Copilot (CSV), Z.ai (JSON), and Gemini, DeepSeek, Perplexity, Grok, Poe via browser extension exports (ZIP/JSON)
• Incremental Sync: Re-import exports without duplicates — only new/updated conversations are written
• Change Detection: Content hashing detects modifications even when timestamps don't change
• Version History: Track how conversations evolve across syncs with SHA-256 hashing
• Remote Deletion Detection: Conversations absent from newer exports are flagged as "remote-deleted" but preserved locally

Example:

# First sync
augur sync chatgpt --from ~/Downloads/chatgpt-export.zip
# Output: Imported 142 conversations.
#   New: 142 | Updated: 0 | Remote-modified: 0 | Unchanged: 0

# Re-sync weeks later with updated export
augur sync chatgpt --from ~/Downloads/chatgpt-export-2026-02-20.zip
# Output: Imported 8 conversations.
#   New: 5 | Updated: 3 | Remote-modified: 0 | Unchanged: 134 | Remote-deleted: 0

Conversation History

• List Conversations: View all imported conversations with metadata
• Filter by Provider: Show only conversations from a specific provider (all 9 supported)
• Filter by Status: View active, remote-deleted, locally-deleted, or all conversations
• View Full Conversations: Read complete message history with metadata

Example:

# List all active conversations (default)
augur history list

# List only Claude conversations
augur history list --provider claude

# Show remote-deleted conversations
augur history list --status remote-deleted

# View a full conversation
augur history view 8a2f3b4c-1234-5678-90ab-cdef12345678

Unified Format & Search

• On-Demand Indexing: Generate searchable indexes only when needed (zero overhead for archive-only users)
• Cross-Provider Search: Search ChatGPT and Claude conversations with one query
• Fast Full-Text Search: SQLite FTS5 indexes for sub-second searches across thousands of conversations
• Automatic Maintenance: Once generated, unified indexes stay synced automatically

Example:

# Generate unified format for search (one-time, per provider)
augur index generate --provider chatgpt
augur index generate --provider claude

# Search across all providers
augur search --query "python async functions"

# Search within one provider only
augur search --query "docker compose" --provider chatgpt --limit 10

Conversation Management

• Tagging: Add local-only tags to organize conversations across providers
• Deletion: Soft-delete conversations with mandatory sync-before-delete safety (Constitution II) — deleted conversations are not re-imported on next sync
• Cross-Provider Conversion: Copy conversations between provider namespaces
• Key Rotation: Re-encrypt all conversation files with a new passphrase
• Index Rebuild: Reconstruct the SQLite index from encrypted files (safety net)

Example:

# Tag a conversation
augur tag add 8a2f3b4c-... "important"

# Convert between providers
augur convert --from chatgpt --to claude --conversation 8a2f3b4c-...

# Rotate encryption key
augur rotate-key

# Rebuild index from encrypted files
augur index rebuild

Encryption & Security

• AES-256-GCM Encryption: Military-grade encryption for all conversation files
• Argon2id Key Derivation: Memory-hard KDF resistant to GPU brute force (OWASP recommended)
• OS Keychain Integration: Cached keys stored in macOS Keychain, Linux secret-service, Windows Credential Manager
• No Plaintext on Disk: Conversations never written unencrypted (except in-memory during processing)
• Individual File Encryption: Each conversation encrypted separately for granular control

---

Supported Providers

ChatGPT (OpenAI)

Status: Fully supported

Export Format: ZIP file containing conversations.json (single file for small accounts) or conversations-000.json, conversations-001.json, … shards for large accounts. Both layouts are handled automatically.

Features Preserved:

• Full message history with timestamps
• Conversation branching (follows primary path from root to current node)
• Model information (GPT-3.5, GPT-4, etc.)
• Hidden messages and branch points (metadata)
• Archived status
• DALL-E images (text placeholder: [Image: DALL-E generation])

Not Preserved: Code interpreter files (stored as placeholders)

---

Claude (Anthropic)

Status: Fully supported

Export Format: ZIP file containing conversations.json

Features Preserved:

• Full message history with timestamps
• Extended thinking blocks
• Artifacts (title + content)
• Tool use/results
• Voice notes (transcriptions)
• File attachments (metadata only — filenames, types, sizes)
• Starred conversations
• Model information

Not Preserved: Actual file binaries (export contains metadata only)

---

Microsoft Copilot

Status: Fully supported

Export Format: CSV file from Microsoft privacy dashboard

Features Preserved:

• Conversation exchanges (human and AI messages)
• Timestamps
• Conversation duration metadata
• Original conversation names

Limitations:

• No unique conversation IDs (augur generates UUIDs)
• Limited metadata compared to ChatGPT/Claude

---

Z.ai

Status: Fully supported (since v0.1.0)

Export Format: JSON file (z-ai-chat-export-{timestamp}.json)

Features Preserved:

• Full message history with branching support
• Multiple AI models per conversation (GLM-4.7, GLM-5, etc.)
• MCP server integrations (deep-research, vibe-coding, etc.)
• Web search metadata
• Conversation tags
• Feature flags (deep_research, etc.)
• Archived/pinned status
• Auto web search settings
• Extended thinking mode settings
• Folder organization

Note: Z.ai provides the most comprehensive export among all providers, including native tag support and MCP server tracking.

---

Gemini (Google)

Status: Fully supported (via browser extension)

Export Format: ZIP file containing per-conversation JSON files (exported by augur's Gemini browser extension)

Features Preserved:

• Full message history with timestamps
• Provider-native content parts (text, code, image, video, audio, embed, canvas)
• Extracted plain text for full-text search
• Timestamp source tracking (message-range vs export-time)

Limitations:

• Requires augur's browser extension to export (no native Gemini export)
• DOM extraction is best-effort (Google's DOM is undocumented and may change)
• Timestamps derived from DOM elements with fallback to export time

---

DeepSeek

Status: Fully supported (via browser extension)

Export Format: ZIP or JSON file (exported by augur's DeepSeek browser extension)

Features Preserved:

• Full message history with timestamps
• Conversation metadata (title, model, timestamps)
• Provider-native content parts in unified format
• Extracted plain text for full-text search

Limitations:

• Requires augur's browser extension to export (no native DeepSeek export)

---

Perplexity

Status: Fully supported (via browser extension)

Export Format: ZIP or JSON file (exported by augur's Perplexity browser extension)

Features Preserved:

• Full message history with timestamps
• Conversation metadata (title, model, timestamps)
• Provider-native content parts in unified format
• Extracted plain text for full-text search

Limitations:

• Requires augur's browser extension to export (no native Perplexity export)

---

Grok (xAI)

Status: Fully supported (via browser extension)

Export Format: ZIP or JSON file (exported by augur's Grok browser extension)

Features Preserved:

• Full message history with timestamps
• Conversation metadata (title, model, timestamps)
• Provider-native content parts in unified format
• Extracted plain text for full-text search

Limitations:

• Requires augur's browser extension to export (no native Grok export)

---

Poe (Quora)

Status: Fully supported (via browser extension)

Export Format: ZIP or JSON file (exported by augur's Poe browser extension)

Features Preserved:

• Full message history with timestamps
• Conversation metadata (title, model, timestamps)
• Provider-native content parts in unified format
• Extracted plain text for full-text search

Limitations:

• Requires augur's browser extension to export (no native Poe export)

---

Quick Start

1. Install

# Clone repository
git clone https://github.com/AIinfusedS/augur.git
cd augur

# Setup environment (installs Go if needed)
./scripts/setup.sh

# Build
go build -o augur ./cmd/augur

# Verify installation
./augur --version

2. Export Conversations from Your Provider

See Export Instructions below for provider-specific steps.

3. Import Your First Conversations

# ChatGPT
./augur sync chatgpt --from ~/Downloads/chatgpt-export.zip

# Claude
./augur sync claude --from ~/Downloads/claude-export.zip

# Copilot
./augur sync copilot --from ~/Downloads/copilot-activity.csv

# Z.ai
./augur sync zai --from ~/Downloads/z-ai-chat-export-2026-02-13.json

# Gemini extension export
./augur sync gemini --from ~/Downloads/gemini-export.zip

# DeepSeek extension export
./augur sync deepseek --from ~/Downloads/deepseek-export.zip

# Perplexity extension export
./augur sync perplexity --from ~/Downloads/perplexity-export.zip

# Grok extension export
./augur sync grok --from ~/Downloads/grok-export.zip

# Poe extension export
./augur sync poe --from ~/Downloads/poe-export.zip

First-time setup: You'll be prompted to create an encryption passphrase. This passphrase derives the encryption key for all conversation files. Choose a strong passphrase and store it securely (password manager recommended).

4. View Your Conversations

# List all conversations
./augur history list

# View a conversation (copy ID from list output)
./augur history view 8a2f3b4c-1234-5678-90ab-cdef12345678

5. (Optional) Enable Search

# Generate unified format for search
./augur index generate --provider chatgpt

# Search your conversations
./augur search --query "machine learning"

---

Installation

Prerequisites

• macOS: Homebrew (for brew install go)
• Linux: apt, dnf, pacman, or Homebrew
• Windows: WSL or Git Bash

From Source

# Clone repository
git clone https://github.com/AIinfusedS/augur.git
cd augur

# Automated setup (installs Go 1.26 if needed, downloads dependencies)
./scripts/setup.sh

# Build local binary
go build -o augur ./cmd/augur

# Optional: Install to PATH
sudo mv augur /usr/local/bin/

Cross-Platform Build

# Build for all platforms (macOS arm64/amd64, Linux amd64/arm64, Windows amd64/386)
./scripts/build.sh

# Binaries output to build/
ls build/
# augur-darwin-amd64
# augur-darwin-arm64
# augur-linux-amd64
# augur-linux-arm64
# augur-windows-386.exe
# augur-windows-amd64.exe

---

Command Reference

augur sync

Import conversations from provider exports.

Subcommands:

augur sync chatgpt --from <path-to-zip>
augur sync claude --from <path-to-zip>
augur sync copilot --from <path-to-csv-or-extension-json-zip>
augur sync zai --from <path-to-json-or-csv>
augur sync gemini --from <path-to-zip>
augur sync deepseek --from <path-to-zip-or-json>
augur sync perplexity --from <path-to-zip-or-json>
augur sync grok --from <path-to-zip-or-json>
augur sync poe --from <path-to-zip-or-json>

Flags:

• --from <path> (required): Path to export file

Behavior:

• First sync: Imports all conversations
• Subsequent syncs: Only imports new/updated conversations (compares IDs, timestamps, and content hashes)
• Detects remote deletions: Conversations absent from newer exports are flagged but preserved locally
• Detects silent modifications: Content changes without timestamp updates are flagged as remote-modified
• Prompts for passphrase on first use or when keychain cache expires
• Automatically maintains unified format indexes (if previously generated)

Output:

Imported 142 conversations.
  New: 5 | Updated: 3 | Remote-modified: 0 | Unchanged: 134 | Skipped: 0 | Remote-deleted: 0

---

augur history list

List imported conversations with metadata.

Flags:

• --provider <name> (optional): Filter by provider (chatgpt, claude, copilot, zai, gemini, deepseek, perplexity, grok, poe)
• --status <status> (optional): Filter by status (active, remote-deleted, remote-modified, locally-deleted, all) — default: active
• --tag <tag> (optional): Filter by conversation tag

Output:

TITLE                                     PROVIDER      DATE          UNIFIED    MESSAGES
Async Python patterns                     chatgpt       2026-02-10    yes        47
Claude Code architecture                  claude        2026-02-08    yes        23
Docker troubleshooting                    copilot       2026-02-05    no         12

Showing 142 of 142 conversations.

Examples:

# All conversations (active only by default)
augur history list

# Only Claude conversations
augur history list --provider claude

# Show remote-deleted conversations
augur history list --status remote-deleted

# Show remotely modified conversations
augur history list --status remote-modified

# Show all conversations regardless of status
augur history list --status all

---

augur history view

View full conversation content with all messages.

Usage:

augur history view <conversation-id>

Output:

=== Conversation ===
Title: Async Python patterns
Provider: chatgpt
Created: 2026-01-15 14:23:10
Updated: 2026-02-10 09:47:32
Messages: 47
Versions: 3
⚠ This conversation was modified remotely since last sync

=== ChatGPT Metadata ===
Default Model: gpt-4-turbo
Models Used: [gpt-4-turbo gpt-3.5-turbo]
Branch Points: 2

=== Messages ===

[USER] 2026-01-15 14:23:10
How do I handle async exceptions in Python?

---

[ASSISTANT] 2026-01-15 14:23:45
When working with async functions in Python, there are several...

Metadata Sections (provider-specific):

• ChatGPT: Default model, models used, branch points, hidden messages, archived status
• Claude: Model, starred status, summary, extended thinking, tool use, attachments, voice notes, content types
• Copilot: Human/AI message counts, conversation duration, original name
• Z.ai: Models, MCP servers, tags, features, flags, auto web search, enable thinking, archived, pinned, folder ID, share ID

---

augur index generate

Generate unified format indexes for search (on-demand, not automatic).

Flags:

• --provider <name> (required): Provider to index (chatgpt, claude, copilot, zai, gemini, deepseek, perplexity, grok, poe)

Behavior:

• Converts provider-native conversations to searchable unified format
• Compresses and encrypts unified format files
• Creates indexes in ~/.augur/indexes/<provider>/
• Once generated, subsequent syncs automatically maintain unified format

Output:

Generating unified format indexes for chatgpt...

Generation complete for chatgpt:
  Successful: 142 conversations
  Total size: 45823040 bytes
  Compressed: 22911520 bytes
  Ratio: 50.0%
  Location: /Users/username/.augur/indexes/chatgpt

Use Case: Run this once per provider before using augur search. Archive-only users can skip this entirely (zero storage overhead).

---

augur index rebuild

Rebuild the SQLite index from encrypted conversation files. This is the safety net that makes SQLite a rebuildable derived index (Constitution I).

Usage:

augur index rebuild

Behavior:

• Scans all .augr files under ~/.augur/conversations/
• Decrypts each file and extracts metadata
• Rebuilds the conversations table, FTS index, and tags
• Reports progress and errors

Use Case: Run this when augur.db is deleted, corrupted, or when switching machines.

---

augur search

Search across conversation indexes.

Flags:

• --query <text> (required): Search query
• --provider <name> (optional): Filter by provider (chatgpt, claude, copilot, zai, gemini, deepseek, perplexity, grok, poe)
• --limit <number> (optional): Max results to return (default: 50)
• --from <date> (optional): Date range start (YYYY-MM-DD)
• --to <date> (optional): Date range end (YYYY-MM-DD)
• --tag <tag> (optional): Filter by conversation tag
• --role <role> (optional): Filter by message sender (user, assistant, system)

Prerequisites: Conversations are indexed during sync. For older data, run augur index generate.

Output:

Search Results for: "async python"
Matches: 12 conversations

TITLE                                     PROVIDER      MESSAGES    UPDATED
Async Python patterns                     chatgpt       47          2026-02-10
Python concurrency deep dive              claude        23          2026-01-28
asyncio event loop debugging              chatgpt       15          2026-01-15

Examples:

# Search all providers
augur search --query "docker compose errors"

# Search within one provider
augur search --query "rust async" --provider chatgpt

# Limit results
augur search --query "API" --limit 10

---

augur convert

Convert conversations between provider formats. Creates a copy under the target provider namespace; the original is unchanged.

Flags:

• --from <provider> (required): Source provider (validated against the conversation's actual provider)
• --to <provider> (required): Target provider (must differ from source)
• --conversation <id> (required): Conversation ID to convert

Example:

augur convert --from chatgpt --to claude --conversation 8a2f3b4c-...

---

augur delete

Soft-delete conversations from local storage. The encrypted file is removed, but a tombstone record (sync_status=locally-deleted) is preserved in the index so the conversation is not re-imported on the next sync. Constitution II mandates every conversation must be synced before deletion.

Deleted conversations are hidden from history list by default but visible with --status=locally-deleted or --status=all.

Usage:

# Delete single conversation
augur delete <conversation-id>

# Bulk delete all conversations for a provider
augur delete --all --provider chatgpt --confirm

# View deleted conversations
augur history list --status locally-deleted

Flags:

• --all: Delete all conversations for a provider
• --provider <name>: Provider for bulk delete
• --confirm: Required for bulk operations

---

augur tag

Add, remove, or list tags on conversations. Tags are local-only (never pushed to providers) and survive index rebuilds.

Subcommands:

# Add a tag
augur tag add <conversation-id> <tag>

# Remove a tag
augur tag remove <conversation-id> <tag>

# List all tags with counts
augur tag list

# List tags for a specific conversation
augur tag list <conversation-id>

Integration: Use --tag flag with augur history list and augur search to filter by tag.

---

augur rotate-key

Re-encrypt all conversation files with a new passphrase. Atomic operation using temp-file-then-rename.

Usage:

augur rotate-key

Behavior:

1. Prompts for old passphrase (verifies against config)
2. Prompts for new passphrase (with confirmation)
3. Re-encrypts every .augr and .augur file
4. Updates encryption config and keychain

---

Export Instructions

ChatGPT (OpenAI)

1. Log in to chat.openai.com
2. Click your profile (bottom-left)
3. Settings > Data controls > Export data
4. Click "Export"
5. Wait for email (arrives within minutes to hours)
6. Download ZIP file from email link
7. Import: augur sync chatgpt --from ~/Downloads/chatgpt-export.zip

File Format: ZIP containing conversations.json (main data) for small accounts, or conversations-000.json / conversations-001.json / … shards for large accounts — augur handles both automatically. Also present but ignored: chat.html, user.json, message_feedback.json

Export Size: Varies by conversation count (typically 1-50 MB for hundreds of conversations)

---

Claude (Anthropic)

1. Log in to claude.ai
2. Click Settings (gear icon, top-right)
3. Privacy > Export data
4. Click "Request export"
5. Wait for email (24-hour download link)
6. Download ZIP file from email link
7. Import: augur sync claude --from ~/Downloads/claude-export.zip

File Format: ZIP containing conversations.json (single file, different schema than ChatGPT)

Export Size: Varies by conversation count

---

Microsoft Copilot

1. Log in to your Microsoft account
2. Go to Microsoft Privacy Dashboard
3. Navigate to "Download your data"
4. Select "Copilot" or "Activity History"
5. Download CSV file
6. Import: augur sync copilot --from ~/Downloads/copilot-activity.csv

File Format: CSV with conversation exchanges (timestamp, prompt, response)

Limitations:

• CSV format provides less structured metadata than ChatGPT/Claude exports
• No unique conversation IDs (augur generates UUIDs based on content hashing)

---

Z.ai

1. Log in to z.ai
2. Navigate to Settings or Export section
3. Click "Export conversations" or equivalent option
4. Download JSON file (z-ai-chat-export-{timestamp}.json)
5. Import: augur sync zai --from ~/Downloads/z-ai-chat-export-2026-02-13.json

File Format: JSON array of conversation objects with full metadata

Export Size: Varies by conversation count

Note: Z.ai provides the most comprehensive export format, including:

• Native conversation tags
• MCP server configurations
• Multi-model tracking
• Feature flags and capabilities
• Folder organization metadata

---

Gemini (Google)

1. Install the augur Gemini exporter extension (see browser-extensions/history-extensions/gemini-exporter-extension/ or gemini-exporter-chrome/)
2. Navigate to gemini.google.com
3. Click the extension icon and select conversations to export
4. Choose export format (JSON recommended for augur)
5. Download ZIP file
6. Import: augur sync gemini --from ~/Downloads/gemini-export.zip

File Format: ZIP containing per-conversation JSON files in augur's unified format

---

DeepSeek

1. Install the augur DeepSeek exporter extension (see browser-extensions/history-extensions/deepseek-exporter-extension/ or deepseek-exporter-chrome/)
2. Navigate to chat.deepseek.com
3. Click the extension icon and select conversations to export
4. Choose export format (JSON recommended for augur)
5. Download ZIP file
6. Import: augur sync deepseek --from ~/Downloads/deepseek-export.zip

File Format: ZIP or JSON in augur's unified format

---

Perplexity

1. Install the augur Perplexity exporter extension (see browser-extensions/history-extensions/perplexity-exporter-extension/ or perplexity-exporter-chrome/)
2. Navigate to perplexity.ai
3. Click the extension icon and select conversations to export
4. Choose export format (JSON recommended for augur)
5. Download ZIP file
6. Import: augur sync perplexity --from ~/Downloads/perplexity-export.zip

File Format: ZIP or JSON in augur's unified format

---

Grok (xAI)

1. Install the augur Grok exporter extension (see browser-extensions/history-extensions/grok-exporter-extension/ or grok-exporter-chrome/)
2. Navigate to grok.com
3. Click the extension icon and select conversations to export
4. Choose export format (JSON recommended for augur)
5. Download ZIP file
6. Import: augur sync grok --from ~/Downloads/grok-export.zip

File Format: ZIP or JSON in augur's unified format

---

Poe (Quora)

1. Install the augur Poe exporter extension (see browser-extensions/history-extensions/poe-exporter-extension/ or poe-exporter-chrome/)
2. Navigate to poe.com
3. Click the extension icon and select conversations to export
4. Choose export format (JSON recommended for augur)
5. Download ZIP file
6. Import: augur sync poe --from ~/Downloads/poe-export.zip

File Format: ZIP or JSON in augur's unified format

---

Security & Privacy

Encryption Details

Algorithm: AES-256-GCM (Galois/Counter Mode)

• Key Size: 256 bits (32 bytes)
• Authentication: Authenticated encryption (detects tampering)
• Wrong Passphrase Detection: GCM authentication tag fails with incorrect key

Key Derivation Function: Argon2id (OWASP recommended)

• Time parameter: 1 iteration
• Memory: 64 MiB (65536 KiB)
• Parallelism: 4 threads
• Salt: 16 bytes (crypto/rand)
• Output: 32-byte AES-256 key

Why Argon2id?

• Memory-hard: Resistant to GPU/ASIC brute force attacks
• OWASP-recommended (defeats PBKDF2's compute-only weakness)
• Pure Go implementation (no CGo, cross-platform compatible)

Keychain Integration

Purpose: Cache derived encryption keys to avoid re-prompting every command

TTL: 1 hour (default, configurable via AUGUR_KEYCHAIN_TTL env var)

Platform Storage:

Platform	Backend	Security
macOS	Keychain	OS-level access control, encrypted at rest
Linux	secret-service (D-Bus)	Per-user encryption via gnome-keyring/KWallet
Windows	Credential Manager	Windows Credential vault, encrypted

Fallback: If keychain unavailable (CI, Docker, headless Linux), falls back to in-memory-only (re-prompt every invocation)

Storage Format:

{
  "key": "<base64-encoded-derived-key>",
  "expires_at": "2026-02-13T15:00:00Z"
}

Data Storage

Location: ~/.augur/ (Linux/macOS) or %APPDATA%\augur\ (Windows)

Structure:

~/.augur/
├── conversations/           # Encrypted conversation files
│   ├── chatgpt/
│   │   └── 8a2f3b4c....json.enc
│   ├── claude/
│   │   └── 7b1e2a3d....json.enc
│   ├── copilot/
│   └── zai/
├── indexes/                 # Unified format (optional, generated on-demand)
│   ├── chatgpt/
│   │   └── 8a2f3b4c....augur
│   └── claude/
│       └── 7b1e2a3d....augur
└── augur.db                 # SQLite index (rebuildable, no raw content)

File Encryption:

• Each conversation = individual encrypted file
• Encrypted filename: <conversation-id>.json.enc
• Unified format: <conversation-id>.augur (compressed + encrypted)

SQLite Index Contents (plaintext, rebuildable):

• Conversation metadata: ID, title, provider, timestamps, message count
• Sync status: active, remote-deleted, remote-modified, locally-deleted
• Sync state: last sync timestamp per provider
• FTS5 search tokens (extracted from messages, no full content)

Version history (timestamps and content hashes) is stored ONLY in encrypted files, never in SQLite.

What's NOT in SQLite:

• Full message bodies
• Conversation content
• Sensitive metadata

Rebuild Index: If augur.db is deleted/corrupted, augur can reconstruct it by scanning encrypted conversation files.

Threat Model

Protected Against:

• Disk theft: All conversations encrypted at rest
• Unauthorized local access: OS keychain protects cached keys
• Brute force: Argon2id's memory-hardness makes attacks expensive
• Tampering: AES-GCM authentication detects modified files

NOT Protected Against:

• Passphrase compromise: If attacker obtains your passphrase, all files are readable
• Memory dump attacks: Decrypted conversations exist in memory during processing
• Malware: Keyloggers can capture passphrase during entry
• Physical access with unlocked keychain: Cached keys readable if OS session unlocked

Best Practices:

• Use a strong, unique passphrase (20+ characters recommended)
• Store passphrase in password manager
• Enable disk encryption (FileVault, LUKS, BitLocker) as additional layer
• Lock your computer when away

---

Architecture

Principles

augur follows strict architectural principles (see .specify/memory/constitution.md):

#	Principle	Requirement
I	Local-First, Sync-Safe	Encrypted files are sole source of truth. SQLite is rebuildable.
II	Mandatory Sync Before Delete	NON-NEGOTIABLE. Verify imported_at before any delete. Zero exceptions.
III	Provider Isolation	Each provider in internal/provider/{name}/. No cross-provider imports.
IV	Clean Layered Architecture	CLI -> Service -> Data Access. No layer skipping.
V	Language-Agnostic Contracts	All interfaces documented in contracts/. Generic types only.
VI	Cross-Platform Parity	No CGo. filepath.Join for paths. Identical on macOS/Linux/Windows.
VII	Test Discipline	Table-driven tests. Never delete tests to make failures pass.
VIII	Encrypted Local Storage	AES-256-GCM per file. Keys from passphrase or keychain. Never plaintext on disk.
IX	Cross-Provider Conversion	Lossless for common attributes. Best-effort for metadata.
X	Conversation Tagging	User-defined tags. Many-to-many. Local-only. Survive sync cycles.
XI	Conversation Search	FTS5 across all providers. Filter by provider, tag, date, participant.

Layer Structure

┌─────────────────────────────────────────────────┐
│                 CLI Layer                       │
│  (internal/cli/)                                │
│  - Argument parsing                             │
│  - Output formatting                            │
│  - User interaction                             │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│               Service Layer                     │
│  (internal/service/)                            │
│  - Business logic                               │
│  - Orchestration                                │
│  - Transaction coordination                     │
└─────────────────┬───────────────────────────────┘
                  │
         ┌────────┼────────┐
         ▼        ▼        ▼
┌────────────┬────────┬────────────┐
│  Provider  │ Storage│    Sync    │
│  (I/O)     │  (I/O) │  (Engine)  │
├────────────┼────────┼────────────┤
│ chatgpt/   │ files  │ classifier │
│ claude/    │ index  │ detector   │
│ copilot/   │ crypto │ versioner  │
│ zai/       │        │            │
└────────────┴────────┴────────────┘

Dependencies: Always point inward (CLI -> Service -> Data Access, never reverse)

Data Flow

Import Flow:

Provider Export File
    ↓
Provider Parser (internal/provider/{name}/)
    ↓
Canonical Conversation Model (internal/model/)
    ↓
Sync Engine (internal/sync/)
    ├─ Change Detection (content hash comparison)
    ├─ Version History (append new version entry)
    └─ Classification (new/updated/unchanged/remote-deleted/remote-modified)
    ↓
Storage Layer (internal/storage/)
    ├─ Encrypt conversation (AES-256-GCM)
    ├─ Write encrypted file (conversations/{provider}/{id}.json.enc)
    └─ Update SQLite index (metadata + search tokens)
    ↓
Unified Format Maintenance (if previously indexed)
    ├─ Regenerate unified format for changed conversations
    └─ Update compressed+encrypted .augur files

Search Flow:

User Query
    ↓
Search Service (internal/service/conversion/)
    ↓
SQLite FTS5 Index
    ↓
Conversation IDs + Metadata
    ↓
Ranked Results

View Flow:

Conversation ID
    ↓
Storage Layer
    ├─ Read encrypted file
    ├─ Derive decryption key (from keychain or prompt)
    └─ Decrypt (AES-256-GCM)
    ↓
Canonical Conversation Model
    ↓
CLI Formatter (history.go)
    ↓
Console Output

Project Layout

augur/
├── cmd/
│   └── augur/
│       └── main.go              # Entry point
├── internal/
│   ├── cli/                     # CLI commands (Cobra)
│   │   ├── root.go              # Root command, version, global flags
│   │   ├── sync.go              # Sync commands (4 provider subcommands)
│   │   ├── history.go           # history list + history view
│   │   ├── search.go            # search with FTS5 filters
│   │   ├── index.go             # index generate + index rebuild
│   │   ├── convert.go           # Cross-provider conversion
│   │   ├── delete.go            # Delete with Constitution II safety
│   │   ├── tag.go               # Tag add/remove/list
│   │   └── rotate.go            # Key rotation
│   ├── service/                 # Business logic orchestration
│   │   ├── augur.go             # Service layer (all command implementations)
│   │   └── conversion/          # Unified format subsystem
│   │       ├── generator.go     # Unified format generation
│   │       ├── serializer.go    # Compression + encryption pipeline
│   │       ├── maintenance.go   # Post-sync unified format updates
│   │       ├── search.go        # FTS5 search service
│   │       ├── errors.go        # Structured error types
│   │       └── formatter.go     # Error formatters
│   ├── provider/                # Provider implementations
│   │   ├── provider.go          # Shared Provider interface
│   │   ├── chatgpt/             # ChatGPT ZIP parser
│   │   │   ├── chatgpt.go
│   │   │   └── parser.go
│   │   ├── claude/              # Claude ZIP parser
│   │   │   ├── claude.go
│   │   │   ├── parser.go
│   │   │   └── extraction.go
│   │   ├── copilot/             # Copilot CSV parser
│   │   │   ├── copilot.go
│   │   │   └── parser.go
│   │   └── zai/                 # Z.ai JSON parser
│   │       ├── zai.go
│   │       └── parser.go
│   ├── storage/                 # Data persistence
│   │   ├── filestore.go         # Encrypted file I/O
│   │   ├── index.go             # SQLite index with FTS5
│   │   ├── encryption.go        # AES-256-GCM + Argon2id
│   │   ├── keychain.go          # OS keychain with configurable TTL
│   │   └── compression.go       # zstd compression
│   ├── sync/                    # Sync engine
│   │   └── engine.go            # Import orchestration + classification
│   └── model/                   # Core data types
│       ├── conversation.go      # Conversation, Message, Version structs
│       ├── errors.go            # Error types
│       └── types.go             # Shared type definitions
├── contracts/                   # Language-agnostic interface specs
│   ├── cli-service.md
│   ├── service-storage.md
│   ├── service-provider.md
│   ├── sync-engine.md
│   └── unified-format.md
├── specs/                       # Feature specifications (10 specs)
│   ├── 001-project-bootstrap/
│   ├── 002-chatgpt-sync/
│   ├── 003-claude-sync/
│   ├── 004-unified-format/
│   ├── 005-conversion-error-handling/
│   ├── 006-filter-history-status/
│   ├── 007-view-conversation/
│   ├── 008-change-detection/
│   ├── 009-cli-e2e-tests/
│   └── 010-zai-provider/
├── test/
│   └── e2e/                     # End-to-end CLI tests
│       ├── sync_test.go
│       ├── history_test.go
│       ├── errors_test.go
│       └── versions_test.go
├── infra/
│   └── runners/                    # Docker-based self-hosted GitHub Actions runner
│       ├── Dockerfile              # Runner image: Ubuntu 24.04 + Go 1.26 + Node 24
│       ├── entrypoint.sh           # Auto-register, run ephemeral, handle cleanup
│       ├── docker-compose.yml      # Production-hardened, env-driven orchestration
│       ├── .env.example            # Shared config template (GitHub PAT)
│       ├── envs/
│       │   └── augur.env.example   # Per-repo config template (identity + resources)
│       └── README.md               # Full setup, scaling, monitoring, security docs
├── .github/
│   └── workflows/
│       ├── ci-quality-gates.yml    # CI: vet, test, extension Jest suites
│       └── build-runner-image.yml  # Build + push runner image to GHCR
├── scripts/
│   ├── setup.sh                 # Cross-platform setup entrypoint
│   ├── setup-macos-dev.sh       # macOS developer bootstrap
│   ├── build.sh                 # Cross-platform build
│   ├── ci-local.sh              # Local CI quality gates runner
│   ├── actions-local.sh         # Setup/start/stop local GitHub Actions runtime
│   ├── runner.sh                # Self-hosted GitHub Actions runner management
│   └── check-contract-drift.sh  # Contract drift enforcement
├── .specify/
│   └── memory/
│       └── constitution.md      # 11 architectural principles (v1.1.0)
├── BACKLOG.md                   # Development backlog (all milestones delivered)
├── README.md                    # This file
└── CLAUDE.md                    # Development guidelines

Technology Stack

Component	Technology	Version	Why
Language	Go	1.26	Pure Go (no CGo), cross-platform, fast compilation
CLI Framework	spf13/cobra	v1.10.2	Industry standard, rich flag support
Database	modernc.org/sqlite	v1.45.0	Pure Go SQLite, FTS5 support, no CGo
Encryption (KDF)	golang.org/x/crypto/argon2	stdlib	Memory-hard, OWASP-recommended
Encryption (AES)	crypto/aes, crypto/cipher	stdlib	AES-256-GCM, authenticated encryption
Keychain	zalando/go-keyring	latest	Cross-platform, pure Go (exec/D-Bus/syscall)
Compression	klauspost/compress/zstd	latest	Pure Go, deterministic, 50-70% ratio
Hashing	crypto/sha256	stdlib	Deterministic, cryptographically secure

No CGo: All dependencies are pure Go, enabling clean cross-compilation with CGO_ENABLED=0

---

Product Map

Current Status (v0.1.0)

All milestones M1-M9 delivered. Comprehensive code audit against all 10 feature specifications (148 functional requirements) complete — 146 implemented, 1 covered by README (HELP.md), 1 deferred (man page).

Delivered Features

Feature	Status	Notes
ChatGPT sync (ZIP export)	Working	Incremental sync, all message types, DALL-E placeholders
Claude sync (ZIP export)	Working	Extended thinking, artifacts, tool use, attachments, voice notes
Copilot sync (CSV export)	Working	UUID generation for missing IDs
Z.ai sync (JSON export)	Working	Branching, MCP servers, tags, multi-model
Encrypted storage (AES-256-GCM)	Working	Individual file encryption, Argon2id KDF
OS keychain integration	Working	macOS Keychain/Linux secret-service/Windows Credential Manager
Configurable keychain TTL	Working	AUGUR_KEYCHAIN_TTL env var
SQLite derived index	Working	Rebuildable from encrypted files (Constitution I)
Incremental sync (timestamp-based)	Working	New/updated/unchanged detection
Remote deletion detection	Working	Flag + preserve locally
Content hash change detection	Working	SHA-256, detects silent modifications
Version history tracking (sync layer)	Working	Append-only version entries per sync
Conversation listing with filters	Working	Provider, status, tag filters
Full conversation viewing	Working	Provider-specific metadata display per provider
Unified format generation	Working	On-demand, per provider
Unified format auto-maintenance	Working	Post-sync regeneration
Cross-provider search (FTS5)	Working	Multi-provider, date/tag/role filters
FTS index population during sync	Working	Automatic for new/updated conversations
Conversation tagging	Working	Add/remove/list, local-only, survives sync
Conversation deletion	Working	Constitution II enforcement (mandatory sync before delete)
Cross-provider conversion	Working	Copy between provider namespaces
Key rotation	Working	Re-encrypt all files atomically
Index rebuild	Working	Reconstruct SQLite from encrypted files
Structured error handling	Working	ConversionError with retryable/fatal/validation classifications
CLI E2E tests	Working	All 4 providers, multiple scenarios, edge cases
Cross-platform builds	Working	macOS/Linux/Windows, arm64/amd64
--config-dir flag	Working	Data directory override
Disk full error detection	Working	Specific error message for ENOSPC
Atomic file writes	Working	Temp-then-rename prevents corruption
ZIP entry size bounds	Working	3-layer defense (64 MiB limit) prevents memory exhaustion from oversized exports

Future Enhancements

See BACKLOG.md for the full history of completed milestones and remaining future items.

Long-Term Vision

• Version history diffing (see what changed between sync versions)
• Export conversations to markdown/HTML for sharing
• Batch operations (tag/delete multiple conversations)
• Conversation analytics (topic extraction, conversation graphs)
• TUI (Terminal UI) for interactive browsing
• Web UI (local server for rich visualization)
• Backup/restore (export augur's encrypted storage for migration)

Non-Goals

Things augur will NOT do:

• Remote API Access: augur is export-only (no OAuth, no API keys, no network calls to providers)
• Real-Time Sync: Syncing requires manual export from providers (no background polling)
• Cloud Storage: All data stays local (optional encrypted cloud backup may be added later)
• Conversation Generation: augur archives conversations, doesn't create them
• Provider Account Management: No login, no session management, no provider state modification
• Message Editing: Conversations are read-only archives (edits detected via version history)

---

Known Issues

No critical or high-priority issues remain. A comprehensive spec-vs-implementation audit (February 2026) identified and resolved all bugs across 148 functional requirements. See BACKLOG.md for the full audit record.

Deferred

ID	Feature	Notes
F-01	Man page (augur.1)	README serves as comprehensive documentation. Man page deferred to post-v1.0.

---

Development

For full local setup and bootstrap instructions, see DEVELOPER-GUIDE.md. For Docker-based Linux runner infrastructure, see infra/runners/README.md.

Prerequisites

• macOS 26.3+ (primary supported local setup path)
• Go: 1.26 or later
• Node.js + npm: Required for browser-extension test suites
• Git: For cloning repository
• Homebrew: Installed automatically by setup script on macOS if missing

Setup Development Environment

# Clone repository
git clone https://github.com/AIinfusedS/augur.git
cd augur

# Full macOS bootstrap (installs CLT/Homebrew/tools, Go+npm deps, builds binary)
./scripts/setup-macos-dev.sh

# Optional: run full Go + extension test verification during setup
./scripts/setup-macos-dev.sh --with-tests

# Cross-platform entrypoint (uses setup-macos-dev.sh on macOS)
./scripts/setup.sh

# Verify setup
go version
go mod verify

Build

# Local development build
go build -o augur ./cmd/augur

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

Cross-Platform Build

# Build for all platforms
./scripts/build.sh

# Output:
# build/augur-darwin-amd64
# build/augur-darwin-arm64
# build/augur-linux-amd64
# build/augur-linux-arm64
# build/augur-windows-amd64.exe

Testing

Local CI Pipeline (same gates as GitHub workflow):

# Run all CI gates locally (contracts + backend + extensions)
./scripts/ci-local.sh

# Run only backend gates
./scripts/ci-local.sh --backend

# Run selected extension suites only
./scripts/ci-local.sh --extensions --suite tests --suite tests-copilot

Run GitHub Actions Workflow Locally (act + local runtime):

# One-time setup (macOS): install act + colima + docker cli
./scripts/actions-local.sh --mode setup

# Optional: force Homebrew metadata refresh even when dependencies already exist
./scripts/actions-local.sh --mode setup --refresh-brew

# Start runtime apps required by act
./scripts/actions-local.sh --mode start

# Run the workflow locally
act -W .github/workflows/ci-quality-gates.yml

# Stop runtime apps started for local Actions execution
./scripts/actions-local.sh --mode stop

Self-Hosted GitHub Actions Runner (run CI on your own machine or server):

# macOS: download runner, register with GitHub, install launchd service
./scripts/runner.sh --mode setup

# Linux: build Docker image, create .env files, start container
# Docker infrastructure lives in infra/runners/ (Dockerfile, compose, env templates)
./scripts/runner.sh --mode setup

# Lifecycle (both platforms): start / stop / status / uninstall
./scripts/runner.sh --mode status

# Activate: set repo variable CI_RUNS_ON
# macOS: ["self-hosted", "macOS", "ARM64"]
# Linux: ["self-hosted", "Linux", "X64"]
# See DEVELOPER-GUIDE.md for full instructions.

The runner image is auto-built and pushed to GHCR by the build-runner-image.yml workflow on Dockerfile/entrypoint changes and weekly. Linux runners pull from ghcr.io/aiinfuseds/augur-runner:latest by default (configurable via RUNNER_IMAGE env var in infra/runners/envs/augur.env). See infra/runners/README.md for scaling, resource tuning, monitoring, and security hardening.

Unit Tests:

# Run all tests
go test ./...

# Run specific package tests
go test ./internal/provider/chatgpt/

# Run with verbose output
go test -v ./internal/storage/

# Run with coverage
go test -cover ./internal/sync/

CLI End-to-End Tests:

# Run E2E tests
go test ./test/e2e/ -v

# Run specific test
go test ./test/e2e/ -v -run TestSync_BasicWorkflow

Test Fixtures:

• Located in internal/provider/{name}/testdata/ and test/e2e/testdata/
• Sample exports for each provider (anonymized)
• Used for parser validation and regression testing

Code Style

Formatting:

# Format code (required before commit)
go fmt ./...

# Run linter
golangci-lint run

Conventions:

• Follow standard Go conventions (gofmt, golint)
• Table-driven tests preferred
• Descriptive variable names (no single-letter except loop counters)
• Comments on exported functions/types (godoc)

Configuration

Environment Variables:

# Override data directory (default: ~/.augur)
export AUGUR_DATA_DIR=/path/to/data

# Set passphrase non-interactively (for scripts/CI)
export AUGUR_PASSPHRASE="your-passphrase"

# Configure keychain cache TTL (default: 1h)
# Accepts Go duration strings: "30m", "2h", "90s"
export AUGUR_KEYCHAIN_TTL="2h"

CLI Flags:

# Override data directory via flag
augur --config-dir /path/to/data sync chatgpt --from export.zip

# Enable verbose error output
augur --verbose sync chatgpt --from export.zip

Contributing

Development Workflow:

1. Create feature branch from main: git checkout -b milestone-N-description
2. Implement following Constitution principles
3. Write tests (table-driven preferred)
4. Update contracts if interface changes (contracts/ directory)
5. Run tests: go test ./...
6. Format code: go fmt ./...
7. Commit with descriptive message
8. Push and create Pull Request

Adding a New Provider:

1. Create internal/provider/{name}/ directory
2. Implement Provider interface in {name}.go
3. Implement parser in parser.go
4. Add test fixtures in testdata/
5. Write table-driven tests in {name}_test.go
6. Update internal/cli/sync.go with new subcommand
7. Update contract: contracts/service-provider.md
8. Update this README: Supported Providers

Adding a New CLI Command:

1. Create internal/cli/{command}.go
2. Define cobra command structure
3. Implement execute{Command}() functions (testable, no direct CLI dependencies)
4. Write tests in the appropriate test file
5. Update contract: contracts/cli-service.md
6. Update this README: Command Reference

Debugging

Enable Verbose Errors:

# All commands support --verbose flag
augur sync chatgpt --from export.zip --verbose

Inspect Encrypted Files:

# Encrypted files are binary (cannot cat/less)
# Use augur to view:
augur history view <conversation-id>

Rebuild SQLite Index:

# Delete corrupted index and rebuild from encrypted files
rm ~/.augur/augur.db
augur index rebuild

---

License

Proprietary - sintheus.com

All rights reserved. This software is proprietary and may not be copied, modified, or distributed without explicit written permission from the copyright holder.

---

Support

Issues: GitHub Issues

Documentation: This README + DEVELOPER-GUIDE.md + BACKLOG.md + Constitution + Runner Docs

---

Acknowledgments

Built with:

• Cobra - CLI framework
• modernc.org/sqlite - Pure Go SQLite
• go-keyring - Cross-platform keychain
• compress/zstd - Compression
• golang.org/x/crypto - Argon2id KDF

Inspired by the need for permanent, local-first ownership of AI conversation histories.

---

Version: v0.1.0 Last Updated: 2026-02-21