- 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 earlier commit missed 8 spots that still presented the graph
backend as undecided (00-overview x2, 12-storage x2, 13-microservice
x2, 06-ingestion, plan/05). All now pinned to Neo4j per ADR 0008.
Co-Authored-By: Claude <noreply@anthropic.com>
Cognee's default graph DB is Kuzu (PR #1022, June 2025). We override
to Neo4j for battle-testedness + Java UDFs. The time model
(time_in_window/overlap, era tree, current token) now ships as a
Neo4j Java UDF — queryable inline in Cypher, the contract was_true_at
depends on. Kuzu has no Java UDF mechanism, so on Kuzu the time model
would have been app-layer Python called outside the query. The POC's
pure-Python port becomes the reference impl + test oracle.
Resolves the 'verify which backend' hedge that was never executed:
- 08-architecture.md: storage line, diagram, time-model impl, hosting
- 22-cognee-boundary.md: storage ownership
- CONTEXT.md: Cognee entry pinned to Neo4j
- 00-overview.md: ADR index
Post-cognify consistency hook (Q10 second half): Cognee exposes no
built-in hook. 04-consistency.md updated — live sweep runs as a final
Task in run_custom_pipeline (post-ingest, <100ms); nightly full sweep
runs as external cron. Both write the same :ConsistencyRun shape.
Co-Authored-By: Claude <noreply@anthropic.com>
Cognee exposes two ontology mechanisms:
- graph_model= (Pydantic DataPoint hierarchy) — a CONTRACT;
the LLM can only emit fields/labels that fit the declared
schema. Invalid extractions are structurally rejected.
- ontology_file_path= (RDF/OWL) — ENRICHMENT; tags matched
entities ontology_valid=True but does not constrain output.
We pick graph_model= so the slice-3 risk ('reject triples with
unknown labels') is enforced at the LLM layer, not post-filtered.
OWL is deferred — it's interop we don't need yet, and can be
layered on later as enrichment without displacing the contract.
Trade-off: adding a label is a code change (new DataPoint subclass),
not a YAML edit. That rigidity is the point for a typed-ontology
engine; TypeTemplate (slice 5) is the 'add types without code'
escape hatch layered on top.
Also fixed cognee-integration.md: replaced two fictional Cognee
APIs (extract_graph_from_data.set_prompt, register_dataset) with
the real surface — remember(custom_prompt=, graph_model=) for the
prose path and add_data_points() for the structured path. Added
the 'graph_model enforces shape not value' caveat pointing to the
consistency engine (slice 2) as the second gate.
Slice 3 AC 3.5a added: a 37th label is structurally rejected by
graph_model (proves ADR 0007 holds).
Co-Authored-By: Claude <noreply@anthropic.com>
Research into Cognee's actual API (docs.cognee.ai) confirmed the
docs made a load-bearing false claim: that the Lore Engine
'inherits and generalizes' a Contradiction node, get_contradictions
tool, 8 inherited MCP tools, and neo4j-init.cypher from the substrate.
Cognee ships NONE of that. Cognee provides DataPoint + custom graph
models + remember/recall + a Cypher/APOC graph-rule pattern. So:
- Slice 2 (consistency) is a from-scratch BUILD, not a generalization
- Categories A/B/D (Contradiction/Anachronism/Orphan) are ours
- Category C (declarative OntologyRule) rides Cognee's Cypher pattern
- '8 inherited tools' -> '8 base tools' (one wraps cognee.recall)
- '7 inherited labels' -> '7 base types' (Lore Engine originals on DataPoint)
Fixed across 04-consistency, 01-ontology, 05-mcp-tools, 00-overview,
09-roadmap, 15-related-work, 16-comparison. Historical GraphMCP
comparisons left intact.
Added CONTEXT.md (glossary) — the grill-with-docs skill mandates it
and 6 ADRs' worth of resolved terms (Lineage/Faction/Region/Plane/
LoreSource/extraction+source confidence/disputed edge/retcon/Setting/
ConsistencyRun/Cognee) had no single home. New readers no longer mine
ADR prose for the vocabulary.
Co-Authored-By: Claude <noreply@anthropic.com>
The 18 design docs were the engine spec. These 12 new files are
the operational layer that goes with it:
Design (docs/):
- 18-eval-policy.md thresholds + cadence (lifted from slice 7)
- 19-retcon-policy.md declare/preserve/surface retcons; codex syntax stub
- 20-multi-setting-policy settings.yaml; cross-setting queries
- 21-quickstart.md 1-page 'first 5 minutes'
- 22-cognee-boundary.md substrate vs domain contract
- cognee-integration.md recipe for prompt override + LiteLLM routing
Registries (docs/prompts/, docs/models/):
- prompts/README.md convention; system-prompt.md mirror, extraction-prompt.md stub
- models/README.md convention; minimax-m3.md primary notes
ADRs (docs/adr/):
- 0006-cognee-version-pin.md Cognee pinned at 1.1.2; harness is the upgrade gate
Index updates:
- 00-overview.md full doc set with categories
- 07-reasoning-harness.md link to prompt mirror
- 09-roadmap.md link to operational docs
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>
