A Stable Project ID Keeps APC Portable and APX Local

A lot of agent tooling problems start with a bad identity model. If a runtime treats a folder path as the project identity, everything looks fine until you rename the repo, move it to another machine, or register the same code from a different checkout.

APC and APX avoid that trap by splitting identity from runtime state.

APC is the portable context layer. It keeps the committed project contract in the repository. APX is the daily-use runtime and tooling layer. It reads that contract, then keeps sessions, messages, caches, and other machine-local state outside the repo.

A small file is what makes that split work: .apc/project.json.

project.json gives the project a durable identity

The APC docs define .apc/project.json as the canonical metadata file for a project. Its job is intentionally boring: say what the project is called, which APC version it targets, and when that metadata set was created.

A minimal APC shape looks like this:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}

APX extends that practical story with one more field when it initializes a real working project:

{
  "name": "my-app",
  "version": "0.1.0",
  "apf": "0.1.0",
  "created": "2026-01-15T10:00:00Z",
  "apx_id": "077078af9dd7"
}

That apx_id is the key detail. APX documents it as the stable identifier that links the committed APC definition to local runtime state under ~/.apx/projects/<apx_id>/.

So folder path is not the identity. Repo display name is not enough either. The stable id is the bridge.

Why that matters in daily work

Imagine this sequence:

1. You run apx init in a repository.
2. APX creates .apc/project.json and generates apx_id once.
3. You register the project with APX.
4. APX stores runtime state under ~/.apx/projects/<apx_id>/.

Now later you:

• rename the repo directory
• move it to another path
• clone it on another machine
• reopen it from a different tool

The APC contract still travels with the repo, because it lives in AGENTS.md and .apc/. The APX runtime state still has a clear local home, because it hangs off the stable id, not off an unstable folder name.

That is exactly the APC/APX division in practice:

• APC says what project this is.
• APX says what happened while this machine worked on it.

Without a stable id, a runtime has to guess. It may create duplicate local projects, lose message history after a rename, or tie private runtime state too tightly to one filesystem path.

Portable definition, local runtime

The APX project docs make the storage split explicit:

• <repo>/.apc/ holds agent definitions, skills, MCP hints, and project config.
• ~/.apx/projects/<id>/ holds sessions, conversations, messages, caches, task logs, and other runtime files.

That design has two benefits.

First, the repository stays reviewable and clone-safe. APC contains portable context, not machine junk.

Second, APX stays honest about privacy and locality. Runtime transcripts, caches, and logs do not quietly end up in git just because a tool needed somewhere convenient to put them.

One practical rule

Treat .apc/project.json like identity, not like a scratchpad.

Do not turn it into a dump of runtime flags, private state, or session metadata. The APC spec keeps it small for a reason. The more stable it stays, the more reliable the bridge to APX becomes.

Likewise, do not change apx_id casually. APX documents that field as the permanent key for the local runtime folder. If you break that link, APX will not know that old local state belongs to the same committed project. If you move the repo, the APX docs point to apx project rebuild as the right repair step.

Bottom line

Portable context needs a stable identity, not a lucky pathname.

APC provides the committed project contract. APX provides the local runtime layer. .apc/project.json is the small boundary object that lets both sides do their job without leaking into each other.

That is not glamorous design. It is better: it keeps project meaning portable and runtime state local.