Kaysser Kayyali
798f12825a
Two sources that produce the same (subject, relation, object)
with conflicting time bounds no longer get merged silently. The
edge merger now keeps them as separate Edge records, marks both
is_disputed=True, and links them via disputed_with. Slice 2's
consistency engine will turn this into a Contradiction node.
POC changes:
- Edge.is_disputed: bool (default False)
- Edge.disputed_with: list[Edge]
- _windows_consistent(a_from, a_until, b_from, b_until) helper
- was_true_at response now includes is_disputed +
disputed_with_sources fields
- tests/test_confidence.py: 5 new cases (11/11 pass)
The POC codex has no real disputes, so is_disputed is always
false in the demo output. The machinery is in place for slice
1, where family_tree.yaml can produce temporal disagreements
between two source files.
ADRs:
- 0001-aggregate-confidence-floor.md: aggregate is min of
per-source (extraction*source), not mean or max.
- 0002-disputed-edges-stay-separate.md: conflicting bounds
produce two edges, not one merged.
Co-Authored-By: Claude <noreply@anthropic.com>
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 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 | Goals, design philosophy, what we inherit vs. what we add |
| 01 | Ontology | Node labels, edge types, properties — the full world model |
| 02 | Time Model | Eras, calendars, temporal validity, "was X true at time T?" |
| 03 | Macro↔Micro Association | How lineage chains, location hierarchies, and faction membership bind micro details to macro context |
| 04 | Consistency Engine | Rules, anachronism detection, contradiction pattern extensions |
| 05 | MCP Tool Catalog | One section per tool — purpose, signature, returns, when to use |
| 06 | Ingestion Pipelines | How to ingest structured lore (timelines, family trees, gazetteers, bestiary) and free prose |
| 07 | Reasoning Harness | LLM prompt patterns + tool-chaining recipes for the most important question types |
| 08 | Architecture | System diagram, data flow, service layout |
| 09 | Roadmap | Phased build plan — MVP first, then layers |
| 10 | Critique | Self-pressure-test: what could break, where this could fail |
| 11 | Extensibility | v1.1 — polymorphic DomainEntity + TypeTemplate model. New domains as YAML, not code. |
| 12 | Storage Strategy | v1.1 — which data goes in Neo4j, Postgres, pgvector, Redis, S3. Why and when. |
| 13 | Microservice Decomposition | v1.1 — split the mcp-server monolith. Macro/micro iteration speeds. |
| 14 | Worked Examples | v1.1 — three end-to-end examples: thieves-guild missions, war campaigns, black-market economy. |
| 15 | Related Work | Survey of GraphRAG, Cognee, LightRAG, Generative Agents, IVIE, WikiChat, TKG methods, CoK. With stars, citations, and direct quotes from abstracts. |
| 16 | Comparison & Critical Thinking | Head-to-head with GraphRAG, Cognee, Generative Agents. Honest assessment of where the Lore Engine is worse. Strategic recommendation. |
| 17 | Planes of Existence | 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:
- Remember. Capture the world as a typed, temporal, source-attributed graph — not a bag of facts.
- 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.
- Reason. Provide tools that compose:
was_allied_with+at_time+as_far_as= "Were House Vyr and the Crimson Pact allied in 340 TA?" - 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.