Context intelligence: choosing what the AI reads

What context intelligence does

An AI coding tool can only take into account the text in its context window. That is its working memory for the conversation: your prompt, the instructions it has loaded and the files it has read. Context intelligence is the part of Paqad that decides what goes into that window at the start of each message. The aim is to give the agent the rules and project facts that apply to the task in hand, without loading every document in the repository.

Most of this work is done by scripts, not by the AI. Scripts work out which rules apply to the files being changed and prepare a small context file ahead of time. The AI then decides how to use what it has been given.

What loads by default

What goes in depends on how Paqad's router classified your request. When the request is a code change (the feature development workflow), or has not been classified yet, the context carries three things. Sizes are counted in tokens, the units AI models measure text in (roughly four characters of English each).

• A rule manifest. One short line for every rule in docs/instructions/rules/, so the agent knows every rule exists.
• Full text only for the rules that apply. A script matches each rule's file patterns against the files in play and includes the full text of the matches. This is called lean rule loading. It is on by default (the lean_rules setting).
• An existing-surface digest. Short cards describing functions and components that already exist in the areas being touched, capped at about 1,000 tokens (the existing_surface_tokens setting). This nudges the agent to reuse code rather than rewrite it.

For other requests, such as a question about the project, the rule sections are left out. For small talk that matches no workflow, nothing is retrieved either. See Workflow routing for how requests are classified.

How the context reaches the agent

1. When you send a prompt, a hook (a small script the AI tool runs automatically at set moments) starts a background job, paqad-ai rag refresh-context. It starts at most once every 20 seconds.
2. The job writes .paqad/context/session-context.md. The file holds the rule manifest, the applicable rule text, the digest and, when retrieval is switched on, a few retrieved passages.
3. On each prompt, the hook reads that file and adds it to the prompt inside a [paqad-context] block. The read has a 50 millisecond time limit so it never holds up your prompt. The file is prepared in the background, so a refresh usually shows up on the following prompt.

If the file is missing, empty or slow to read, nothing is added. The agent then works as it would without Paqad's context file: it reads the files it needs itself.

What the measured saving means

The paqad-ai README reports a 49 to 61 percent smaller resident load. That figure has a specific context:

• It compares the instruction text loaded at session start with lean rule loading against loading the full rule tree.
• It was measured on two projects: the paqad-ai repository itself (61 percent) and a freshly onboarded React project (49 percent).
• It used a rough tokenizer that counts four characters as one token.

It is not a promise for your project and it does not measure retrieval. Your result depends on how many rules and documents you have. The measuring script, scripts/measure-footprint.mjs, is in the paqad-ai source repository, not in the npm package. To measure your own project, run it from a clone of that repository:

node scripts/measure-footprint.mjs --project /path/to/your-project

Checking context loading with doctor

paqad-ai doctor includes two related checks:

• Lean rule footprint acceptable compares the size of .paqad/context/session-context.md with the size of the full rule set. It warns when the lean file is not smaller.
• Context hit rate acceptable reads .paqad/session/context-hit-log.json, which records the share of loaded files the agent actually used, and compares it with a target of 0.7. In 1.91.1 none of the hooks Paqad registers writes this log, so on most projects the check simply reports that there are no context logs yet.

See paqad-ai doctor for the full list of checks.

Optional retrieval on top

Paqad can also search an index of your project and add a few relevant passages to the context file. This is retrieval-augmented generation (RAG), and it is off by default. When it is off, or has nothing confident to offer, the agent falls back to reading files itself. See Retrieval (RAG) overview.

Who decides what

• Scripts decide which rules apply (by matching file paths, not by guessing), what goes into the context file, the size caps, and whether anything is injected.
• The AI decides whether to read more files and how to use what it was given. Retrieved passages are marked as hints to check against the live files.
• You decide whether lean rule loading and retrieval are on, through .paqad/.config.