Local AI with Ollama

What is "Local AI"?

The Companion (the floating avatar that talks to you, reacts to your screen, and can trigger effects) has two possible brains:

• Cloud AI - the default. Your chat lines go to a small proxy server we run, which forwards them to a hosted language model. Comes with daily limits (100/day for free, 1000/day for supporters), no install required.
• Local AI - you run a language model on your own computer using Ollama. Nothing leaves your machine. No request limits. No subscription required. You pay in disk space, RAM, and (optionally) GPU cycles instead.

Both brains implement the same internal interface (IAiService) so every feature that talks to the Companion - chat, screen awareness, video reactions, lock screen, keyword catches - works identically with either backend. You can switch between them in Companion → AI at any time without restarting the app.

Why local instead of cloud?

You'd choose local AI if any of these matter to you:

• Privacy. Chat lines, screen context, persona - none of it travels over the internet. The model lives in %LOCALAPPDATA%\Programs\Ollama and runs on http://localhost:11434. There is no AI-related network egress from the app once it's set up.
• No daily limits. The cloud proxy caps requests to keep costs sane. Local AI is bounded only by how fast your hardware can run the model.
• No login. Cloud AI needs an account; local AI does not.
• Customization. Want a 70B model? A roleplay-tuned fine-tune? A totally different persona? Just ollama pull a different tag and point the app at it.
• Offline use. Once installed, local AI works with the network unplugged.

The tradeoffs are real:

• Disk. The default qwen3.5:latest model is about 6.6 GB. Bigger models can be 20-40 GB.
• First response is slow. Cold-start (model loading from disk into RAM or VRAM) is ~30-60 seconds for an 8B-class model on CPU. The app warms the model on startup to hide this, but the very first request after a fresh install still takes a moment.
• Response time depends on hardware. On a GPU, replies feel snappy (1-3 seconds). On a CPU-only laptop, a chat reply can take 10-20 seconds. Reasoning models (qwen3, deepseek-r1) are slower still, which is why the app sends think:false to disable their internal reasoning phase by default.

Architecture at a glance

Everything in the Companion's brain lives under Services/AIService/. The shape:

AiServiceStrategy is what the rest of the app talks to. It checks CompanionPrompt.UseLocalAi on every call and lazily constructs whichever provider is active. Switching providers at runtime is free - no restart, no re-init.

The cloud provider is stateless: every request includes the full system prompt and the user line; the proxy holds no state. The local provider holds a persistent chat history in memory and on disk so the Companion can remember you across sessions.

The setup wizard, step by step

Opening Companion → Use Local AI for the first time launches the Local AI Setup Wizard. It's a single window that walks through every step needed to go from zero to a working local model.

The request lifecycle

What happens when you type a message into the Companion chat and hit enter, assuming local AI is selected. (Awareness reactions, video-done hints, lock-screen comments, and keyword catches all follow the same path with different system prompts and inputs.)

Concurrency control

A semaphore guarantees one in-flight request at a time. Behavior depends on who's asking:

• User-triggered request while busy - drops the new call but returns a random "still thinking" phrase (e.g. "Bambi's thinking real hard right now...") so you don't get silence. Mods can supply their own thinking phrases.
• Automated request while busy (awareness, video-done, etc.) - drops silently. Better to skip a passive reaction than queue them up and have the Companion fire stale comments seconds later.

Prompt freshness

The system message at index 0 is rebuilt on every call. Changes to your persona, knowledge base, mods, or content mode take effect immediately - no need to restart or clear history.

History rollback on failure

If the request errors or returns empty content, the just-appended user turn is popped off so it doesn't poison future requests with an unanswered turn.

The think:false flag

Reasoning models (qwen3, deepseek-r1, and their relatives) have an internal "thinking" phase where they output long chains of reasoning before the actual answer. For roleplay chat this adds 30-50 seconds of latency for no benefit. think:false cuts that out. Non-reasoning models ignore the flag.

How the persona is built

The system prompt sent to the model is assembled by BambiSprite from several layers. This is shared between the cloud and local providers - both end up sending the same system prompt structure. From outer to inner:

