Lore

Lore captures AI coding sessions and links them to git commits.

When you use AI coding tools like Claude Code or Aider, the conversation history contains valuable context. This includes everything from the prompts you wrote, the approaches you tried, and the decisions you made. Git captures the final code, but does not contain reasoning history for your commits. Lore preserves both.

MCP Integration: Lore includes an MCP server that lets AI tools query your session history directly. Claude Code can search past sessions, retrieve context, and pick up where you left off.

Use Cases
How It Works
Installation
Quick Start
Example Workflow
MCP Server
Search
Session Awareness
Command Reference
Supported Tools
Background Daemon
Git Hooks
Output Formats
Configuration
Database Management
Session Deletion
Shell Completions
Data Location
License
Contributing

Use Cases

Code review: See the AI conversation that produced a PR, not just the diff
Debugging: Understand why code was written a certain way by reading the original discussion
Knowledge transfer: When someone leaves a project, their AI conversations stay with the code
Learning: Study how problems were solved by browsing linked sessions
Search: Find that conversation where you solved a similar problem - search by keyword, project, tool, or date

How It Works

Lore reads session data from AI coding tools, stores it in a local SQLite database, and creates links between sessions and git commits.

Capture

Lore includes parsers for each supported tool. Import existing sessions with lore import, or run lore daemon start to watch for new sessions in real-time.

Storage

Sessions and messages are stored in a SQLite database at ~/.lore/lore.db. The schema includes:

sessions: ID, tool, timestamps, working directory, message count
messages: ID, session ID, role (user/assistant), content, timestamp
session_links: Maps session IDs to git commit SHAs

Full-text search uses SQLite FTS5 to index message content.

Linking

Links connect sessions to commits. You can create them:

Manually: lore link <session-id> --commit <sha>
Via hooks: lore hooks install adds a post-commit hook that prompts for linking

Links are bidirectional: given a session, find its commits; given a commit, find its sessions.

Installation

Homebrew (macOS)

brew install varalys/tap/lore

From crates.io

cargo install lore-cli

From Releases

Download the latest binary from GitHub Releases and add it to your PATH.

From Source

git clone https://github.com/varalys/lore.git
cd lore
cargo install --path .

Quick Start

# First time? Run init for guided setup
lore init

# Or just start using lore - it will prompt for setup automatically
lore sessions

# Example output - shows branch transitions during each session
# ID        STARTED           MESSAGES  BRANCH                    DIRECTORY
# c9731a91  2025-12-25 17:52       566  main -> feat/auth -> main myapp
# 24af9690  2025-12-22 19:13      1910  feat/phase-0-foundati...  lore

# View a session
lore show abc123

# Link a session to the current commit
lore link abc123

# Later, view what sessions informed a commit
lore show --commit HEAD

Example Workflow

# You're reviewing a PR and want to understand a change
$ git log --oneline -1
a1b2c3d feat: add rate limiting to API

$ lore show --commit a1b2c3d
Sessions linked to commit a1b2c3d:

  Session: 7f3a2b1
  Tool: claude-code
  Duration: 45 minutes
  Messages: 23

# View the full conversation
$ lore show 7f3a2b1

MCP Server

Lore includes an MCP (Model Context Protocol) server that allows AI coding tools to query your session history directly. This enables tools like Claude Code to access your past sessions and reasoning history.

Starting the Server

lore mcp serve

The server runs on stdio and responds to MCP protocol requests.

Configuring Claude Code

Add Lore to your Claude Code MCP settings. Edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Claude Code after editing the configuration.

Available Tools

The MCP server exposes these tools to AI assistants:

Tool	Description
`lore_search`	Search session messages for text content
`lore_get_session`	Get full details of a session by ID
`lore_list_sessions`	List recent sessions with optional filters
`lore_get_context`	Get recent session context for a repository
`lore_get_linked_sessions`	Get sessions linked to a git commit

Example Usage

Once configured, Claude Code can use Lore tools naturally:

"Search my sessions for authentication code"
"Show me the last session in this project"
"What sessions are linked to the previous commit?"

The AI assistant will automatically call the appropriate Lore tools and incorporate the results into its responses.

Search

Find any conversation across all your AI coding sessions:

# Basic search
lore search "authentication"

# Filter by tool
lore search "bug fix" --tool claude-code

# Filter by date range
lore search "refactor" --since 2025-12-01 --until 2025-12-15

# Filter by project or branch
lore search "api" --project myapp
lore search "feature" --branch main

# Combine filters
lore search "database" --tool aider --project backend --since 2025-12-01

# Show more context around matches
lore search "error handling" --context 3

Search matches message content, project names, branches, and tool names. Results show surrounding context so you can understand the conversation flow.

Session Awareness

Lore helps you pick up where you left off and organize your sessions:

# See what session is active in the current directory
lore current

# Get quick context on recent sessions in this repo
lore context

# Get detailed summary of the last session (for "continue where we left off")
lore context --last

# Add a bookmark or note to the current session
lore annotate "Implemented auth, need to add tests"

# Tag sessions for organization
lore tag abc123 needs-review
lore tag abc123 feature-auth
lore sessions --tag needs-review    # Filter by tag

# Add a summary to a session for future reference
lore summarize abc123 "Added OAuth2 login flow with Google and GitHub providers"
lore summarize abc123 --show        # View existing summary

