Ghostlight/README.md

# Ghostlight

Ghostlight is a research and implementation home for socially persistent
generative agents.

The project is about characters and simulated people who remain coherent under
time, pressure, memory, culture, misreading, masks, incentives, and changing
relationships. The aim is not to make a language model sound charming for one
scene. The aim is to build machinery that can track who someone is, what they
believe, what they hide, how they see other people, and how their behavior
changes when the world leans on them.

In practical terms, Ghostlight is building the state and projection layer for
character-driven generation:

- durable canonical character state
- observer-specific perceived state
- directional relationship stance
- cultural and institutional pressure
- memory and goal selection
- speaker-local prompt projection
- evaluation targets for emergent verbal behavior
- a future path for training smaller specialist projection models

The first concrete consumer is Aetheria authoring support, especially Call of
the Void content generation, dialogue scaffolding, and procedural drama for
narrated stories in the Aetheria timeline.

## Core Idea

Ghostlight separates three things that are easy to blur together:

1. **Canonical state**
   What is true about a character, relationship, event, memory, or scene.

2. **Perceived state**
   What a particular observer thinks is true, including misreadings,
   attribution bias, suspicion, trust, projection, and partial knowledge.

3. **Prompt projection**
   A temporary speaker-local prompt surface for one scene or turn.

The prompt is not the character. The prompt is a rendered slice of state.

That distinction matters because believable dialogue should come from pressure,
not vibes. Cat being sarcastic should fall out of shame sensitivity, distance
seeking, suspicion, relationship tension, scene stakes, and dry pointed voice.
Oz withholding information should fall out of mask rigidity, privacy pressure,
relationship fear, and the need to stay useful. The system should be able to
show its work.

## Current Status

Ghostlight is early architecture plus executable schema seams.

Currently present:

- v0 canonical agent-state schema
- required variable lists for state families and relationship stance
- Call of the Void-flavored Cat/Oz fixture
- dependency-free fixture validator
- prompt projection contract
- projection distillation plan for teacher/student projector training
- persistence surfaces for re-entry, evidence, planning, and compaction hygiene

Not present yet:

- runtime prompt renderer
- projection training dataset
- student projection model
- event/classifier pipeline
- simulation loop
- relationship update engine
- culture prior engine

## How Projection Is Supposed To Work

For one speaker in one scene, Ghostlight should gather speaker-local state:

- what the speaker knows
- what they believe
- what they want
- what they are protecting
- what memories are active
- how they read the listener
- what the relationship currently feels like
- what pressures the scene applies
- what voice surface is active

The projection layer turns that into compact pressure prose and prompt sections.
The dialogue model then writes from that pressure model.

Longer term, a frontier model can act as a teacher projector that generates
reviewed projection artifacts. Those artifacts can train a smaller student
projector once the projection schema, deterministic input slicer, and evaluator
are stable.

## Repo Tour

- `AGENTS.md`: operating discipline for humans and agents
- `state/map.yaml`: canonical project map and current next action
- `state/scratch.md`: disposable working memory for one bounded subgoal
- `state/evidence.jsonl`: distilled belief-changing evidence
- `notes/fresh-workspace-handoff.md`: compact re-entry packet
- `notes/ghostlight-current-system-map.md`: current repo machinery
- `notes/ghostlight-implementation-plan.md`: larger implementation sequence
- `notes/architecture-rationale.md`: why the persistence and state split exists
- `docs/research/`: research backlog and modeling notes
- `docs/aetheria/`: Aetheria source material used by Ghostlight
- `docs/architecture/`: state, projection, and authoring architecture
- `schemas/`: JSON schema contracts and required field lists
- `examples/`: schema fixtures and future projection examples
- `tools/ghostlight_state.py`: state inspection and evidence helper
- `tools/ghostlight_prepare_compaction.py`: pre-compaction audit helper
- `tools/validate_agent_state.py`: focused fixture validator

## Useful Commands

```powershell
npm run state:status
npm run state:prepare-compaction
npm run schema:validate
```

To add distilled evidence:

```powershell
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\ghostlight_state.py' add-evidence --type design --status accepted --note '...'
```

## Best Starting Points

- `docs/architecture/canonical-agent-state-schema.md`
- `docs/architecture/agent-state-variable-glossary.md`
- `docs/architecture/prompt-projection-contract.md`
- `docs/architecture/projection-distillation-plan.md`
- `examples/agent-state.call-of-the-void.json`

For Codex-driven work, read `AGENTS.md` before changing the repo. It contains
the working rules that keep the project state coherent between sessions.