---
url: https://lettuceai.app/docs/companion-mode
title: "Companion Mode — LettuceAI"
description: "Companion Mode gives a character a living soul that grows from your shared memories, a real-time emotional and relationship state, and dedicated pages for setting it up and watching the bond evolve."
---

Menu 

# Companion Mode

Companion Mode is the relationship-oriented chat mode in LettuceAI. It gives a character a written "soul" that quietly grows over time, a live emotional and relationship state that shifts with every message, and shared memory that can follow you across every chat with that companion. It is built for bonds that last, not one-off scenes.

Opt-in and additive

Companion Mode is fully opt-in. It only activates for characters whose interaction mode is set to Companion. Roleplay characters and regular chats are completely unaffected: nothing about Companion Mode changes how non-companion chats prompt, remember, or store data. If you never turn it on, it is simply not there.

Runs on your device

The pieces that make a companion feel alive (reading emotion, recognizing who and what gets mentioned, recalling past moments) run locally on your device using a few small models. The app only reaches out to your chosen provider for the actual reply, exactly like roleplay mode does.

## Companion vs Roleplay

Every character is created in one of two interaction modes. You pick the mode during character creation (and can change it later from the character editor) using the **Interaction Mode** selector.

| Mode | What drives it | Best for |
| --- | --- | --- |
| Roleplay | Scenes, situational framing, the standard prompt path. | Scene-first storytelling, one-shot scenarios, narrative play. |
| Companion | A living soul plus real-time emotional and relationship state. | Persistent relationships, slow-build dynamics, ongoing bonds. |

Companion Mode does not remove scenes. They are still supported as opening context (and you can skip them entirely for a companion). The emphasis simply shifts from framing a scene to keeping a relationship alive between sessions. There is no global switch: roleplay characters keep their original behavior even with all the companion pieces installed.

## The companion soul

The soul is the heart of a companion. It is who they are underneath the basic character card: their nature, their history, the things they love, the things that frighten them, and how they handle their feelings. You write it in the **Companion Soul** step during creation, or in the **Soul** tab of the character editor afterward. You can author every word yourself, or let the Soul Generator draft it for you and then edit freely.

### The twelve identity blocks

The soul is built from twelve short written blocks. Each one is plain text, and each comes with worked examples you can insert and adapt. You only have to fill in what matters to you: empty blocks are fine.

-   **Essence**: who they are underneath the card definition.
-   **Traits**: their defining personality traits, a few words each.
-   **Backstory**: how they came to be. Origin, formative events, what they do.
-   **Appearance**: how they look and dress, including a signature outfit or style.
-   **Goals**: what they are working toward. Ambitions, quests, unfinished business.
-   **Likes and Favorites**: favorites and small joys. Food, color, music, little gestures.
-   **Inner Voice**: how they sound in close conversation.
-   **Relational Style**: how they attach, trust, retreat, and reconnect.
-   **Vulnerabilities**: soft spots, insecurities, things they rarely say out loud.
-   **Fears**: what they can be pressured on. Literal fears and the things that unsettle them.
-   **Habits**: recurring tells, rituals, and conversational patterns.
-   **Boundaries**: lines they will not cross, the pace they keep, and their comfort limits.

Why fears get their own block

Fears are kept separate on purpose. They describe what genuinely unsettles a companion, so the character can react believably when a scene touches one of those nerves, instead of staying unflappable about everything. The Soul Generator is aware of this block and will draft fears alongside the rest.

### Fine-tuning the feelings

Below the written blocks, a **Fine-tune feelings** section lets you shape the companion's emotional makeup with sliders. Most people can leave these at their sensible defaults, but they are there if you want precise control.

-   **Baseline Affect** (ten sliders): the companion's default emotional tone, for example warmth running from cold to affectionate. These set the mood the companion rests at and gently returns to between turns.
-   **Regulation Style** (nine sliders): how they handle feelings before showing them, including suppression, volatility, and pride. This is what creates the gap between what a companion feels and what they actually let you see.
-   **Relationship Defaults** (four sliders): where the relationship starts on closeness, trust, affection, and tension when you begin chatting.

The soul editor also carries two switches that apply to this companion everywhere: **Time Awareness** and **Shared Memory Across Sessions**. Both default to off and are explained in their own sections below.

## The Soul Generator

