Claude Vault

Transform your Claude conversations into a searchable, organized knowledge base in Obsidian.

Quick Start

pip install -e .
claude-vault init          # run inside your Obsidian vault folder
claude-vault sync ~/Downloads/conversations.json

That's it. Your conversations are now in conversations/ as Markdown files.

Installation

Requirements: Python 3.9+, optional: Ollama for AI tagging and semantic search.

git clone https://github.com/MarioPadilla/claude-vault.git
cd claude-vault
python3 -m venv venv && source venv/bin/activate
pip install -e .

Optional — Ollama setup for AI features:

ollama serve
ollama pull llama3.2:3b        # for tagging & summarization
ollama pull nomic-embed-text   # for semantic search

Features

• Local-first — everything stays on your machine, no external APIs required
• Three import formats — Claude Web exports (.json), Claude Code history (.jsonl), and OpenCode sessions (.db) auto-detected
• AI tagging & summarization — local LLM (Ollama) generates tags and summaries; falls back to keyword extraction
• Semantic search — find conversations by concept, not just exact words
• Smart relationship detection — automatically links related conversations via shared tags
• Bi-directional sync — rename or move files freely; UUID tracking keeps everything in sync
• Watch mode — auto-syncs when your export files change
• PII protection — detect, redact, or skip conversations containing personal or sensitive data
• Dry-run mode — preview all changes before writing anything

Usage

Export your conversations

1. Go to claude.ai → Settings → Export data
2. This downloads conversations.json
3. For Claude Code history, point directly at ~/.claude

Sync

# Web export (auto-detected)
claude-vault sync ~/Downloads/conversations.json

# Claude Code history
claude-vault sync ~/.claude

# OpenCode (auto-detected from .db extension)
claude-vault sync ~/.local/share/opencode/opencode.db

# OpenCode (uses default path)
claude-vault sync --source opencode

# Preview changes without writing
claude-vault sync conversations.json --dry-run

Search

# Semantic search (requires Ollama + nomic-embed-text)
claude-vault search "async error handling"

# Keyword search
claude-vault search "python" --mode keyword

# Filter by tag
claude-vault search "API" --tag debugging

Watch mode

claude-vault watch-add ~/Downloads --source web   # register a path
claude-vault watch                                # start (foreground)
claude-vault watch-status
claude-vault watch-stop

PII & sensitive content protection

Scan conversations for personal or confidential data before they are written to disk.

Off by default. Without --detect-pii (or pii.enabled in the config) nothing is scanned, and a sync writes your conversations exactly as they are, including any password or API key you pasted into a chat. sync tells you when it wrote files without a scan. This matters most if your vault lives in a synced folder (Drive, iCloud, Dropbox).

What it looks for:

• Provider tokens: Anthropic, OpenAI, GitHub, GitLab, Google, AWS, Slack, Stripe, Hugging Face, npm, SendGrid
• JWTs, Authorization: Bearer/Basic headers, private key blocks, and connection strings with a password
• name = value credentials (password:, api_key=, AWS_SECRET_ACCESS_KEY=...), and long random-looking tokens
• Emails, phone numbers, SSNs (US format), credit card numbers (checksum-validated), IP addresses
• If Ollama is running, an LLM pass also classifies broader sensitive content

It is built for coding sessions: git SHAs, hashes, UUIDs, identifiers and token counts are not flagged.

Risk levels: high (SSN, card, provider token, JWT, private key, connection string), medium (email, phone, random token), low (IP, credential context).

# Tag conversations that contain PII (adds pii-* tags + frontmatter fields)
claude-vault sync conversations.json --detect-pii

# Redact PII before writing — stored files contain [REDACTED-EMAIL] etc.
claude-vault sync conversations.json --detect-pii --redact-pii

# Skip conversations at medium risk or above entirely
claude-vault sync conversations.json --detect-pii --skip-sensitive

To make these behaviours permanent, set them in ~/.claude-vault/config.json:

{
  "pii": {
    "enabled": false,
    "redact": false,
    "skip_sensitive": false,
    "use_llm": true,
    "risk_threshold": "medium"
  }
}

If the config file cannot be read (invalid JSON, wrong value), Claude Vault warns and falls back to the defaults, which means PII handling is off.

What scanned files look like. Every conversation that went through the scan carries pii_scanned: true, pii_detector (the detector version) and pii_llm (false when only the regex pass ran, for example because Ollama was down). A conversation with none of these was never scanned: treat it as unknown, not as clean. Findings add pii_detected, risk_level and pii_types. When the detector improves, the next PII-enabled sync scans each conversation once more.

Limits to know about

• Redacting the vault does not undo a leak. A key that appeared in a chat was already sent to the model provider. If a real credential shows up, rotate it.
• Your source data is untouched. Claude Code keeps plaintext transcripts in ~/.claude/projects/. Claude Vault only controls what it writes into your vault; it does not clean those files.
• --skip-sensitive does not remove files that already exist. It keeps new sensitive conversations out. If a file was written before, sync lists it ("already in your vault, not removed") and leaves it for you to delete or move.
• Detection is pattern matching plus an optional LLM, not a guarantee. It misses secrets that have no recognisable format (for example a bare hex key), and it can flag harmless text. Review a vault before sharing it.
• Redaction covers message text, titles and summaries. A file that already exists keeps its old filename on re-sync.

Other commands

claude-vault status              # vault statistics
claude-vault retag               # regenerate AI tags (requires Ollama)
claude-vault retag --force       # regenerate even existing tags
claude-vault verify              # check file/database consistency
claude-vault verify --cleanup    # remove orphaned database entries
claude-vault config              # view current configuration

Use claude-vault [command] --help for full options on any command.

Configuration

Global config lives at ~/.claude-vault/config.json. Run claude-vault config to view and edit it.

Key settings:

Troubleshooting

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for setup and pull request guidelines.

License

Claude Vault is dual-licensed:

AGPL-3.0 (free) — for personal use, open-source projects, education, and non-commercial work. Modifications must be shared under the same license.

Commercial license — required for proprietary applications, SaaS products, or any deployment where you cannot comply with AGPL-3.0 copyleft terms. Contact via GitHub for pricing.