APX Session Compact Turns a Long Thread Into a Durable Artifact

APC is the portable context layer. APX is the runtime and tooling layer that makes that context useful day to day. apx session compact sits right on that boundary: it takes a long conversation and turns it into something you can keep using later.

That is the important part. A raw transcript is not a good long-term artifact. It is too noisy, too detailed, and too expensive to reopen mentally. A compacted session is different. It keeps the useful shape of the work while dropping the turn-by-turn clutter.

What compact is for

APX treats a session as the durable record of an agent invocation or work thread. Conversations are the raw log. Sessions are the thing you come back to. apx session compact <slug> exists to collapse the conversation side into a shorter, readable summary on disk.

That makes compact a recovery tool, not a diary tool.

If you only need a quick orientation, apx session summary <id> is enough. If you want to preserve the result of a long session so you can reopen it later without rereading the whole transcript, compact is the right move.

Why the split matters

This split is easy to miss if you think every agent output should live in one giant log. That sounds simple, but it breaks down fast.

• Logs are good for traceability.
• Summaries are good for orientation.
• Compact summaries are good for durable handoff.
• APC memory is good for stable project facts.

APX should not try to turn every conversation into project truth. That job belongs to APC. APX should keep the live runtime bounded and make the finished work easy to store.

So the rule is boring and useful:

1. Keep raw turn history while the work is active.
2. Compact when the thread is done enough to preserve.
3. Move only stable facts into APC memory or docs.

That avoids one of the common mistakes in agent workflows: promoting transient chat noise into permanent project context.

A practical workflow

Imagine a session where an agent reviewed a bug, checked logs, tried two fixes, and finally settled on a clean answer. The transcript may be useful for audit, but not for daily reading.

The workflow becomes simple:

apx session summary <id>
apx session compact reviewer --conversation <id>

Read first, compact second.

The first command gives you the gist. The second one makes sure the useful result survives as a smaller artifact. After that, the session is easier to revisit, and the next person does not need to replay every false start.

When not to compact

Do not compact too early.

If the thread is still changing, compacting only hides useful context. That is especially true when you are still editing code, waiting on a tool result, or deciding between two approaches. In those cases the raw conversation is still the right source.

Compact when the conversation has crossed from exploration into record-keeping. Good signals:

• The decision is final enough.
• The next step is outside the current thread.
• You want a handoff, not another round of back-and-forth.
• The transcript is long enough that reopening it would waste time.

APC stays portable, APX stays local

This is the deeper reason the command matters.

APC keeps project context portable in the repo. APX keeps runtime state local on the machine. apx session compact helps APX do its job well: preserve a useful result without pretending the whole transcript belongs in the project contract.

That boundary is healthy. APC stays small and reviewable. APX stays flexible and disposable where it should be. The compacted session sits in the middle: durable enough to matter, local enough to stay honest.

Bottom line

apx session compact is not about archiving everything.

It is about turning one finished thread into a reusable artifact. Use session summary to orient yourself. Use session compact to preserve the result. Use APC memory for facts that should travel with the project.

That is the split that keeps the system readable: APC for portable context, APX for daily runtime, compact for the handoff between them.