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 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.