Architecture

Six layer engines plus an optional self-concept layer plus the alignment composer

Each motivational layer ships as a standalone module. The shape is constant across the six core modules (plus the optional seventh, self-concept): a data-model file, an engine file exposing an asynchronous public class, and a small re-export surface that keeps the import path tidy.

• Values Engine — create, read, update, and delete values; check whether a candidate action aligns with them; detect structural conflicts on the Schwartz circumplex; rank values for a given context; round-trip exports and imports.
• Beliefs Engine — manage beliefs; absorb evidence with confidence-weighted updates (cites AGM); query by domain; decay stale entries.
• Purpose Engine — primary, secondary, and contextual purposes; setters for each; a consistency check against values and beliefs.
• Desires Engine — manage desires; update intensity; link desires to values and beliefs; generate goal candidates.
• Goals Engine — manage goals; update progress (auto-completes at full); validated status transitions; goal decomposition; deadline checking.
• Self-Concept Engine (opt-in) — append-only autobiographical episodes; a behaviour-inference loop (cited as inspired by Bem self-perception); a lesson-integration loop (cited as inspired by SDT's organismic integration theory); an identity-drift check (cited as inspired by Erikson coherence). See Future for research foundations.
• Alignment Engine — composes the core engines (plus self-concept when present): alignment checks, conflict resolution, goal suggestions, goal validation, and a full-audit sweep.

Events and integration seams

Every engine exposes an event-subscription method and emits structured events at lifecycle transitions: a value is added, a belief gets new evidence, a belief's confidence changes, a contextual purpose is set, a desire's intensity is updated, a goal is created or decomposed, an alignment finding is resolved, and so on. Handlers may be synchronous or asynchronous — the engines await anything that is awaitable.

The intended integration shape is: register handlers at construction; let the agent's runtime loop drive the engines; subscribe an audit log or observability sink to the events. The full-audit sweep plugs into the same event bus and is intended to run periodically (say, hourly) so drift surfaces before it bites.

Storage abstraction

Every engine takes a small storage abstraction in its constructor. The contract is intentionally minimal — a handful of asynchronous methods for reading, writing, listing, deleting, and counting keyed records. Three backends ship in the box:

• In-memory — tests and ephemeral experiments.
• Single-file JSON — atomic writes with file locking.
• SQLite — write-ahead-logging mode for serious prototyping, behind an optional install extra.

Bring-your-own backends (Postgres, Redis, any key-value store) satisfy the same contract. See Integration for adapter recipes.

Comparison with classical agent architectures

What we deliberately leave out

The framework is a values/belief/purpose layer — not an agent kernel. Tasks (the bottom of the diagram) are the integrator's responsibility; the framework reasons about them but does not store them. Likewise, planning, scheduling, tool use, and prompt construction are explicit non-goals. Embed alongside; don't rip-and-replace.