Kaysser Kayyali
7d2ab8699f
The /docs review surfaced two categories of work: real bugs and a substrate decision. This commit lands both. Pure fixes: - Fix markdown table corruption in 01-ontology.md (3 `||` lines + duplicate `### Magic, culture, language` header) - Replace wrong tool/label/doc count claims with the real numbers: 30 -> 45 MCP tools, 14 -> 36 node labels, 14 -> 18 docs - Resolve Phase 11 collision in 09-roadmap.md (v1.1 phases renumbered to 4-7 in the unified plan; v1 Polish keeps its Phase 11) - Propagate the v1.2 world_id -> Setting/Plane deprecation to the v1.1 docs (11, 12, 14, 17): YAML world_id -> setting_id, Postgres world table -> setting table, Cypher index renamed, migration steps 6 + 7 added in 17-planes.md Cognee substrate switch (the strategy change): - 00-overview.md: substrate line now Cognee, not GraphMCP-Example - 08-architecture.md: full system diagram, services layout, hosting, and resource budget rewritten for Cognee as the substrate - 11-extensibility.md: 4-layer diagram reframed (Cognee data-model extension; template-watcher is a Cognee data-pipeline) - 12-storage-strategy.md: 5 stores collapse to 3 layers; saga pattern removed (Cognee handles cross-store transactions) - 13-microservice-decomposition.md: full rewrite (Cognee is the gateway; no monolith problem; 5+ Go services collapse to one in-process Python extension) - 14-examples.md: Example 6 added (full 8-step Cognee integration walkthrough from "stand up Cognee" to "template-driven tool call") - 15-related-work.md: Cognee reframed as substrate, not option - 16-comparison.md: strategic section reframed (decision made, not debate); the build order is now in 09-roadmap.md (Cognee-spike-first) - 10-critique.md: S1.4, S1.5, S2.5, S2.6 status updated for Cognee - 07-reasoning-harness.md: system prompt mentions Cognee + cognee.recall fallback - 06-ingestion.md: Path 1 (prose) via cognee.add/cognify; Path 2 (YAML) via Lore Engine parser; Go-worker section replaced Build plan (09-roadmap.md): the v1+v1.1 work collapses from 43 days on GraphMCP-Example to 33 days on Cognee. The MVP is end of Phase 3 (16 days): Cognee spike, typed ontology, time model, 45 MCP tools. Phase 4-6 add the consistency engine, TypeTemplate polymorphic extension, and reasoning-harness validation. 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.