Amadeus

Amadeus is a persona runtime core — a small, platform-neutral library for giving a conversational character a continuous self: durable memory, an evolving mood, a felt sense of who it is talking to, and guardrails that keep it recognizably the same person across every session.

It depends only on httpx and the standard library. It knows nothing about any particular chat platform or LLM provider — those live behind a handful of ports, so the same core can sit behind a Discord bot, a QQ bot, a web app, or a test harness without changing a line of domain logic.

Persona: Makise Kurisu (牧濑红莉栖). The library is persona-agnostic in structure — the character is configuration, not hard-coded — but it ships tuned for her.

Why it exists

Most chatbots are amnesiac: each conversation starts from zero, and personality is a system prompt re-pasted every turn. Amadeus treats persona and memory as stateful, evolving backend concerns instead:

• One self across all conversations. Mood, recent experiences, and relationships persist and evolve between sessions rather than resetting each time.
• Deterministic where it matters. Emotional tone, familiarity, and trust move by explicit math (EMA, time-decay, saturating growth, threshold transitions) — never by hidden randomness — so every state is inspectable, editable, and reproducible.
• The character stays the character. A semantic consistency guard vets self-evolution before it is written, so the persona drifts toward growth, not away from itself.

Architecture at a glance

Amadeus is built as a hexagon (ports-and-adapters):

Inbound ── RuntimeCore (facade, the home of orchestration)
             ├─ domain/*   capabilities (identity, injection, archiving,
             │             synthesis, relationship, forget, diary, …)
             ├─ ports      outbound protocols (memory / chat / storage / logger)
             └─ slots      optional interfaces (constitution / consistency / reflection)
Outbound ── adapters implement the ports for a concrete platform

• amadeus.RuntimeCore — the orchestration facade. build_injection assembles what the persona should be primed with this turn; archive_turn records the exchange and drives memory flushing. Management entry points (recall / search / status / forget / reflect / diary / …) return structured results, never platform messages.
• amadeus.ports — MemoryPort, ChatPort, StoragePort, Logger. Adapters translate a concrete platform's objects into these shapes; the core only ever sees the protocols.
• amadeus.slots — ConstitutionProvider / ConsistencyJudge / ReflectionFence. Each is optional; when left unset the corresponding step is simply skipped.

Capabilities

Layer	What it does
Continuous self	A cross-session mood + weighted recent experiences + optimistic-locked version. Evolves by feeding the whole conversation arc to the LLM, gated by privacy rails and a second-person fence.
Affect	A numeric tone layer over the self: warmth / playfulness / defiance / vulnerability in [0,1], moved by EMA and lazy time-metabolism, with an optional threshold transition (a brief "flare") that recovers on a double half-life. Rendered to the model as numbers + natural-language anchors.
Familiarity & trust	Per-user familiarity (a saturating scalar) and a subjective-logic trust triple (belief, disbelief, uncertainty) with time decay and multi-hop propagation — two orthogonal axes of "how well do I know you".
Social cognition	Attributed facts (who said what), disclosure gating (what may be shared with whom), alias resolution, user↔user relationship edges, and an LLM-evolved relational narrative.
Consistency guard	An LLM-as-judge that vets self-evolution before it is persisted — protecting the persona, not filtering for safety. Fails open: a judge outage never blocks growth.

The mathematical model behind the evolving layers — affect as order parameters in a dissipative dynamical system, familiarity as a monotone history functional, trust on a classical probability simplex — is written up in docs/05.

Install & test

python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[test]"
.venv/Scripts/python.exe -m pytest -q

Requires Python ≥ 3.12. The suite runs with no platform SDK installed — the core is self-contained.

Documentation

Doc	Topic
docs/01	Architecture — hexagon, ports, facade, slots
docs/02	Component ownership & dependency boundaries
docs/03	Cross-session continuous self
docs/04	Affect layer
docs/05	State-space mathematical formalization
docs/06	Social cognition layer
docs/07	Persona consistency guard

License

See LICENSE.