> ## Documentation Index
> Fetch the complete documentation index at: https://cactal.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Project context

> Give the Cactal agent durable, website-specific knowledge and reference material.

Project context gives the Cactal agent durable information about one website. Use project knowledge for guidance the agent should always see, and upload files for reference material it can consult when relevant.

The agent loads project knowledge, agent notes, and the file index when it starts handling your request, including when it continues after an approval pause. During the request, search and read tools retrieve current document content, and tool results report changes the agent makes. Notes consolidated during preparation are available to the same run.

## Project knowledge

Project knowledge is one free-form text document per website that the Cactal agent sees in full on every request. Use plain text, Markdown, headings, lists, or any structure that works for you. Write the brand voice, audience details, business facts, terminology, and design rules that should consistently shape the agent's work. Only you edit this text; the document holds up to 20,000 characters, and your current request still takes precedence when it conflicts with older project knowledge.

## Agent notes

Agent notes sit beside project knowledge on the Context tab and go with every request too. Cactal writes them for you: whenever a long conversation is summarized, it distills the durable facts, decisions, rejected directions, and constraints from the turns being summarized into a short list, drops anything the agent can rediscover from the website itself such as progress logs and version numbers, and keeps the whole list under 4,000 characters. Each rewrite shows up as a step in the agent conversation. Ask the agent to remember or forget something and it updates the notes immediately.

Edit either text in place whenever it is wrong or out of date. If a text changed while you were editing it, saving asks you to load the latest version first so nothing is overwritten.

Agents connected over MCP or the API read the same texts and keep their own notes through the agent notes operations; see [Bring your own agent](/docs/agents/overview).

## Context files

Each uploaded document is converted into bounded Markdown. PDFs and DOCX files use Firecrawl Parse, while text files are normalized locally. Cactal also creates a one-sentence description that helps the agent decide when to read it. The agent receives only a compact index by default, then searches or reads selected ranges on demand.

Images remain images and are returned directly when the agent needs to inspect them. Each image also carries its extracted [color palette](/docs/concepts/assets#colors) as `colors`, `transparentShare`, and `translucentShare` in the index the agent receives, so the exact brand colors in a moodboard or reference screenshot reach the agent without a request.

For short relevant documents, the agent can read directly. For larger documents, it can search several literal terms across selected files together and receive compact passages with overlapping text merged. This lets it gather evidence for independent questions in one request and read further only when needed.

API and MCP clients can use `websiteKnowledge.search` (`POST /websiteKnowledge/search`) with `websiteId`, selected `resourceIds`, and 1–8 `queries`. Matching ignores case and treats each query as literal text within a line. All queries share `maxCharacters`, from 4,000 to 16,000 characters, defaulting to 8,000. The response includes up to 20 passages with source line ranges and zero-based `queryIndexes` into the returned `queries` array. Each query reports `matched` and `truncated`; truncation means more evidence may remain. A passage's `clipped` flag indicates that its first or last line is partial. Missing, unavailable, non-text, and out-of-website ids appear in `unavailableResourceIds`, while available documents still return results. This is the single search operation, using the `websiteKnowledge.search` permission. To search one document for one term, pass one entry in each array. Ranged reads remain available.

<Note>
  Project context is separate from website assets. Context files stay private and are never published with your website or served from its public CDN.
</Note>

## Supported files and limits

| File                | Processing                                                                              |
| ------------------- | --------------------------------------------------------------------------------------- |
| PDF                 | Firecrawl conversion to Markdown with automatic OCR fallback                            |
| DOCX                | Firecrawl conversion to Markdown, including Word files with an incorrect text extension |
| TXT and Markdown    | Common text encodings converted to normalized Markdown                                  |
| PNG, JPEG, and WebP | Retained as directly readable visual references                                         |

A website can keep up to 25 context files. You can download the original upload directly from private storage at any time from its menu. PDFs can contain up to 50 pages. Documents can be up to 10 MiB, while images can be up to 2 MB. Uploads reserve a slot while the request is running. If preparation fails, Cactal discards the upload and releases the slot.

Password-protected, corrupt, unsupported mismatches, legacy DOC/PPT, executable, archive, audio, video, and unlisted file types are rejected. Firecrawl processes no more than 50 PDF pages, and Cactal rejects the upload rather than retaining truncated content.

## Processing limits

Firecrawl first extracts native PDF text and automatically falls back to OCR for scanned or image-only pages. TXT and Markdown files are normalized directly by Cactal without being sent for document parsing.

TXT and Markdown files saved as UTF-8, UTF-16, or common Windows text are converted automatically. If a file named as TXT or Markdown is actually a DOCX document, Cactal detects and repairs its type before processing it. Markdown preserves document content for search and ranged reads, but it does not reproduce every visual detail of a PDF or Word document.

## Privacy

Originals and normalized text remain private to the website. PDF and DOCX bytes are sent to Firecrawl solely for document parsing and are subject to Firecrawl's data-processing terms.

To create the short description, Cactal sends a bounded text excerpt or the uploaded image to its configured AI inference provider. The full document is not added to every agent request.

Project knowledge remains private to the website and is sent to the configured AI inference provider as part of each agent request. Clearing the field removes it from the context loaded for the next agent run or approval continuation.

Deleting a context file makes it unavailable to search and read tools immediately and removes it from the index loaded for the next agent run or approval continuation. Physical storage cleanup follows Cactal's retained deletion lifecycle.