Brings the docs into sync with what shipped in
slice 6 (712→761 tests, 7 sub-slices):
- Setting↔Plane membership is encoded as a
``setting_id`` field on the Plane node, not as a
HAS_PLANE edge. The pure-Cypher pattern in the
design is the *intent*; the engine stores it
differently for the 1-to-many reverse-lookup.
Updated 01-ontology.md, 11-extensibility.md,
14-examples.md, 17-planes.md accordingly.
- EXISTS_IN (entity → Setting) is the timeless
type-assertion; time-bounded planar location is
LOCATED_IN_PLANE (entity → Plane) with valid_from
/valid_until. Updated the edge-type table, the
Cypher examples, and the migration story.
- 17-planes.md: clarified "EXISTS_IN is many-to-many
(setting level, not plane level)"; the legacy v1.1
EXISTS_IN (entity → plane) is folded into
LOCATED_IN_PLANE for the time-bounded case and
removed from the timeless one.
- ADR 0013 — the v1.2 plane-model migration story.
Documents the 7 locked decisions (Setting/Plane
first-class, setting_id field encoding, the
GraphBackend Protocol extensions, the read-tool
setting filter, the 4 plane-relation edge types,
the migration's idempotency), what was rejected
and why, and the consequences for the Neo4j
parity follow-up.
Co-Authored-By: Claude <noreply@anthropic.com>
- Add docs/how-it-works.html: self-contained explainer with inline SVG
diagrams, ELI5 tone. Covers the big idea, plain-AI vs Lore Engine,
the cast (Cognee/Neo4j/Minimax-M3/45 tools), question flow, why time
matters, disputed edges + confidence, how lore gets in, the
consistency safety net, and how it differs from a wiki.
- Soften the false-precise '36 labels' bucket arithmetic to honest
'roughly 36' across 00-overview, 11-extensibility, 10-critique
(sub-arithmetic didn't reconcile across docs).
Co-Authored-By: Claude <noreply@anthropic.com>
Three findings from the Cognee-API review:
ADR 0009 (the big one): edges with time/confidence are reified
:Relation nodes, promoted v1.1 -> v1. Cognee's graph_model can't
carry valid_from/valid_until/confidence on a native edge (an edge
is a nested DataPoint field; the Edge object only has weight +
relationship_type). So any edge the time model, consistency engine,
disputed-edge machinery, and retcon policy operate on is a Relation
node. Structural edges (is_type, template-wiring) stay native.
Propagated: 11-extensibility (Relation now v1, +disputed/retcon
fields), 04-consistency (Category A + B Cypher match through Relation
nodes, materialize is_disputed/disputed_with), 00-overview count,
CONTEXT.md (+Relation term), slice 1/3/6 notes.
Finding 1: cognee.recall is not 'low-precision' — it returns scored
multi-source RecallResponse objects (incl cypher/triplet/temporal
kinds), session-aware. It's the fallback because results are
un-typed/un-cited/un-time-bounded, not low-precision. Reframed in
07-reasoning-harness + 05-mcp-tools.
Finding 3: 'register our 45 tools with Cognee's dispatch' was false.
Cognee ships cognee-mcp (a fixed 14-tool surface) — a reference
server, not a registry we extend. Lore Engine runs its own MCP
server (45 tools), calls Cognee's Python API in-process. Reframed
in 00-overview + 22-cognee-boundary.
Co-Authored-By: Claude <noreply@anthropic.com>
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>
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.
