A lightweight CLI tool and MCP server that standardizes commit messages as structured context for AI coding agents. Uses git trailers to capture decision rationale, rejected alternatives, and forward-looking constraints in a machine-readable format. Enables agents to ingest rich project context without external tools or proprietary platforms.

Quick Start • Features • Examples • Contributing

What is this?

Lore is a lightweight CLI tool and Model Context Protocol server that turns git commit trailers into structured context for AI coding agents. It helps solo developers and small teams retain decision rationale across sessions so agents understand why code changed, not just what changed.

$ lore extract --path src/api --since 2024-09-01
Decision-Rationale: Chose REST over GraphQL to reduce initial complexity
Constraint: Avoid external auth providers due to internal SSO mandate
Rejected-Alternative: WebSocket subscription model (added latency concerns)

Problem

AI coding agents lose institutional knowledge because commits only capture code diffs, not the reasoning behind decisions. Solo developers and small teams waste time re-explaining context to agents across sessions, or agents make ill-informed changes because they can't access past constraints and alternatives. Current solutions require external wikis, documentation systems, or manual prompt engineering.

Features

Feature	Description
Git Trailer Parsing	Extracts and validates Lore-specific trailers (Decision-Rationale, Rejected-Alternative, Constraint) from commit messages, handling multi-line values and RFC‑compliant formatting.
Contextual History Extraction	Walks git history to collect all Lore trailers, groups decisions by file paths, builds chronological chains, and surfaces forward‑looking constraints.
Agent‑Optimized Formatting	Produces token‑efficient markdown summaries, decision trees, and constraint matrices in JSON, YAML, or plain text for direct consumption by AI agents.
MCP Server	Implements a Model Context Protocol server with real‑time query endpoints, caching, and filtered access by path, author, date, or trailer type.
Interactive Commit Authoring	Guides users through trailer prompts, validates required fields before commit, and integrates with git hooks for automated checks.
Version‑Aware Constraint Analysis	Uses semantic‑version parsing to evaluate how constraints evolve across releases and flags conflicting requirements.

Quick Start

1. Clone the repository:

   git clone https://github.com/m2ai-portfolio/lore.git
   cd lore

2. Install dependencies:

   pip install -e .

3. Make sure you are in a git repository and run the validation command to see existing trailers:

   lore validate

   Sample output:

   ✅ 12 commits validated
   ⚠️ 2 commits missing Decision-Rationale trailer
   

Examples

Extract decision context for a module

lore extract --path src/auth --format markdown

Output:

# Authentication Module Context

## Decision-Rationale
- Chose OIDC over SAML to simplify token handling (commit a1b2c3d)
- Rejected custom JWT approach due to lack of audience validation (commit f4e5d6c)

## Constraint
- Must support refresh token rotation per internal security policy (commit 9z8x7y6)

Generate an agent‑ready prompt under a token limit

lore format --agent-prompt --max-tokens 400

Output:

Project uses REST APIs with OAuth2 for auth. Decisions: adopted OIDC for simplicity, rejected GraphQL to avoid over-fetching. Constraints: no external auth providers, refresh token rotation required. Recent work focused on password‑reset flow and rate‑limit handling.

Export full context as JSON for downstream tools

lore export --format json --output lore-context.json

Output (first lines of lore-context.json):

{
  "generated_at": "2025-09-16T12:34:56Z",
  "commits_analyzed": 57,
  "context": {
    "src/auth": {
      "decisions": [
        {
          "rationale": "Chose OIDC over SAML to simplify token handling",
          "commit": "a1b2c3d4",
          "date": "2024-08-12"
        }
      ],
      "constraints": [
        {
          "description": "Must support refresh token rotation per internal security policy",
          "commit": "9z8x7y6",
          "date": "2024-07-03"
        }
      ]
    }
  }
}

File Structure

Lore: Git Trailers for Agent Context/
  src/                    # Core source code
    lore/
      cli/                # CLI commands and helpers
      core/               # Domain logic: parsing, extraction, modeling
      formatters/         # Output formatting for agents
      mcp/                # Model Context Protocol server
      storage/            # SQLite cache and migrations
  tests/                  # Unit and integration test suite
  pyproject.toml          # Project metadata and dependencies
  requirements.txt        # Pip requirements for development
  README.md               # This file

Tech Stack

Technology	Purpose
Python 3.11+	Core language
Click	CLI framework
GitPython	Git repository operations
Pydantic	Data validation and settings
FastAPI	MCP server implementation
SQLite	Local context caching
pytest	Testing framework
rich	CLI output formatting
python-semantic-version	Version constraint parsing

Contributing

Fork the repo, create a feature branch, make changes, run pytest, and submit a pull request. Please follow the existing code style.

License

MIT

Author

Matthew Snow -- [M2AI](https://m2ai.co) | [@m2ai-portfolio](https://github.com/m2ai-portfolio)