Lore

lore — Framework-agnostic Memory Management

What this skill is

A long-term knowledge base for a software project, maintained by AI agents. It is not a dev journal or a changelog. It captures the kind of context that normally lives only in the original developer's head:

• What the project is, how it is shaped (architecture)
• Why specific choices were made over alternatives (decisions)
• How code should be written and what to avoid (conventions)

This knowledge is persisted as plain Markdown files in .lore/ at the project root. Any agent that can read files can consume them.

When to Use

The skill uses a two-tier trigger model.

Tier 1 — Loading the skill

Load this skill when the user explicitly invokes lore, names a subcommand, references .lore/, or asks to record, recall, audit, sync, or compress project memory about decisions, architecture, conventions, or monorepo scopes. Generic phrases like "init", "compress", "audit", or "query" alone are not enough — they may map to the agent's native commands or unrelated tasks (Claude Code's /init, /compact, security audits, SQL queries, etc.).

Tier 2 — Internal proposals (after the skill is loaded)

Once the skill is loaded for this session, certain commands may proactively propose themselves based on internal thresholds. These proposals still require user acceptance — the skill never mutates files silently.

• sync proposes when 50+ changed lines span 2+ directories, OR a new top-level module/directory/dependency was added or removed, OR a new convention was explicitly discussed in chat.
• compress appends a [COMPRESS NOTICE] to sync proposals when entries > 500, SUMMARY.md is missing, or last compression > 30 days ago.
• sync emits [ALERT] markers when an active entry conflicts with current code or with a candidate change.
• mirror regenerates automatically during compress if auto_mirror: true is set in .lore/.config.json.

Other commands (init, query, history) are always explicit — they need user intent. See references/workflows.md for when each workflow is used.

Which command do I need?

The step-by-step procedures for all seven commands live in references/workflows.md — load that file before executing any command.

Already have .lore/? Adding a new scope is still sync — init is only for first-time setup or an explicit start-over. A change that introduces a new scope does not reinitialize the memory bank; sync creates the scope directories directly (see references/workflows.md sync step 2).

Start minimal. lore does not require a monorepo or mirrors. Single-package projects get _global/ only (no scopes). Single-host setups can set mirror_targets: [] in .lore/.config.json to disable mirror generation and read .lore/SUMMARY.md directly.

Happy path. init once -> then the recurring cadence is sync (record) / query (recall) / audit (check) -> compress when SUMMARY grows stale (or a [COMPRESS NOTICE] appears) -> mirror to publish structural changes.

Reference index

Detailed specifications live in references/. Load these on demand.

Memory architecture

Directory layout

.lore/
|-- SUMMARY.md        # Top-level digest of key entries. New agents read this first, then open referenced entries.
|-- .config.json      # Optional config: auto_mirror, sync_trust, mirror_targets, etc.
|-- _global/          # Cross-scope facts (whole-project architecture, global decisions)
|   |-- ARCHITECTURE.md
|   |-- DECISIONS.md
|   `-- CONVENTIONS.md
|-- scopes/           # Per-scope facts
|   `-- <scope-name>/
|       |-- ARCHITECTURE.md
|       |-- DECISIONS.md
|       `-- CONVENTIONS.md
|-- draft/            # Used only by `init`. Proposals pending user confirmation.
|-- audit/            # Used only by `audit`. Reports; never mutates main files.
`-- .archive/         # My notes backups (mirror wipe only); see references/platform-mirrors.md.

Scope detection and creation: init detects scope boundaries once (see references/monorepo-detection.md for marker detection across pnpm / Yarn / npm / Lerna / Nx / Rush / Cargo / Go / Bazel); sync creates the scope directories when a change introduces a new scope (see references/workflows.md sync step 2). Single-package projects fall back to _global/ only.

Layer semantics

Each layer answers one kind of question. The boundary that trips people up most is fact vs. reason: the choice itself is ARCH, the reasoning behind it is DEC.

