Valence User Guide

⚡ Getting Started

Valence is a cross-model AI chat interface for Windows. It lets you chat with multiple AI providers (OpenAI, Claude, Gemini, Grok, and more) from a single app, switching between them mid-conversation with context preserved.

Prerequisites

• Windows 10 (build 19041+) or Windows 11
• WebView2 Runtime — usually pre-installed on Windows 10/11. If missing, Valence will prompt you to install it
• An API key from at least one AI provider, OR Ollama installed for free local models

First Launch

When you launch Valence for the first time, a setup wizard walks you through configuration:

1. Your Name — Valence uses this to personalize the chat experience.
2. Choose a Provider — Select your primary AI provider (you can add more later in Settings).
3. Enter API Key — Paste your API key. For Ollama, just confirm the endpoint URL (default: http://localhost:11434). See the API Key Guides for help getting keys.
4. Done — You're ready to chat. The main window opens with your chosen provider active.

Where Things Are Stored

• Settings: %AppData%\AIOverlayV2.1\settings.json
• Saved chats: Configurable in Settings > Storage (default: Documents\AIOverlay)
• API keys: Encrypted using Windows DPAPI — they never leave your machine in plain text

💬 Chat & Conversations

The chat window is your main workspace. Type a message, hit send, and the AI responds in real-time via streaming.

Sending Messages

• Enter in the input field sends the message (when input is focused)
• Ctrl + Enter also sends (works as an alternative)
• Shift+Enter adds a newline without sending

Streaming Responses

AI responses stream in real-time — you see each word as it's generated. A progress indicator shows while the response is being generated. Press Esc to stop generation early.

Markdown & Code Blocks

AI responses render full Markdown: bold, italic, lists, headers, links, and code blocks with syntax highlighting. Code blocks include a Copy button for quick clipboard access.

Conversation Branching

When you regenerate a response (Ctrl + Shift + R), Valence creates a branch — an alternate version of the response. A branch navigator (< 2/3 >) appears so you can compare different responses and pick the best one.

Editing Messages

Hover over any of your messages to see the edit button. Click it, modify the text, then choose Save & Regenerate to get a new AI response based on your edit.

Conversation Sidebar

Click the sidebar icon (or use the menu) to access saved conversations:

• Save — Save the current conversation for later
• Load — Click any saved conversation to restore it
• Search — Filter conversations by title or content
• Sort — By newest, oldest, A–Z, or most messages
• Delete — Remove saved conversations you no longer need
• Export — Copy conversation to clipboard as formatted text

Quick Actions

• Ctrl + L — Clear conversation / start a new chat
• Ctrl + Shift + C — Copy entire conversation to clipboard
• Ctrl + F — Search within the current conversation

⬡ AI Providers

Valence supports 8 AI providers. Configure API keys in Settings > API Keys, then switch between providers at any time — your conversation history carries over.

Switching Providers

Use the provider dropdown in the chat header to switch at any time. Your conversation history stays intact — the new provider picks up where the last one left off.

Model Selection

Each provider offers multiple models. Click the model name next to the provider dropdown to choose a specific model. Valence remembers your last-used model per provider.

Vision Support

Providers marked "Vision: Yes" can analyze images you paste or drag into the chat. See Files & Images for details.

For step-by-step API key setup instructions, see the API Key Guides.

👤 Profiles & Personas

Profiles let you create custom AI personas with different behaviors, instructions, and settings. Switch between a "Code Reviewer", a "Creative Writer", or any persona you design.

Creating a Profile

1. Click the profile dropdown in the chat header and select New Profile.
2. Enter a name (up to 50 characters).
3. Pick an icon from 12 options (robot, laptop, pencil, art, chart, science, books, target, bolt, brain, sparkle, wrench).
4. Write system instructions (up to 10,000 characters) — these tell the AI how to behave when this profile is active. Example: "You are a senior code reviewer. Be direct. Focus on bugs, performance, and readability."
5. Optionally set overrides (see below).
6. Click Save.

Profile Overrides

Each profile can optionally override global settings:

• Temperature — Controls AI creativity (0.0 = precise/deterministic, 2.0 = maximum creativity). Default is 0.7. Adjustable in 0.05 steps.
• Default Model — Automatically switch to a specific provider/model when this profile is activated.
• HIVE Cartridge — Route memories to a specific cartridge (when HIVE is available).

Switching Profiles

Use the profile dropdown in the chat header. Switching profiles immediately applies the new system instructions and any overrides.

Import & Export

Profiles can be exported as JSON files and imported on another machine. Use the import/export buttons in the profile editor to share personas with others.

⇄ Auto-Triggers

Auto-Triggers let you switch AI providers mid-conversation by typing a prefix. Start your message with @Claude and it automatically routes to Anthropic; type @Grok to switch to xAI.

How It Works

1. Type @TriggerWord at the start of your message (e.g., @Claude explain recursion).
2. Valence detects the trigger, switches to the mapped provider/model, and sends the message (minus the trigger prefix).
3. A notification appears confirming the switch (toggleable).

Managing Triggers

Go to Settings > Auto-Triggers to view, create, edit, or delete triggers.

• Master Toggle — Enable/disable all auto-triggers at once.
• Notification Toggle — Show/hide the "Switched to..." notification.

Creating a Custom Trigger

Each trigger has these fields:

• Trigger Word — The @word prefix (e.g., @Code).
• Display Name — Friendly label shown in notifications.
• Provider & Model — Which AI to route to.
• Description — Optional note for your reference.
• Voice Phrases — Comma-separated phrases that activate this trigger via voice input (e.g., "hey claude, ask claude"). Supports fuzzy matching for speech recognition errors.
• Persist Switch — If enabled, the provider stays active after the response. If disabled, it reverts to your previous provider.

✦ Abilities

Abilities are special commands that the AI can invoke during a conversation. When the AI determines an ability would be helpful, it includes the command in its response and Valence executes it automatically.

Built-in Abilities

MCP Tool Abilities

When you connect MCP servers (see MCP Integration), each discovered tool appears as an ability. These work the same way — the AI invokes them using #tool_name{arguments}.

Managing Abilities

Go to Settings > Abilities to see all available abilities and toggle each one on or off. Disabled abilities won't be offered to the AI.

🔌 MCP Integration

The Model Context Protocol (MCP) lets you connect external tool servers that extend what the AI can do. Search the web, read local files, manage GitHub issues — all through natural conversation.

How It Works

1. You configure an MCP server in Settings (a command that runs a tool server).
2. Valence connects and automatically discovers what tools the server offers.
3. Each tool becomes an ability the AI can invoke during conversation.
4. When the AI uses a tool, Valence executes it and feeds the result back into the conversation.

Adding an MCP Server

1. Go to Settings > MCP.
2. Enable MCP if not already on.
3. Click Add MCP Server.
4. Fill in: Name (friendly label), Command (e.g., npx), Arguments (e.g., -y @modelcontextprotocol/server-filesystem C:/Users), and optionally Environment Variables (for API keys the server needs).
5. Click Save. Valence connects and discovers tools automatically.

Quick-Start Examples

Server Management

• Toggle — Enable/disable a server without removing it.
• Reconnect — If a server disconnects, click Reconnect to re-establish the connection.
• Remove — Delete a server and unregister all its tools.

⬚ Tabs

Tabs let you run multiple independent conversations at once, each with its own message history and AI context.

Tab Basics

• Ctrl + T or click the + button — Open a new tab
• Ctrl + W or click the X on a tab — Close a tab
• Ctrl + Tab / Ctrl + Shift + Tab — Cycle between tabs
• Ctrl + 1 through Ctrl + 5 — Jump to a specific tab
• Click a tab to switch to it

Tab Settings

Configure in Settings > Tabs:

• Max Tabs — Limit how many tabs can be open at once (1–10, default 5).

Context Sharing

Share conversation context from one tab to another:

1. Right-click the source tab.
2. Select Share Context To and pick the target tab.
3. A summary of the source conversation is injected into the target tab as reference.

Context sharing settings (in Settings > Tabs):

• Enable/Disable — Turn context sharing on or off.
• Truncation Length — How many characters of context to share (100–2,000, default 500).
• Mode — one_shot injects context once; the target tab proceeds independently after that.

⚖️ Compare Models

Compare how different AI models respond to the same prompt, side by side. Useful for finding the best model for a task, evaluating response quality, or getting multiple perspectives.

Opening Compare Models

• Click the hamburger menu (top-right) → Compare Models
• The modal opens with a prompt field pre-filled with your last message

Selecting Models

• Two model slots are shown by default. Click + Add model for a third.
• Each slot has a Provider dropdown (only providers with configured API keys appear) and a Model dropdown.
• Slot 1 is pre-filled with your currently active provider and model.
• You can select the same provider in multiple slots (e.g., compare GPT-4o vs GPT-4o-mini).

Running a Comparison

• Edit the prompt if needed, then click Compare.
• Responses stream in real time into each slot. A pulsing border indicates which slots are still streaming.
• If one provider fails, the other slots continue — errors are shown inline per slot.
• Your existing conversation history is included as context, so the AI has the same background for all models.

Cancelling

• Close the modal or click Cancel at any time to stop all active streams.
• Partial responses remain visible until the modal closes.

📊 Context Management

AI models have a limited context window (how many tokens they can process at once). Context Management automatically summarizes older messages when you're approaching the limit, so your conversation can continue indefinitely.

How It Works

1. You set a token threshold (or leave it at 0 for auto-detection based on your current model).
2. When the conversation exceeds the threshold, older messages are summarized into a compact recap.
3. Recent messages (the last N you configure) are always kept in full.
4. The original messages are preserved in storage — only the AI's view is compressed.

Settings

Configure in Settings > Context:

• Enable/Disable — Master toggle for context management.
• Token Threshold — When to trigger summarization. Set to 0 for auto-detection (recommended).
• Recent Messages to Keep — How many recent messages to preserve in full (default 10).
• Summary Style — Concise (shorter, key points only) or Detailed (more nuance preserved).
• Show Notifications — Alert you when summarization occurs.

File Chunking

When you attach large files, context management can split them into chunks for processing:

• Enable/Disable — Toggle file chunk handling.
• Chunk Overlap — Percentage of overlap between chunks (default 10%).
• Max Chunks — Maximum number of chunks to process (default 20).

🎨 Themes & Appearance

Customize Valence's look with 8 built-in themes and typography settings.

Themes

Go to Settings > Theme to preview and apply themes. Click any theme to apply it instantly.

Typography

Also in Settings > Theme:

• Font Family — System, Inter, Roboto, or Mono.
• Font Size — Small (13px), Medium (14px), or Large (16px).
• Compact Mode — Reduces spacing for denser information display.

Window Settings

• Window Opacity — Adjust transparency from 50% to 100% (Settings > Theme).
• Always on Top — Keep Valence above other windows.
• Reset to Defaults — Revert all visual settings to factory defaults.

🎤 Voice Input

Dictate messages using Windows Speech Recognition. Works offline using your system's built-in speech engine.

Using Voice Input

• Ctrl + M — Toggle continuous voice input on/off. Speak naturally and your words appear in the input field.
• Ctrl + Alt + T — Push-to-talk (global hotkey). Hold to speak, release to stop. Works even when Valence is minimized.

Voice Triggers

You can switch AI providers by voice. If you've set up voice phrases on your Auto-Triggers (see Auto-Triggers), saying "Hey Claude" or "ask Google" will route your message to the matching provider.

Voice triggers use fuzzy matching to handle speech recognition errors — "Hey Cloud" will still match "Hey Claude".

📎 Files & Images

Attach text files and images to your messages for the AI to analyze.

Text File Attachments

How to attach: Drag and drop a file onto the chat window.

Supported types (21):

.txt .md .json .xml .csv .yaml .yml .cs .js .ts .py .html .css .sql .jsx .tsx .vue .go .rs .java .cpp .h

Size limit: 500 KB per file.

Image Attachments

How to attach: Drag and drop an image, or paste from clipboard (Ctrl + V).

Supported types: PNG, JPEG, WebP, GIF.

Size limit: 2 MB per image.

Images appear inline in your message. Click an image to open a full-size lightbox with a download button.

Vision Providers

Not all providers can analyze images. Providers with vision support:

• OpenAI (GPT-4o, GPT-4 Turbo)
• Anthropic (Claude 3+ models)
• Google Gemini
• Ollama (with vision-capable models like LLaVA)

If you attach an image with a non-vision provider active, the image will be sent but the AI may not be able to analyze it visually.

📝 Message Templates

Save frequently used prompts as templates for quick reuse. Great for code review requests, email drafts, analysis prompts, or any workflow you repeat often.

Creating a Template

1. Click the templates button near the input area.
2. Click New Template.
3. Enter a name and the template content (up to 5,000 characters).
4. Click Save.

Using a Template

1. Click the templates button to open the template browser.
2. Click a template to insert its content into the input field.
3. Edit the inserted text if needed, then send.

Managing Templates

• Edit — Update an existing template's name or content.
• Delete — Remove a template you no longer need.
• Search — Filter templates by name when you have many.

💾 Storage & Data

Valence stores all data locally on your machine. Nothing is sent to Helix AI Labs servers.

Storage Locations

• Settings: %AppData%\AIOverlayV2.1\settings.json
• Saved Conversations: Configurable folder (default: Documents\AIOverlay)
• Local Memory: Documents\AIOverlay\LocalMemory\{ProfileId}\
• Profiles: Stored alongside settings

Changing the Storage Path

Go to Settings > Storage to change where conversations are saved. Click Browse to pick a new folder.

API Key Security

API keys are encrypted using Windows DPAPI (Data Protection API) before being saved. They are tied to your Windows user account and cannot be read by other users or on other machines.

Settings Backup

• Export Settings — Download all settings as a JSON file (Settings > Storage).
• Import Settings — Restore settings from a previously exported file.

🧠 Local Memory

Local Memory gives Valence persistent memory across conversations. The AI can remember facts, preferences, and context from previous chats and recall them automatically — all stored locally on your machine.

Enabling Local Memory

Go to Settings > Memory and toggle Enable Local Memory on. This activates the #remember and #recall abilities for local storage.

Save Modes

Auto-Save

Set the Auto-Save Interval to automatically save conversations to memory after N AI responses. Set to 0 to disable auto-save (manual only via the "Save Current Chat to Memory" button).

Recall Triggers

When Recall Triggers are enabled, the AI automatically searches your memory when you ask about past conversations. Phrases like "do you remember...", "what did we discuss about...", or "remind me about..." trigger a memory search. Results are injected into the AI’s context so it can answer with information from previous sessions.

Memory Browser

The Memory Browser (Settings > Memory) shows all saved memories with their title, date, summary, and topic tags.

• Pagination — memories load 20 at a time. Click Show More to load the next batch.
• Instant Filter — type in the search box to filter memories by title, summary, or topics in real time.
• Deep Search — press Enter or click the Search button to run an AI-powered search across all memory content.
• Delete — click the trash icon on any memory to permanently remove it.

📥 Import Conversations

Bring your conversation history from other AI providers into Valence’s local memory. Imported conversations are indexed as memories — searchable, browsable, and available for AI recall.

ChatGPT

Two import options are available:

• Browser Login (recommended) — Click Import from ChatGPT. A browser window opens where you log in to your OpenAI account. Confirm the import, and Valence fetches your conversations via the API. Fast and automatic.
• ZIP Export — Click Import from ZIP file. First, request your data export from ChatGPT > Settings > Data Controls > Export Data. Once you receive the email, download the ZIP and select it in Valence. Good if the browser login doesn’t work for you.

Claude

Click Import from Claude. A browser window opens where you log in to your Anthropic account. Confirm the import, and Valence fetches your conversation history automatically.

Gemini

Click Import from Gemini. A browser window opens where you log in to your Google account. Confirm the import. Unlike ChatGPT and Claude, Gemini doesn’t have a bulk export API, so Valence navigates through your conversations one at a time. This may take several minutes depending on how many conversations you have. Progress updates appear in real time.

What Gets Imported

Each conversation is saved as a local memory entry with:

• Title — the original conversation title from the provider
• Summary — AI-generated summary of the conversation content
• Topics — auto-extracted topic tags for search and filtering
• Message Count — number of messages in the original conversation
• Date — the original creation date of the conversation

⬡ H.I.V.E. Memory Coming 2026

Heuristic Intelligent Vault Ecosystem — persistent memory infrastructure for Valence.

HIVE will enable the AI to remember facts, preferences, and context across conversations. Key capabilities:

• Cross-Conversation Memory — The AI remembers what you've discussed in previous sessions.
• Semantic Search — Graph-augmented search finds relevant memories based on meaning, not just keywords.
• Cartridge System — Organize memories into cartridges (e.g., "Work Projects", "Personal", "Code Knowledge") for targeted recall.
• Tiered Storage — Hot, warm, and cold tiers for efficient memory management.
• Natural Language Recall — Say "do you remember..." or "remind me about..." and HIVE searches automatically.

When available, HIVE will be configured in Settings > HIVE. The #remember and #recall abilities (already in the Abilities tab) will connect to your HIVE server.

Learn more at helixailabs.com/hive_explore.html.

⌨ Keyboard Shortcuts

Quick reference for all keyboard shortcuts. Access this list anytime from the ? button in the chat header.

General

Messages

Voice

Window

Tabs

🔑 Licensing

Valence uses a simple licensing model with no feature gating — every feature is available to every user.

Trial Mode (7 Days)

When you first launch Valence, a 7-day free trial starts automatically. During the trial, you have full access to every feature. The remaining days are shown in the app.

Licensed Mode

To activate a license:

1. Go to Settings > License.
2. Paste your license key (format: VALENCE-...).
3. Click Activate. The key is validated instantly.

Legacy keys with the ECHO- prefix are also accepted.

Expired Trial

If the 7-day trial expires without a license key, a lock screen appears. Enter a valid license key to continue using Valence.

Purchase a license at helixailabs.com/valence_pricing.html.

🔧 Troubleshooting

Common issues and how to fix them.