> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/reference/appfarm-ai/context-handling.md).

# Context handling

To effectively build and modify your application, Appfarm AI needs to understand not just your immediate request, but the current state of your app. This concept is known as **context**.

### The context package

When you send a message to Appfarm AI, we compile a "context package" that is sent to the Large Language Model (LLM). This package consists of three main parts:

1. **System instructions and Solution memory:** The core rules Appfarm has defined for the AI, combined with your [Solution memory](#solution-memory-and-agent-knowledge) and any older agent knowledge.
2. **Application metadata:** The definition of your app (the data model, views, actions, etc.).
3. **Message history:** The conversation thread, including your prompts and the AI's previous responses.

When **Development data access** is turned on, the context can also include record values from the Development environment. See [Development data](#development-data).

Files you attach to a prompt with **Add files** (the **+** button in the prompt field) are also added to the context and sent to the AI model providers Appfarm AI uses.

This context is sent to Appfarm AI both when using **Build** mode and **Ask,** but the system instruction and amount of metadata may vary.

All subagents have variants of this context package: All subagents have different system instructions, and the metadata sent to the subagents differ (e.g. data model subagent does not receive metadata for views).

### Application metadata

The most dynamic part of the context is the **application metadata**. This allows the agents to understand your object classes, UI structure, and logic flows.

#### **Optimization and on-demand fetching**

Appfarm AI doesn't send the entire application metadata with every message. It uses a **model map** approach:

* **Model map:** Once per thread, the agents get a compact map of the whole Solution: the names, types, and IDs of apps, views, actions, Flows, object classes, enums, and more.
* **On-demand fetching:** The agents use **Tools** to read the full metadata of the parts they need, including the view or action you are currently working on in Appfarm Create.

{% hint style="info" %}
**Building blocks:** When the subagents are building, they also use tools to collect definitions of specific building blocks (such as how a specific action node or UI Component is structured) to ensure they generate valid metadata.
{% endhint %}

{% hint style="info" %}
**All apps in the Solution**: The model map covers all apps and Flows in the Solution. You can refer to another app or view by name, and Appfarm AI reads its details on demand.
{% endhint %}

### Development data

By default, Appfarm AI doesn't read the values stored in your solution. When it generates records or needs to reference existing records, it reads record IDs and the number of records in an object class in the Development environment.

If an Owner turns on **Development data access** in [Settings](/reference/appfarm-create/settings.md#appfarm-ai) > **Appfarm AI**, Appfarm AI can also read the values of records in the Development environment. It uses them to answer questions about your data, for example why a list shows no records, and to match existing records when it generates more. The values it reads are added to the context and sent to the AI model providers Appfarm AI uses. Appfarm AI reads values only when a request needs them. Looking up record IDs never includes values.

Appfarm AI never reads data from the Test or Production environments, and it can't read the User object class. Ask doesn't read development data.

### Message history and long threads

To maintain a coherent conversation, Appfarm AI sends the chat history along with your new prompt. However, LLMs have a limit on how much information they can process at once (the context window).

As your conversation thread grows:

* **Full history:** The whole thread is sent with every step. A long thread is slower, costs more per step, and the AI can lose track of details from early in the thread.
* **Hand-off to a new thread:** When a build thread grows long, Appfarm AI asks **Continue in a new thread?**. Click **Start new thread** and the build goes on in a new thread that starts from a short brief of what is built and what is next, instead of the full history. **Continue here** keeps the current thread.
* **Your earlier prompts:** A new thread only knows what the brief carries. Restate key requirements in a new message, or put lasting rules in Solution memory.

In a task-based plan, each subagent gets a clean thread for every task. The orchestrator generates the necessary info to the agents through the task description.

{% hint style="success" %}
If a thread becomes very long, with many messages with different intents, fixes and comments, the AI might lose track of your current intent, and a task list might become irrelevant. In these cases, it is recommended to start a new thread.
{% endhint %}

### Solution memory and agent knowledge

Solution memory holds facts about your Solution that every developer shares, such as naming conventions or customer constraints. Each new thread reads all of it when it starts, and it stays in the system instructions block of every request in that thread, including threads started by a hand-off. A change to Solution memory reaches threads started after the change.

**Agent knowledge** is deprecated. If you have defined custom instructions in the agent knowledge settings, Appfarm AI still includes them in the system instructions block of every request, but add new guidelines to Solution memory instead. Both are found in Settings under **Appfarm AI**.

### Impact on credit usage

The size of the context directly impacts the **credit consumption** of your request.

* **Complexity = tokens:** A large app with many components requires more metadata. Therefore, asking the AI to modify a massive, complex app will consume more tokens (and thus more credits) than modifying a simple view. This also applies if the Solution is large, since the model map covers the whole Solution.
* **History cost:** Long threads containing much back-and-forth discussion (or tasks) carry more data than a fresh thread.

### Context window and limits

#### Limits and Errors

While the LLM context window is large (typically 1M tokens), very large views or extensive app structures can exceed this limit. If this occurs, you will see the following error:

> *"Context window exceeded. The current view, Action, or app is too large. Narrow the scope and try again."*

#### How to Reduce Context Size

If you encounter this limit, try the following:

* Simplify the View: Reduce the number of components (i.e., remove hidden duplicates).
* Change Perspective: Navigate to a smaller, more focused view before using the AI.
* Restart Conversation: Start a new chat to clear the accumulated history.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.appfarm.io/reference/appfarm-ai/context-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
