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

# How Contexity Works: Agent Context Architecture Guide

> Contexity sits between your AI agent and your project. Agents retrieve bounded, task-aware context packs instead of raw memory dumps.

Contexity sits between your AI coding agent and your project, acting as an intelligent intermediary that delivers only what the agent needs to complete a task. Instead of flooding an agent with a raw memory dump, Contexity assembles a bounded, task-aware context pack — shaped by what you're working on, what your project graph knows, and how fresh and trusted each piece of context is.

## Main Pieces

Contexity organizes project knowledge into distinct layers, each serving a specific role in the context pipeline.

| Piece                | Purpose                                                             |
| -------------------- | ------------------------------------------------------------------- |
| Project identity     | Connects a repo checkout to Contexity state                         |
| Project intelligence | Source-backed graph and route/project map                           |
| Context items        | Durable project notes, decisions, failed attempts, and obligations  |
| External references  | Slack threads, issue comments, docs, repos, and links               |
| External signals     | Extracted requirements, decisions, warnings, and research takeaways |
| Run ledger           | Records what the host did during a task                             |
| Metrics              | Heuristic or benchmark-backed value summaries                       |

## Normal Agent Flow

Every Contexity-assisted task follows a predictable lifecycle. Your host (the AI agent's execution environment) drives each step.

<Steps>
  <Step title="Start run">
    Start a Contexity run with the user task. This opens a ledger entry and anchors the session to the current project identity.
  </Step>

  <Step title="Retrieve pack">
    Retrieve the task-relevant context pack before broad exploration or any edits. Contexity selects items based on task text, trust state, freshness, and your token budget.
  </Step>

  <Step title="Map impact">
    When a file or route becomes relevant, ask Contexity for upstream and downstream impact. The project intelligence graph surfaces what else is likely to be affected.
  </Step>

  <Step title="Detect changes">
    After edits, Contexity maps changed files through the project graph and flags any context items that may now be stale or in need of review.
  </Step>

  <Step title="Close run">
    Record used context, validation results, unresolved threads, and metrics. The run ledger captures what actually happened so future tasks can build on it.
  </Step>
</Steps>

## Why Packs Are Bounded

Context packs are intentionally small. Giving an agent too much context is as harmful as giving it too little — old decisions and noisy notes become hidden instructions that silently steer code in the wrong direction.

Contexity selects each pack using:

* Current task text
* Task plan hints from the host
* Source-backed project intelligence
* Trust state of each context item
* Freshness state of each context item
* Stale-file and deletion-tombstone checks
* Your configured token budget

This combination keeps the agent focused on what is genuinely relevant to the task at hand.

## Local-First by Default

Contexity is designed to run entirely on your local machine. It does not require cloud authentication for the standard product path. Host setup, MCP serving, project state, and context capsules all operate locally, which means your project context never leaves your machine unless you explicitly configure an external sync.