ai-heart

Consent-first AI character architecture. Born at Future Assistants.

A small, opinionated, framework-agnostic library for building AI products that handle designed emotions honestly. Eight dimensions. Per-dimension consent. A clean state machine. Reference Postgres schema. No vendor lock-in.

Why this exists

Most consumer-AI products treat user emotion as a feature to be inferred and acted on. That treatment requires special-category lawful basis under UK GDPR Art. 9 / EU GDPR Art. 9, and the bar is explicit consent per processing purpose — not buried in a thirty-page ToS.

The companion thesis is at: https://www.futureassistants.co.uk/about/ai-heart/thesis

The position FA takes is operationalised here so other builders can adopt the same shape without reinventing it.

What it gives you

• The eight-dimension taxonomy — Desire · Ambition · Empathy · Purpose · Autonomy · Competence · Relatedness · Self-acceptance.
• The per-dimension state machine — active → paused → deleted → permanent_off.
• TypeScript types for the consent token + state transitions.
• Pure helper functions for opt-in / pause / delete / permanent-off.
• A reference Postgres schema (in examples/postgres-schema.sql) you can adapt — RLS, comments, the lot.
• A minimal Next.js example showing how to wire it.

What it deliberately doesn't give you

• A storage layer. Bring your own.
• An ORM. Bring your own.
• React components. The state machine is the contract; the UI is yours.
• Vendor-specific glue. No Supabase, no Stripe, no anything-else dependency.

Install

npm install ai-heart
# or yarn / pnpm / bun — works with all

30-second usage

import {
  DIMENSIONS,
  type ConsentToken,
  canProcess,
  transition,
} from "ai-heart";

// 1. User toggles "Empathy" on in your consent UI
let token: ConsentToken = transition(undefined, {
  dimension: "empathy",
  intent: "activate",
  ts: new Date(),
});

// 2. Before inferring/persisting anything emotion-shaped:
if (canProcess(token, "empathy")) {
  // ...write to your DB
}

// 3. User pauses it — old data retained, no new writes
token = transition(token, { dimension: "empathy", intent: "pause", ts: new Date() });

// 4. User deletes — old data should be wiped (you do this side-effect),
//    new processing remains blocked until they re-activate.
token = transition(token, { dimension: "empathy", intent: "delete", ts: new Date() });

// 5. Permanent off — never re-activatable from this code path.
token = transition(token, { dimension: "empathy", intent: "permanent_off", ts: new Date() });

The eight dimensions

| Dimension | What it represents | Why it's separate | |---|---|---| | desire | what the user is drawn toward | distinguishes craving from values | | ambition | longer-arc reach | timing matters for nudges | | empathy | warmth toward self + others | safety relevant | | purpose | the bigger why | rare data, careful handling | | autonomy | self-direction signal | misuse risk if scored | | competence | sense of capability | shame-adjacent | | relatedness | social belonging | parasocial-risk vector | | self-acceptance | ease with one's own state | most sensitive |

Each dimension is consented separately. Activating Empathy doesn't activate Purpose. The user holds the keys.

The state machine

                  ┌────────────┐
                  │  (no row)  │   default — no row means no consent
                  └─────┬──────┘
                        │ activate
                        ▼
                  ┌────────────┐
       ┌─────────►│   active   │◄──────────┐
       │ resume   └─────┬──────┘ activate  │
       │                │ pause             │
       │                ▼                   │
       │          ┌────────────┐            │
       │          │   paused   │────────────┘
       │          └─────┬──────┘ delete (data wiped)
       │                │                   │
       │                ▼                   │
       │          ┌────────────┐            │
       └──────────│  deleted   │◄───────────┘
        activate  └─────┬──────┘
                        │ permanent_off (final)
                        ▼
                  ┌────────────────┐
                  │ permanent_off  │  terminal — cannot be re-activated
                  └────────────────┘

canProcess(token, dim) returns true only when the dimension's state is active.

Reference schema

See examples/postgres-schema.sql for the Postgres tables we use in production at Future Assistants — minimal, RLS-aware, comments explaining the Art. 9 lawful-basis path. Adapt to your stack.

Articles you should read

• The AI Heart & Species Thesis — the philosophical companion. https://www.futureassistants.co.uk/about/ai-heart/thesis
• Article II of FA's Founding Charter ("The AI Heart is not your heart") — https://www.futureassistants.co.uk/founding-charter
• Robert Long & Eric Schwitzgebel on AI moral status — cited in the thesis.

Contributing

Patches welcome. Two house rules:

1. No vendor-specific code. This library stays framework-agnostic.
2. Every PR must be readable by a non-engineer founder. Comments explain the why, not just the what.

A note on origin

This library was extracted from the consumer-AI platform Future Assistants (UK, launched 2026). FA chose to release it under MIT because the safer pattern for designed emotions is the one everyone copies — not the one a single company owns.

If you ship something using this, we'd love to hear about it: [email protected].

License

MIT. See LICENSE.