CLI Reference

Complete reference for all Lore CLI commands.

Setup & Auth

Search & Research

Project Briefs

Project briefs are living synthesis documents that evolve as new sources enter. They track current state, key evidence with citations, open questions, and project trajectory. Briefs auto-update when material content is ingested into a project (debounced 60s for projects, 30s for workstreams), so they stay current without manual intervention. Log entries don't trigger regen — they're folded in at the next material regen.

Project Context & Corrections

lore context add includes all non-deleted project sources by default, writes copied snapshots instead of symlinks, and registers the repo for daemon refresh. It also writes .lore/.gitignore so generated context stays out of the host repo unless you intentionally change that. Empty projects are allowed: Lore creates the scaffold now and the daemon populates it after sources for that project exist.

A repo-local .lore/ working copy currently tracks one Lore project. Running lore context add <other-project> replaces clean context; active proposals must be reviewed or explicitly discarded with --force.

lore context remove is the safe off switch. It unregisters daemon refresh, removes only the generated working copy, refuses to discard active proposals unless you pass --force, and leaves canonical Lore unchanged.

Ingest

Correcting a source. lore ingest --replaces <id> --reason "<why>" supersedes an existing source with new content, creating a v2 in its version chain while v1 stays immutable — the by-id correction primitive with provenance, no .lore/ working copy required. <id> is a full source id or an unambiguous 8+ char prefix. Tags and project/workstream routing inherit from the parent (passing --tags / --project / --workstream is an error, not a silent no-op); --title / --type / --url / --name are optional overrides. Identical content short-circuits as a no-op; a stale parent prints the current chain head and a ready-to-run retry. This is the CLI surface for the same path the MCP ingest tool exposes via replaces + reason. In-place action: update stays MCP-only — versioned replace is the correction primitive on the CLI.

Log

Log entries are lightweight status updates, decisions, and progress notes. They are searchable via search and included in project briefs, but hidden from list_sources by default. The MCP log tool writes the same shape — lore log add is its CLI mirror.

Sync & Sources

