🧶 MythWeave Chronicles

Complete lore management system for AAA game development — 200+ entity types, AI-powered extraction, and multi-agent team coordination.

MythWeave turns raw narrative text into structured, validated game lore. Feed it a chapter of your game's story, and a team of specialized AI agents will extract characters, locations, quests, factions, items, cinematics — everything — into a clean JSON knowledge base.

🔀 How this differs from MiroFish technically

This repository is the canonical lore / world-model layer. The embedded MiroFish/ project is a simulation runtime + interactive report UI.

Current recommendation: for new lore generation, extraction, and structured entity write-back workflows, prefer CAMEL.Bridge/ in this repo first. Use MiroFish/ only when you specifically need the simulation runtime, social-agent behavior, or the interactive report UI.

Aspect	loreSystem (this repo)	MiroFish/ subproject
Primary role	Structured lore extraction, validation, storage	Multi-agent social simulation, report generation, graph exploration
Backend style	Python-first DDD / repository architecture	Flask API orchestrating simulation and report workflows
Frontend	Optional local GUI (PyQt6) + CLI + MCP	Web frontend with Vue 3 + Vite + D3
Core AI pattern	Claude Code agent teams + domain extraction skills	OASIS/CAMEL agent simulation + ReportAgent tool calling
Data layer	SQLite / SQLAlchemy / in-memory repositories / Elasticsearch	Zep Cloud + Cognee-style graph memory + runtime action logs
Package/runtime tooling	Poetry/pip-style Python workflow	Mixed npm + uv + Python backend workflow

In short: loreSystem compiles the world canon, while MiroFish simulates how actors behave inside that world. They are complementary systems, not the same stack in different folders — and right now the preferred default path is CAMEL.Bridge/ inside loreSystem, not the MiroFish/ subproject.

🗺️ CAMEL.Bridge continuity architecture

This C4 diagram shows the preferred current generation path: CAMEL.Bridge CLI → RumorBridgeService → canonical SQLite persistence, optional Qdrant semantic memory, and canon-control via CanonicalPersistEngine.

---

✨ Key Features

Feature	Description
200+ Entity Types	34 categories covering every aspect of AAA game design
Agent Teams	5 specialist AI teams extract lore in parallel
33 Domain Skills	Claude Code skills for entity extraction from text
MCP Server	Model Context Protocol server with 22 CRUD tools
DDD Architecture	Clean Domain → Application → Infrastructure layers
Multi-tenant	Run multiple game projects simultaneously
Dual Storage	In-Memory and SQLite backends, 100% repository coverage
Validation	Invariant checks, UUID tracking, version control

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Claude Code (for agent team features)

Installation

git clone https://github.com/bivex/loreSystem && cd loreSystem
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
make hooks-install

The repository ships its git hooks in .githooks/ so they survive fresh clones. Run make hooks-install once per clone to activate them.

Run

# Main application
python main.py

# Preferred current AI bridge path
python CAMEL.Bridge/run_rumor_pipeline.py --help

# MCP server (standalone)
python lore_mcp_server/run_server.py

# CLI
python -m src --help

# Tests
python -m pytest tests/ -v

---

🤖 LM Studio & Local Models

CAMEL.Bridge now works with local models via LM Studio! No API keys required, fully offline generation.

Setup LM Studio

