AI Learning Priority

Halo’s AI agents draw from many sources: custom instructions, your knowledge base, inbox training, conversation history, and the data attached to the visitor right now. When two sources disagree, the agent has to follow one of them. Learning priority is the order Halo uses to make that call. This article documents the priority order so you can decide where to put information based on how strictly you want the AI to follow it.

​

The priority stack

Higher items take precedence on conflicts. Layers 1 through 7 are static. They go into the cached part of the system prompt, so they are identical across every turn of a chat. Layers 8 through 10 are dynamic or context-heavy: org context is rebuilt from data, the knowledge base is similarity-gated each turn, and behavior context can change on every request. Live session whisper: From Inbox > Conversations, teammates can still send a real-time note that steers the very next AI reply. That path writes both a transient transcript entry (for the active session) and, when the visitor is identified, a durable Inbox Training row scoped to that customer. See Live Conversations.

​

What each layer is for

​

1. Platform safety (Halo team only)

Halo controls a small set of platform-wide guardrails (privacy boundaries, retrieval rules, etc.). You don’t write these. They sit at the top so nothing below can override them.

​

2. Guidance

Short, individually managed directives the AI always follows. Each guideline is a discrete entry you can toggle on/off, edit, and reorder from Knowledge -> Guidance. Use them for:

• Facts and rules you never want the AI to forget. “Office hours are 9-5 ET.”
• Voice and word choices. “Always refer to our pricing as ‘simple, predictable pricing.’”
• Hard constraints. “Never promise a delivery date for a feature that’s still in progress.”

Guidelines always make it into the prompt regardless of what the visitor is asking. They are not similarity-gated like the knowledge base. If you want the rule to apply on every reply, this is the right place. A per-agent Custom Instruction (layer 7) can override an individual guideline for that specific agent.

​

3. Inbox Training

Durable directives your team saves while working real conversations. They are injected on every AI reply for matching context: org-wide, per customer, or per company. Manage and review them under Knowledge -> Inbox Training. Create entries from:

• The ticket Inbox training composer mode (scopes are chosen automatically; org-wide text is scrubbed for PII before save).
• A live session whisper (user-scoped when the visitor is identified; also nudges the next reply on the transcript).
• The agent Train tab (Inbox Training button on a correction, org-wide and scrubbed).

Inbox Training sits below Guidance and above Internal Docs. On conflicts, Inbox Training wins over Internal Docs and the knowledge base. A per-agent Custom Instruction can still override a line when it explicitly contradicts for that agent.

​

4. Internal Docs

Long-form reference content the AI can rely on for every reply, not just when the visitor’s question happens to be a close match. Each doc is a titled markdown entry you manage in Knowledge -> Internal Docs. Use Internal Docs when a single guideline is too short to capture what you need to say. Examples:

• Refund policy. “Customers on the Pro plan can request a full refund within 30 days. After 30 days we offer pro-rated credit. Annual plans require manager approval for refunds.”
• Common troubleshooting. “If a customer reports the widget isn’t loading, first ask whether they see any errors in the browser console. Then check whether their domain is on the allowed origins list.”
• Account cancellation steps. Step-by-step instructions the AI should walk a customer through.

Internal Docs sit at layer 4 because they are always injected (like Guidance), but they sit below Guidance and Inbox Training so a guideline or training line can still override a doc on conflicts.

​

5. Global Instructions

A single textarea applied to every agent in your org. Use this for general personality and behavior. “Be concise and friendly. Don’t make up information.” It’s still high priority but expressed as one block of prose rather than discrete rules, which is why we recommend Guidance for sharper directives.

​

6. Agent Instructions

The main system prompt for an individual agent. This is where each agent’s personality and primary job description lives. A “Sales” agent and a “Support” agent in the same org typically have very different Agent Instructions but share the same Global Instructions and Guidance.

​

7. Custom Instructions

Per-agent overrides. Use this when one specific agent should behave differently from the rest of your org. Because Custom Instructions are rendered later in the system prompt, they win on conflicts with anything above for that agent.

​

8. Org context

Auto-built blocks: company info, the visitor’s profile and traits, recent activity, past ticket history, engagement stats, etc. You don’t edit this directly. It’s drawn from your org’s settings, your CRM integrations, and the user data your widget sends.

​

9. Knowledge Base (RAG)

Everything else you put into Halo’s knowledge base: uploaded files, crawled URLs, help center articles, integrations data (HubSpot, Intercom, Fathom, Slack, etc.), and content auto-learned from resolved tickets. Unlike the layers above, this is similarity-gated: the AI only sees the chunks most relevant to what the visitor just asked. This is where the bulk of your AI’s knowledge lives. But because retrieval is similarity-based, there’s no guarantee a specific chunk shows up on any given turn. If you have a directive that must always apply, put it in Guidance (layer 2), Inbox Training (layer 3), or Internal Docs (layer 4), not the knowledge base.

​

10. Visitor behavior context

Optional data your widget can attach to a turn (current page, recently clicked elements, etc.). Useful for context, lowest priority because it’s request-specific.

​

Where to put information: a decision guide

A useful rule of thumb: the higher you put it, the more strictly the AI follows it, but the more it costs in every prompt’s token budget. Guidance, Inbox Training, and Internal Docs are powerful because they are always injected for matching context, so keep them tight and high-signal. The Knowledge Base is where long-tail reference content belongs.

​

Internal Docs vs Knowledge Base

Both Internal Docs (layer 4) and the Knowledge Base (layer 9) hold reference content the AI uses to answer customers. The difference is how it gets into a given reply:

• Internal Docs are always injected. Every reply, regardless of what the visitor asked, includes the full content of your Internal Docs. The AI can never “miss” them because the question wasn’t a close embedding match.
• Knowledge Base is similarity-gated. Files, URLs, help center articles, and integrations data only show up when the visitor’s question is semantically similar to a chunk. The AI may or may not see any given page on any given turn.

Use Internal Docs for the small set of must-always-apply reference material (policies, common workflows, things you’d be unhappy if the AI got wrong). Put the long tail of “useful when relevant” content in the Knowledge Base. In both cases, customers never see the source content. Halo never links to Internal Docs or Knowledge Base entries in replies. The AI paraphrases what it knows. Don’t write anything in either place that you wouldn’t be okay with the AI repeating to a customer in their own words.

​

When sources disagree

The AI follows the higher-priority source. If a guideline says “Always offer a 14-day trial” and an Internal Doc says “We discontinued the 14-day trial last month,” the guideline wins because it’s higher in the stack. To resolve the conflict, update the guideline (or delete the stale Internal Doc). A Custom Instruction (per-agent) can override a guideline or Internal Doc for that specific agent. This is the intended escape hatch for “the org rule is X, but my Sales agent does Y.”

​

Where to go next