Supported file formats: Markdown, JSON, JSONL, plain text, CSV, HTML, XML, PDF, and images (JPEG, PNG, GIF, WebP). The default glob is **/* (all files). Use --glob to restrict to specific types.

Lore Cloud/Supabase is the primary sync layer. Git in LORE_DATA_DIR is optional local history; generated files such as sources/.paths.json and deleted-hashes.json are caches and should not block daemon refresh. If lore sync status reports repair-needed Git state, run lore sync repair.

Documents

Deleted documents are excluded from search, briefs, and list results. They can be restored at any time with lore docs restore.

Ambient vs. signal sources. Every source carries a capability profile. signal sources — transcripts, meetings, deliberate captures — are first-class browsable documents. ambient sources — raw terminal / observed-session scroll — are still indexed, searchable (lore find), and citable, but hidden from the Sources browse views (lore docs list, the TUI Sources list) so they don't pollute the surfaces you scan. The ambient partition has its own home: lore docs list --all / lore ambient list on the CLI, and the TUI Observations tab. Promote ambient → signal (or demote the other way) with lore docs reclassify <id> --to signal|ambient; every reclassification writes an org_ops_log row (op_kind='source-reclassified') for audit.

Capture-origin filters. Producer-stamped fields (capture_method, app_bundle_id, app_name) carry through to the source row at ingest. These are attribute-plane axes — they describe how the source was captured, not where it lives. Use --capture-method to filter by the producer rule that fired (e.g. show me every voice note), or --app to filter by source app (e.g. show me every Slack-captured source). The same filters compose into MCP list_sources and search for agents. The TUI's source-detail preview renders a "captured via X" chip when these fields are populated.

Ambient corpus

The ambient corpus is a distinct surface (its own retention policy, its own visibility default, its own GC), so its primitives live under lore ambient. Promotion is the quality gate: it lifts a worthwhile observation into the browsable signal corpus as a curated derivative — a new source stamped with parent_source_id (→ the ambient row) and derived_from='ambient-promotion'. Promotion never flips the ambient row in place; the raw observation stays put and will TTL-expire on its own unless pinned. lore docs reclassify lives under lore docs because it's a source-row operation that composes with the rest of the docs CRUD. The TUI surfaces the same partition as the Observations tab (the 6th top-bar tab) — a browsable, salience-triaged staging inbox — with a read-only review panel on Shift-R.

Retention + TTL. Every ambient observation is stamped with an expires_at at ingest — created_at plus a tier: 7 days for sensitive captures (visibility='personal' ambient, or a sensitive capture_method such as browser_gmail) and 30 days for normal ambient. Both tiers are operator-tunable via the config keys ambient_ttl_normal_days / ambient_ttl_sensitive_days. The sync daemon's periodic tick auto-GCs everything past its deadline (pinned and brief-cited rows are exempt) — a soft-delete, recoverable with lore docs restore. The auto-GC is gated behind the config flag ambient_auto_gc (default on) so a regression can be disabled without a revert. Promotion is the value-preservation path; lore ambient pin is the lighter-weight "keep this" — both null out expires_at permanently.

Typical retention sweep:

lore ambient stats                       # see how it's growing
lore ambient expiring --within 7         # what's about to expire — promote/pin the keepers
lore ambient gc --dry-run                # preview the TTL-expired set
lore ambient gc --yes                    # soft-delete it (the daemon does this automatically)

The safety check refuses any source whose chunks are cited in a current workspace brief, regardless of age.

Projects

Hints

Landing-view hints are one-line state observations rendered above the project tree in lore browse — closer to git status ("your branch is ahead of origin/main") than to a wizard. Each hint pairs a predicate (the substrate state it watches) with a pre-filled CLI verb. One at a time, highest-priority active wins; self-clearing when the predicate flips false; machine-local dismissal (~/.config/lore/hints.json, does not sync).

The five registered hints:

Discipline. Dismissal is an override on top of the predicate, not a replacement: predicate-false always wins, so a hint disappears when you act on it whether or not you ever dismissed it. Hints never appear outside the landing view; metrics-style observations (e.g., "auto-router has been returning audience=ambiguous 80% of the time") belong in lore doctor, not here.

Entities

The entity registry is the thin people / companies / products / deals bridge layer. Entities are resolved automatically as content is ingested — these commands manage the registry.

Procedures

Procedural memory is the team's "how we act" layer — scope-attached operational constraints (release cadences, onboarding playbooks, review checklists), distinct from briefs (which describe what's true). Procedures ratchet: agents propose, humans confirm.

The scope expression accepts workspace, project:<slug>, or workstream:<project>/<workstream> (workstream slugs are project-scoped, not workspace-unique). Procedures with status='confirmed' are folded into lore brief stack automatically — that's how agents read them as part of their inherited operating context.

Open Questions

Open questions are the open_question epistemic-item primitive — scoped, cited, lifecycle-bearing units of unresolved knowledge-state. Distinct from procedures (normative — how to act) and briefs (descriptive — what's true). There is no ratification gate: any actor files an open question and any actor resolves it.

answered and dismissed are both terminal — there is no reopen. Every status change appends an entry to the question's lifecycle_events log. visibility is scope-derived when not passed explicitly (a personal-kind workspace → personal, RLS-isolated to the owner; else workspace).

Lint

lore lint is the substrate-hygiene pass — a cheap, deterministic check over the epistemic substrate. Where lore doctor checks the plumbing (DB connectivity, sync age, extraction lag), lore lint checks whether briefs are current, scopes are briefed, and tracked questions are fresh. The five deterministic checks make no LLM calls — free, and runnable in a commit hook (it exits non-zero when any check warns or fails).

The five deterministic checks: stale briefs (a brief whose live source count has run ≥ N ahead of its generation count — N defaults to 10, tunable via lint_stale_brief_threshold), missing briefs (a project/workstream with no brief row), orphaned scopes (a brief that stands on nothing — every cited source soft-deleted, or the scope has zero live sources), brief leakage (a brief still referencing a soft-deleted source), and stale open questions (status='open' past its review_after date). Exit code: 0 pass, 1 warn, 2 fail.

--contradictions — the opt-in LLM pass

lore lint --contradictions adds a sixth check: a batched claude-haiku-4-5 pass that compares claims within a scope — across a brief's prose and evidence sections and the source documents it cites — and flags pairs that contradict, each citing both claims and their source ids. It is opt-in so the default lore lint stays a zero-cost commit-hook pass, and cost-gated under LORE_MAX_DAILY_TOKEN_SPEND_CENTS — past the daily cap the check skips rather than crashing the run. A flagged contradiction is surfaced for human adjudication, never auto-resolved: each is filed as an open question at the scope citing both sources, so it shows up in lore questions and in lore attention; resolve or dismiss it with lore questions resolve/dismiss <id>. Re-runs dedup against contradictions already filed in any status.

Attention

lore attention is the attention surface — what needs action now. Where lore doctor checks the plumbing and lore lint checks epistemic hygiene, lore attention answers "what should I act on?" It is a union of cheap deterministic predicate-queries over tracked state — never an LLM-ranked feed: every item is a predicate that fires every time its condition holds.

The predicates: stale open questions (an open question past its review_after), approaching reviews (an open question due for review soon), failed ingests (a file the sync quarantine is skipping — silent data loss until acted on), expiring ambient (an ambient observation inside its pre-expiry TTL window — the same rows lore ambient expiring lists), and stale briefs (a leaf brief drifted past the staleness threshold behind its scope — the same signal lore lint flags, surfaced as a regen prompt). The surface is visibility-filtered to you — a personal open question never surfaces to a team agent. Items are ordered into deterministic urgency tiers (overdue > due soon > info). lore ambient expiring stays as a focused alias; its rows now also appear here in the unified surface. The same surface is exposed over MCP as the attention tool, which an operator-run "chief of staff" agent polls.

Timeline

lore timeline is the substrate diff for a time window — every source, log, ambient observation, and open-question lifecycle event (filed / resolved / dismissed) that touched the substrate in the window, ordered by time. It's the one command that answers "what happened today / this week" without manually unioning lore find, lore docs list, lore ambient list, and lore log show (each of which defaults to a different corpus / visibility and caps differently).

The window grammar is 24h / 7d / 4w / 3mo (or an ISO-8601 timestamp). Degradations are disclosed, not silent: an unbounded read that hits the cap, or a stale local mirror, prints a visible warning so an empty result never reads as "nothing happened." The same surface is exposed over MCP as the timeline tool — there the corpus default is signal and visibility defaults to workspace (agent-safe; personal / any refuse agent callers), so an agent can persist its last-run timestamp and call timeline(since: that_ts) at SessionStart to boot on the diff since it last ran. For a date filter over just sources, lore docs list --since/--before is the narrower tool.

Agents

Lore attributes every write to an actor — a human or a named agent. Humans get their actor automatically; agents are provisioned explicitly, each with its own identity.

A process running under LORE_AGENT_TOKEN (set by a scheduled runtime, or via the agent credential file) acts as that agent for every write. See the agent guide for the full actor model.

Per-workstream write permissions

Agents are scoped to their home workstream + explicit grants. Writes outside that set are refused at the database layer — the agent gets Agent "<name>" is not authorized to write to workstream "<slug>". Allowed: <home>, <grants>. Operator can fix with: lore agent grant <name> <slug>. Humans are unaffected — they write workspace-wide.

Agents with no home and no grants keep workspace-wide write (the legacy upgrade default) and are flagged workspace-wide (yellow) in lore agent list so the operator can scope them when ready.

MCP Server

Skills

Browse TUI

lore browse opens the landing view — a morning-glance front door that shows workspace shape (project tree with workstreams nested + freshness chips) and a recent-activity feed in one screen. Pass --list to skip straight to the flat document list (the pre-landing-view behavior); any startup filter (--project / --workstream / --type) also implies list view.

Landing view:

The landing view may render a one-line hint banner between the header and the project tree — a state observation (e.g., "Workspace brief is 14d+ old. Generate fresh: lore brief generate workspace."). Hints are one-at-a-time, highest-priority active wins, and self-clearing: once the underlying state changes (you regenerate the brief, the queue empties, a workstream gets created), the banner disappears on its own — no manual cleanup needed. Press d to durably mute the current hint without acting on it; lore hints (CLI) is the audit + override surface. The five registered hints: empty workspace, project-bloat (≥10 sources, no workstreams), stale workspace brief, ≥5 pending personal-review entries, ≥3 stale workstream briefs.

List view (flat document list — --list or any startup filter):

Activity panel (Shift-A from any non-input mode):

The panel reads from the substrate's write tables (sources joined to workspace_actors via actor_id; procedures joined via proposed_by) within a 24-hour window, capped at 100 rows. It is a deposit feed — distinct from lore audit / org_ops_log, which records structural operations (renames, merges, deletes) and is not folded in here.

Observations panel (the 6th top-bar tab — Tab to it, or 6):

The Observations tab surfaces the ambient partition — passively captured content (watched videos, browsed threads, terminal/observed-session scroll) staged for review. Both the tab and the Shift-R review panel are read-only browse surfaces; the promotion action lives in the CLI (lore ambient review / lore ambient promote). Un-promoted observations TTL-expire on their own — the daemon auto-GCs everything past its expires_at deadline (see Retention + TTL above). lore ambient list is the CLI mirror of the tab.

Chunks browser (Shift-C from list — workspace-wide; c from document view — source-scoped drill-in):

The browser is the human-side parity surface for lore find (CLI) and the find MCP tool — same public.chunks data, same field set (type, evidence_type, confidence, citation_text, span), rendered for terminal reading. Workspace-wide view caps at 100 rows ordered by recency; source drill-in shows every current chunk for the source ordered by source_span_start (reading order). Both views render filter chips inline in the header. The source-detail preview also gains an N chunks · M decisions · K commitments summary line under the metadata block so you know whether c will surface anything before pressing it.

Document view:

Updates

Environment Variables

These can be set via environment or via lore setup (stored in ~/.config/lore/config.json):