# Manual CONTEXT.md vs a self-maintaining knowledge base

A hand-written CONTEXT.md is a good instinct that loses to a moving codebase. Here's the token math, and what a self-maintaining alternative changes.

Keeping a `CONTEXT.md` so your AI tools have a project summary is a good instinct. The problem isn't the idea — it's that manual work loses to a moving codebase.

## Two failure modes of the hand-written doc

1. **It rots.** The moment someone renames a service or moves a module, the doc is wrong — and nobody notices until an agent confidently repeats the stale version.
2. **It's not query-scoped.** A big `CONTEXT.md` is loaded whole, every question, whether it's relevant or not. On a real 1,600-file app we measured a hand-written docs corpus at ~119k tokens — costing tens of thousands of tokens to load per question, more than reading the code cold.

## The token math

For one question, on real repos:

- **Cold agent** (re-reads relevant files): ~12,500 tokens
- **Hand-written docs** (loaded wholesale): ~66,000 tokens
- **SecondOS** (query-scoped map cards): ~2,200 tokens

The manual doc is often *worse* than no doc, because it's big and unscoped.

## What a self-maintaining knowledge base changes

SecondOS's [living knowledge base](/docs/knowledge-base) is the same instinct — read a summary, not the whole source — but generated for you, **query-scoped**, structure-aware, and **re-mapped on every sync so it can't rot**. It's the discipline of a well-kept CONTEXT.md, without the upkeep, and it's smaller *and* fresher.

The reason our own `MEMORY.md` works is that we look at it every day; most teams can't. SecondOS is that, automated. [See how we measured it](/benchmark).