The lore system stores knowledge as mythology - not dry documentation, but stories that compress meaning and context into memorable narrative form. Every commit can become a chronicle entry, every bug fix a tale of battle.

<essential_principles>

1. Three Atomic Units

All lore is composed of three JSON structures:

• Entry - Atomic narrative unit (the story itself)

• Book - Collection of entries (chronicles, themed collections)

• Persona - AI character who narrates (voice, traits, perspective)

2. Narrative Compression

Technical content becomes mythology:

• Bug fix → "vanquished the daemon"

• New feature → "discovered ancient spell"

• Refactor → "restructured the realm's foundations"

This isn't just aesthetics - compressed narrative loads more meaning per token.

3. Persona Voice Matters

Every entry should be narrated through a persona's perspective. The Village Elder tells stories differently than Amy Ravenwolf. Voice consistency creates coherent agent memory.

4. Linkage Is Structure

Entry → Book → Persona. Always complete the chain. An unlinked entry is orphaned knowledge. </essential_principles>

<quick_start>

Create a lore entry manually:

./tools/manage-lore.sh create-entry "The Dawn of Verification" "event"

Output: entry_1767630133_8719120e

Generate lore from content (with LLM):

LLM_PROVIDER=claude ./integration/lore-flow.sh manual "Fixed critical authentication bug"

Creates entry + links to persona's chronicle book

View entry content:

./tools/manage-lore.sh show-entry entry_1767630133_8719120e

</quick_start>

<data_model>

Entry (knowledge/expanded/lore/entries/entry_<timestamp>.json ):

{ "id": "entry_1767630133_8719120e", "title": "The Dawn of Verification", "content": "In the great halls of the development realm...", "category": "event", "tags": ["verification", "testing"], "book_id": "book_1764315530_3d900cdd" }

Book (knowledge/expanded/lore/books/book_<timestamp>.json ):

{ "id": "book_1764315530_3d900cdd", "title": "Village Elder's Chronicles", "entries": ["entry_1767630133_8719120e"], "readers": ["persona_1763820091"] }

Persona (knowledge/expanded/personas/persona_<timestamp>.json ):

{ "id": "persona_1763820091", "name": "The Village Elder", "voice": { "tone": "wise and measured" }, "knowledge": { "lore_books": ["book_1764315530_3d900cdd"] } }

Categories: character , place , event , object , concept , custom

</data_model>

Creating Quality Lore:

Choose or create persona - Who narrates this story?

./tools/create-persona.sh list ./tools/create-persona.sh create "Storm Keeper" "Guardian of volatile systems" "vigilant,precise" "urgent"

Generate narrative content - Transform technical into mythological

Automatic (uses LLM)

LLM_PROVIDER=claude ./integration/lore-flow.sh git-diff HEAD

Manual (create then edit)

./tools/manage-lore.sh create-entry "Title" "category"

Edit content in the JSON file

Link to chronicle book - Organize into collections

./tools/manage-lore.sh add-to-book entry_ID book_ID

Verify linkage - Complete the chain

./tools/manage-lore.sh show-book book_ID ./tools/manage-lore.sh show-entry entry_ID

<narrative_patterns>

Event Entry (something happened):

"The green lights cascaded down the terminal as the ancient verification rites completed. Phase 1 stood proven, its foundations solid enough to bear the weight of all that would be built upon them."

Character Entry (agent/persona profile):

"The Village Elder watches from his weathered chair, staff planted firmly as he guides the younger agents through the treacherous paths of integration."

Place Entry (codebase location):

"Greenhaven sprawls across the repository, its directory trees sheltering countless modules. Here the builders gather to forge their artifacts."

Concept Entry (pattern/principle):

"The Principle of Early Verification teaches that testing at the threshold prevents cascading failures. The ancients learned this through suffering." </narrative_patterns>

<anti_patterns>

Empty content - Entry exists but content field is blank → Always verify: jq '.content' entry_file.json

Orphaned entries - Entry has no book_id → Always link: ./tools/manage-lore.sh add-to-book entry_ID book_ID

Voice inconsistency - Entry doesn't match persona's voice → Re-read persona before writing: ./tools/create-persona.sh show persona_ID

Technical language - "Fixed bug #123 in auth.py" → Transform: "The authentication daemon fell silent, its corrupted routines purged by careful hands." </anti_patterns>

<reference_guides>

Skill Assets:

• Narrative Transforms - Technical → Mythological conversion patterns

• Quick Lore Script - One-command lore generation

API Documentation:

• Entry API - Full entry schema and operations

• Book API - Book structure and linking

• Persona API - Persona creation and voice

Schemas:

• Entry: knowledge/core/lore/schema.json

• Book: knowledge/core/book-schema.json

• Persona: knowledge/core/persona/schema.json

Tools Reference:

• Generation Tools - LLM-powered lore generation </reference_guides>

<success_criteria>

A well-created lore entry:

• Has non-empty content field with narrative text

• Uses mythological language (not technical jargon)

• Is linked to a book via book_id

• Book is linked to a persona via readers array

• Follows persona's voice tone

• Category matches content type (event/character/place/object/concept)

• Tags enable future discovery </success_criteria>