Lore Documentation

Everything you need to get started with Lore, the AI coding agent that remembers your project.

Installation

Lore ships as a single binary. No dependencies, no runtime, no IDE required.

One-liner install (recommended)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/fayzkk889/lore/main/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/fayzkk889/lore/main/install.ps1 | iex

Manual download

Grab the latest release for your platform from GitHub Releases:

Install (macOS / Linux)

# Extract and move to your PATH
tar -xzf lore_*.tar.gz
sudo mv lore /usr/local/bin/
lore --version

Install (Windows)

# Extract the zip, then add the folder to your PATH
# Or just run lore.exe directly from the extracted folder
.\lore.exe --version

Authentication

Lore uses Google OAuth for authentication. One command, pick your Google account, and you're in. Free tier gives you 300K tokens/month with every feature included.

Sign in with Google

Run the login command. Your browser opens, you pick a Google account, and the CLI authenticates automatically:

lore auth login

That's it. No license keys, no email forms, no copy-pasting UUIDs. The CLI spins up a local server, receives the session token from Google OAuth, and stores it securely.

Manual fallbacks

If the browser flow doesn't work (headless server, SSH session), you can authenticate manually:

# Paste a session token from the browser fallback page
lore auth login --token YOUR-SESSION-TOKEN

# Legacy license key (backward compatible)
lore auth login --key YOUR-LICENSE-KEY

Check your current auth status anytime:

lore auth status

This shows your email, tier, token cap, and current monthly usage. To log out:

lore auth logout

Upgrading to a paid tier

Pick a plan on loredev.co and check out with the same email you used for Google sign-in. Your tier upgrades automatically on the next CLI request. No action needed.

Quick start

Three commands to go from zero to productive:

# 1. Authenticate (free tier or paid key)
lore auth login

# 2. Initialize your project (scans codebase, builds wiki)
cd your-project/
lore init

# 3. Start coding
lore

That's it. Lore scans your project, builds a wiki, and you're chatting with full project context. Every session after this starts with all prior knowledge loaded automatically.

Plans + tokens

Every plan includes every feature. Wiki memory, teach mode, diff preview, rollback, self-check, PDF export. The only difference is how many tokens you get per month.

Token usage is tracked server-side per license. When you hit your monthly cap, requests are blocked until the next month. The counter resets automatically on the 1st of each month.

Your local budget settings (in config.toml) work alongside the server-side cap. You can set a dollar-based cap that's lower than your tier limit for personal spending control.

Wiki memory

Lore's core differentiator. A .lore/ directory at your project root that stores everything Lore learns about your codebase. It's human-readable, git-tracked, and yours forever.

How it works

When you run lore init, Lore scans your project directory (skipping node_modules, .git, etc.), collects file structure and code samples, and generates wiki pages covering your architecture, conventions, and patterns.

On each subsequent session, Lore loads the wiki into its context. When you exit (or type /exit), Lore compiles everything discussed into wiki updates: new pages for new topics, edits to existing pages, and a log entry in log.md.

Wikilinks

Wiki pages reference each other with [[double-bracket]] links, just like Obsidian or Notion. When Lore encounters a wikilink in conversation, it loads that page into context dynamically. The more you use Lore, the richer the web of knowledge becomes.

LORE.md

Drop a LORE.md file in your project root with standing instructions that Lore follows every session. Think of it as your project's coding constitution.

# Project Rules
- Use error wrapping with fmt.Errorf
- Never use global variables
- All functions must have comments
- Run tests before committing
- Use table-driven tests

Lore reads this file on every session start, alongside the auto-generated wiki. The wiki is Lore's memory; LORE.md is your rules. Both are loaded into context for every request.

Streaming + AI

Lore streams responses word by word in real-time. No more frozen screens wondering if anything is happening. You see the AI's plan appear as it thinks, then the diff preview box appears when code is ready.

Lore's AI engine reads your actual source files, traces logic across functions, and understands your project's patterns before writing code. It selects only the relevant context per request, which means faster responses and lower token usage.

Smart context

Instead of sending your entire wiki and codebase on every request, Lore picks only what's relevant: the top wiki pages matching your question and the specific code snippets that matter. This cuts token usage by 40-50% while improving response quality.

On long sessions, Lore's AI engine automatically compresses context to stay within limits without losing the thread of the conversation. You don't need to manage this — it happens transparently in the background.

Deep code review

