7d81a761f9
Replaces the v1.1 'world_id is a string' model with a graph-of-planes. Driven by Kay's Q2 ('worlds are planes') and the v1.2 design review.
- 17-planes.md (NEW): the plane taxonomy, the four relation types, Cypher patterns, migration from world_id, open questions
- 01-ontology.md: Plane and Setting as first-class nodes; the 6 plane-relation edge types
- 02-time-model.md: plane-aware time (entity_planes_at_time as the 6th time-aware primitive)
- 08-architecture.md: data flow for plane questions (the 'can I get from X to Y' pattern)
- 11-extensibility.md: how to add custom planes and plane-relations without code
- 12-storage-strategy.md: planes are pure graph (no Postgres/Redis/Qdrant/S3 changes)
- 14-examples.md: example 5 — full Setting + planes + Roland + Asmodeus + LLM tool calls
- README.md: v1.2 entry + doc 17 in the table of contents
The POC rebuild (T10) is the next step: migrate the existing 4 world_id values to Setting/Plane nodes and update the plugin queries to use EXISTS_IN/LOCATED_IN.
52 lines
4.5 KiB
Markdown
52 lines
4.5 KiB
Markdown
# Lore Engine
|
|
|
|
A Neo4j-backed world ontology and modular MCP tool surface that lets an LLM reason about a high-fantasy world with **historical accuracy**, **temporal consistency**, and **macro↔micro association**.
|
|
|
|
Built on top of the existing [GraphMCP-Example](https://git.homelab.local/kaykayyali/GraphMCP-Example) stack (Neo4j + Redis Streams + Go MCP server), with extensions for the things a *world* needs that a *message archive* does not.
|
|
|
|
**v1.2 (current):** adds first-class `Plane` and `Setting` graph nodes with `REFLECTS` / `LAYER_OF` / `ADJACENT_TO` / `ACCESSIBLE_VIA` relations. Replaces the v1.1 flat `world_id` strings with the model from `17-planes.md`. The v1.1 extension model (`DomainEntity`, multi-store) is unchanged.
|
|
|
|
**v1.1:** adds polymorphic `DomainEntity` extension model, multi-store storage strategy, and a microservice decomposition plan. See `11-extensibility.md`, `12-storage-strategy.md`, `13-microservice-decomposition.md`, `14-examples.md`.
|
|
|
|
---
|
|
|
|
## Read in this order
|
|
|
|
| # | Doc | What it covers |
|
|
|---|---|---|
|
|
| 00 | [Overview](docs/00-overview.md) | Goals, design philosophy, what we inherit vs. what we add |
|
|
| 01 | [Ontology](docs/01-ontology.md) | Node labels, edge types, properties — the full world model |
|
|
| 02 | [Time Model](docs/02-time-model.md) | Eras, calendars, temporal validity, "was X true at time T?" |
|
|
| 03 | [Macro↔Micro Association](docs/03-macro-micro.md) | How lineage chains, location hierarchies, and faction membership bind micro details to macro context |
|
|
| 04 | [Consistency Engine](docs/04-consistency.md) | Rules, anachronism detection, contradiction pattern extensions |
|
|
| 05 | [MCP Tool Catalog](docs/05-mcp-tools.md) | One section per tool — purpose, signature, returns, when to use |
|
|
| 06 | [Ingestion Pipelines](docs/06-ingestion.md) | How to ingest structured lore (timelines, family trees, gazetteers, bestiary) and free prose |
|
|
| 07 | [Reasoning Harness](docs/07-reasoning-harness.md) | LLM prompt patterns + tool-chaining recipes for the most important question types |
|
|
| 08 | [Architecture](docs/08-architecture.md) | System diagram, data flow, service layout |
|
|
| 09 | [Roadmap](docs/09-roadmap.md) | Phased build plan — MVP first, then layers |
|
|
| 10 | [Critique](docs/10-critique.md) | Self-pressure-test: what could break, where this could fail |
|
|
| 11 | [Extensibility](docs/11-extensibility.md) | **v1.1** — polymorphic `DomainEntity` + `TypeTemplate` model. New domains as YAML, not code. |
|
|
| 12 | [Storage Strategy](docs/12-storage-strategy.md) | **v1.1** — which data goes in Neo4j, Postgres, pgvector, Redis, S3. Why and when. |
|
|
| 13 | [Microservice Decomposition](docs/13-microservice-decomposition.md) | **v1.1** — split the mcp-server monolith. Macro/micro iteration speeds. |
|
|
| 14 | [Worked Examples](docs/14-examples.md) | **v1.1** — three end-to-end examples: thieves-guild missions, war campaigns, black-market economy. |
|
|
| 15 | [Related Work](docs/15-related-work.md) | Survey of GraphRAG, Cognee, LightRAG, Generative Agents, IVIE, WikiChat, TKG methods, CoK. With stars, citations, and direct quotes from abstracts. |
|
|
| 16 | [Comparison & Critical Thinking](docs/16-comparison.md) | Head-to-head with GraphRAG, Cognee, Generative Agents. Honest assessment of where the Lore Engine is worse. Strategic recommendation. |
|
|
| 17 | [Planes of Existence](docs/17-planes.md) | **v1.2** — first-class `Setting` and `Plane` graph nodes, the plane taxonomy (`material` / `reflection` / `transit` / `outer` / `demiplane` / etc.), the four plane-relation edge types, and the migration from the v1.1 `world_id` string. |
|
|
|
|
## The 30-second pitch
|
|
|
|
A Lore Engine has four jobs, and only four:
|
|
|
|
1. **Remember.** Capture the world as a typed, temporal, source-attributed graph — not a bag of facts.
|
|
2. **Scope.** When the LLM asks about Aldric, it gets *Aldric's* context — not the world's. When it asks about Aldric-in-340-TA, it gets the right slice of his life.
|
|
3. **Reason.** Provide tools that compose: `was_allied_with` + `at_time` + `as_far_as` = "Were House Vyr and the Crimson Pact allied in 340 TA?"
|
|
4. **Verify.** Flag anachronisms, contradictions, and missing lineages *before* the LLM hallucinates around them.
|
|
|
|
Everything else is implementation detail.
|
|
|
|
## Status
|
|
|
|
**Design phase.** No code yet. This repo is the design contract — read it, red-team it, then we build.
|
|
|
|
The underlying graph infrastructure (Neo4j, Redis, MCP transport) is already production in `GraphMCP-Example`. The Lore Engine adds ontology, time model, consistency rules, and ~12 new MCP tools on top of that substrate.
|