You never have to write a soul from a blank page. The Soul Generator drafts one for you from the character's name, definition, and any scenes you have set. Find it in the **Generate from character** card inside the soul editor and tap **Generate soul**. It stays disabled until the character has at least a name and a definition (it will tell you which one is missing).

-   **Watch it think**: while it works, a status pill shows live steps such as authoring identity, setting the baseline mood, tuning emotional regulation, and finishing up. You can expand it to watch the text stream in as it is written.
-   **Stop anytime**: a **Stop** button next to the status cancels the run immediately. A canceled run leaves your existing soul untouched.
-   **Review before applying**: when it finishes, a **Review generated soul** panel opens showing all twelve blocks as editable fields (changed fields are marked) along with the before-and-after slider changes. From there you can **Apply**, **Regenerate**, **Discard**, or open **Direction** to steer the next draft.
-   **Optional steering**: the **Direction** box lets you nudge how the soul is drafted (a tone, a theme, a detail you want included). Leave it empty to let the model decide from the character alone.

You control which model writes souls and how, from **Settings > Companion Soul Writer**: pick the generation model (or use the app default), choose a structured fallback format (JSON or XML) for local models that cannot use tool calling, and optionally supply your own Soul Writer prompt template.

## How the soul grows over time

This is what makes a companion feel like it is truly getting to know you. The soul you write is the starting point, not a cage. As you talk and the companion forms memories, parts of its personality can quietly evolve. We call this **soul growth**.

