# How to give AI coding agents context about your codebase

Why coding agents start every session empty, the ways teams fill the gap today, and what context an agent needs to change a real system safely.

Source: https://sphoton.io/ai-coding-agent-context · Updated November 2026

## The short version

- A coding agent does not remember your system between sessions. Each one starts empty.
- Reading files tells an agent what the code says, not which modules a change really reaches or why a rule exists.
- Instruction files, code retrieval and MCP servers each help; none of them says what is true about the system today.
- The context worth giving is the impact and the conditions of each module, checked by an engineer and flagged when the code moves.
- Sphoton keeps that as a certified knowledge map, and its agent reads it over MCP on your own infrastructure.

## 1. Why agents start every session empty

A coding agent works inside a session. It reads files, builds an understanding of the part of the system in front of it, makes a change, and when the session ends the understanding goes with it. The next session, or the next engineer's agent, starts again from nothing and has the system explained again.

On a small codebase that costs some time. On a real system it costs correctness: the agent changes four of the five places a change touches, because the fifth is linked by a rule nobody wrote in the code.

## 2. The ways teams give agents context today

| Approach | What it gives the agent | What it leaves out |
| --- | --- | --- |
| Instruction files (for example `CLAUDE.md`, `AGENTS.md`, editor rules) | Conventions, commands and warnings, loaded at the start of every session. | They are hand-written and nobody checks them against the code, so they grow stale and long. |
| Letting the agent explore | What the files in front of it say. | Links the code does not make, and the reasons behind its rules. Costs time and tokens every session. |
| Retrieval over the code (indexing, embeddings) | Code that looks related to the task. | Similar is not the same as affected; the answer is produced fresh each time and nobody has signed it. |
| MCP servers for outside context | A standard way for an agent to read context it does not hold. | An MCP server is a channel. The question is what it serves. |
| A certified knowledge map, served over MCP | Each module's purpose, data, behaviour, boundaries and impact, checked by an engineer at a code revision. | It is built module by module, so start with the parts your team asks about most. |

## 3. What context an agent actually needs

To change a real system safely, an agent needs the same things a careful senior engineer checks before a change:

- **Impact:** every module the change reaches, including the ones the code does not point to.
- **Conditions:** the rules that hold between modules, and why they are there.
- **Boundaries:** what a module must not do, and where it stops.
- **Currency:** whether what it is reading is still true at today's revision of the code.

The last one is the one most context lacks. Context that might be stale is context an agent cannot safely act on.

## 4. Keeping the context true

Context stays true when someone accountable checks it and something notices when the code moves on. In a certified knowledge map, a senior engineer certifies each module's entry at a revision of the code, and the certificate carries their name and the date. When a merge touches a certified part, that part is marked *needs review* until someone certifies it again. An agent reading the map knows what is current and what is behind.

## 5. Keeping the code and the context private

Giving agents context should not mean handing your code to another company. With Sphoton:

- The desktop app reads your repository on your machine. Your code is not uploaded.
- Everything Sphoton stores is encrypted on your device before it is sent (`AES-256-GCM`, keys derived from your password with `Argon2id`). Its servers hold ciphertext only.
- Commander, the agent that reads the map, is deployed by you, inside your network.
- Every model call goes out under your own key, through Anthropic directly or Amazon Bedrock. Sphoton never bills you for tokens.

## 6. Doing it with Sphoton

Sphoton turns your codebase into a certified knowledge map of your software. Your engineers certify each part of the map, and your team and your coding agents read the same map: people in the Sphoton app, agents over MCP through Commander. Your agents start every session with what the system knows today.

Teams pay per seat, from $10 to $35 a person by role, plus $100 a month for Commander: a team of eight pays **$295 a month**. One developer pays $200 a month, flat, with every role and Commander included. The full pricing is in the [docs](https://sphoton.io/docs#s6), and the beta starts with a short call: [join the beta](https://sphoton.io/#join).

## 7. Questions

**Is an instruction file like CLAUDE.md or AGENTS.md enough?**

For conventions and commands, often yes. For what the system does and what a change reaches, it is a hand-written note that nobody checks against the code. Keep it for conventions and give agents a certified map for the system itself.

**What is MCP?**

The Model Context Protocol, the standard way coding agents read outside context. Commander, Sphoton's agent, reads the map over MCP.

**Does Sphoton replace our coding agents?**

No. It gives the work they do certified knowledge to start from, so they stop guessing at what a change reaches.

**Which AI models does Sphoton use?**

Yours. Every call goes out under your own model key, and you pay your provider directly. Commander uses Claude models, through Anthropic directly or through Amazon Bedrock.

**Does our code leave our machines?**

No. The desktop app reads your repository locally, and what Sphoton stores is encrypted on your device first.

**Which repositories does it work with?**

Any Git repository on your machine, whether it is hosted on GitHub, GitLab, Bitbucket, Azure DevOps or your own server. The desktop app runs on Windows and macOS.

---
© 2026 Sphoton · sphoton.io