# Lore

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![CI](https://github.com/varalys/lore/actions/workflows/ci.yml/badge.svg)](https://github.com/varalys/lore/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/varalys/lore)](https://github.com/varalys/lore/releases)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20WSL2-blue)

**Reasoning history for code.**

Lore records your AI coding sessions and links them to git commits. Run `lore blame` on any line to see the conversation that produced it. Sessions sync through your existing git remotes, encrypted, with no server and no account.

**Documentation:** [lore.varalys.com](https://lore.varalys.com)

## 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
- **Knowledge transfer**: AI conversations stay with the code when people leave
- **Search**: Find that conversation where you solved a similar problem

## Installation

### Homebrew (macOS)

```bash
brew install varalys/tap/lore
```

### Arch Linux (AUR)

```bash
yay -S lore-cli-bin
```

Or with any AUR helper. See [lore-cli-bin](https://aur.archlinux.org/packages/lore-cli-bin).

### From crates.io

```bash
cargo install lore-cli
```

### From Releases

Download from [GitHub Releases](https://github.com/varalys/lore/releases).

## Quick Start

```bash
# Initial setup (detects tools, imports sessions)
lore init

# List sessions
lore sessions

# View a session
lore show abc123

# Link to current commit
lore link abc123

# Link active sessions in this repo to HEAD
lore link --current

# Find sessions for a commit
lore show --commit HEAD

# Trace a line of code to its AI session
lore blame src/main.rs:42

# Search across all sessions
lore search "authentication"

# Sync reasoning history over git (encrypted, serverless)
lore sync setup
lore sync
```

### Example: ```lore blame```

```
$ lore blame src/auth.rs:42

Commit:
  a1b2c3d4  <username> 2025-12-15 14:30
  feat: add rate limiting to login endpoint

Line content:
      if attempts > 5 { return Err(RateLimitExceeded) }

Linked sessions (1):

  f8e7d6c5  claude-code (127 messages)
    Started: 2025-12-15 13:45
    Relevant context:
      ...decided on 5 attempts as the threshold based on industry standards...
      Let me add rate limiting to prevent brute force attacks.
```

## Key Features

| Feature | Description |
|---------|-------------|
| **Blame** | Trace any line of code to the AI session that produced it |
| **Git-ref Sync** | Sync reasoning through your existing git remotes, encrypted; share by passphrase |
| **Cross-tool Memory** | Mirror one tool's project memory so any LLM can read it over MCP |
| **Session Capture** | One history across 10+ AI coding tools |
| **Git Linking** | Connect sessions to commits |
| **Full-text Search** | Find any past conversation |
| **MCP Server** | Let AI tools query your history |
| **Background Daemon** | Real-time capture (optional) |

## Sync

Lore syncs reasoning history through your existing git remotes, with no server and no account. Sessions are encrypted on your machine before they touch a remote, so the git host only ever sees ciphertext.

- **Per-repo store**: encrypted sessions ride inside the project's own repo under `refs/lore/sessions`, so reasoning travels with the code. A teammate who clones the repo and knows the shared passphrase can read it and run `lore blame`.
- **Global store** (`lore sync --global`): a private aggregate of all your sessions across every tool and repo, for multi-machine backup.
- **Automatic sync**: `lore hooks install` adds a `pre-push` hook that runs `lore sync` on every `git push` (best-effort, never blocks the push).
- **Team sharing**: share the repo plus the passphrase out of band. No accounts, no seats, serverless.

See the [Sync Guide](https://lore.varalys.com/guides/sync/) for details.

## Memory

Coding tools write their own per-project memory (running notes, next steps, corrections) that other tools cannot see. Lore mirrors that memory and exposes it over MCP, so switching tools keeps the context. Point Codex, or any MCP client, at `lore mcp serve` and it can read the memory another tool wrote for the same repo.

- Read-only: Lore mirrors the tool's memory files, it never modifies them.
- Scoped to the current repo.
- `lore memories` lists what has been mirrored.

Currently mirrors Claude Code memory, with more tools to follow. See the [Memory Guide](https://lore.varalys.com/guides/memory/) for details.

## Supported Tools

Claude Code, Codex CLI, Gemini CLI, Amp, Aider, Continue.dev, Cline, Roo Code, Kilo Code, OpenCode

See [Supported Tools](https://lore.varalys.com/reference/supported-tools/) for details.

## MCP Integration

Let Claude Code query your session history:

```bash
claude mcp add lore -- lore mcp serve
```

Claude can then search sessions, retrieve context, and continue where you left off.

See [MCP Guide](https://lore.varalys.com/guides/mcp/) for setup details.

## Documentation

Full documentation at **[lore.varalys.com](https://lore.varalys.com)**:

- [Installation](https://lore.varalys.com/getting-started/installation/)
- [Quick Start](https://lore.varalys.com/getting-started/quick-start/)
- [Command Reference](https://lore.varalys.com/commands/)
- [Guides](https://lore.varalys.com/guides/linking/)
- [FAQ](https://lore.varalys.com/about/faq/)

## Data Location

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

All data stays on your machine by default. Sync is opt-in and encrypted end to end.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