![How companion memories turn into soul growth without overwriting the authored soul](https://lhdgeo5fms.ufs.sh/f/m0TBUtMLsaiE8T7sJ7qFdHBKrgh7YW2EbSeyfUJVmjDRkonu)

As you chat, new memories feed a growth cycle. Only the parts allowed to change are updated, conflicts supersede older growth, and everything is added as an overlay so the soul you wrote is never overwritten.

### What growth does

After the companion replies, the app notes any new memories from the exchange. In the background, a growth pass looks at those fresh memories alongside the companion's changeable traits and decides whether anything about them has genuinely shifted. Maybe they have picked up a new favorite, warmed up to a topic they used to avoid, or revealed a goal. When it finds a real change, it records a small **growth entry** layered on top of your authored soul.

Your writing is never overwritten

Growth never edits the words you wrote. It stacks gentle adjustments on top of the authored soul. A trait's current value is your original plus any active growth, so you can always clear growth and get your original companion back exactly as written.

When a new realization conflicts with an older one, the new entry **supersedes** the old one rather than piling up beside it, so the companion does not hold two contradictory beliefs at once. Retired entries are kept as a short history. Much less often, once enough small changes have built up, a **consolidation** pass folds them into the companion's deeper core so the personality stays coherent instead of drifting.

### Seeing and managing growth

You stay in control of everything growth does. The **Relationship** page for a companion chat has a **Soul growth** section that lists how the changeable traits have evolved, with badges showing whether each entry was added or adjusted and how many memories it came from. From there you can:

-   **Remove a single entry**, with a confirmation first. This drops just that evolving trait and never touches your authored soul.
-   **Clear all growth**, also confirmed first. This wipes every accumulated change (including retired history) and returns the companion to exactly the soul you wrote.

If a companion has not formed any growth yet, the section simply says so. Growth is companion-only and entirely optional in spirit: clearing it is always safe.

## Which parts change, and how fast

Not everything about a companion should shift at the same speed. A person's favorite snack can change in a week, but who they are at their core should not. LettuceAI sorts the soul into a few mutability levels so growth feels natural rather than chaotic.

| Level | How it changes | Covers |
| --- | --- | --- |
| Fixed | Never changes on its own. | Backstory. |
| Core (very slow) | Only the rare consolidation pass can ever touch it. | Essence and traits. |
| Slowly evolving | Shifts gradually through ordinary growth. | Appearance, goals, inner voice, relational style, vulnerabilities, fears, habits, boundaries. |
| Quickly evolving | The most responsive to new memories. | Likes and favorites. |

The core identity is special: it is authored once and stored as-is, and any evolution is layered over it rather than rewriting it. In the companion pages, the original core values appear as read-only cards, while anything growth has changed shows up under the Soul growth section, so you can always tell what you wrote apart from what evolved. On the relationship meters, values that have risen above their starting point fill in a warm color, while values that have dropped below it are shown in a danger color so a cooling bond is easy to spot at a glance.

## Live session state

Separate from the soul, every companion chat keeps a live state that updates from your messages. The soul is who they are; the live state is how they feel and where the relationship stands right now. Unlike memory, this state stays per chat: different conversations with the same companion can be in different emotional places.

### Emotional state

-   **Felt**: what the companion is actually experiencing inside.
-   **Expressed**: the version that surfaces in replies after their regulation style is applied.
-   **Blocked**: what is felt but held back. The gap between felt and expressed.
-   **Momentum**: which way the feelings have been trending over recent turns.
-   **Active drivers**: short labels for what is behind the current mood, drawn from the last message.
-   **Confidence**: how sure the emotion reading was on the last turn. Lower confidence produces a softer, more cautious update.

Felt vs expressed

A central idea in companion mode is that what a companion _feels_ and what they _show_ are tracked separately. Regulation traits like suppression and emotional transparency decide how much of the felt state actually reaches you, which is why a guarded companion can be hurting without ever saying so.

### Relationship state

The bond itself is tracked on a handful of meters, each with plain low and high anchors so the numbers mean something.

| Meter | Low | High |
| --- | --- | --- |
| Closeness | Withdrawn | Intimate |
| Trust | Distrustful | Trusting |
| Affection | Hostile | Affectionate |
| Tension | Easy | Charged |
| Stability | Volatile | Stable |

The page also shows the number of interactions and when you last spoke. Meters start low and build over time, and each meter's trend is compared against the character's defaults so you can see whether things are warming up or cooling down.

State settles in as you talk

A brand-new companion chat does not need to write out its full state right away. The runtime can fall back to sensible values from the soul and the relationship defaults, and your first real message is usually what locks in the live state for that chat.

## What happens on a companion turn

Companion mode adds a few quiet steps around a normal reply. The order matters, because it lets the same reply reflect how the companion just reacted to you.

1.  You send a message.
2.  The previous emotional state relaxes back toward the companion's baseline based on how long it has been since you last spoke, so a long absence cools a heated moment.
3.  The on-device emotion reader looks at your message and produces a few confident labels (such as love, gratitude, sadness, or anger), each of which nudges the emotional and relationship meters.
4.  Those nudges are scaled by the companion's volatility and applied, then their regulation style derives what they actually express from what they feel.
5.  The relationship meters update: closeness and affection drift gently upward on any turn, while trust, tension, and stability move only in response to specific signals.
6.  A compact summary of the companion's current state is woven into the prompt, and the reply is generated with that live context in view.
7.  After the reply is saved, memory processing and the soul growth pass run in the background.

It fails gracefully

If the on-device emotion reader is unavailable on a given turn, the companion keeps chatting. It simply applies a near-neutral update and pauses emotional changes until the model is back, rather than blocking the conversation.

## Companion memory

Companion memory uses the same dynamic memory engine as the rest of the app, presented through a relationship-oriented lens. From a companion chat's **Memory** page you can browse, search, filter, pin, warm up or cool down, re-date, edit, or delete memories, and even hand-edit the running context summary.

### Shared memory across sessions

The soul editor's **Shared Memory Across Sessions** switch (off by default) decides how memory is scoped for a companion. When it is on, every chat with that companion draws from a single shared memory pool, so something they learn in one conversation carries into the others, and an edit in one chat affects them all. Even with sharing on, the emotional state and the relationship meters stay separate per chat.

### When memories go stale

People change their minds, and so should a companion's memory of you. When a new memory contradicts an older one (you moved cities, you changed jobs), the new memory **supersedes** the old one: the outdated fact stops influencing replies, but a trail is kept so nothing is silently lost. On the Memory page you can filter between active and superseded entries, and superseded items are dimmed and clearly tagged.

### Scheduled notes

Scheduled notes let you hand the companion dated background context that it only picks up when the day arrives. Think birthdays, anniversaries, or a seasonal beat you want acknowledged. For each note you set the exact text the companion will read, an optional label, whether it repeats (once, daily, weekly, monthly, or yearly), and the date and time window it is active. You can disable a note to keep it saved without it entering prompts, and preview which notes would be active on any chosen date.

### Custom memory prompts

Companion chats share the app's dynamic memory backend, so the same customization applies. Under **Settings > Dynamic Memory** you can swap in your own **Summary Prompt** (how recent turns get summarized into durable context) and **Memory Manager Prompt** (how memories get added, updated, and removed), or leave both on the built-in defaults.

## Time awareness

Time awareness lets a companion know what day and time it is and remember when things happened. It is off by default. The soul editor's **Time Awareness** switch sets the default for new chats with that companion, and any individual chat can override it from its own settings.

When it is on:

-   **Live time in the conversation**: the companion is told the current local date and time, so it can react to the hour, the weekday, or the season naturally.
-   **Time-stamped memories**: new memories record when they happened, which is what makes questions like "what did we do last weekend" pull back the right moments.
-   **Time-aware recall**: when you mention a period like "yesterday" or "a few weeks ago", memory retrieval can focus on that window instead of guessing.

A per-chat **Time Override** gives you finer control over the clock the companion sees. **Live** uses the real clock, **Frozen** holds a fixed moment in place, and **Ticking** keeps advancing from a time you set. This shifts both the time the companion perceives and how the recency of memories is judged, which is handy for stories set in a different moment.

## Setting up a companion

Setting up a companion is a guided flow, and the app handles the technical parts for you.

1.  **Choose the mode**: in the character's Description step, pick **Companion** in the Interaction Mode selector.
2.  **Install the on-device pieces**: the first time you do this, a setup guide appears explaining that a companion runs on your device and needs a few small models, a one-time download. Tap to start it.
3.  **Keep your place during the download**: starting the download takes you to a queue page that installs the models one after another and shows progress. When it finishes, it counts down and returns you to exactly where you were, with everything you had already typed still intact.
4.  **Learn how it works**: once the models are ready, the guide returns with a short explainer covering emotional state, the relationship, and memory, plus an optional prompt to shape the soul.
5.  **Shape the soul**: in the Companion Soul step, write the twelve blocks yourself or use the Soul Generator, fine-tune the feelings if you want, and set the optional Direction for generation.

Sensible defaults, then generate

There are no personality presets to wade through. A new companion starts from sensible defaults, and the Soul Generator gives you a full first draft to react to. From there you only change what you care about.

## The on-device models

Companion mode relies on a small set of local models. When you switch a character into companion mode, the app checks which ones are present and offers to download anything missing before you continue. Chatting is forgiving if one is missing (it degrades rather than blocks), but the experience is fullest with all four installed.

-   **Embedding model** (about 90 MB): powers memory recall and semantic search.
-   **Emotion classifier** (about 120 MB): reads each message and produces the signals that move the emotional state.
-   **Entity extractor** (about 140 MB): recognizes people, places, and things so memories can be linked together.
-   **Memory router** (about 70 MB): decides how a new memory should be categorized.

Local-first

All of these analysis models run on your device. Providers are used only for the actual chat reply, the same as in roleplay mode.

You can manage these downloads from **Settings > Companions**, which shows each model's status with install and uninstall controls, an overall readiness banner, and a pointer into Dynamic Memory settings (companion chats share that backend). The companion-specific generation settings live under **Settings > Companion Soul Writer**.

## Companion pages in a chat

So the system never feels like a black box, a companion chat exposes dedicated pages from its header.

-   **Relationship page**: the live meters (closeness, trust, affection, tension, stability), interaction count, top felt and expressed emotions, recent momentum and drivers, and the Soul growth section where you review and manage how the personality has evolved.
-   **Memory page**: the full companion memory browser with category filters, search, the active-or-superseded filter, pinning, warming and cooling, re-dating, editing, and deletion.
-   **Soul page**: edit the soul and run the Soul Generator without leaving the conversation.

## When to use companion mode

-   **Use Companion Mode** for ongoing relationships where continuity, emotional tone, and a bond that grows matter more than scene framing.
-   **Use Roleplay Mode** for scene-driven stories, one-shot scenarios, or characters where a live emotional state would feel out of place.

It is still your chat

Companion mode never takes the wheel. You can always edit the soul, clear growth, adjust memory, regenerate replies, or switch providers. The relationship is something the app tends for you, not something it locks you out of.

[

PreviousSystem Prompts

](/docs/system-prompts)[

NextMemory System

](/docs/memory)