Chao Context Model

This page explains what Chao context is, how it is assembled, and why it is structured the way it is. It is intended to give you a mental model before working with the Chao API.

See also

• Reference: Chao Context API
• How-to: Start a Chao Session

---

What is Chao?

Chao is Chainabit's behavioral advisor — an AI coaching layer that understands your habits, streaks, and goals at the Chainy level. Unlike a general-purpose assistant, Chao is anchored to a specific Chainy and draws on durable memory and real productivity history to give grounded, personalized coaching.

A Chainy is a personal goal system — a collection of chains (habits) unified by a shared vision. Chao's context is always scoped to one Chainy at a time.

---

How Context Is Assembled

When you request Chao context, four data sources are retrieved in parallel and merged into a single snapshot:

Source	What it provides
Chainy memories	Durable observations about your patterns, preferences, and goals — accumulated over time
Chain productivity data	Current streak, longest streak, total completions, and status for each chain in the Chainy
Recent completions	The last 10 completion events across the Chainy's chains, ordered by recency
Active bits	Pending tasks in this Chainy, ordered by priority then scheduled date (up to 15)

This snapshot is passed into Chao's AI context window so coaching responses are grounded in your actual history, not generic advice.

---

Context Hierarchy

When multiple context layers compete for limited context budget, Chao prioritizes them in this order (highest to lowest):

1. Session context — the current conversation state and recent messages
2. Chainy memories — durable, Chainy-scoped memories (preferences, behavioral patterns, goals)
3. Personal memory — account-wide memory entries not tied to a specific Chainy
4. Chain and completion history — streak data and recent activity
5. Workspace context — workspace-level settings and policies (if applicable)
6. Account context — account-wide preferences and configuration

Higher-priority layers are preserved when the context budget is constrained. Lower-priority layers are summarized or dropped.

---

Memory Scoping

Memories in Chainabit have a scope that determines what context they appear in:

Scope	Visible to Chao?	Description
chainy	Yes — for matching Chainy only	Specific to a single Chainy
account	Yes — across all Chainy sessions	Account-wide observations
workspace	Yes — when workspace matches	Workspace-level observations

A memory scoped to Chainy A is never injected into a Chao session for Chainy B. Memories are isolated at the Chainy boundary.

---

Memory Types

Each memory entry has a type that describes what kind of information it holds:

Type	Description
preference	Stated or inferred preferences (e.g. "prefers morning sessions")
behavioral_pattern	Observed recurring behaviors (e.g. "skips chains on weekends")
goal	Explicit or inferred goals for this Chainy
observation	One-off factual observations that don't fit other types

---

Ownership and Security

Chao context is always account-scoped. The API enforces:

• Account ownership: The chainyId must belong to the authenticated account. Supplying another account's chainyId returns 404, not an empty response — this prevents resource enumeration.
• Memory isolation: Chainy-scoped memories from one Chainy are never visible in another Chainy's session.
• Prompt sanitization: All memory content is sanitized before injection into the AI prompt context. Content that matches known prompt-injection patterns is stripped.
• No evidence leakage: Internal evidence arrays attached to memories are excluded from the prompt context (available only via the Memory API).

---

General Mode vs. Chainy Mode

Chao operates in two modes depending on how you call the API:

Mode	When	What Chao knows
Chainy	chainyId provided	Chainy-scoped memories, active pending bits (priority-ordered), chain streaks, recent completions
General	chainyId omitted	Account-wide memories, near-term bits, active chainies

General mode is designed for open-ended conversations — "what should I focus on today?", "how's my week looking?", "talk me through my goals". Chao has a broad view across all your goal systems and upcoming tasks.

Chainy mode is designed for deep coaching within a single goal system — habit streaks, completion patterns, memories specific to that Chainy.

First-message enrichment

On the first message of a Chainy session, Chao also receives the Chainy's vision statement and target date. This gives Chao full goal context to open with a grounded coaching response. Subsequent messages omit these fields to preserve the context budget.

How Chao addresses you

Chao addresses you by name only when it's appropriate — opening a new session, returning after time away, or when a moment is genuinely worth your direct attention (a clarification, an urgent warning, a milestone, an emotionally heavy point). In normal conversation it stays out of the way. Repeated name use across every reply feels artificial and adds nothing; Chao prioritises a calm, natural cadence over surface familiarity.

What general mode surfaces

In general mode, Chao receives:

• Account memories — durable observations about your patterns and preferences not tied to a specific goal
• Bits (tasks) — near-term tasks scored by urgency (overdue > today > tomorrow > this week) and priority; top 10 are surfaced
• Chainies — your active goal systems with their title and vision description (up to 5)

Bits are scored as follows:

Condition	Date weight	Priority boost
Overdue	50	p1: +10, p2: +7, p3: +4, p4: +1
Today	40	same
Tomorrow	25	same
This week	10	same

Date proximity is the dominant factor. Priority is a tiebreaker between same-day items.

---

Chao as an Acting Agent

Chao does not only work with pre-loaded context snapshots. When a session uses Chao as the assistant, Chao can also call tools dynamically during a conversation to fetch live data on demand.

This means Chao can answer questions like "what's overdue this week?" or "show me all bits in my Morning Athlete chainy" by querying your actual data in real time — not just the static snapshot loaded at session start.

What tools does Chao have?

Chao has access to 10 built-in tools across three categories:

Category	What Chao can do
Calendar	Look up today's bits, a specific week, an arbitrary date range, or all overdue items
Bits	Search, filter, and fetch individual tasks
Chainies	List, search, and fetch details about your goal systems

These tools are called internally by Chao during a response. You do not call them directly.

How does this work in practice?

When you send a message to Chao in a session, the platform may run multiple internal steps before Chao responds:

1. Chao receives your message and decides whether it needs to fetch data.
2. If yes, Chao calls one or more tools (for example, calendar.overdue or bits.search).
3. The results are fed back to Chao.
4. Chao writes its final response using the real data it retrieved.

From the client side, you see tool progress events on the SSE stream (tool.started, tool.completed) followed by the text response as usual. See SSE Streaming for details on these events.

Data access boundaries

All tool calls are scoped to your account. Chao cannot read or modify data outside your account boundary. When inside a Chainy session, Chao prioritizes that Chainy's bits and memories but is not restricted to them — it may query other chainies and bits in your account when cross-goal context is relevant to your coaching objective.

Relationship to context snapshots

The static context snapshot (loaded via GET /ai/chao/context) and tool calling are complementary:

• The snapshot gives Chao a quick summary at session start (memories, recent bits, active chainies).
• Tool calls give Chao the ability to drill into specific data that wasn't in the initial snapshot.

If Chao already has the answer from the snapshot, it will respond without calling tools. Tool calls only happen when deeper or more specific data is needed.

Relationship to Sessions

Fetching Chao context directly (via GET /ai/chao/context) gives you the raw resolved snapshot. This is useful for inspecting what Chao knows before a session starts.

When you create a session with assistantType: "chao" and primaryContextType: "chainy", the platform automatically resolves and injects this context into every AI interaction within the session. You do not need to fetch and inject it manually.