Skip to content

Repository Guide

This page explains how to read the repository without collapsing everything into one misleading label.

The Repo Has Six Main Surfaces

1. DDA-X Framework

This is the conceptual and engineering core:

  • surprise as prediction error in embedding space
  • rigidity as a control variable
  • identity persistence through attractor dynamics
  • memory retrieval shaped by similarity, recency, and salience
  • reply control through state-aware prompting and selection

The best entry points are:

2. Simulation Lineage

The simulations/ directory contains the long arc of development.

Some files belong to the curated chronology documented in:

Other files are newer branches, utilities, experiments, visualizers, or adjacent prototypes. That means the chronology is real, but it is not the whole living surface of the folder.

The main non-chronology families currently visible are:

  • pressure and fracture experiments
  • mythic and narrative branches
  • companion and character systems
  • interfaces and support surfaces

That family split is captured more explicitly in Codebase Taxonomy.

3. Applied Systems

Some DDA-X builds are no longer best understood as raw simulations. They are companion systems, interfaces, or domain-facing applications.

Current examples include:

  • apps/brobot/true_brobot.py
  • apps/brobot/brobot_ui.py
  • apps/eckhart/azure_phi_chat.py
  • apps/eckhart/eckhart_terminal.py
  • apps/mad_hatter/mad_hatter_chatbot.py
  • apps/repository_guardian/repository_guardian.py
  • apps/singularity/singularity_chatbot.py
  • apps/torahbot/torah_study_bot.py
  • apps/torahbot/torahbot_ui.py

This is the surface where DDA-X stops being only a research object and becomes a usable software artifact.

4. Live Agent Runtime

The Discord scaffold turns the framework into a persistent interactive agent.

Core pieces:

  • run_discord_agent.py
  • src/discord_agent/config.py
  • src/discord_agent/runtime.py
  • src/discord_agent/bot.py
  • configs/discord_agent/*.json

Supporting docs:

5. Support Utilities

The scripts/ directory holds the reusable support layer around the main research surfaces.

Current examples:

  • scripts/debug_api/openai_probe.py
  • scripts/session_tools/repository_guardian_dashboard.py
  • scripts/session_tools/analyze_flame_war.py
  • scripts/simulation_support/repository_guardian_stress_test.py
  • scripts/vanilla_comparison.py

Use this layer for inspection, dashboards, validation, export, and operational probing.

6. Archive Surface

The repository also keeps an explicit archive for older build systems, legacy docs, preserved prompt artifacts, historical manifests, and retired code paths.

Start here:

  • archive/README.md

That material matters for provenance and historical interpretation, but it is not the same thing as the current public execution surface.

Where The Repo Is Headed

The repo is being framed as a living v1, not a sealed archive. The public direction for the next phase lives in Research Roadmap.

How To Read The Simulation Folder

The safest way to understand simulations/ is:

  • older files often show the formation of key mechanics
  • later files often contain the strongest or most integrated work
  • not every file plays the same role

There are at least four recurring categories inside that folder:

  • core simulations
  • visualizers and renderers
  • verification scripts
  • side branches and applied experiments

Some of those applied experiments are strong enough to be promoted into apps/ over time. That is why a single hard count can misrepresent the repo.

Where The Refined Master Prompt Fits

refined_master_prompt.md is best understood as a synthesis artifact.

It captures accumulated thinking, framing, and language from the project's evolution. It is important, but it is not the only canonical source of truth. The framework also lives in code, docs, simulation behavior, and the live agent runtime.

What Counts As The Public Surface

If you are presenting DDA-X as an open-source body of work, the clean public surface is:

  • the framework docs
  • the simulation lineage docs
  • the applied systems surface
  • the Discord agent scaffold
  • the support tooling surface
  • the key profile/config/runtime files

Local runtime state, private Discord logs, and ephemeral debug artifacts are not part of that public surface.

Do not think of this repo as a frozen paper supplement.

Think of it as:

  • a research scaffold
  • a simulation lab
  • an applied software surface
  • an applied agent runtime
  • a support tooling layer
  • a preserved archive behind the active implementation

That framing is closer to what the repository actually is.