When you ask Lore to review, audit, or scan your code, it switches to a special mode: it reads your actual source files (up to 10 files, 15K characters) and analyzes the real code, not wiki summaries.

Lore can also request additional files mid-conversation. If it needs to trace a function across modules, it reads those files automatically and continues its analysis. Up to 3 rounds of exploration before delivering findings.

you › scan this project for bugs and give me a detailed report

Expect file paths, line references, and specific findings rather than generic advice.

Session lifecycle

Every Lore session follows the same pattern:

# 1. Start: wiki loaded into context
lore
# Loads index.md + conventions.md + architecture/overview.md + last-session.md

# 2. Chat: full project context, dynamic wikilinks
# Ask questions, request changes, explore code
# Press Enter for single line, Ctrl+D for multi-line or large pastes

# 3. Changes: diff preview -> approve -> snapshot -> apply
# Every change is previewed before applying

# 4. Exit: wiki compile
/exit
# Session distilled into wiki updates + log entry

# 5. Next session: all prior context loaded automatically

Teach mode

Teach mode makes Lore explain what it did and why. Three levels of depth:

Learning docs are auto-saved to .lore/learnings/ with YAML front-matter (date, topic, tags). Export them anytime:

lore export-learning auth-middleware     # single doc
lore export-learning --all                # combined PDF

Diff preview + rollback

Every code change Lore proposes gets a visual diff. You choose what happens:

[a]pply    Apply the changes
[A]lways   Apply and auto-apply all future changes this session
[p]review  See a detailed line-by-line diff
[r]eject   Discard the changes
[t]each    Explain what this code does

After applying, Lore shows a summary: what was built, exact commands to test, and suggested next steps.

Before every apply, Lore creates a git snapshot commit (prefixed lore-snapshot:). If something goes wrong:

lore history            # see recent snapshots
lore rollback           # interactive restore
lore rollback --last    # restore most recent snapshot

Shell + Git commands

Run shell commands directly from Lore without switching terminals:

/sh go run main.go
/sh npm test
/sh curl http://localhost:8080/health

Auto-shell mode

Let the AI execute commands it suggests automatically:

/auto-sh on    # AI-suggested commands run automatically
/auto-sh off   # back to manual confirmation

Git workflows

AI-powered commit messages and pull requests:

/commit            # AI reads your diff, generates commit message, commits
/pr Fix auth bug   # creates a PR with AI-generated description

Budget + cost metering

Lore shows your token spend in real-time and enforces budget caps at two levels.

Server-side token limits

Every plan has a monthly token cap enforced by the API. When you reach your limit, Lore returns a clear message telling you to wait for the next month or upgrade your plan.

Local budget controls

You can also set a personal dollar-based budget in your config that works independently:

# See your spending
/cost      # today / weekly / monthly / session breakdown
/budget    # budget status with progress bar

Configure your monthly cap in ~/.lore/config.toml:

[budget]
monthly_cap = 5.00    # hard cap in USD
warn_at = 80          # warning at 80% usage

When you hit either cap (server-side tokens or local budget), requests are blocked until the next month. The monthly counter resets automatically on the first of each month.

Self-check

After applying code changes, Lore can automatically run your build/test command to verify nothing broke.

# Toggle during a session
/selfcheck on
/selfcheck off

Lore auto-detects your project type:

If the build fails, Lore offers to fix the error automatically (up to 3 retries). After 3 failures, it auto-rolls back to the pre-apply snapshot.

CLI commands

Slash commands

Use these inside the interactive REPL:

Configuration

Lore uses a TOML config file at ~/.lore/config.toml:

# API connection (auto-configured)
session_token = ""   # auto-set by lore auth login

# Budget
[budget]
monthly_cap = 5.00    # USD, 0 = unlimited
warn_at = 80          # percentage

# Teach mode default
[teach]
mode = "off"          # off | brief | standard | deep

# Display
[display]
show_token_meter = true

# Self-check
[selfcheck]
enabled = true

Wiki structure

The .lore/ directory at your project root:

.lore/
  index.md              # Master catalog (auto-generated)
  log.md                # Append-only session timeline
  schema.md             # Wiki maintenance rules
  conventions.md        # Naming, patterns (auto-generated)
  architecture/
    overview.md         # System architecture (auto-generated)
  entities/             # Domain entities
  decisions/            # Architecture decision records
  bugs/                 # Bug records
  learnings/            # Teach mode output (auto-saved)

All wiki pages are Markdown, human-readable, and git-tracked. You can edit them manually and Lore will respect your changes in the next session.