Source: https://docs.amadalis.ai/optimization/affinity-engine/

# The affinity engine, explained

Checked against the product’s code on 7 November 2026.

Use **Optimization** > **Personalization** > **Engine** in the site admin to inspect and change how recorded actions contribute to visitor interest scores.

The [affinity](https://docs.amadalis.ai/reference/glossary/#affinity) engine keeps interest scores for a visitor. Relevant actions add weight to those scores. Time reduces them. [Audiences](https://docs.amadalis.ai/reference/glossary/#audience) and recommendations can use the resulting strength.

The scores come from configured arithmetic. With the same settings, activity and time, the calculation gives the same result.

## Setup comes first

1.  Open **Optimization**.
2.  Open **Personalization**.
3.  Open **Engine**.
4.  Read **Affinity on** or **Affinity off**. The information tip beside it gives the reason.

[![Personalization settings: Saved · revision 1, Affinity on, with the tip "Affinity is on for this site: the engine learns on 2 axes, and 1 thing is personalized for a behavioral audience."](https://docs.amadalis.ai/images/steps/S048-affinity-engine-on-and-saved.png)](https://docs.amadalis.ai/images/steps/S048-affinity-engine-on-and-saved.png "Open full-size image")

The Engine says whether affinity is on, and why.

The saved settings have Affinity on, and the fields below set how many interest points each recorded visitor action adds.

Showing targeted content needs saved settings, an active piece of content assigned to an affinity audience and the personalization service connection. Your content interests and relevant [events](https://docs.amadalis.ai/reference/glossary/#event) also need to be configured. Ask Amadalis to check that setup with you before relying on the scores.

[![Events & Capture with Content click selected: on, 15 events from 10 visitors in 28 days, all from the Recommendations section.](https://docs.amadalis.ai/images/steps/S048-affinity-engine-event-content-click.png)](https://docs.amadalis.ai/images/steps/S048-affinity-engine-event-content-click.png "Open full-size image")

Check that the event the engine counts is actually arriving.

In the **Add an interest** panel:

1.  Enter the **Interest name**.
2.  In **Read from**, enter the tag or field on your content that carries it.
3.  Use the add button below the fields.

The interest is only staged until you choose **Save** and approve the change. Follow [Tune and review](https://docs.amadalis.ai/optimization/affinity-engine/#tune-and-review) below to save it. Content categories and tags can also supply interests through the [content catalog](https://docs.amadalis.ai/reference/glossary/#content-catalog).

## Build the content catalog

A catalog snapshot is the content list saved at one point in time.

The content catalog is separate from the section and theme catalogs. Prepare your published content and its [categories and tags](https://docs.amadalis.ai/content/pages-posts-and-media/#group-content-with-categories-and-tags) first.

[![Content catalog: active snapshot of 25 items, built and activated Oct 31, 1 axis, 2 audiences, and the Items tab.](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-active-snapshot.png)](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-active-snapshot.png "Open full-size image")

The active catalog snapshot.

The active catalog snapshot contains 25 items, with its build and activation times shown beside it.

1.  Open **Optimization**.
    
2.  Open **Catalog**.
    
3.  Choose **Build the catalog** if none exists, or **Rebuild the catalog** for an existing one.
    
4.  Read **Build this site’s content catalog?** or **Rebuild the content catalog?** and its scope.
    
    [![Rebuild the content catalog? replacing 25 items, becoming 26, adding Docs Walk First Page, reversible, with Keep the current catalog.](https://docs.amadalis.ai/images/steps/S101-affinity-engine-rebuild-card.png)](https://docs.amadalis.ai/images/steps/S101-affinity-engine-rebuild-card.png "Open full-size image")
    
    Rebuilding shows what it would add and remove first.
    

The rebuild replaces the active catalog snapshot, independently of publishing a page draft.

5.  Confirm **Build the catalog** or **Rebuild and publish the catalog**, as offered.
6.  Inspect **Items**.
7.  Inspect **Values**.
8.  Inspect **Audiences**.
9.  Inspect **Suggested tags**.
10.  Compare the content and values with what you expected to include.

[![Values tab: accessories and layers, 3 items each, each with its active audience.](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-values.png)](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-values.png "Open full-size image")

Each tag value and the audience it earned.

[![Audiences tab: Accessories Affinity and Layers Affinity, active, with members.](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-audiences.png)](https://docs.amadalis.ai/images/steps/S101-affinity-engine-catalog-audiences.png "Open full-size image")

The audiences generated from the values.

11.  Under **Suggested tags**, choose **Propose tags**.
12.  Read the separate approval.
13.  Confirm **Propose tags** if you want those suggestions prepared.
14.  Review the suggestions it returns.
15.  Choose **Approve** or **Decline** on the suggestion’s row.
16.  Read the prepared change.
17.  Confirm **Approve the tag** or **Decline the tag**, or choose **Leave it proposed**.

A suggestion is not an accepted tag.

[![Suggested tags: No tag suggestions waiting, with Propose tags.](https://docs.amadalis.ai/images/steps/S101-affinity-engine-suggested-tags.png)](https://docs.amadalis.ai/images/steps/S101-affinity-engine-suggested-tags.png "Open full-size image")

Proposed tags wait here for a person.

No tag suggestions are waiting for approval, and Propose tags is the control for requesting suggestions.

Use a receipt’s **Undo** when offered to restore the previous catalog state. A rebuilt catalog alone does not establish that affinity delivery is configured. Check the service, settings, audience and active-content prerequisites above.

## What adds to a score

An event must carry a value for a configured interest and have a positive weight. The engine first reduces the old score for elapsed time, then adds that action’s weight.

A page visit alone does not establish a particular interest. Check which events your site actually sends in **Insights**, then **Events & Capture**. An event appearing in a settings list is not proof that your site sends it.

Use **What each visitor action counts for** to review the weights. A larger weight adds more evidence for the values carried by that action.

A blank weight counts as zero. The greyed number in an empty field is the platform’s suggested value, and it does not apply until you enter it and save.

[![Weight fields: Clicked a piece of content set to 2 points; empty fields show greyed suggested values.](https://docs.amadalis.ai/images/steps/S049-affinity-engine-weight-controls.png)](https://docs.amadalis.ai/images/steps/S049-affinity-engine-weight-controls.png "Open full-size image")

Each action's points. A blank field counts nothing.

[![Visitor Data, Interests and audiences: the demo visitor’s Layers score is 0.53 and direct-channel score is 0.63.](https://docs.amadalis.ai/images/steps/S049-affinity-engine-score-after-one-click.png)](https://docs.amadalis.ai/images/steps/S049-affinity-engine-score-after-one-click.png "Open full-size image")

Read the current scores on Interests and audiences.

## How interest fades

The raw score is the interest total after action weights and their fading over time, before it is converted to a strength between zero and one.

**How long interest lasts** controls the decay rate. In the platform’s initial settings, that value is seven days. The screen reads this as interest halving about every 4.9 days of inactivity. The score continues to fade over time.

[![How long interest lasts 7 days ("Interest halves about every 4.9 days of inactivity") and the How interest fades chart.](https://docs.amadalis.ai/images/steps/S050-affinity-engine-how-interest-fades.png)](https://docs.amadalis.ai/images/steps/S050-affinity-engine-how-interest-fades.png "Open full-size image")

The memory setting and what it does over time.

The downward curve shows interest scores fading during inactivity rather than ending at a fixed deadline.

The raw score is converted into a strength between zero and one. **How much activity counts as strong interest** controls how much evidence is needed for a high strength.

For example, with a raw score of 3 and that setting at 1.8:

```
strength = 3 / (3 + 1.8) = 0.625
```

At a join threshold of 0.6, that passes the interest check. This is a calculation example. Actual delivery also needs a usable audience, active targeted content and visitor consent.

## When an audience applies

A threshold is a boundary value.

**A visitor joins an audience at** sets the join threshold. **and leaves when it falls below** sets the lower threshold used for recorded membership exits.

[![A visitor joins an audience at 0.6 and leaves below 0.45, with The gap between them.](https://docs.amadalis.ai/images/steps/S051-affinity-engine-join-and-leave-thresholds.png)](https://docs.amadalis.ai/images/steps/S051-affinity-engine-join-and-leave-thresholds.png "Open full-size image")

Joining and leaving use two marks, so membership does not flicker.

There are two views to understand. Page delivery checks the current faded score against that audience’s join threshold. Recorded membership transitions use the join and leave thresholds when activity is processed. A delivered page and the recorded member list can therefore change at different times.

Use the audience’s definition and **Members & why** alongside a check of the delivered content. A tune for one audience can override its join threshold, memory and evidence setting. An interest can also set its own values in the interests table, and where both apply, the interest’s own setting wins. Current limitation: the audience’s leave setting and individual action weights do not provide separate page delivery controls.

## How recommendations use scores

A **Recommendations** section ranks catalog items using the visitor’s strengths for the items’ tags. The Composer offers **Always show first**, but currently refuses saving changes to pins. Changes to **Never show** and **What each card shows** are refused too; see [Recommendations](https://docs.amadalis.ai/optimization/recommendations/) for the saving limits.

Set **When there is nothing to personalise on** for cases without a usable score. The choices are **The most recently updated items**, **Your pins, then catalog order** and **Hide the section entirely**.

With **Hide the section entirely**, a visitor without a usable score sees no section at all, not even your pinned items.

A usable catalog, settings and service connection are part of this setup. Personalization consent and Global Privacy Control also govern whether visitor interest can be used or updated.

## Tune and review

A revision is a saved version of the settings.

1.  Change the intended setting in **Engine**.
2.  Choose **Save**.
3.  Read **Review this change**.
4.  Choose **Approve & save** if it matches your intent.
5.  Read the resulting revision and its receipt, which offers **Undo this change**.

[![Review this change: Watched a video to the end now earns 2 points (it counted for nothing), the note Docs walk: a test revision, rolled back next, where it takes effect, and Approve & save.](https://docs.amadalis.ai/images/steps/S053-affinity-engine-new-revision-review-card.png)](https://docs.amadalis.ai/images/steps/S053-affinity-engine-new-revision-review-card.png "Open full-size image")

Every saved change is reviewed first.

Open **Change history**, followed by its revision count, to inspect earlier revisions. **Roll back to this** restored a different written video weight as a new revision, and **Undo this change** returned the previous settings. Restoring a revision with a blank video weight was refused when the current weight was zero. Do not treat a blank field and a written zero as an interchangeable put-back. The revision 3 picture below records an earlier manual save, not an automatic restore.

[![Personalization Change history shows revision 1 In force with its reason; name hidden.](https://docs.amadalis.ai/images/steps/S053-affinity-engine-change-history.png)](https://docs.amadalis.ai/images/steps/S053-affinity-engine-change-history.png "Open full-size image")

Change history lists recent saved revisions.

[![Personalization Change history shows revision 2 In force and revision 1 Earlier, with Saved revision 2 and Undo this change; name hidden.](https://docs.amadalis.ai/images/steps/S053-affinity-engine-history-two-revisions.png)](https://docs.amadalis.ai/images/steps/S053-affinity-engine-history-two-revisions.png "Open full-size image")

Each save is a revision with its reason.

[![The history with revision 3 Docs walk: put revision 1's settings back, In force, above revisions 2 and 1.](https://docs.amadalis.ai/images/steps/S053-affinity-engine-history-restored-revision-3.png)](https://docs.amadalis.ai/images/steps/S053-affinity-engine-history-restored-revision-3.png "Open full-size image")

Putting settings back writes a new revision.

Revision 3 was manually saved after the attempt to restore earlier settings was refused.

Continue with [Audiences and targeted content](https://docs.amadalis.ai/optimization/audiences-and-targeted-content/) to put an interest audience to use.