Boundary rule: "we use X" -> ARCH; "why X over Y" -> DEC. A short inline reason (e.g. reason: streaming + RSC) may stay on an ARCH entry when it fits; anything with alternatives or tradeoffs ("why X over Y") is a DEC entry that references the ARCH ID (see references/entry-format.md for the atomicity rule and splitting examples).

Placement (all three layers): affects 2+ scopes (e.g. "use pnpm workspaces", "TypeScript strict") -> the _global/ file; affects exactly one scope -> that scope's file.

There is no separate metadata file. Every status lives as inline tags on entries themselves.

Entry format

Each entry is a Markdown bullet (2 lines or fewer), with a layer prefix, a deterministic ID, and inline status tags. See references/entry-format.md for the full spec (ID generation via content hash, tag semantics, cross-file reference format, splitting rules).

- [ARCH-2026-07-09-a3f2] Use Next.js App Router; reason: streaming + RSC. #added:2026-07-09
- [DEC-2026-02-03-7c19] Chose Zustand over Redux; reason: 60% less boilerplate. #added:2026-02-03
- [CONV-2026-01-20-b1e8] Never commit secrets; use `dotenv` + `.env.local` (gitignored). #added:2026-01-20

Platform mirror

The canonical store is .lore/*. Agents that expect a single config file at the project root (CLAUDE.md for Claude Code, .cursorrules for Cursor, .clinerules for Cline, AGENTS.md for Aider, etc.) read a synced projection of that store.

A mirror is a synced projection, not a strict derivative. It contains two sections: a Skill-managed ## Lore section (rewritten on mirror regeneration) and a user-editable ## My notes section (preserved verbatim). Both sections are legitimate mirror content; the Skill never touches My notes. The two-section template and the <!-- LORE:START --> / <!-- LORE:END --> boundary markers are specified in references/platform-mirrors.md.

Default behavior:

• Init: targets are auto-detected (existing platform files in repo root). If none detected, ask the user via multi-select which agents they use. For each detected file lacking a ## Lore section, ask take over / preserve / abort per file. Auto-create missing files with the full two-section template; refresh existing lore mirrors; preserve My notes verbatim.
• Compress: controlled by .lore/.config.json#auto_mirror. Default is false (ask per target). When true, mirrors update automatically. My notes section is always preserved.
• Sync: never touches mirrors by default. To restore mirror updates on every sync, set sync_updates_mirror: true in .lore/.config.json (see references/config.md).

By default the Lore section is an index into .lore/ — paths plus a per-scope one-line description, ~600 bytes worst case. The agent reads .lore/SUMMARY.md (or calls lore query <term>) on demand.

Mirror update triggers

Platform mirrors are regenerated on only three occasions, not on every sync:

1. init completion — first time the mirror is created or restructured
2. compress completion — SUMMARY.md changed, so mirrors reflect the new digest
3. Explicit lore mirror command — user forces a regeneration

sync only updates .lore/* files. This is deliberate: mirror files are agent-facing entry points, not a per-change log. Regenerating them on every sync would clutter git log and dilute the "human-merged" signal that mirror files are supposed to provide. Use lore mirror after a batch of changes when you want the agent-facing view to catch up.

If a project needs old behavior (mirror updates on every sync), set sync_updates_mirror: true in .lore/.config.json (see references/config.md).

Mirror structure validation

Regeneration is not a blind rewrite: each target's two-section structure is validated first (per the section detection rules in references/platform-mirrors.md). If a target lacks the --- separator, lacks a ## My notes section, or is a user-notes-only file without ## Lore, report the anomaly and ask the user how to proceed — never overwrite an anomalous file silently. My notes is preserved verbatim across regenerations; if the user asks to wipe a target's My notes, archive the old content to .lore/.archive/<file>-<date>.md first, then write a clean mirror.

LangGraph / DeepAgents typically don't need a mirror file — they read .lore/*.md directly or ingest into the system prompt at runtime (the user's responsibility).