Content
# SessionVault
[](https://pypi.org/project/sessionvault/)
[](LICENSE)
[](https://www.python.org/downloads/)
Unified extraction, management, and search of local conversation history across multiple AI coding tools.
**Supported Tools:** Claude Code · Codex CLI / App · Cursor · Antigravity
---
## Features
- **One-Click Sync** — Extract conversations from local storage of each tool and unify them in SQLite
- **Full-Text Search** — FTS5 engine for second-level search of all historical conversations
- **MCP Integration** — Directly search historical conversations in Cursor / Claude Code
- **Cross-Platform** — Automatic detection of paths for macOS / Windows / Linux
## Installation
```bash
pip install sessionvault
```
For MCP functionality:
```bash
pip install sessionvault[mcp]
```
For full functionality (MCP + TUI + Web UI):
```bash
pip install sessionvault[all]
```
## Quick Start
### 1. Sync Data
```bash
# Sync all tools
sessionvault sync
# Sync only a specific tool
sessionvault sync --tool claude-code
sessionvault sync --tool codex
sessionvault sync --tool cursor
# Sync only recent 7 days
sessionvault sync --since 7d
# Preview without writing
sessionvault sync --dry-run
```
### 2. Search Conversations
```bash
# Search by keyword
sessionvault search "medical data"
# Filter by tool
sessionvault search "medical data" --tool codex
# Filter by project
sessionvault search "medical data" --project medical
```
### 3. View Statistics
```bash
sessionvault stats
sessionvault projects
sessionvault sessions
```
### 4. Export Sessions
```bash
sessionvault export <session-id>
```
## MCP Integration
Directly search your historical conversations in Cursor or Claude Code.
### Cursor Configuration
Edit `~/.cursor/mcp.json` and add:
```json
{
"mcpServers": {
"sessionvault": {
"command": "python3",
"args": ["-m", "ai_conversations.mcp_server"]
}
}
}
```
> If Cursor cannot find `python3`, use the absolute path, e.g., `/usr/bin/python3` or `/opt/anaconda3/bin/python3`
### Claude Code Configuration
Add to `~/.claude/.mcp.json`:
```json
{
"mcpServers": {
"sessionvault": {
"command": "python3",
"args": ["-m", "ai_conversations.mcp_server"]
}
}
}
```
### Usage
After configuration, ask in Cursor / Claude Code:
- "Search for conversations about medical data governance"
- "List all projects across tools"
- "What did I discuss in Codex?"
The AI will automatically call `sessionvault` to search and return results.
## Data Sources
| Tool | Data Location | Format |
|---|---|---|
| Claude Code | `~/.claude/projects/` | JSONL |
| Codex CLI + App | `~/.codex/sessions/` | JSONL |
| Cursor | `~/Library/Application Support/Cursor/` | SQLite |
| Antigravity | `~/Library/Application Support/Antigravity IDE/` | SQLite |
Paths are automatically adapted for macOS / Windows / Linux.
## Project Structure
```
sessionvault/
├── pyproject.toml
├── src/ai_conversations/
│ ├── cli.py # CLI entry
│ ├── db.py # SQLite database
│ ├── models.py # Data models
│ ├── paths.py # Cross-platform path detection
│ ├── mcp_server.py # MCP server
│ └── extractors/
│ ├── base.py # Base class
│ ├── claude_code.py # Claude Code
│ ├── codex.py # Codex
│ ├── cursor.py # Cursor
│ └── antigravity.py # Antigravity
└── tests/
```
## Development
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
```
## License
Apache-2.0
