Celeborn Code vs a plain CLAUDE.md file: what's the difference?
A plain CLAUDE.md file and Celeborn Code both put project memory on disk, but they scale differently. CLAUDE.md loads in full on every session and grows without bound, so context gets heavier over time. Celeborn Code keeps a tiered .context/ directory where only a bounded Hot tier loads at start and everything deeper is reached on demand by search — so the context footprint stays small no matter how much memory accumulates. Install with `uv tool install celeborn`.
uv tool install celeborn && celeborn initWhere CLAUDE.md works and where it breaks
CLAUDE.md is excellent for a stable, small set of project instructions. It is durable and simple. But it has one load setting: everything, every session. As a project accumulates decisions, notes, and history, the file grows, and every session pays to load all of it — the opposite of what you want as a project matures.
It also has no recall mechanism. There is no way to reach an old detail without it already being in the file, and no faithful record of what actually happened turn by turn.
What Celeborn Code adds
Celeborn Code keeps the good part — memory in files — and fixes the scaling. Only the Hot tier loads on start; warm notes and a journal tail load on demand; cold archives, distilled learnings, and decisions are reached through a full-text index that returns snippets. A per-turn automatic record captures what happened deterministically, with secrets redacted, as a safety net beneath the authored tiers.
It also adds coordination a single file cannot: a shared kanban board and file-touch protocol so multiple agents in one repo see who is doing what.
On one long-lived project, Celeborn's own memory-economy counter estimates roughly 325 million tokens saved across 167 session-load events — the difference between loading the bounded Hot tier and re-reading the entire accumulated context each time. The number is an estimate and grows with project age; the mechanism is what matters: the Hot tier stays a few thousand tokens no matter how much total memory the project accumulates.
You can keep both
Celeborn Code does not replace CLAUDE.md — it complements it. Keep CLAUDE.md for durable instructions and let Celeborn Code manage the growing, searchable memory and the automatic record. Install with `uv tool install celeborn`, then `celeborn init`.
Frequently asked
- Do I have to delete my CLAUDE.md to use Celeborn Code?
- No. They complement each other. CLAUDE.md is good for durable instructions; Celeborn Code manages the larger, searchable, growing memory and the automatic per-turn record.
- Why does CLAUDE.md get expensive over time?
- Because it loads in full on every session. As it accumulates history it grows without bound, and each session pays to load all of it. Celeborn Code's Hot tier is bounded, so load cost stays roughly flat as memory grows.