Workflows

August 27, 2026 · View on GitHub

lore has seven workflows. This document explains when to use each one, in plain language. For the operational specification the agent follows when running them, see skill/references/workflows.md.

中文版

Overview

Workflow	What it does	Frequency
`init`	Set up `.lore/` and platform mirror files	Once per project
`sync`	Update `.lore/` after a code change	After each feature
`query`	Search `.lore/` for an answer	Every session
`audit`	Find stale or contradictory entries	Quarterly
`compress`	Rebuild `SUMMARY.md`	When SUMMARY is stale
`mirror`	Regenerate platform files from `.lore/`	After batch of syncs
`history`	Show git commits for an entry / file / scope	When investigating

`init`

One-line: Create .lore/ and take over your existing CLAUDE.md / AGENTS.md.

When you say it: "lore init" — once per project, or when adding lore to a project that already has platform files.

What happens:

Agent scans for existing platform files (CLAUDE.md, AGENTS.md, .cursorrules, etc.)
For each file found, asks you: take over / preserve / abort
Detects monorepo structure (pnpm workspaces, Cargo workspace, etc.) and proposes scope list
Writes initial .lore/ draft (entries with #added:<today> + deterministic IDs)
Shows you a summary of what will be created
On your confirm: moves draft to .lore/, generates SUMMARY.md, refreshes platform files

Real scenarios:

New project, first time using lore → lore init
Old project already has CLAUDE.md, want lore to manage it → lore init and take over
Monorepo with separate frontend/ and backend/ → init detects both, asks for scope names

Output: Full .lore/ directory + updated platform files + populated .config.json.

`sync`

One-line: After a code change, update .lore/ with what changed.

When you say it: "lore sync" — after committing a feature, refactor, or new dependency.

What happens:

Agent detects the delta from two sources, combined and de-duplicated:
- Commits since last sync — git diff <last_sync_sha>..HEAD (when the config has a reachable last_sync_sha; falls back to working-tree diff alone if it's absent or unreachable, with a [WARN] to stderr).
- Uncommitted changes — git diff HEAD when HEAD exists, including net staged and unstaged changes.
- New files — inspect added paths and scan untracked files listed by git ls-files --others --exclude-standard.
- Empty repo — enumerate paths with git ls-files --cached --others --exclude-standard and scan current working-tree files; do not run HEAD-based diffs.
If the change is significant (≥50 lines / ≥2 dirs, or new module/dir/dep, or a new convention was discussed), the agent proactively proposes.
For each candidate entry, the agent classifies it as [NEW] / [STALE] / [REFINED] and checks for contradictions against existing entries in the same scope/layer — contradictions are flagged as [ALERT]. This is sync's own contradiction-detection step; a full lore audit is a separate command that walks every entry.
Runs find_duplicates.py --json --candidate "<entry body>" for each candidate before writing (or supplies the body via --candidate-file with a UTF-8 file). Only a semantically equivalent active entry in the applicable scope can suppress a candidate; also compare unsaved candidates with each other.
Emits a proposal with [NEW]/[STALE]/[REFINED]/[ALERT] markers. Default trust level is medium; de-duplicate hits and tags-only REFINEDs auto-apply without per-item confirmation and are reported afterward. Body-changing REFINEDs (new ID + supersede link), NEW, STALE, and ALERT require confirmation.
You accept or reject per marker; accepted markers get applied to .lore/*.md. Then last_sync_sha advances to the current HEAD so the next sync spans the right commit range.

Real scenarios:

"I just added a new dependency — update lore" → lore sync
"We decided to stop using React Query, switch to SWR" → lore sync after the code change
"There's a new module — capture it" → lore sync

Output: Updated .lore/*.md files with new entries (and #verified / #stale tags where appropriate).

Note: sync does NOT update platform mirror files (that's a separate mirror command). Reason: keeps git log of agent-facing files readable.

`query`

One-line: Search .lore/ for an answer to a question.

When you say it: "lore query " — any time you want to know what's in memory.

What happens:

Agent reads .lore/SUMMARY.md (the table of contents)
Fuzzy matches your query against active entries (neither #stale nor #superseded-by); for historical questions, identifies the status of inactive entries
Returns matched entries with stable [file#ID] references
Optionally drills into specific scope files for more detail

Real scenarios:

"What database does this project use?" → lore query database
"Why did we pick Zustand?" → lore query zustand
"What are the conventions for backend modules?" → lore query backend:conventions

Output: Bounded list of matched entries:

[_global/DECISIONS.md#DEC-2026-07-11-6137] Picked OpenAI-compatible LLM API
[scopes/backend/CONVENTIONS.md#CONV-2026-07-11-9b89] Embedding has two backends

The [file#ID] reference lets the agent cat the file for full text.

`audit`

One-line: Find stale or contradictory entries in .lore/.

When you say it: "lore audit" — quarterly review, or before a big refactor.

What happens:

Runs find_stale.py to find entries whose reference date (#verified if present, else #added) is older than 90 days, plus broken #superseded-by chains.
For each entry, walks the referenced code path against the current filesystem and checks for contradictions (memory says react@18, package.json says 16).
Writes a structured report to .lore/audit/audit-<date>.md grouped by severity (CONFLICT, STALE, UNVERIFIED, BROKEN_CHAIN).

Real scenarios:

"Are there any lore entries that contradict the current code?" → lore audit
Quarterly hygiene check → lore audit
Before onboarding a new contributor → lore audit to clean up stale entries

Output: A dated report file under .lore/audit/:

# Memory Audit Report

> Date: 2026-07-09
> Findings: 2 CONFLICT, 1 STALE, 5 UNVERIFIED, 0 BROKEN_CHAIN

## Scope: backend

### CONFLICT
- [CONV-2026-03-01-1f8c] says "use webpack"
  Evidence: `package.json` declares `"vite"`

### STALE
- [ARCH-2026-01-15-d7a3] references `nx.json`
  Evidence: file no longer exists at repo root

Note: audit does NOT modify any .lore/*.md file and does NOT emit ALERT blocks (ALERT is reserved for sync and query). To act on findings, run sync with proposal-driven updates.

`compress`

One-line: Rebuild .lore/SUMMARY.md from current entries.

When you say it: "lore compress" — when SUMMARY is stale (entries > 500, or > 30 days since last compress), or before sharing lore with someone new.

What happens:

Enumerates all entries via list_entries.py
Excludes entries with #stale or #superseded-by, even without a successor; untagged entries remain eligible, and age alone does not exclude an entry
For each (scope, layer) pair, picks 3–5 most important entries
Writes SUMMARY.md per template
If auto_mirror: true in config, regenerates platform mirrors; otherwise asks per target and only writes the ones you accept. (This is the second mirror update trigger — sync deliberately does not regenerate mirrors.)
Stops after mirror regeneration has either written or been declined per target.

Real scenarios:

"Refresh the summary" → lore compress
"I haven't compressed in 2 months" → lore compress
"Onboard a new contributor — make sure SUMMARY is fresh" → lore compress

Output: Updated SUMMARY.md (and possibly mirror files).

Idempotent: Running twice produces the same result (modulo date stamp).

`mirror`

One-line: Regenerate platform files (CLAUDE.md, AGENTS.md, etc.) from current .lore/.

When you say it: "lore mirror" — after a batch of syncs, or to manually sync mirrors after editing .lore/*.md.

What happens:

Reads current .lore/SUMMARY.md and scope indices
For each target, detects section boundary (## Lore / --- / ## My notes)
Computes new Lore section content
Content-based dedup: skips write if byte-identical to existing
Replaces Lore section; preserves My notes verbatim
Writes file back

Real scenarios:

"I just did a batch of syncs — update the agent-facing files" → lore mirror
"I edited .lore/SUMMARY.md manually — propagate to mirrors" → lore mirror
"Verify the mirror hasn't drifted" → lore mirror (no-op reports confirm)

Output: Updated CLAUDE.md / AGENTS.md / etc., or "No changes needed" if nothing changed.

`history`

One-line: Show git commits related to an entry, file, or scope.

When you say it: "lore history ||--scope=" — when investigating "why does this exist" or "when did this change".

What happens:

Entry form: lore history DEC-2026-02-03-7c19 — finds the entry, derives its #added date, runs git log --since=<date> on the referenced code file
File form: lore history frontend/src/store.ts — runs git log --since=1970 on that path
Scope form: lore history --scope=frontend — runs file form on every .lore/scopes/frontend/*.md

Real scenarios:

"Why did we pick Postgres?" → find the entry via query, then lore history <id>
"When did this file change?" → lore history <file>
Debugging: "what's the recent history of this module?" → lore history <path>

Output:

# history: [DEC-2026-02-03-7c19]

> Entry: scopes/backend/DECISIONS.md
> Since: 2026-02-03T00:00:00 (entry #added date)
> File: backend/app/auth.py
> Commits: 2 (showing all)

## 9f264f4 (2026-05-12, Alice)
refactor: extract chat agent_loop (#87)

## def5678 (2026-03-08, Bob)
feat: switch chat chain to chat_fast (#74)

Quick reference

I want to...	Use
Start lore on a project	`init`
Update lore after a code change	`sync`
Find what's in memory	`query`
Find stale entries	`audit`
Refresh the summary	`compress`
Update agent-facing files	`mirror`
Trace why something exists	`history`

For the operational specification (what the agent actually does step-by-step), see skill/references/workflows.md. For per-platform file mapping (which platforms read which files), see skill/references/platform-mirrors.md.