# What is a codebase knowledge map?

A plain record of what each part of your software does, which other parts it reaches, and why, kept true as the code changes and read by people and coding agents alike.

Source: https://sphoton.io/codebase-knowledge-map · Updated October 2026

## The short version

- A codebase knowledge map records what each module of a system does: its purpose, data, behaviour, boundaries and impact.
- It holds what the code does not say: which modules a change really reaches, and why the conditions between them exist.
- A useful map is certified: an engineer signs each entry at a revision of the code.
- When the code changes, the entries it touches are marked for review, so the map never silently drifts.
- People read it to make changes safely. Coding agents read it so they stop starting every session empty.

## 1. The definition

A **codebase knowledge map** is a structured record of a software system, written module by module and bound to the code it describes. Each entry says what one part of the system is for, what data it owns, how it behaves, where its boundaries are, and what else it reaches when it changes.

It is not a copy of the code and not a diagram generated once and forgotten. It is the knowledge a senior engineer carries in their head about the system, written down in one place where the whole team, and the team's coding agents, can read it.

## 2. Why the code alone is not enough

Every software team knows things its code does not say: which modules a change really reaches, the conditions that hold between them, and why they are there. That knowledge usually lives in three fragile places:

- **A few people.** The senior engineers who answer the same questions all day. When they are away, the team guesses.
- **Documents that drift.** Wikis and design notes are right the day they are written and wrong a few merges later, with nothing to say which.
- **Agent sessions that forget.** A coding agent learns the system during a session and starts the next one empty.

The cost shows up as changes that miss a place: a new hire finds four of the five places a change touches, and the fifth surfaces in QA.

## 3. What an entry holds

| Part | What it records |
| --- | --- |
| Purpose | What the module is for, in the words of the business it serves. |
| Data | What it owns, reads and writes. |
| Behaviour | What it does, including the rules and conditions it enforces. |
| Boundaries | Where it starts and stops, and what it must not do. |
| Impact | What else it reaches when it changes, including the parts the code does not point to. |

## 4. Certified, not just generated

Anyone can generate a description of code. What makes a map worth relying on is that someone who knows the system has checked it. In a certified map, a senior engineer reads a module's entry and certifies it at a specific revision of the code. The certificate carries their name and the date.

Certification also makes the map honest about time. When a merge touches a certified part, that part is marked *needs review* until someone certifies it again. Readers always know what is current and what is behind.

## 5. How it compares

Teams already keep knowledge about their code in several places. Each does one job well; none of them is a certified, current record of what the system does.

| Approach | Good at | Where it falls short |
| --- | --- | --- |
| READMEs, wikis, design documents | Explaining intent when they are written. | Nothing marks them stale when the code changes, so readers cannot tell what still holds. |
| Code search and code graphs | Finding where something is defined and what calls it. | They show links the code makes, not the ones it does not, and not why a condition exists. |
| Agent instruction files (for example `CLAUDE.md`, `AGENTS.md`, editor rules) | Conventions and commands an agent should follow. | Hand-written and unchecked against the code; they grow long and stale as the system grows. |
| Retrieval over the code (indexing, embeddings) | Pulling up code that looks related to a question. | Answers are produced fresh each time and nobody has signed them. |
| A certified knowledge map | What each module does and reaches, checked by an engineer at a code revision, flagged when the code moves on. | It takes engineers' time to certify, which is why it is built module by module, starting where people ask most. |

## 6. How coding agents use it

A coding agent is only as good as the context it starts with. Without a map it reads files until it thinks it understands, and the next session starts again from nothing. With a map it starts from what the system knows today: which modules a change reaches, and the conditions it must keep.

Agents read outside context through MCP, the Model Context Protocol. In Sphoton, Commander, Sphoton's agent, reads the map over MCP and runs on your own infrastructure, so the work your coding agents do starts from certified knowledge instead of guesses.

## 7. Building one with Sphoton

Sphoton builds and keeps a certified knowledge map of your codebase. Your team and your coding agents read the same map.

1. **Open your repository** in the Sphoton desktop app on Windows or macOS. It reads the code on your machine and never uploads it. Any Git repository works, wherever it is hosted.
2. **Map the modules people ask about most.** Start where the questions are, not with the whole system.
3. **Certify them.** A senior engineer signs each entry at a revision of the code.
4. **Invite your team** and connect Commander, with your own model keys, so your coding agents read the map.

Your record is encrypted on your device before it is sent, and you bring your own model keys. The details are in the [docs](https://sphoton.io/docs); the path from first call to live is in the [onboarding guide](https://sphoton.io/onboarding).

## 8. Questions

**Is a knowledge map the same as documentation?**

No. Documentation explains what someone meant when they wrote it. A knowledge map is bound to the code, certified at a revision, and marked for review when that code changes, so it says what is true now.

**Is it the same as a dependency graph?**

No. A dependency graph shows the links the code makes. A knowledge map also records the links it does not make, such as two modules that must agree on a rule, and why.

**Who writes the entries?**

Sphoton builds the map module by module from your code, and your engineers certify each entry. Nothing counts as certified until an engineer has signed it.

**How does the map stay current?**

A merge that touches a certified part marks it needs review until it is certified again, so the map never silently drifts.

**Does our code leave our machines?**

No. The Sphoton desktop app reads your repository locally. What Sphoton stores is your record, encrypted on your device before it is sent.

**Where do we start?**

With one repository and the modules your team asks about most. Join the beta by booking a call at sphoton.io.

---
© 2026 Sphoton · sphoton.io