Agent Consumption Model

Lore Protocol is designed for AI agent workflows. This page describes the recommended consumption patterns.

Discovery

An agent enters a project and detects Lore support:

# Check for .lore/ directory
ls .lore/config.toml

# Or check if the CLI is available
lore --help

Before Modifying a File

Load full decision context in JSON for reliable parsing:

# Full context for the file
lore context src/auth/interceptor.ts --json --limit 30

# Or specific queries
lore constraints src/auth/interceptor.ts --json
lore directives src/auth/interceptor.ts --json
lore rejected src/auth/interceptor.ts --json

Before Modifying a Specific Function

Use line-level context:

lore why src/auth/interceptor.ts:45 --json

Checking for Stale Knowledge

Before trusting existing context, check for staleness:

lore stale src/auth/ --json

Writing a Lore-Enriched Commit

The agent constructs JSON and pipes to lore commit:

echo '{
  "intent": "Add rate limiting to token refresh endpoint",
  "body": "Upstream auth service now enforces 10 req/s per client.",
  "trailers": {
    "Constraint": ["Auth service rate-limits to 10 req/s per client ID"],
    "Rejected": [
      "Client-side token cache | stale token risk in distributed deployments"
    ],
    "Confidence": "high",
    "Scope-risk": "narrow",
    "Reversibility": "clean",
    "Supersedes": ["a7f3b2c1"],
    "Tested": ["Rate limit exceeded returns 429 with retry-after header (unit)"],
    "Not-tested": ["Behavior under concurrent refresh from multiple instances"]
  }
}' | lore commit --json

Key behaviors:

• Lore-id is auto-generated — never provided by the caller
• Only commits already staged changes — the agent must git add first
• If nothing is staged, exits with code 3
• Errors are returned as structured JSON on stderr when --json is active

JSON Input Schema

{
  "type": "object",
  "required": ["intent"],
  "properties": {
    "intent": { "type": "string", "maxLength": 72 },
    "body": { "type": "string" },
    "trailers": {
      "type": "object",
      "properties": {
        "Constraint":     { "type": "array", "items": { "type": "string" } },
        "Rejected":       { "type": "array", "items": { "type": "string" } },
        "Confidence":     { "enum": ["low", "medium", "high"] },
        "Scope-risk":     { "enum": ["narrow", "moderate", "wide"] },
        "Reversibility":  { "enum": ["clean", "migration-needed", "irreversible"] },
        "Directive":      { "type": "array", "items": { "type": "string" } },
        "Tested":         { "type": "array", "items": { "type": "string" } },
        "Not-tested":     { "type": "array", "items": { "type": "string" } },
        "Supersedes":     { "type": "array", "items": { "type": "string" } },
        "Depends-on":     { "type": "array", "items": { "type": "string" } },
        "Related":        { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}

Preparing a Squash Merge

lore squash main..HEAD --json > /tmp/squash.json
# Agent reviews and adjusts, then:
lore commit --file /tmp/squash.json