Tags, annotations, and summaries appear in lore show output and help you quickly understand past sessions.

Command Reference

Essential commands to get started:

lore init           # First-run setup (auto-detects AI tools)
lore import         # Import sessions from enabled tools
lore sessions       # List recent sessions
lore show <id>      # View session details
lore search <query> # Full-text search
lore context --last # Quick summary of last session
lore daemon start   # Start real-time capture

Run lore --help for the full command list, or lore <command> --help for details on any command.

Supported Tools

Lore targets Linux, macOS, and WSL2. Windows native support is planned for a future release. For WSL2, CLI-based tools work as long as the sessions live in the Linux filesystem. VS Code extension sessions are only discovered when the extensions run in WSL (Remote - WSL); if you run VS Code natively on Windows, those sessions live under %APPDATA% and are not detected today.

Tool	Format	Storage Location
Claude Code	JSONL	`~/.claude/projects/`
Codex CLI	JSONL	`~/.codex/sessions/`
Gemini CLI	JSON	`~/.gemini/tmp/*/chats/`
Amp	JSON	`~/.local/share/amp/threads/`
Aider	Markdown	`.aider.chat.history.md`
Continue.dev	JSON	`~/.continue/sessions/`
Cline	JSON	VS Code extension storage
Roo Code	JSON	VS Code extension storage
Kilo Code	JSON	VS Code extension storage
OpenCode	JSON	`~/.local/share/opencode/storage/`

Building an AI coding tool? We welcome contributions to support additional tools. Open an issue with your tool's session storage location and format, or submit a PR adding a watcher. See CONTRIBUTING.md for details.

Background Daemon

The daemon watches for new sessions in real-time and imports them automatically.

Manual Start

lore daemon start    # Start watching
lore daemon status   # Check what's being watched
lore daemon logs     # View daemon logs
lore daemon stop     # Stop watching

Run as a Service

Install the daemon as a system service to start automatically on login.

macOS with Homebrew (Recommended)

If you installed via Homebrew, use brew services:

brew services start lore
brew services stop lore

Linux with systemd

Use the built-in service installer:

lore daemon install    # Install and enable systemd service
lore daemon uninstall  # Remove systemd service

The service restarts automatically on failure.

Manual systemd Setup (Linux)

If you prefer to configure systemd yourself:

mkdir -p ~/.config/systemd/user

Create ~/.config/systemd/user/lore.service:

[Unit]
Description=Lore AI session capture daemon
After=default.target

[Service]
Type=simple
ExecStart=%h/.cargo/bin/lore daemon start --foreground
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Then enable and start:

systemctl --user daemon-reload
systemctl --user enable --now lore.service
systemctl --user status lore.service

Git Hooks

Install hooks to automatically record session links on commit:

lore hooks install   # Install post-commit hook
lore hooks status    # Check hook status
lore hooks uninstall # Remove hooks

Output Formats

Commands support --format for scripting and integration:

lore sessions --format json
lore show abc123 --format json
lore show abc123 --format markdown
lore status --format json

Configuration

On first run, Lore prompts for setup automatically. You can also run lore init manually.

The init wizard:

Detects installed AI coding tools
Shows which tools have existing sessions
Lets you choose which watchers to enable
Offers to import existing sessions
Offers to install shell completions
Offers to start the background service (for real-time capture)

Configure which tools to track:

lore config set watchers claude-code,aider,gemini
lore config get watchers

For scripting, use --no-init to skip the first-run prompt:

lore --no-init sessions --format json

Database Management

Lore provides commands for managing the database:

# View database statistics
lore db stats

# Example output:
# Database Statistics
#
#   Sessions:  142
#   Messages:  8934
#   Links:     67
#   File size: 12.45 MB
#
# Date Range
#   Oldest:   2024-06-15 09:23
#   Newest:   2025-01-02 14:56
#
# Sessions by Tool
#    claude-code:  98
#          aider:  31
#         gemini:  13

# Reclaim unused disk space
lore db vacuum

# Delete old sessions (preview first with --dry-run)
lore db prune --older-than 90d --dry-run
lore db prune --older-than 6m --force

Duration formats for --older-than:

Nd - days (e.g., 90d)
Nw - weeks (e.g., 12w)
Nm - months (e.g., 6m)
Ny - years (e.g., 1y)

Session Deletion

Delete a single session and all its data:

lore delete abc123

This permanently removes the session, its messages, and any commit links.

Shell Completions

The easiest way to install completions is to let Lore auto-detect your shell:

lore completions install

Or specify a shell explicitly:

lore completions install --shell fish

You can also output completions to stdout for manual installation:

lore completions bash > ~/.local/share/bash-completion/completions/lore
lore completions zsh > ~/.zfunc/_lore
lore completions fish > ~/.config/fish/completions/lore.fish

After installing, restart your shell or source the completion file.

PowerShell and Elvish completions are also available (lore completions powershell, lore completions elvish) and will be documented when Windows support is added.

Data Location

~/.lore/
├── lore.db       # SQLite database
├── config.yaml   # Configuration
└── logs/         # Daemon logs

All data stays on your machine. There is no cloud sync or external service.

License

Apache 2.0

Contributing

See CONTRIBUTING.md.

lore-cli 0.1.3