Maintenance

Lore maintenance is local and bounded. Session hooks do not provide wall-clock scheduling: automatic work runs when a session starts, so use the maintenance script with cron or launchd when timing matters.

Choose a mode

Copilot and Pi run the automatic sweep in-process. Claude Code, Codex, and Antigravity run lore-cli.mjs hook as a short-lived process, so their session-start hook instead spawns a detached scripts/run-maintenance.mjs --background and returns immediately — it finishes a moment later, under a cross-process lock that keeps concurrent sessions from double-running it.

Inspect before changing anything

From the Lore checkout:

node scripts/run-maintenance.mjs --status
node scripts/run-maintenance.mjs --dry-run

The in-session equivalent is maintenance_schedule_run({ dryRun: true }). Start with a dry run when enabling a new task.

The optional browser dashboard keeps this inspection read-only. Its overview shows the last successful native capture, pending bytes, resumable source checkpoints, embedding coverage, and recent fallback diagnostics. A resume button only copies a command for review; it does not run capture from the browser. Running the copied native capture --resume command performs capture and may write evidence. Each pass reads at most 4 MiB with a 250 ms cooperative read budget, retains at most a 1 MiB incomplete record, and reports skipped oversized records through categorical health.

Useful task cadence

The built-in defaults suggest validation every 12 hours, replay every 24 hours, backlog review every 6 hours, and index upkeep every 12 hours when enabled. traceCompaction is hourly and doctorSnapshot is daily when their rollout gates are enabled.

Memory hygiene

Hygiene is report-only in shadow mode. After reviewing candidates, apply may supersede open-loop or assistant-goal memories only when deterministic later evidence satisfies the scope rules. Applied rows receive an auto-hygiene:<run-id> marker.

To reverse one exact run:

maintenance_schedule_run({
  action: "rollback_hygiene",
  marker: "auto-hygiene:<run-id>",
  actor: "operator",
  reason: "false positive"
})

Rollback restores rows carrying that marker and records an audit artifact.

Schedule outside sessions

Example cron entry:

0 */6 * * * LORE_HOME=/Users/YOU/.config/lore /path/to/node /Users/YOU/.copilot/extensions/lore/scripts/run-maintenance.mjs --tasks validationCorpus,backlogReview >> /Users/YOU/.config/lore/maintenance.log 2>&1

Use an absolute Node path because cron has a minimal PATH. Set LORE_HOME or LORE_CONFIG explicitly; use LORE_COPILOT_HOME when Copilot input files are elsewhere. Without a configured Lore home, legacy fallback remains available until the new home exists. On macOS, launchd is the recommended scheduler; the full property-list example lives in docs/maintenance-scheduling.md.

Recovery and isolation

Stale deferred jobs and abandoned maintenance runs are reclaimed after their configured 30-minute defaults. Failed migrations and tasks use forward recovery and leave the database intact. Point maintenance only at the configured Lore database; do not aim it at fixtures or another user’s data.

Administrative repair and purge follow the same review boundary: preview first, then apply only with the preview fingerprint and explicit candidate IDs. Repair candidate IDs are limited to actionable source re-extraction or repository mapping candidates. Purge aggregate candidates use typed IDs such as aggregate:episode_digest:<json-primary-key> and require includeDependentAggregates: true plus every residual aggregate ID selected from the preview. Purge removes selected derived records while retaining raw sources and recovery snapshots; it is not secure erasure.