Files

Kaysser Kayyali c8a8dcef2e docs: operational layer — eval policy, retcon policy, multi-setting, quickstart, Cognee boundary, prompt + model registries

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>

2026-06-17 22:16:07 -04:00

2.7 KiB

Raw Permalink Blame History

21 — Quickstart (the first 5 minutes)

Status: 📋 planned. A 1-page guide for a world-builder who has never seen the engine.

Goal

A new user can go from git clone to a working lore.recall("Who is Aldric?") in under 5 minutes, with no reading of the 18 design docs required.

Prerequisites

Python 3.11+
Docker (for Cognee + Neo4j)
A Minimax-M3 API key ($MINIMAX_API_KEY) — see docs/models/minimax-m3.md

Steps

# 1. Clone and install
git clone https://github.com/<owner>/lore-engine
cd lore-engine
pip install -e .

# 2. Stand up the substrate
docker compose up -d          # brings up Cognee + Neo4j + vector store

# 3. Configure the LLM
export LLM_MODEL=openai/minimax-m3
export OPENAI_BASE_URL=https://api.minimax.io/v1
export OPENAI_API_KEY=$MINIMAX_API_KEY

# 4. Ingest the sample codex (Mardonari campaign, ~150 files)
python3 scripts/01_ingest.py

# 5. Smoke test — this is the moment of truth
python3 scripts/02_demo.py --query "Who is Aldric Raventhorne?"
# Expected output:
#   Aldric Raventhorne is a human noble of House Vyr, founder of the
#   Crimson Pact, and a central figure in the 3rd Age politics of
#   Mardonari. He is the son of Theron Raventhorne...
#   Sources: Aldric_Raventhorne.md, Crimson_Pact_founding.md

If step 5 returns a structured answer with sources, the engine is working. If it returns "I don't know" or an error, see docs/22-cognee-boundary.md#troubleshooting.

Common recipes

"I want to add a faction"

# 1. Create the codex file
$EDITOR lore_engine_poc/seed/factions/My_Faction.md
# frontmatter:
#   ---
#   title: My Faction
#   type: faction
#   setting: mardonari
#   founded: 3rd_age.year_400
#   sources: [my_session_47.md]
#   ---

# 2. Re-ingest
python3 scripts/01_ingest.py

# 3. Query
python3 scripts/02_demo.py --query "Tell me about My Faction."

"I want to retcon a founding event"

See docs/19-retcon-policy.md. The TL;DR is: edit the superseding file's frontmatter to add a supersedes: block referencing the old event, then re-ingest. The old edge is preserved, not deleted.

"I want to add a new entity type (e.g., starship)"

Out of scope for v1. See docs/11-extensibility.md for the v1.1 TypeTemplate system. Until then, all new entity types are expressible as DomainEntity with a type discriminator property.

"I want to swap the LLM"

See docs/models/README.md. The minimum is to change LLM_MODEL and OPENAI_BASE_URL. The full eval harness should pass before shipping the swap — see docs/18-eval-policy.md.

Where to go next

docs/00-overview.md — what the engine is
docs/14-examples.md — worked examples
docs/plan/00-slice-0-poc.md — what's already built
docs/22-cognee-boundary.md — substrate specifics

2.7 KiB Raw Permalink Blame History