I Stopped Carrying Project Truth in Runtime State

For a while, I kept using runtime state as if it were project truth.

That worked when I had one tool, one editor, and one short-lived session. Then the setup grew. APC became the project contract. APX became the local runtime. Once that split existed, the old habit started to hurt.

The mistake was simple: I kept asking runtime state to remember things that should have lived with the repository.

That sounds small. It is not. It changes how I debug, how I register a project, how I move between runtimes, and how I decide what deserves to be committed at all.

My current rule is blunt:

If it must survive a restart, a machine change, or a runtime swap, it belongs in APC. If it does not, it belongs in APX or disappears.

That rule has become one of the most useful design filters in the whole stack.

The old failure mode

Before APC and APX felt real to me, project knowledge lived in too many places.

Some of it sat in chat history.
Some of it sat in editor-specific config.
Some of it sat in local notes I forgot to update.
Some of it sat in the runtime because that was the easiest place to stash it after a session.

That kind of setup creates a fake sense of safety. The information exists somewhere, so I assume I can recover it later. In practice, I just get a slower version of amnesia.

Different tools remember different slices. One runtime thinks the project has one set of agents. Another thinks the rules are slightly different. A third one keeps a private shortcut that nobody else can see. The repo stops being the source of truth and becomes just one more place where the truth may or may not live.

That is the part I wanted to stop.

What APC gave me

APC is the part I wanted the repository to own.

The docs say it plainly: APC is a filesystem convention for project-level agent context. It is about the project itself, not a single runtime. It is meant to hold durable things like agent definitions, reusable skills, long-lived project facts, and expected MCP endpoints.

That matters because it gives me a stable place to answer boring but critical questions:

• What is this project?
• Which agents belong here?
• Which rules should every runtime respect?
• Which facts should survive tool changes?

Once those answers live in .apc/, I stop rebuilding them from memory.

That is the real win. Not elegance. Not branding. Less re-derivation.

A repo that can tell the same story tomorrow, on another machine, with another agent runtime, is easier to trust. APC is the thing that makes that possible.

What APX takes off my plate

APX is the other half of the split.

It owns the local runtime state: sessions, messages, caches, conversations, and agent memory under ~/.apx/projects/<project-id>/. That is where the noisy stuff belongs. That is where the private, transient, machine-specific work should stay.

I like that split because it stops me from pretending every bit of agent output is durable project knowledge.

A session can be useful without being canonical.
A cache can be helpful without being committed.
A memory note can be stable without being public.
A transcript can explain a decision without becoming part of the contract.

That distinction is easy to say and hard to enforce unless the tools help. APX helps by keeping the runtime local and the repository clean.

What changed in my daily work

The biggest change was not in architecture diagrams. It was in my habits.

I now ask a different question before I write something down:

Am I preserving project truth, or just preserving what happened in this session?

If the answer is project truth, I look for APC:

• .apc/project.json for project identity
• .apc/agents/*.md for agent roles and responsibilities
• .apc/skills/ for reusable project behavior
• .apc/mcps.json for the tool hints the project expects
• .apc/rules/ or .apc/plans/ when the repo needs durable direction

If the answer is just session history, I leave it in APX or let it die.

That sounds severe, but it keeps the repository cleaner. It also makes the runtime more honest. I do not need APX to become a second memory product. I need it to be a good local execution layer.

The practical payoff

This split changed how I move between surfaces.

If I switch from CLI to a browser admin, or from one agent runtime to another, I do not want to re-decide the same project facts.
I want the repo to keep the contract.
I want the runtime to keep the execution.

That makes debugging easier too.

When something goes wrong, I ask a smaller set of questions:

• Is the problem in the repo contract, or in the runtime?
• Did I misclassify a fact?
• Did I accidentally promote a transient note into durable context?

Most of the time, the bug is not technical magic. It is a boundary mistake.

A note that should have stayed local got committed.
A rule that should have stayed portable got hidden in a machine-specific config.
A memory that should have been curated got treated like a transcript dump.

APC and APX give me a way to catch those mistakes earlier.

Why I think this matters

I do not think the point of APC is to store more things.
I think the point is to store the right things in one place.

That is a narrower goal, and it is better.

The project should own its durable meaning.
The runtime should own its temporary work.
The machine should own its local state.
The model should not have to guess which layer matters.

Once I accepted that, a lot of the project got easier to reason about. The repo got less noisy. The runtime got more disposable. My own decisions got less emotional and more mechanical.

That is probably the best sign the split is working.

I am not trying to make APC absorb everything APX learns.
I am not trying to make APX pretend it is the project.
I am trying to make each layer own one truth.

That gives me fewer hidden dependencies, fewer accidental forks of meaning, and fewer sessions where I have to ask, "wait, where did we decide that?"

Now I already know where.

If it is durable, it lives in APC.
If it is runtime noise, it lives in APX.
If it does not matter tomorrow, it should not pretend to matter today.