Architecture

Six layer engines + optional Self-Concept + AlignmentEngine

Each motivational layer ships as a standalone module under src/<layer>/. The shape is constant across the six core modules (plus the optional seventh, Self-Concept): a models.py with Pydantic v2 models, an engine.py exposing an async public class, and an __init__.py re-exporting the public surface.

• ValuesEngine — CRUD; check_action; detect_structural_conflicts; rank_for_context; round-tripping export_values/import_values.
• BeliefsEngine — CRUD; add_evidence (cites AGM); query_by_domain; decay_stale.
• PurposeEngine — primary, secondary, contextual purposes; set_primary, add_secondary, add_contextual; check_consistency.
• DesiresEngine — CRUD; update_intensity; idempotent link_to_value/link_to_belief; generate_goal_candidates.
• GoalsEngine — CRUD; update_progress (auto-completes at 1.0); set_status (validated transitions); decompose; check_deadlines.
• SelfConceptEngine (opt-in) — append-only autobiographical episodes; infer_from_behaviour (Bem self-perception theory); integrate_lessons (SDT organismic integration); check_identity_drift (Erikson coherence). See Future for research foundations.
• AlignmentEngine — composes the five core engines (plus Self-Concept when present); check_alignment, resolve_conflict, suggest_goals, validate_goal, full_audit.

Events and integration seams

Every engine exposes an on(event, handler) method and emits structured events at lifecycle transitions: value_added, belief.evidence_added, belief.confidence_changed, purpose.contextual_set, desire.intensity_updated, goal.created, goal.decomposed, alignment.resolved, and so on. Handlers may be sync or async — the engines await anything with an __await__.

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. AlignmentEngine.full_audit plugs into the same event bus and is intended to run on a periodic sweep (say, hourly) so drift surfaces before it bites.

Storage Protocol

Every engine takes a StorageBackend in its constructor. The Protocol is intentionally minimal — five async methods:

class StorageBackend(Protocol):
    async def get(self, key: str) -> dict | None: ...
    async def set(self, key: str, value: dict) -> None: ...
    async def list(self, prefix: str, *, limit: int | None = None,
                   offset: int = 0) -> list[dict]: ...
    async def delete(self, key: str) -> None: ...
    async def count(self, prefix: str) -> int: ...

Three backends ship in-tree:

• InMemoryStorage — tests, ephemeral experiments.
• JsonFileStorage — single-file, atomic writes, file locking.
• SqliteStorage — async aiosqlite with WAL mode for serious prototyping (behind the optional [sqlite] extra).

Bring-your-own backends (Postgres, Redis, key-value stores) hold the same Protocol. 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.