Configuration

Lore reads settings from .lore/config.json (JSON) at the instance root and from environment variables.

.lore/config.json

{
  "version": "1.0.0",
  "treeDepth": 5,
  "nudgeThreshold": 15,
  "warnThreshold": 30,
  "profile": "standard"
}

Fields

Field	Type	Default	Description
version	string	--	Displayed in the session banner (=== LORE v1.0.0 ===)
treeDepth	number	5	Max directory depth in the knowledge map tree
nudgeThreshold	number	15	Bash commands before a gentle capture reminder
warnThreshold	number	30	Bash commands before a strong capture warning
profile	string	"standard"	Hook behavior profile. See Hook Profile.

All fields are optional. Missing fields fall back to defaults. If .lore/config.json is missing or contains a parse error, all fields silently fall back to defaults — no error is thrown.

Metadata fields — name and created are informational, set during instance creation. Not used by framework logic.

subagentDefaults

Controls which worker agent tiers are generated and which model each tier uses in Claude Code.

{
  "subagentDefaults": {
    "claude": {
      "fast": "haiku",
      "default": "sonnet",
      "powerful": "opus"
    }
  }
}

subagentDefaults.claude accepts up to three tier keys:

Key	Generated agent	Description
default	lore-worker (always generated)	Standard worker. Uses claude.default model if set; omits model field otherwise (platform picks its own default).
fast	lore-worker-fast (only when key is set)	Lightweight worker for cheap, parallelizable tasks.
powerful	lore-worker-powerful (only when key is set)	High-capability worker for complex reasoning tasks.

lore-worker is always generated by sync-platform-skills.sh. lore-worker-fast and lore-worker-powerful are only generated when their respective tier key is present in the config.

Model values in subagentDefaults.claude are the full deployment names your platform uses — these appear in the session banner and orchestrator context so you know which models are active. The generated .claude/agents/ frontmatter always uses short aliases (haiku, sonnet, opus) regardless of what is in config, because Claude Code only recognizes those aliases in agent frontmatter.

Standard (Anthropic API): Use short aliases directly in config — they work as-is.

{ "claude": { "fast": "haiku", "default": "sonnet", "powerful": "opus" } }

Foundry / Bedrock / Vertex: Set full deployment names in config for display, and map the short aliases to your deployments via env vars in ~/.claude/settings.json:

{
  "subagentDefaults": {
    "claude": {
      "fast": "claude-haiku-4-5",
      "default": "claude-sonnet-4-6",
      "powerful": "claude-opus-4-6"
    }
  }
}

{
  "env": {
    "CLAUDE_CODE_USE_FOUNDRY": "1",
    "ANTHROPIC_FOUNDRY_RESOURCE": "your-resource-name",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6"
  }
}

Claude Code resolves haiku → ANTHROPIC_DEFAULT_HAIKU_MODEL, sonnet → ANTHROPIC_DEFAULT_SONNET_MODEL, and opus → ANTHROPIC_DEFAULT_OPUS_MODEL at runtime. All three env vars must be set — without them, Claude Code falls back to its own hardcoded model IDs which may not exist in your deployment.

Hook Profile

Controls which hook behaviors are active for the session.

{
  "profile": "discovery"
}

Any unrecognized value (or a missing profile key) falls back to standard.

Value	Behavior
standard	Default. All hooks active. Capture nudges at normal thresholds.
minimal	Per-tool nudges off. Session banner notes to use /lore-capture manually. Use when hooks feel noisy.
discovery	All hooks active with lower default thresholds (nudge=5, warn=10). Banner adds aggressive capture instructions for environment mapping and skill creation. Use during initial setup or unfamiliar codebase exploration.

MCP Search Server

The Docker sidecar exposes three MCP tools for knowledge base access:

Tool	Description
lore_search	Semantic search — returns ranked snippets by topic
lore_read	Read a full file by path (use after lore_search)
lore_health	Container and index status

Configured via .mcp.json at the instance root (scaffolded by create-lore). Works in any platform with MCP support — Claude Code natively, Cursor via .cursor/mcp.json. Requires the Docker sidecar to be running. See Docs UI & Semantic Search for setup.

Tuning for Large Instances

The largest contributor to session banner size is the knowledge map — a directory-only tree of docs/, skills/, and agents/. Size grows with the number of directories, not documents.

treeDepth limits how many directory levels the knowledge map displays. Default is 5. Reducing to 3 or 4 hides deep nesting while showing top-level structure.

When to act:

• Knowledge map exceeds ~50 lines → reduce treeDepth or reorganize subdirectories
• MEMORY.local.md exceeds ~50 lines → route content to skills or docs/knowledge/
• Conventions section growing → keep it focused on rules, move reference material to docs/knowledge/
• Many active work items → archive completed items with /lore-capture

Archived items (in archive/ subdirectories) are excluded from the knowledge map tree — they do not appear in the session banner. This keeps the map focused on active content.

Environment Variables

Variable	Description
LORE_DEBUG=1	Enable debug logging to stderr
LORE_HOOK_LOG=1	Enable structured hook event logging to .git/lore-hook-events.jsonl
LORE_HUB	Internal. Set by /lore-link to point cross-repo hooks back to the hub

Hook Event Logging

LORE_HOOK_LOG enables structured event logging for all hooks across all three platforms. Each hook fire writes a JSON line to .git/lore-hook-events.jsonl. Zero cost when disabled.

export LORE_HOOK_LOG=1

Each entry records:

{"ts": 1740000000000, "platform": "cursor", "hook": "capture-nudge", "event": "beforeShellExecution", "output_size": 52, "state": {"bash": 3}}

Field	Description
ts	Unix epoch milliseconds
platform	claude, cursor, or opencode
hook	Hook filename (e.g., capture-nudge, session-init)
event	Platform event name (e.g., beforeShellExecution, PostToolUse)
output_size	Characters injected into the agent's context (0 for silent hooks)
state	Optional hook-specific snapshot (bash counter, flags)

Analyze collected data:

bash .lore/scripts/analyze-hook-logs.sh

The report shows fires per platform, fires per hook, average output sizes, estimated accumulated context tokens, and any hooks that never fired. To reset: rm .git/lore-hook-events.jsonl.