Celeborn

You are working in a project that keeps its memory on disk, in a .context/ directory, instead of
in the conversation. This lets the session stay light and resume cheaply after compaction. Your job
is to read from that memory cheaply and write back to it with discipline so the next session
(or the next thread, or you after a compaction) lands oriented instead of lost.

The mechanical work is done by a CLI: celeborn (alias cel), or
python3 <celeborn>/scripts/celeborn.py. You bring the judgment — what to write, what to promote,
what to forget. See references/memory-protocol.md and references/tiers.md for the full model.

The one rule

Only the Hot tier enters context by default, and it is size-bounded no matter how much total
memory exists. Everything deeper is reached on demand by targeted search returning snippets — never
by loading whole files "to be safe." That is the entire context economy. Don't break it by reading
the whole journal or every durable doc.

Single source of truth

.context/ is the only home for durable project context. Do not create or maintain parallel
context files — CLAUDE_CONTEXT.md, NOTES.md, PROGRESS.md, TODO.md, scratch hand-off docs.
They drift, they aren't tiered, and they aren't searchable. Every fact that should outlive the
conversation goes into a tier (state.md / journal.md / learnings.md / durable/*), and every
session hydrates from Celeborn via ORIENT — never from an ad-hoc file.

If a repo already has such a file when you arrive: migrate its live content into the right tiers, then
replace the file with a one-line pointer (e.g. "Context now lives in .context/ — run celeborn status.") so nothing links into a void. One source of truth, one place to read, one place to write.

First thing, every session: ORIENT

Run celeborn status (the SessionStart hook may have already done this for you). It prints the Hot
tier: session.json, state.md, and durable/manifest.md. Read those, and stop. Pull more only
when the task needs it:

• a durable/*.md body — by pointer from the manifest
• the tail of journal.md — if resuming in-progress work
• celeborn search "<query>" — for anything older or uncertain (returns file#anchor + snippet)

Now you know the current focus and the next action. Begin.

As you work: CHECKPOINT

After each meaningful unit of work — anything you'd hate to re-derive after a compaction:

1. Rewrite .context/state.md in place so "Now / Next action / Open threads" are current.
   Never append history here; exactly one current state.
2. Append one entry to the bottom of .context/journal.md (what you did + evidence pointer + next).
3. Update .context/session.json (focus, next_action, branch, status, updated_at).

If PreCompact fires, checkpoint immediately — the window is about to be summarized.

Keep memory lean: FORGET & PROMOTE

• Journal over budget? → celeborn archive (moves old entries to journal-archive/, still searchable).
• state.md bloating? → condense; push detail to the journal or a durable doc.
• A reusable lesson emerged? → celeborn promote --to learnings --title "..." --note "...".
• A lesson became a stable repo truth? → celeborn promote --to durable --doc <name> --title "..." --note "..."
  (also writes a manifest.md pointer). Delete memory you stop trusting.

Promotion flow: journal → learnings → durable.

Renewing: REMIND (keep the window light)

As the live context grows, invite the user to renew it — clearing is safe because the memory is on
disk. Roughly every ~100k tokens, surface celeborn remind --tokens <current> --last <previous> (it
stays silent unless a new increment is crossed) and offer the host's clear command. On Claude Code
that's /clear, which — with the SessionStart hook wired — wipes history and reloads the Hot
tier in one step. If you can't supply a live count, feed turn deltas with celeborn record turn --tokens <delta> and call celeborn remind --auto, which fires off Celeborn's own rolling estimate.
Portable across all coding systems — see references/reminders.md.

Ending or restarting: HANDOFF

Before ending a long session, or to escape a bloated context, run celeborn handoff. It regenerates
handoff.md (branch, status, next action, risks, and a paste-ready resume prompt) from state.md +
session.json. Starting a fresh thread from a good handoff is the cheapest compaction there is.

After compaction

Your history is gone but your memory isn't. Follow references/rehydration.md: read session.json
→ state.md → durable/manifest.md, then resume from the next action. Don't re-do completed work
(journal.md shows what's done). Trust the repo over a stale note; fix the note on your next checkpoint.

Setup (if .context/ doesn't exist yet)

celeborn init scaffolds it from templates and gitignores the derived index.db. Then seed
state.md with the current focus and next action, celeborn index, and celeborn doctor to confirm
health. Never put secrets in .context/ — celeborn doctor scans for them.

Public repo → private memory. By default .context/ is committed (it travels with a private
repo for free). In a public repo that would publish your working journal, so run
celeborn init --private to gitignore .context/ and move it across machines with celeborn sync
instead. init auto-detects a public repo (via gh) and defaults to private there; --public forces
the committed behavior.

Command reference

status and metrics are read-only — inspecting never changes the numbers. See
references/metrics.md for how the estimate is computed.