Configuration

Lore reads JSON configuration from ~/.config/lore/lore.json (or $XDG_CONFIG_HOME/lore/lore.json; XDG_CONFIG_HOME must be absolute). LORE_HOME overrides the Lore directory, LORE_CONFIG overrides the config file path without relocating the database, and LORE_COPILOT_HOME changes the Copilot input home. When no Lore home is configured and the new home does not exist, legacy files under ~/.copilot remain supported. New keys are additive, and a minimal config is valid:

{ "enabled": true }

Important paths

The default path settings are:

Keep the raw store and derived store separate. Lore reads the raw store and writes derived memory to lore.db.

Migrating an existing installation

Lore keeps using legacy files under ~/.copilot only when no Lore home is configured and the new home does not exist. Creating the new home selects it, so existing users must migrate before creating it. Stop Lore sessions, then run npm run migrate-home -- --from <old> --to <new> (the defaults are the legacy and new homes). The command never overwrites the destination, leaves the source untouched, and preserves custom configured paths. If you choose a custom destination, set LORE_HOME to it in each harness. Update or unset any LORE_CONFIG override that still points to the old config.

Core controls

enabled must be true for Lore to initialise. budgets limits the amount of procedural, semantic, episode, commitment, and working-profile context assembled for a prompt. limits bounds searches, prompt context, cross-repository results, and metric windows.

The runtime defaults are intentionally conservative: local inference, TypeSafe reranking, maintenance, embeddings, and trace recording are off. Some rollout-gated surfaces are enabled by default but remain experimental. The checked-in lore.example.json enables archive import, maintenance, and several experimental features, but leaves local inference disabled. Merge only the features you intend to enable.

Deferred extraction

The default configuration can enqueue extraction at session end and process it at session start. deferredExtraction.processCurrentRepositoryOnly keeps automatic work focused. useLocalInference requires both this setting and localInference.enabled.

TypeSafe reranking

typesafe.enabled + typesafe.rerank.enabled opt prompt recall into reranking by TypeSafe’s Jev model. Embeddings rank memories by similarity; Jev grades each candidate’s usefulness against the actual prompt, and Lore reorders the shortlist by that score in code. typesafe.features.enabled additionally scores rows once and stores the result: standing directives below features.minDurability (one-off instructions like “there should be a live env key”) are kept out of the always-on list, the most specific directives win the six available slots, and memory hygiene reports memories below features.minSpecificity as vague review candidates — a review signal that never supersedes anything. Credential-looking content is never sent to the provider, and it is redacted from the assembled context before that reaches a model too. Both are off by default, run with a 3-second timeout, send the prompt and candidate memory content to api.typesafe.ai, and fail open to the fused order on any provider error. Set the API key with, in precedence order, the LORE_TYPESAFE_API_KEY environment variable, the macOS keychain (typesafe.apiKeyKeychain: true for service lore-typesafe, or { service, account } to override either), or plaintext typesafe.apiKey — prefer the first two so the key never sits in lore.json. The keychain lookup (security find-generic-password, no shell) only runs on macOS, is cached for the process lifetime, and fails open like a missing key on any error; expect roughly 30-50 ms per lookup on hosts that run one process per hook (Codex, Claude Code, Antigravity). Then preview the effect on your own store with node scripts/rerank-preview.mjs --prompt "...".

Maintenance scheduler

maintenanceScheduler.enabled controls the scheduler. autoRunOnSessionStart allows bounded due work to run in the background. The scheduler can run validation, replay, backlog review, trace compaction, index upkeep, deferred extraction, memory hygiene, and extraction revalidation according to the enabled task map.

Memory hygiene defaults to mode: "off". Use "shadow" to record candidates without changing memories. "apply" can supersede only rows with deterministic completion evidence; each change has an auto-hygiene:<run-id> marker and can be rolled back by the maintenance tool.

Extraction revalidation (maintenanceScheduler.extractionRevalidation, task extractionRevalidation) is a separate, also opt-in and off-by-default check: it replays the current grammar against rule-extracted user_preference / directive / rejected_approach / recurring_mistake rows whose extractorVersion predates the running grammar, and reports (or, in apply, reversibly acts on) rows the grammar would no longer produce (a standing directive that no longer parses, or a recurring_mistake clause that is now a rejected fragment/question/quote), would classify differently, or would no longer keep global. Run it on demand with lore audit-extractions (--apply to act, --action rollback --marker extractor-revalidation:<run-id> to undo). It never creates a suppression: a rejected row means the grammar wouldn’t produce it today, not that anyone asked to forget it.

Rollout flags

Rollout flags gate evolving surfaces such as memoryDomains, refreshableObservations, traceRecorder, evolutionLedger, loreDoctor, and hybridRetrieval. Check the support matrix before enabling a flag in a long-lived setup.

Validate changes

After changing repository defaults or schema, maintainers should run:

npm run validate-schema

For your personal JSON file, use an editor configured with schemas/lore.schema.json. Lore merges known user settings with defaults; it is not a full validator for every unknown key.

A cautious starting point

{
  "enabled": true,
  "deferredExtraction": {
    "enabled": true,
    "autoEnqueueOnSessionEnd": true,
    "autoProcessOnSessionStart": true
  },
  "maintenanceScheduler": {
    "enabled": false
  }
}

Turn on experimental features one at a time so a change in behavior is easy to understand.