ricoeur 0.1.1

A local-first archive, search, and intelligence engine for your LLM conversation history.

ricoeur

A local-first archive, search, and intelligence engine for your LLM conversation history.

Named after Paul Ricoeur, whose work on narrative identity argued that we understand ourselves through the stories we construct from our lived experience. ricoeur reconstructs the narrative of your intellectual life from thousands of AI conversations.

Quickstart

# Install with uv
uv sync

# Initialize the database
uv run ricoeur init

# Import your ChatGPT export
uv run ricoeur import chatgpt ~/Downloads/chatgpt-export/conversations.json

# Import your Claude export
uv run ricoeur import claude ~/Downloads/claude-export/conversations.json

# See what you've got
uv run ricoeur stats

# Search your history
uv run ricoeur search "thermal simulation"

Commands

Command	Description
ricoeur init	Initialize database and config at ~/.ricoeur/
ricoeur import chatgpt <path>	Import from ChatGPT export (.json or .zip)
ricoeur import claude <path>	Import from Claude export (.json or .zip)
ricoeur search <query>	Full-text search across all conversations
ricoeur show <id>	Display a conversation with formatting
ricoeur stats	Analytics dashboard
ricoeur config show	Print current configuration
ricoeur config set <key> <value>	Update a config value

Search

# Basic full-text search
ricoeur search "streamlit dashboard"

# Filter by platform, language, date
ricoeur search "error fix" --platform chatgpt --lang en
ricoeur search "strategie marketing" --lang fr --since 2025-01-01

# Search only in code blocks
ricoeur search "import pandas" --code

# Output formats: table (default), json, full, ids
ricoeur search "MCP" --format json

Import options

# Re-import safely (updates existing, adds new, never deletes)
ricoeur import chatgpt conversations.json --update

# Dry run — parse and validate without writing
ricoeur import chatgpt conversations.json --dry-run

# Only import recent conversations
ricoeur import claude conversations.json --since 2025-01-01

Optional extras

Install additional capabilities as needed:

# Semantic search with sentence-transformers
uv sync --extra embeddings

# Topic modeling with BERTopic
uv sync --extra topics

# Analytics with DuckDB + Parquet
uv sync --extra analytics

# Terminal UI
uv sync --extra tui

# MCP server for Claude Desktop
uv sync --extra mcp

# Web API server
uv sync --extra serve

# Everything
uv sync --extra all

Configuration

Config lives at ~/.ricoeur/config.toml:

[general]
home = "~/.ricoeur"
default_language = "en"

[embeddings]
model = "st:paraphrase-multilingual-mpnet-base-v2"
batch_size = 64
device = "auto"

[topics]
min_cluster_size = 15
n_topics = "auto"

[summarize]
enabled = false
model = "ollama:llama3.2"

Override the data directory with the RICOEUR_HOME environment variable.

Architecture

~/.ricoeur/
├── config.toml          # Configuration
├── ricoeur.db           # SQLite database (FTS5 search)
├── analytics/           # Parquet files for DuckDB
├── embeddings/          # Sentence-transformer vectors
├── models/              # Saved BERTopic models
└── attachments/         # Extracted files

License

MIT