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

This project uses Lore to track reasoning behind code changes. Lore creates a
"high-context" repository where you can understand not just what the code does,
but *why* it was written that way.

## Before Editing Files

Before modifying any file, check if there's existing reasoning context:

  lore explain <file-path>

This will show you:
- Why the code was written this way
- What alternatives were considered and rejected
- Any warnings or notes from previous developers/agents

## After Making Changes

After completing any code change, you MUST record your reasoning:

  lore record -f <changed-file> \
      -m "Brief description of what you did" \
      --trace "Your full reasoning and chain-of-thought explaining:
  - Why you made these specific changes
  - What alternatives you considered
  - Any trade-offs or concerns
  - Warnings for future developers" \
      -r "Alternative 1 you rejected" \
      -r "Alternative 2 you rejected" \
      -T relevant-tag

## Important Guidelines

1. Always run `lore explain` before editing unfamiliar code
2. Always run `lore record` after completing changes
3. Include rejected alternatives - helps future agents avoid dead ends
4. Add warnings about fragile code
5. Be verbose in reasoning traces - more context is always better

3. Few-Shot Examples for CLAUDE.md

Include these examples in your CLAUDE.md to help agents understand the expected format:

Example 1: Bug Fix

lore record -f src/worker.py \
    -m "Fixed race condition in job processing" \
    --trace "The worker was occasionally processing the same job twice because
the job status check and status update weren't atomic. I added a Redis-based
distributed lock using the SETNX command with a 30-second TTL.

I chose 30 seconds because our longest job takes ~20 seconds, giving a 50% buffer.

Warning: If Redis is unavailable, jobs will fail rather than risk duplicates.
This is intentional - duplicate processing causes billing issues." \
    -r "Database row-level locking (too slow, 100ms+ latency)" \
    -r "In-memory lock (doesn't work across multiple workers)" \
    -T bugfix -T concurrency -T redis

Example 2: New Feature

lore record -f src/api/users.py -f src/models/user.py \
    -m "Added user export endpoint for GDPR compliance" \
    --trace "Added GET /api/users/{id}/export endpoint that returns all user data
in JSON format. This is required for GDPR Article 20 (right to data portability).

The endpoint:
1. Requires authentication and user can only export their own data
2. Includes rate limiting (1 request per hour) to prevent abuse
3. Streams large responses to avoid memory issues

Note: We intentionally exclude the 'internal_notes' field from exports as legal
confirmed this is not considered user data under GDPR." \
    -r "CSV format (JSON is more portable and preserves data types)" \
    -r "Background job with email (adds complexity, users want immediate download)" \
    -T feature -T gdpr -T api

Example 3: Refactoring

lore record -f src/billing/calculator.py \
    -m "Refactored billing calculator to use strategy pattern" \
    --trace "The billing calculator had grown to 800+ lines with deeply nested
if/else chains for different pricing tiers. I refactored to use the strategy pattern:

- Created PricingStrategy abstract base class
- Implemented FreeTier, ProTier, EnterpriseTier strategies
- Calculator now delegates to the appropriate strategy

This reduces the main class from 800 to 150 lines.

IMPORTANT: The old calculate_legacy() method is kept for billing runs before
2024-01-01. Do not remove it until we've migrated all historical invoices.
See ticket BILL-1234 for migration timeline." \
    -r "Simple function extraction (doesn't solve the core complexity)" \
    -r "Configuration-driven pricing (not flexible enough for enterprise deals)" \
    -T refactoring -T billing -T design-pattern

4. 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

This project uses Lore to track reasoning behind code changes. Lore creates a
"high-context" repository where you can understand not just what the code does,
but *why* it was written that way.

## Before Editing Files

Before modifying any file, check if there's existing reasoning context:

  lore explain <file-path>

This will show you:
- Why the code was written this way
- What alternatives were considered and rejected
- Any warnings or notes from previous developers/agents

## After Making Changes

After completing any code change, you MUST record your reasoning:

  lore record -f <changed-file> \
      -m "Brief description of what you did" \
      --trace "Your full reasoning and chain-of-thought explaining:
  - Why you made these specific changes
  - What alternatives you considered
  - Any trade-offs or concerns
  - Warnings for future developers" \
      -r "Alternative 1 you rejected" \
      -r "Alternative 2 you rejected" \
      -T relevant-tag

## Important Guidelines

1. Always run `lore explain` before editing unfamiliar code
2. Always run `lore record` after completing changes
3. Include rejected alternatives - helps future agents avoid dead ends
4. Add warnings about fragile code
5. Be verbose in reasoning traces - more context is always better

3. Few-Shot Examples for .cursorrules

Include these examples in your .cursorrules to help agents understand the expected format:

Example 1: Bug Fix

lore record -f src/worker.py \
    -m "Fixed race condition in job processing" \
    --trace "The worker was occasionally processing the same job twice because
the job status check and status update weren't atomic. I added a Redis-based
distributed lock using the SETNX command with a 30-second TTL.

I chose 30 seconds because our longest job takes ~20 seconds, giving a 50% buffer.

Warning: If Redis is unavailable, jobs will fail rather than risk duplicates.
This is intentional - duplicate processing causes billing issues." \
    -r "Database row-level locking (too slow, 100ms+ latency)" \
    -r "In-memory lock (doesn't work across multiple workers)" \
    -T bugfix -T concurrency -T redis

Example 2: New Feature

lore record -f src/api/users.py -f src/models/user.py \
    -m "Added user export endpoint for GDPR compliance" \
    --trace "Added GET /api/users/{id}/export endpoint that returns all user data
in JSON format. This is required for GDPR Article 20 (right to data portability).

The endpoint:
1. Requires authentication and user can only export their own data
2. Includes rate limiting (1 request per hour) to prevent abuse
3. Streams large responses to avoid memory issues

Note: We intentionally exclude the 'internal_notes' field from exports as legal
confirmed this is not considered user data under GDPR." \
    -r "CSV format (JSON is more portable and preserves data types)" \
    -r "Background job with email (adds complexity, users want immediate download)" \
    -T feature -T gdpr -T api

Example 3: Refactoring

lore record -f src/billing/calculator.py \
    -m "Refactored billing calculator to use strategy pattern" \
    --trace "The billing calculator had grown to 800+ lines with deeply nested
if/else chains for different pricing tiers. I refactored to use the strategy pattern:

- Created PricingStrategy abstract base class
- Implemented FreeTier, ProTier, EnterpriseTier strategies
- Calculator now delegates to the appropriate strategy

This reduces the main class from 800 to 150 lines.

IMPORTANT: The old calculate_legacy() method is kept for billing runs before
2024-01-01. Do not remove it until we've migrated all historical invoices.
See ticket BILL-1234 for migration timeline." \
    -r "Simple function extraction (doesn't solve the core complexity)" \
    -r "Configuration-driven pricing (not flexible enough for enterprise deals)" \
    -T refactoring -T billing -T design-pattern

4. 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"]
}