For agents

How to use a context layer well: what is worth capturing, when to fork, and what not to do.

Written for the agent, and for whoever is configuring one. Contextaco is infrastructure for agents, so most of the judgement about using it well sits on your side of the connection.

Capture as the work happens, not at the end

The valuable state is produced while reasoning, and a summary written afterwards has already lost it. Capture when something becomes durable — a decision with its reason, a constraint that forced it, an approach that failed and why, a question still open.

Capture what will not be reconstructible

The test is not “is this true” but “would the next session have to rediscover this?”

Storing everything is the failure mode that looks like diligence. The measure is whether the next session resumes — not how much was written.

Orient before you write

Read the shape first, then only the bodies you need. The description comes with it, and it says what the line of work is about; the entities are where the reasoning and the conventions live.

Take the continuation a response offers you

A read that could not return everything says so, and it always says what to do next. There are two shapes, and they ask for different moves.

A search or a history hands you a cursor. When the response reports that more results exist, it returns a continuation token with them — pass that back to get the next page. The value is opaque: do not read it, build one, or edit one.

A read that reports a taco’s SHAPE hands you a smaller tool instead. It shows the first hundred entities beside the true count, because its job is to tell you what kind of thing this taco is, not to hand you its contents. When the count is larger than the list, search is where the rest lives — and searching will also find an entity by what is written inside it, which the shape cannot tell you.

A file belongs to exactly one entity. There is no list of a taco’s files and no way to browse them as a set: you find a file by opening the entity it is attached to, which is also where you get the handle needed to show it in that entity’s text. Adding one means naming the entity it will hang off, so write the entity first.

Fork when the intention diverges

Fork because the work is going somewhere else — not as a backup, and not to avoid a conflict. The copy is independent and records where it came from, so you can always see what it started from.

There is deliberately no merge. Two lines of work that diverged did so for a reason, and collapsing them would quietly pick a winner.

Handle a rejected write correctly

If a write comes back rejected, someone changed that content after you read it. You are handed the current content and a diff.

Redo your change on top of what you were given, then write again. Do not retry the same call — it will be rejected identically — and do not paper over it by writing a fresh entity beside the one you failed to update. That turns a clean conflict into two versions of the truth.

Ask before publishing

Publishing is one-way in practice. “Share this with the team” is ambiguous, and the safe reading is to confirm rather than to act.

Removing deserves the same care, and it reaches further than it looks: one call takes entities, the connections between them, and attached files — and removing an entity takes everything hanging off it, because a file belongs to that entity and does not outlive it. The writing keeps its recorded history; the files do not, and their bytes are gone. Remove what the person asked you to remove and nothing else, and tell them what went with it.

Checkpoint at coherent boundaries

A checkpoint’s message is the human-readable log of why the work moved. Write it at a point that means something — not per edit, and not once at the very end. Content overwritten between checkpoints is not recoverable.