1. Persona block. The "Bad Influence Bestie" character description: tone (casual texting), topics (makeup, pink things, empty heads), role (tempt the user into being blank). If Slut Mode is on and the current personality preset defines a Slut Mode variant, that variant replaces the default - same character, spicier vibe.
2. Explicit reaction rules. How the Companion reacts when the user mentions explicit topics: flustered redirect rather than full roleplay. Can be overridden per-personality.
3. Knowledge base. Lists of audio playlists and videos the Companion is allowed to recommend, with strict instructions to use exact titles (otherwise the app can't auto-link them). For BambiCloud playlists, the AI is told to wrap titles in markdown link syntax with the exact URL.
4. Global knowledge base links. Anything the user added to the Knowledge Base Links list - extra videos, custom content packs, the user's own files.
5. HypnoTube link pool. If the user configured their own pool, those video names are appended. Names are resolved against the known-links map so the auto-linker can wrap them as clickable URLs.
6. Screen awareness rules. How to react to different categories (work, social, shopping, streaming, hypno content, idle). The Companion sees context as [Category: X | App: Y | Title: Z | Duration: N] and is expected to react appropriately.
7. Output rules. Length cap (typically ~15 words), emoji cap (1 per message), no bracket tags in the visible reply.
8. Quiz context (if you've taken the in-app quiz). The Companion sees your archetype and a short profile snippet, with instructions to reference it naturally ~20% of the time.
9. Mod-aware substitutions. If you're using a mod that renames the user ("Bambi" -> "Unit" for Drone mod, or your chosen term for Sissy Hypno mode), the entire prompt is run through a substitution pass.

Every layer can be customized independently. You can write a totally different persona while keeping the knowledge base intact, or vice versa.

The enrichment block and structured output

When "Allow AI to control effects" is on, the local provider inserts an extra context message right after the system prompt. This is the enrichment block. It's sent as a user-role message but clearly marked [CONTEXT BLOCK - NOT DIALOGUE] so the model treats it as operating instructions rather than something to reply to.

Forces structured JSON output

The block explicitly tells the model that any earlier persona instruction saying "no brackets" or "respond only with text" is overridden by this format. Many community personality presets include strict "no JSON, no tags, just text" rules, which would otherwise conflict with the effect-emission format. The override resolves the conflict in favor of the structured output, and the response field carries the plain-text reply the user actually sees.

Tells the model when to fire effects

The block lists supported commands and gives concrete examples of phrases that should trigger them:

Crucially, the block also says: when the user is just chatting, leave effects empty. Don't fire unprovoked. Combined with the per-effect permission gates, this is what keeps the AI from spam-firing flashes at you during normal conversation.

Provides live context

Two final blocks appear in the enrichment:

The timestamp gives the model a sense of "now." The data block is the contents of assets/knowledge.json - a flat list of static facts the Companion is allowed to know (terminology, names, lore). If the file is missing, the data block is just [].

Sets reply etiquette

• Keep response short (the persona's word limit still applies).
• Don't echo the user's request word-for-word.
• When you DO trigger an effect, briefly acknowledge it ("Flashing for you, hot stuff~").
• Don't trigger video unprompted - videos are disruptive.

Effect commands: letting the AI control the app

The Companion can trigger 11 distinct effect types (plus a none no-op the parser ignores):

Tolerant parsing

The parsing pipeline is intentionally tolerant. Local models love to wrap JSON in markdown fences, mix prose and JSON, leave trailing commas, or close braces incorrectly:

• If the response is wrapped in a ```json ... ``` fence, the fence is stripped.
• If the response is pure JSON with a response field, it's parsed directly.
• Otherwise the parser scans the text for {...} blocks, tries each, replaces any with a response field by their content (so JSON becomes prose), and collects any effects arrays.
• A repair pass handles trailing commas, mismatched braces, and unquoted keys before parsing.
• A sanitizer strips any leftover [Category: ...] or [Mode/Tag] tags the model copied from the input.

Dispatch path

Each parsed command goes through AiCommandService.ExecuteCommand:

1. Validate against settings (master toggle + per-effect gate).
2. Enforce a per-response cap (max 3 commands per AI reply).
3. Append a human-readable line to the AI Brain → Live actions feed on the Companion tab.
4. Build and run the concrete command via the command factory.

The 3-commands-per-reply cap is hard. If the model emits five flash effects in one response (which happens with some models), only the first three execute.

Safety: permissions, caps, and the master toggle

The defaults are conservative. Even after you turn on local AI, the Companion can't fire effects until you explicitly enable them.

The dispatcher checks, in order: master toggle, per-effect toggle, batch cap (3 per reply), and finally per-command field clamps applied at execution time. This three-layer defense means even a misbehaving or jailbroken model can't do something destructive - at worst it spams logs with rejected commands.

Persistent chat memory

The local provider remembers your conversation across app launches. One of the key differences from the cloud provider, which is stateless by design.

• After every successful exchange, the user/assistant pair is appended to in-memory history.
• An async write fires to flush the dialogue to %APPDATA%\ConditioningControlPanel\local_chat_history.json. Disk I/O is off the response path, so chat latency is unaffected.
• On next launch, the history is read back. The system prompt and enrichment block are NOT persisted - they're rebuilt fresh on every call so prompt edits take effect immediately.

The persisted file is capped at 50 pairs (100 messages). When the cap is exceeded, the oldest pairs are dropped first. Keeps the file under ~200 KB in practice and bounds the context the model has to chew through.

You can turn this off in Companion → AI by unchecking "Remember chat between sessions" - that flips ChatMemoryEnabled to false and the provider stops both reading and writing the file. Clearing memory is also available; it deletes both the in-memory history and the on-disk file.

Warm-up, lifecycle, and shutdown

Warm-up on startup

At app startup, right after the AI strategy is constructed, a fire-and-forget warm-up sends POST /api/generate with the configured model and keep_alive=30m and an empty body. Ollama interprets this as "load the model into memory but don't generate anything." The keep_alive value asks the model to stay resident longer than the default 5 minutes - without this, the model would unload after 5 minutes of inactivity and the next chat would pay the cold-start cost again.

Warm-up is silent on failure. If Ollama isn't running yet, it just logs and moves on - the next real chat will surface a clear error.

Shutdown

If the wizard spawned ollama serve itself (because the post-install auto-start didn't fire), that process is tracked. On app exit, only that process is killed. Servers started by the Ollama tray app or the installer's own auto-start are left running - they belong to the user, not to us.

Host changes

If you change the Ollama host while the app is running (say, to point at a remote machine), the host check on every request notices the change, disposes the old HTTP client, and rebuilds one against the new base address. No restart needed.

Error handling and fallbacks

Local model failures look very different from cloud failures, so the local provider has dedicated error-to-text mapping:

If a request returns 200 but with empty content (rare, seen with some models on heavy load), the user gets the mode-appropriate fallback line and the user turn is rolled back from history.

Picking a model

The default is qwen3.5:latest. It's a good fit because:

• ~6.6 GB (fits in most consumer setups).
• Reasoning model - so it can follow the structured-output instructions reliably - but we send think:false to skip the slow reasoning phase during chat.
• Strong on instruction-following and JSON output, which matters for the effect-command flow.

That said, the provider is model-agnostic. Anything you can pull through Ollama and chat with via /api/chat should work. To switch:

1. Pull the new tag manually: ollama pull mistral-nemo:latest.
2. Open Companion → AI and either re-run the setup wizard with an advanced model name, or edit the value in settings directly.
3. The strategy notices the change on the next chat - no restart needed.

Rough guidance

List what's installed with ollama list, or visit http://localhost:11434/api/tags in a browser.

Privacy

Once local AI is set up, the only AI-related network traffic from the app is:

• Ollama's own model downloads (only when you run ollama pull or use the wizard's pull step) - go directly to Ollama's CDN.
• The Ollama installer download (once, from ollama.com) - only during the wizard's install step.

After that, every chat request goes to http://localhost:11434. The model itself runs entirely on your machine. The Companion's chat history is stored in %APPDATA%\ConditioningControlPanel\local_chat_history.json in plain JSON - readable by anything that can open a text file. If that matters, turn off "Remember chat between sessions" or use full-disk encryption.

The cloud provider, by contrast, sends each chat line + your system prompt + your screen-awareness context to the proxy, which forwards to a hosted model. We log request counts and basic auth state but do not log chat content. See the privacy policy for the full breakdown.

Troubleshooting

Advanced: pointing at a remote Ollama

The Ollama host setting accepts any URL. If you have a beefier machine on your LAN (or a remote server you trust), point the app at its Ollama instead:

1. On the server: start Ollama with OLLAMA_HOST=0.0.0.0 so it binds to all interfaces. By default Ollama only listens on localhost.
2. Make sure the model you want is pulled on that machine.
3. In the app: edit Companion → AI → Ollama Host to http://your-server:11434/.
4. The strategy notices the change on the next request, rebuilds its HTTP client, and you're done.

Glossary

Questions, suggestions, or "this section is wrong" reports - open an issue at CC-Labs-llc/ccp-bugs or ping in the Discord. The integration shipped in v5.8.4 and the docs will evolve with it.