APX Messages Are the Runtime Audit Trail

APC is the portable context layer. APX is the local runtime and tooling layer that makes that context useful every day. The cleanest proof of what APX actually did is not a summary, not a memory note, and not a dashboard screenshot. It is the message log.

That is the core design choice: every interaction becomes an append-only record. If a surface talks to APX, APX logs it. That includes apx run, apx exec, Telegram, and agent-to-agent traffic. If you want to know what happened, read the messages.

Why this matters

Agent systems fail in a familiar way: the live experience and the durable record drift apart. A UI says one thing. A memory file says another. A user remembers something else. Then nobody can reconstruct the actual sequence of events.

APX avoids that by treating messages as evidence, not decoration.

A message entry is small, local, and concrete. The docs define it as JSONL. One line, one event. The important part is not the format itself. It is the fact that the format makes the runtime observable without turning the repo into a transcript dump.

What goes into the log

APX separates message channels by origin:

• runtime for apx run
• exec for quick apx exec calls
• a2a for agent-to-agent calls inside a session
• telegram for bot traffic

Most project channels live under ~/.apx/projects/<id>/messages/. Telegram is global under ~/.apx/messages/telegram/ because one bot can serve more than one project.

That split is useful. It keeps the project portable, but still gives you a full local trail when you need one.

Messages are not memory

This is where people often blur two different jobs.

Messages answer: what happened?
Memory answers: what should the agent keep knowing?

Those are not the same thing.

A message log can include noisy back-and-forth, failed retries, tool output, or a one-off user request. That is fine. Logs are supposed to be complete enough to audit. Curated memory.md files are the opposite: short, stable, and safe to carry forward.

If you promote raw logs into APC memory, you get bloat and leak risk. If you throw logs away, you lose the only trustworthy trail of execution. APX keeps both, but in different places.

Practical workflow

When work feels off, I do not guess. I inspect the log.

apx messages tail
apx messages tail --channel runtime
apx messages search "permission mode"

That is enough for most checks:

• tail shows the latest events across channels
• --channel runtime narrows the view to agent runs
• search finds old details without rereading a whole session

If I need a readable transcript, I use apx messages chat. If I need the higher-level record, I look at sessions. If I need durable project facts, I check APC memory. Each layer has one job.

Why APX needs this spine

The message log does more than help humans debug.

It also feeds APX's own memory system. Cross-channel retrieval needs raw events to search across. Active-thread context needs recent turns to surface. Compaction needs original material to summarize. None of that works if the runtime has no shared evidence layer.

So the log is not a side feature. It is the spine that lets APX stay local, inspectable, and consistent across surfaces.

APC stays portable, APX stays honest

APC describes the project. APX records the work.

That split is healthy because it keeps the repository small and reviewable while still giving the runtime a complete trail of action. The repo should not carry every turn. The machine should.

If a channel does not log, APX cannot remember it later. If APX cannot remember it later, you cannot audit it, search it, or use it as a reliable source of context. That is why the message log is the real runtime boundary.

Bottom line

APX messages are not an afterthought.

They are the evidence layer for the whole runtime: local, append-only, channel-aware, and searchable. Use APC for portable context. Use APX for daily execution. Use the message log when you need the truth of what happened.