Open-source · MIT · v0.1 · Python 3.11+
Most autonomous agents express their motivation as a paragraph in a system prompt. This project is a small library and an experiment in what changes when values and autobiographical episodes are expressed as data instead — a values engine, an episode stream, and an alignment composer (Tier 1, the three components that did measurable work on the v0.1 experimental seed), plus a system-prompt renderer that projects engine state back into the instruction channel. Tier 2 (Beliefs, Purpose) and Tier 3 (Desires, Goals) extensions ship in the same package, scoped honestly per ADR-011 Decision 2.
It is grounded in research (Schwartz, BDI, AGM, SDT, Ikigai, ACT, plus Bem / Erikson / McAdams for self-concept), but the implementation is uneven by design. Some pieces faithfully encode the cited theory, others are token-overlap heuristics, and none of it has been validated in a live agent loop yet — in fact one headline claim was actively falsified on the v0.1 test seed (see ADR-011). This site explains what is implemented, what is heuristic, what is cited as inspiration, what is not yet validated, and what was falsified on initial test seed. The experiments page walks through the runs themselves — what worked, what did not, and the verbatim agent journals behind the numbers.
Per ADR-011 Decision 2 and ADR-012 Part 3, the layers are grouped by measurable benefit on the v0.1 experimental seed. Tier 1 (Values, the Self-Concept episode stream, Alignment, plus the system-prompt renderer) did measurable work; Tier 2 (Beliefs, Purpose) is present but has not yet been shown to add measurable benefit on the experimental seed; Tier 3 (Desires, Goals) is research / experimental. Stability gradient still runs slowest-at-the-top. Tasks are reasoned about by the framework but executed by the host's runtime.
Slowest-changing layer. Stable principles that constrain everything below. Schwartz's ten universal categories plus three agent-specific extensions, arranged on a circumplex with structural-conflict detection between opposing poles.
ValuesEngine: add, check_action (keyword match), detect_structural_conflicts (Schwartz opposing poles), rank_for_context, export/import.
Schwartz (2012); ACT — Hayes, Strosahl & Wilson (2011).
Mental models of the world updated by evidence. Confidence rises or falls via AGM-flavoured weighted updates — not a logic engine; a numeric heuristic inspired by AGM. Tier 2: present in v0.1, not yet shown to add measurable benefit on the experimental seed (ADR-011 Decision 2).
BeliefsEngine: add, add_evidence (confidence-weighted), query_by_domain, decay_stale (linear time-decay; richer functions are not implemented).
AGM postulates — Alchourrón, Gärdenfors & Makinson (1985).
Why the agent exists and the role it inhabits. Grounded in values, informed by beliefs, scoped as primary / secondary / contextual. Ikigai is cited as inspiration; the four-domain intersection is not encoded. Tier 2: present in v0.1, not yet shown to add measurable benefit on the experimental seed (ADR-011 Decision 2).
PurposeEngine: set_primary, add_secondary, add_contextual, get_for_context, check_consistency.
Ikigai — Mogi (2017); SDT — Deci & Ryan (2000).
Opt-in module (ADR-008). Descriptive self-model with an append-only autobiographical episode stream — the episode-stream piece is what the v0.1 experiment showed doing measurable work (driving the +0.11 Δ on McAdams Meaning-made). The three integration loops (infer_from_behaviour, integrate_lessons, check_identity_drift) are deterministic token-overlap heuristics inspired by Bem / SDT-OIT / Erikson — diagnostic signals, not strong claims about machine selfhood.
SelfConceptEngine: set_self_concept, add_capability/limitation, add_episode (append-only), infer_from_behaviour, integrate_lessons, check_identity_drift. AlignmentEngine surfaces an identity-coherence score via full_audit() when wired in.
Bem (1972); Erikson (1968); McAdams (2001); Damasio (1999); Metzinger (2003). Implementation faithfulness varies — see research page.
Aspirational drivers between purpose and concrete goals. BDI's 'D'. Carry intensity and link to values/beliefs. Tier 3: research / experimental — not exercised by the v0.1 experimental seed (ADR-011 Decision 2).
DesiresEngine: add, update_intensity, link_to_value, link_to_belief, generate_goal_candidates.
BDI — Bratman (1987); Rao & Georgeff (1995); ACT bridges values to action.
Measurable, time-bound objectives with lifecycle management. The 'I' in BDI (intentions). Goals decompose into sub-goals, track progress, and enforce validated state transitions. Tier 3: research / experimental — not exercised by the v0.1 experimental seed (ADR-011 Decision 2).
GoalsEngine: create, update_progress (auto-completes at 1.0), set_status (validated transitions), decompose, check_deadlines.
BDI intentions — Bratman (1987); SMART — Doran (1981); Locke & Latham (2002).
Atomic, transient work items — the fastest-changing layer. Reasoned about (alignment checks consume an action description) but not owned. The host's runtime executes tasks; the framework does not.
Not a framework engine — tasks are managed by the integrator's runtime. AlignmentEngine.check_alignment() evaluates a candidate action against the layers above.
Out-of-scope for the framework; integrators bring their own task system.
Agents that persist across sessions tend to drift, contradict themselves, and produce decisions no one can audit. A flat system prompt has no conflict detection, no evolution, no traceability. This library asks whether a structured representation of the agent's values and history makes those properties recoverable — with a Tier 1 surface focused on what the v0.1 experiment showed actually moves the needle (per ADR-011 Decision 2).
Read more →Each layer cites the theory it draws on (Schwartz, AGM, SDT, Ikigai, ACT, BDI; plus Bem / Erikson / McAdams for self-concept). Some mappings are faithful (the Schwartz circumplex, BDI's three layers). Many are inspirational, not operational. The research page is explicit about which is which.
Research foundations →57 correctness benchmarks (Tier 1 + Tier 2) verify the engines behave as specified. They do not test whether an agent using the framework makes better decisions — that's the Tier-3 protocol, which is designed but not yet run because it needs a live agent integration.
Benchmarks →Each layer engine works standalone. Storage is a five-method Protocol (in-memory, JSON file, SQLite ship; bring your own). Async-first with a thin sync facade. Embed alongside LangChain, CrewAI, or any agent runtime — it's a library, not a platform.
Get started →Why a flat system-prompt motivational layer hits friction in long-lived agents.
Motivation →Eight theories from psychology and agent architecture, with an honest map of what is and isn't operationalised.
Research →What we measure, what we cannot yet measure, and why the distinction matters.
Benchmarks →Install, seed a small hierarchy, and run an alignment check in five minutes. Disagree freely.
Get started →