1. Install LM Studio
2. Load a model (tested with L3-8B-Stheno-v3.2-MLX)
3. Start the server (default: http://127.0.0.1:1234)

Run with Local Model

# Set environment for LM Studio
export CAMEL_MODEL_PLATFORM="OPENAI"
export CAMEL_MODEL_BASE_URL="http://127.0.0.1:1234"
export CAMEL_MODEL_TYPE="l3-8b-stheno-v3.2-mlx"
export CAMEL_MODEL_TEMPERATURE="0.8"

# Run CAMEL Bridge
python CAMEL.Bridge/run_rumor_pipeline.py \
  --tenant-id 1 \
  --world-id 1 \
  --theme "Dark Fantasy" \
  --output-language ru \
  --count 2 \
  --db-path "lore_local.db"

Quick Test Scripts

# Test LM Studio connection
python3 scripts/test_lm_studio.py

# Generate quests with local model
python3 scripts/run_lm_studio.py --type quest --limit 3

Note: Local models are slower than cloud APIs (~8-10s per request) but offer:

• Zero API costs
• Full privacy (data never leaves your machine)
• Custom model fine-tuning
• Offline operation

---

🤖 Agent Team System

The core power of MythWeave is AI-powered lore extraction. You give it narrative text — it gives you structured entities.

Architecture

┌─────────────────────────────────────────────────────┐
│                  extraction-lead                     │
│            (orchestrator, delegate mode)             │
├───────────┬───────────┬───────────┬────────┬────────┤
│ narrative │   world   │  society  │systems │  tech  │
│   team    │   team    │   team    │  team  │  team  │
├───────────┼───────────┼───────────┼────────┼────────┤
│ Stories   │ Geography │ Factions  │ Skills │ Cinema │
│ Characters│ Climate   │ Politics  │ Economy│ Audio  │
│ Quests    │ Cities    │ Religion  │ Items  │ VFX    │
│ Lore      │ Dungeons  │ History   │ Combat │ Travel │
└───────────┴───────────┴───────────┴────────┴────────┘
        ↓           ↓           ↓          ↓         ↓
  narrative.json world.json society.json systems.json technical.json
        └───────────┴─────┬─────┴──────────┴─────────┘
                          ↓
                   merged_lore.json

Teams & Skills

Team	Role	Skills	Output
extraction-lead	Orchestrate, merge, validate	lore-extraction, entity-validator, json-formatter	entities/merged_lore.json
narrative-team	Stories, characters, quests	narrative-writing, character-design, quest-design, lore-writing	entities/narrative.json
world-team	Geography, environments, cities	world-building, environmental-design, urban-design	entities/world.json
society-team	Factions, politics, religion, history	faction-design, political-analysis, social-culture, religious-lore, historical-research	entities/society.json
systems-team	Progression, economy, items, combat	progression-design, economic-modeling, legendary-items, + 6 more	entities/systems.json
technical-team	Cinematics, audio, VFX, transport	cinematic-direction, audio-direction, vfx-design, + 6 more	entities/technical.json

How to Use

Full team extraction (recommended for chapters / long text):

Create an agent team to extract lore from chapter_1.txt.
Use the extraction-lead agent for coordination.
Spawn all 5 domain teammates.
Use delegate mode so the lead only coordinates.

Selective team (for focused text):

Create an agent team for chapter_1.txt.
Use extraction-lead. Spawn only narrative-team and world-team.

Single skill (quick extraction, no team overhead):

/character-design chapter_1.txt
/world-building chapter_1.txt

When to Use What

Scenario	Approach
Full chapter (5+ pages)	Agent team with all 5 specialists
Character-focused scene	/character-design or narrative-team only
Battle description	narrative-team + systems-team
World/map description	world-team only
Quick entity check	Single skill (/faction-design, /quest-design, etc.)

Cross-Reference Protocol

When a teammate finds an entity belonging to another domain, they log a cross-reference:

{
  "cross_references": [
    {
      "domain": "world-team",
      "entity_type": "location",
      "name": "Eldoria Village",
      "note": "Referenced as protagonist's hometown"
    }
  ]
}

The lead resolves all cross-references during the merge phase, connecting entities across domains.

---

📂 Project Structure

loreSystem/
├── src/                          # Main application (DDD)
│   ├── domain/                   #   Entities, value objects, repo interfaces
│   ├── application/              #   Use cases, services
│   ├── infrastructure/           #   SQLite, InMemory implementations
│   └── presentation/             #   CLI, API
│
├── lore_mcp_server/              # Standalone MCP server
│   ├── mcp_server/server.py      #   22 MCP tools
│   └── lore_data/                #   Persistent JSON storage
│
├── CAMEL.Bridge/                 # Preferred current AI bridge for lore generation/write-back
│   └── run_rumor_pipeline.py     #   Live rumor -> narrative -> quest bridge CLI
│
├── .claude/
│   ├── agents/                   # 6 team agent definitions
│   │   ├── extraction-lead.md    #   Orchestrator
│   │   ├── narrative-team.md     #   Stories, characters, quests
│   │   ├── world-team.md         #   Geography, environments
│   │   ├── society-team.md       #   Factions, politics, religion
│   │   ├── systems-team.md       #   Progression, economy, items
│   │   └── technical-team.md     #   Cinema, audio, VFX
│   ├── skills/                   # 33 domain extraction skills
│   └── settings.json             # Agent teams + permissions
│
├── entities/                     # Extracted entity output (JSON)
├── examples/                     # Sample lore JSON files
├── tests/                        # Test suite (unit, integration, e2e)
├── docs/                         # Full documentation
├── CLAUDE.md                     # Project context for AI agents
└── AGENTS.md                     # Agent workflow documentation

---

🏛️ Architecture

Domain-Driven Design

┌──────────────────────────────────────────┐
│              Presentation                │
│          (CLI, API, MCP Server)          │
├──────────────────────────────────────────┤
│              Application                 │
│        (Services, Use Cases, DTOs)       │
├──────────────────────────────────────────┤
│                Domain                    │
│  (Entities, Value Objects, Repo Interfaces)│
├──────────────────────────────────────────┤
│             Infrastructure               │
│    (SQLite, InMemory, Elasticsearch)     │
└──────────────────────────────────────────┘

Repository Status — 100% Coverage (18/18)

All repository interfaces are fully implemented with In-Memory + SQLite backends.

Core Lore System (4)

• WorldRepository — Create/list/delete worlds
• CharacterRepository — Manage characters within worlds
• StoryRepository — Create and organize stories
• PageRepository — Manage content pages

World Building (3)

• ItemRepository — Items and inventory
• LocationRepository — World locations and areas
• EnvironmentRepository — Time, weather, lighting

Game Mechanics (8)

• SessionRepository — Active game sessions
• ChoiceRepository — Interactive story choices
• FlowchartRepository — Story branching
• HandoutRepository — Player documents
• ImageRepository — Asset management
• InspirationRepository — Creative prompts
• MapRepository — Game maps
• TokenboardRepository — Combat boards

Content Organization (3)

• TagRepository — Tag-based organization
• NoteRepository — GM notes and annotations
• TemplateRepository — Reusable templates

Note: Only these 18 entities have repository interfaces and are accessible via the MCP server. The remaining 200+ domain entities exist in the domain model — their business logic is handled within other entities.

---

🌍 Domain Model — 200+ Entities across 34 Categories

Core Game Systems (50 entities)

Category	Count	Entities
Campaign & Story	17	Act, Chapter, Episode, Prologue, Epilogue, PlotBranch, Consequence, Ending, AlternateReality
Characters	9	CharacterEvolution, CharacterVariant, CharacterProfileEntry, MotionCapture, VoiceActor
Quests	7	QuestChain, QuestNode, QuestPrerequisite, QuestObjective, QuestTracker, QuestGiver
Skills & Progression	8	Skill, Perk, Trait, Attribute, Experience, LevelUp, TalentTree, Mastery
Inventory & Crafting	9	Inventory, CraftingRecipe, Material, Component, Blueprint, Enchantment, Socket, Rune, Glyph

World Building (39 entities)

Category	Count	Entities
Locations	10	HubArea, Instance, Dungeon, Raid, Arena, OpenWorldZone, Underground, Skybox, Dimension, PocketDimension
Politics & History	14	Era, EraTransition, Timeline, Calendar, Holiday, Season, TimePeriod, Treaty, Constitution, Law, LegalSystem, Nation, Kingdom, Empire
Economy	8	Trade, Barter, Tax, Tariff, Supply, Demand, Price, Inflation
Military	7	Army, Fleet, WeaponSystem, Defense, Fortification, SiegeEngine, Battalion

Social Systems (22 entities)

Category	Count	Entities
Social Relations	7	Reputation, Affinity, Disposition, Honor, Karma, SocialClass, SocialMobility
Factions	5	FactionHierarchy, FactionIdeology, FactionLeader, FactionResource, FactionTerritory
Religion & Mysticism	10	Cult, Sect, HolySite, Scripture, Ritual, Oath, Summon, Pact, Curse, Blessing

Content & Creativity (25 entities)

Category	Count	Entities
Lore System	8	LoreFragment, CodexEntry, JournalPage, BestiaryEntry, Memory, Dream, Nightmare, SecretArea
Music & Audio	8	Theme, Motif, Score, Soundtrack, VoiceLine, SoundEffect, Ambient, Silence
Visual Effects	5	VisualEffect, Particle, Shader, Lighting, ColorPalette
Cinematography	6	Cutscene, Cinematic, CameraPath, Transition, Fade, Flashback

Advanced Systems (29 entities)

Category	Count	Entities
Architecture	8	District, Ward, Quarter, Plaza, MarketSquare, Slums, NobleDistrict, PortDistrict
Biology & Ecology	6	FoodChain, Migration, Hibernation, Reproduction, Extinction, Evolution
Astronomy	10	Galaxy, Nebula, BlackHole, Wormhole, StarSystem, Moon, Eclipse, Solstice
Weather & Climate	5	WeatherPattern, Cataclysm, Disaster, Miracle, Atmosphere

Gameplay, UGC & Analytics (50+ entities)

Category	Count	Entities
Narrative Devices	6	PlotDevice, DeusExMachina, ChekhovsGun, Foreshadowing, FlashForward, RedHerring
Global Events	7	WorldEvent, SeasonalEvent, Invasion, Plague, Famine, War, Revolution
Travel	6	FastTravelPoint, Waypoint, SavePoint, Checkpoint, Autosave, SpawnPoint
Achievements	6	Achievement, Trophy, Badge, Title, Rank, Leaderboard
Legendary Items	6	LegendaryWeapon, MythicalArmor, DivineItem, CursedItem, ArtifactSet, RelicCollection
Transport	9	Pet, Mount, Familiar, MountEquipment, Vehicle, Spaceship, Airship, Portal, Teleporter
UGC	5	Mod, CustomMap, UserScenario, ShareCode, WorkshopEntry
Localization	5	Localization, Translation, VoiceOver, Subtitle, Dubbing
Analytics	8	PlayerMetric, SessionData, Heatmap, DropRate, ConversionRate, DifficultyCurve, LootTableWeight, BalanceEntities
Institutions	7	Academy, University, School, Library, ResearchCenter, Archive, Museum
Media	7	Newspaper, Radio, Television, Internet, SocialMedia, Propaganda, Rumor
Secrets	8	SecretArea, HiddenPath, EasterEgg, Mystery, Enigma, Riddle, Puzzle, Trap

---

🔧 33 Extraction Skills

All skills live in .claude/skills/ with YAML frontmatter for auto-discovery by Claude Code.

Domain Skills (30) — auto-invoked by Claude when relevant

Skill	Entities	Team
narrative-writing	Story, Chapter, Act, Episode, PlotBranch	narrative
character-design	Character, Relationships, Evolution, Variants	narrative
quest-design	Quest, QuestChain, Objectives, MoralChoice	narrative
lore-writing	LoreFragment, Codex, Bestiary, Dreams	narrative
world-building	Location, Dungeon, Arena, Dimension	world
environmental-design	Weather, Atmosphere, Lighting, Disasters	world
urban-design	District, Ward, Market, Plaza	world
faction-design	Faction, Hierarchy, Territory, Ideology	society
political-analysis	Government, Law, Court, Treaty	society
social-culture	SocialClass, Honor, Karma, Festival	society
religious-lore	Cult, Ritual, Blessing, Curse, Scripture	society
historical-research	Era, Timeline, Calendar, Ceremony	society
progression-design	Skill, Perk, Trait, TalentTree, XP	systems
economic-modeling	Trade, Currency, Shop, Supply/Demand	systems
legendary-items	Artifacts, Runes, Enchantments, Relics	systems
achievement-design	Trophy, Badge, Rank, Leaderboard	systems
puzzle-design	Puzzle, Riddle, Trap, EasterEgg	systems
military-strategy	Army, Fleet, Fortification, War	systems
biology-design	Ecosystem, FoodChain, Evolution	systems
celestial-science	Galaxy, Star, BlackHole, Eclipse	systems
analytics-balance	DropRate, DifficultyCurve, LootTable	systems
cinematic-direction	Cutscene, CameraPath, Flashback	technical
audio-direction	Music, SoundEffect, Motif, Ambient	technical
vfx-design	Particle, Shader, Lighting, ColorPalette	technical
transport-design	Mount, Vehicle, Portal, Airship	technical
content-management	Mod, Localization, UGC, Workshop	technical
media-analysis	Newspaper, Radio, Propaganda, Rumor	technical
research-design	Academy, Library, Archive, Museum	technical
ui-design	Choice, Flowchart, Handout, Tag	technical
technical-systems	193 catch-all entity types (safety net)	technical

Base Skills (3) — background knowledge, auto-loaded

Skill	Purpose
lore-extraction	Base extraction rules for all agents
entity-validator	Type checking, required fields, deduplication
json-formatter	Strict JSON output, UUID generation, schema compliance

---

🔌 MCP Server

The MCP server exposes 22 tools for lore CRUD operations:

python lore_mcp_server/run_server.py

Connect from Claude Code, Claude Desktop, or any MCP client. See MCP Server docs for the full API reference.

---

📖 Documentation

Document	Description
User Guide	Installation and usage
Documentation Index	Full docs navigation
Design & Implementation	Architecture decisions, ADRs
Validation & Verification	Test reports, edge cases
Feature Guides	Detailed feature docs
CLI Quick Reference	Command-line usage
MCP Server Docs	MCP API reference
Gacha Mechanics	Gacha system design

---

� Community Standards

This project follows recommended community standards for open-source development:

Standard	Status	Description
README	✅	Comprehensive project documentation
Code of Conduct	✅ 📄	Community guidelines and expectations
Contributing	✅ 📝	How to contribute to the project
License	✅ 📜	Project licensing information
Security Policy	✅ 🔒	Security vulnerability reporting
Issue Templates	✅ 📋	Standardized issue reporting
Pull Request Template	✅ 🔄	Standardized PR submissions

---

�🧪 Testing

# Full test suite with coverage
python -m pytest tests/ -v --cov=src --cov-report=html

# By marker
python -m pytest tests/ -m unit          # Fast, no I/O
python -m pytest tests/ -m integration   # Database tests
python -m pytest tests/ -m e2e           # Full system

---

🛠️ Tech Stack

Layer	Technologies
Language	Python 3.11+
Architecture	DDD, Hexagonal, Repository Pattern
Storage	SQLite, SQLAlchemy, In-Memory
Validation	Pydantic 2.x
CLI	Click, Rich
GUI	PyQt6
Search	Elasticsearch
Config	PyYAML, python-dotenv
DI	dependency-injector
AI	Claude Code Agent Teams, CAMEL Bridge, 33 Skills, MCP Server
Testing	pytest, pytest-cov

---

🧭 Which path should I use right now?

Prefer CAMEL.Bridge/ when you want

• structured lore generation directly into SQLite
• deterministic bridge-owned persistence and smoke testing
• fast iteration on rumor / event / character / quest / story entity generation
• the current actively preferred workflow in this repository

Use MiroFish/ when you specifically need

• social simulation runs
• report generation over runtime/simulation evidence
• the web UI / graph exploration flow
• experimentation with the simulation subproject itself

Practical rule of thumb

If you're deciding where to start today, start with:

python CAMEL.Bridge/run_rumor_pipeline.py --help

Reach for MiroFish/ only if the task is explicitly about simulation or report UX rather than canonical lore generation.

---

MythWeave Chronicles — built for game developers who take their lore seriously.