A Reasoning Engine for Code

Stores the "why" behind changes

Create a high-context repository where AI agents don't just read your code — they read the minds of previous developers and agents who worked on it.

Get Started View on GitHub

What Lore Captures

While Git tells you who changed code and when, Lore tells you why.

★

Intent

Brief description of what you were trying to accomplish

⚙

Reasoning Trace

Full chain-of-thought, which can be thousands of words

✕

Rejected Alternatives

What you tried but didn't work (and why)

✎

Tags

Categorization for easy searching

All entries are cryptographically linked to file content hashes and optionally to Git commits.

Why Lore?

Feature Comments Commit Messages Lore
Volume Must be short ~50 chars Unlimited (5000+ words)
Searchable Code only Messages only Full reasoning + alternatives
Stability Often deleted Can be amended Immutable, hash-linked
Context What the code does What changed Why it was written that way

Smart Merge Conflict Resolution

When multiple developers work on different branches, Lore preserves all reasoning using append-only merges

❌ Without Lore

Traditional merge conflict:

Branch A: "Refactored JWT validation"

Branch B: "Optimized token caching"

→ Choose one, lose the other ✗

Loss of context and decision history

✓ With Lore

Append-only merge strategy:

Branch A: "Refactored JWT validation"

Branch B: "Optimized token caching"

→ Keep both entries ✓

Complete decision history preserved

Zero Conflicts

No manual merge resolution needed—automatic append-only strategy

Preserve All

Both branches' reasoning preserved together, no context lost

Complete History

View complete decision history with lore explain --all

Example

# After merging two branches with conflicting reasoning
$ lore explain src/auth.rs --all

Agent: claude-code (feature/auth) │ 2026-01-14 10:00:00 UTC
Intent: Refactored JWT validation for security hardening

Agent: claude-code (feature/perf) │ 2026-01-14 11:30:00 UTC
Intent: Optimized token validation caching

# Both perspectives visible—complete context preserved!

Installation

Pre-built binaries are available for Linux, macOS, and Windows

Linux

# x86_64
sudo curl -L https://github.com/avraammavridis/lore/releases/latest/download/lore-linux-x86_64 -o /usr/local/bin/lore && sudo chmod +x /usr/local/bin/lore

# ARM64
sudo curl -L https://github.com/avraammavridis/lore/releases/latest/download/lore-linux-aarch64 -o /usr/local/bin/lore && sudo chmod +x /usr/local/bin/lore

macOS

# Apple Silicon (M1/M2/M3)
sudo curl -L https://github.com/avraammavridis/lore/releases/latest/download/lore-macos-aarch64 -o /usr/local/bin/lore && sudo chmod +x /usr/local/bin/lore

# Intel
sudo curl -L https://github.com/avraammavridis/lore/releases/latest/download/lore-macos-x86_64 -o /usr/local/bin/lore && sudo chmod +x /usr/local/bin/lore

Windows

Download the executable:

Download lore.exe

Or use PowerShell (run as Administrator):

iwr "https://github.com/avraammavridis/lore/releases/latest/download/lore-windows-x86_64.exe" -OutFile "$env:ProgramFiles\lore.exe"

Or view all releases • Build from source

AI Agent Integration

Lore is designed to work seamlessly with AI coding assistants. Add context that persists across sessions.

No Lost Context

Each agent's reasoning is preserved forever

Avoid Repeated Mistakes

Rejected alternatives prevent re-exploring dead ends

Understand Intent

Future agents know why code exists, not just what it does

Searchable History

Query reasoning across the entire project history

Add to your agent's system instructions:

You have access to a tool called `lore`.

Before you edit a file, run `lore explain <file>` to understand the hidden context.

After you finish a task, run `lore record` to save your chain-of-thought
so future agents understand your decisions.
Claude

Claude Code Integration

Configure Claude Code to automatically use Lore for every code change

1. Initialize Lore in your project

lore init --agent "claude-code"

2. Create a CLAUDE.md file in your project root

This file instructs Claude Code to use Lore automatically:

# Lore Integration

Before modifying any file, check for existing reasoning:
  lore explain <file-path>

After completing any code change, record your reasoning:
  lore record -f <file> -m "Brief description" \
      --trace "Full reasoning..." \
      -r "Rejected alternative" \
      -T relevant-tag

3. Commit CLAUDE.md to your repository

All Claude Code sessions will now automatically use Lore

Cursor

Cursor Integration

Configure Cursor to use Lore for persistent reasoning context

1. Initialize Lore in your project

lore init --agent "cursor"

2. Create a .cursorrules file in your project root

Add these instructions to configure Cursor's AI:

# Lore Integration for Cursor

This project uses Lore to track reasoning behind code changes.

## Before Editing Files
Before modifying any file, check if there's existing reasoning:
  lore explain <file-path>

## After Making Changes
After completing code changes, record your reasoning:
  lore record -f <changed-file> \
      -m "Brief description of what you did" \
      --trace "Your full reasoning explaining:
  - Why you made these specific changes
  - What alternatives you considered
  - Any trade-offs or concerns" \
      -r "Alternative you rejected" \
      -T relevant-tag

3. Alternative: Use Cursor Settings

Add to Cursor's "Rules for AI" in Settings > General > Rules for AI:

When working on code:
1. Before editing any file, run 'lore explain <file>' to check for existing context
2. After making changes, run 'lore record' with your reasoning
3. Include rejected alternatives with -r flag
4. Add relevant tags with -T flag

Manual Usage

You can also use Lore directly from the command line

Initialize Lore in your project

lore init --agent "my-agent-id"

Record your reasoning after making changes

lore record -m "Refactoring auth to handle JWTs" \
    --trace "I initially tried using library X, but it conflicted..."

Understand why code exists

lore explain src/auth_middleware.py

Search through reasoning history

lore search "JWT"
lore search "pandas"  # Find all code avoiding pandas

Commands Reference

lore init

Initialize a new Lore repository

lore init --agent "my-agent-id"

lore record

Record reasoning for code changes

lore record -m "Intent" --trace "..."

lore explain

Retrieve reasoning behind a file

lore explain src/auth.py --all

lore search

Search through reasoning history

lore search "JWT" --file auth

lore list

List all recorded entries

lore list --limit 20 --json

lore status

Show Lore status for the repo

lore status

Data Storage

Lore stores data in .lore/ folder (intended to be committed to Git)

.lore/
├── config.json       # Repository configuration
├── index.json        # File → entry ID mappings
├── entries/          # Individual thought objects
│   ├── uuid1.json
│   ├── uuid2.json
│   └── ...
└── .gitignore        # Ignores temp files

Each entry is a JSON file

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "target_file": "src/auth_middleware.py",
  "line_range": [10, 45],
  "file_hash": "sha256:...",
  "commit_hash": "a1b2c3d4...",
  "agent_id": "claude-3-5-sonnet",
  "timestamp": "2024-02-14T10:00:00Z",
  "intent": "Refactoring auth to handle JWTs",
  "reasoning_trace": "I initially tried using library X...",
  "rejected_alternatives": [
    {"name": "Auth0 SDK", "reason": "Dependency conflicts"}
  ],
  "tags": ["auth", "security"]
}